@rynx-ai/server 0.1.0 → 0.1.10-beta.2

package/dist/emulator-surface-ws.d.ts

@@ -0,0 +1,8 @@
+import type { Server } from "node:http";
+import { WebSocketServer } from "ws";
+import { type RuntimeWebAccessPolicy } from "./runtime-web-auth.js";
+import type { RuntimeConnectionResolverHost } from "./server.js";
+export declare function attachEmulatorSurfaceWs(server: Server, deps: {
+    runtimeConnectionResolver?: RuntimeConnectionResolverHost;
+    runtimeWebAccess?: RuntimeWebAccessPolicy;
+}): WebSocketServer;

package/dist/emulator-surface-ws.js

@@ -0,0 +1,198 @@
+import { WebSocket, WebSocketServer } from "ws";
+import { parseRuntimeEmulatorSurfaceClientFrame, RUNTIME_EMULATOR_SURFACE_MAX_FRAME_RATE, } from "@rynx-ai/protocol/runtime-emulator-surface";
+import { authorizeRuntimeWebRequest, RUNTIME_WEB_CAPABILITY_QUERY, } from "./runtime-web-auth.js";
+const SURFACE_PATH = /^\/api\/runtimes\/([^/]+)\/sessions\/([^/]+)\/emulator\/surface$/;
+const SELECTOR_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,255}$/;
+const MAX_ID_BYTES = 512;
+const MAX_BUFFERED_BYTES = 24 * 1024 * 1024;
+const OPEN_TIMEOUT_MS = 10_000;
+const KEEPALIVE_MS = 15_000;
+const MAX_QUEUED_INPUTS = 64;
+export function attachEmulatorSurfaceWs(server, deps) {
+    const wss = new WebSocketServer({ noServer: true, perMessageDeflate: false, maxPayload: 4 * 1024 });
+    server.on("upgrade", (request, socket, head) => {
+        const parsed = parseUpgrade(request);
+        if (!parsed)
+            return;
+        if ("failure" in parsed)
+            return rejectUpgrade(socket, 400, parsed.failure);
+        const authorization = authorizeRuntimeWebRequest(request, {
+            mutation: true,
+            capability: parsed.url.searchParams.get(RUNTIME_WEB_CAPABILITY_QUERY) ?? "",
+            access: deps.runtimeWebAccess,
+        });
+        if (authorization)
+            return rejectUpgrade(socket, authorization.status, authorization.error);
+        try {
+            wss.handleUpgrade(request, socket, head, (ws) => {
+                void handleConnection(ws, parsed.url, parsed.route, deps);
+            });
+        }
+        catch {
+            rejectUpgrade(socket, 400, "invalid Emulator Surface WebSocket upgrade");
+        }
+    });
+    return wss;
+}
+async function handleConnection(ws, url, route, deps) {
+    const bindingId = url.searchParams.get("bindingId");
+    const maximumFrameRate = Number(url.searchParams.get("maximumFrameRate") ?? "3");
+    if (!validId(bindingId) ||
+        !Number.isSafeInteger(maximumFrameRate) ||
+        maximumFrameRate < 1 ||
+        maximumFrameRate > RUNTIME_EMULATOR_SURFACE_MAX_FRAME_RATE) {
+        ws.close(4400, "invalid Emulator Surface options");
+        return;
+    }
+    if (!deps.runtimeConnectionResolver) {
+        ws.close(4406, "Emulator Surface is unavailable");
+        return;
+    }
+    const controller = new AbortController();
+    let lease;
+    let surface;
+    let cleaned = false;
+    let cleanupPromise;
+    let queuedInputs = 0;
+    let inputTail = Promise.resolve();
+    const cleanup = () => {
+        if (cleanupPromise)
+            return cleanupPromise;
+        cleaned = true;
+        cleanupPromise = (async () => {
+            controller.abort(new Error("Emulator Surface browser disconnected"));
+            try {
+                await surface?.close();
+            }
+            finally {
+                lease?.release();
+            }
+        })();
+        return cleanupPromise;
+    };
+    const keepalive = setInterval(() => {
+        if (ws.readyState === WebSocket.OPEN)
+            ws.ping();
+    }, KEEPALIVE_MS);
+    keepalive.unref?.();
+    ws.on("message", (data, isBinary) => {
+        if (isBinary || !surface) {
+            ws.close(4400, "invalid Emulator Surface browser input");
+            void cleanup().catch(() => undefined);
+            return;
+        }
+        let frame;
+        try {
+            frame = parseRuntimeEmulatorSurfaceClientFrame(JSON.parse(data.toString()));
+        }
+        catch {
+            ws.close(4400, "invalid Emulator Surface browser input");
+            void cleanup().catch(() => undefined);
+            return;
+        }
+        if (frame.type !== "emulator.surface.touch" || frame.surfaceId !== surface.ready.surfaceId) {
+            ws.close(4400, "Emulator Surface browser input does not match the active Surface");
+            void cleanup().catch(() => undefined);
+            return;
+        }
+        if (queuedInputs >= MAX_QUEUED_INPUTS) {
+            ws.close(4408, "Emulator Surface browser input queue is full");
+            void cleanup().catch(() => undefined);
+            return;
+        }
+        queuedInputs += 1;
+        inputTail = inputTail
+            .then(async () => {
+            if (cleaned || !surface)
+                return;
+            await surface.sendTouch({
+                phase: frame.phase,
+                x: frame.x,
+                y: frame.y,
+            });
+        })
+            .catch(() => {
+            if (!cleaned)
+                ws.close(4500, "Emulator Surface input failed");
+            void cleanup().catch(() => undefined);
+        })
+            .finally(() => { queuedInputs -= 1; });
+    });
+    ws.on("close", () => void cleanup().catch(() => undefined));
+    ws.on("error", () => void cleanup().catch(() => undefined));
+    try {
+        lease = await deps.runtimeConnectionResolver.acquire(route.selector, { signal: controller.signal });
+        if (lease.target.selector !== route.selector)
+            throw new Error("Runtime resolver returned a mismatched target");
+        surface = await lease.openEmulatorSurface(route.sessionId, bindingId, {
+            signal: controller.signal,
+            timeoutMs: OPEN_TIMEOUT_MS,
+            maximumFrameRate,
+        });
+        if (cleaned)
+            return;
+        await send(ws, JSON.stringify(surface.ready));
+        for await (const frame of surface) {
+            if (cleaned)
+                return;
+            if (ws.bufferedAmount + frame.encodedBytes.byteLength > MAX_BUFFERED_BYTES) {
+                ws.close(4408, "Emulator Surface browser is too slow");
+                return;
+            }
+            await send(ws, frame.encodedBytes, true);
+        }
+        if (!cleaned)
+            ws.close(1000, "Emulator Surface ended");
+    }
+    catch (error) {
+        if (!cleaned && ws.readyState === WebSocket.OPEN) {
+            const message = error instanceof Error ? error.message : "Emulator Surface failed";
+            // 4406 is an actionable daemon-upgrade state. A temporarily offline
+            // Runtime can also report "unavailable" and must stay on the ordinary
+            // reconnect path instead of flashing a false upgrade error.
+            ws.close(message.includes("semantic capability") ? 4406 : 4500, message.slice(0, 120));
+        }
+    }
+    finally {
+        clearInterval(keepalive);
+        await cleanup().catch(() => undefined);
+    }
+}
+function parseUpgrade(request) {
+    let url;
+    try {
+        url = new URL(request.url ?? "", "http://localhost");
+    }
+    catch {
+        return undefined;
+    }
+    const match = SURFACE_PATH.exec(url.pathname);
+    if (!match)
+        return undefined;
+    try {
+        const selector = decodeURIComponent(match[1]);
+        const sessionId = decodeURIComponent(match[2]);
+        if (!SELECTOR_PATTERN.test(selector) || !validId(sessionId))
+            return { failure: "invalid Emulator Surface route" };
+        return { url, route: { selector, sessionId } };
+    }
+    catch {
+        return { failure: "invalid Emulator Surface route encoding" };
+    }
+}
+function validId(value) {
+    return typeof value === "string" && value.length > 0 && Buffer.byteLength(value, "utf8") <= MAX_ID_BYTES && /^[\x21-\x7e]+$/.test(value);
+}
+function send(ws, data, binary = false) {
+    return new Promise((resolve, reject) => {
+        if (ws.readyState !== WebSocket.OPEN)
+            return reject(new Error("Emulator Surface WebSocket is closed"));
+        ws.send(data, { binary }, (error) => error ? reject(error) : resolve());
+    });
+}
+function rejectUpgrade(socket, status, message) {
+    if (socket.destroyed)
+        return;
+    const label = status === 401 ? "Unauthorized" : status === 403 ? "Forbidden" : "Bad Request";
+    socket.end(`HTTP/1.1 ${status} ${label}\r\nConnection: close\r\nContent-Type: text/plain; charset=utf-8\r\nContent-Length: ${Buffer.byteLength(message)}\r\n\r\n${message}`);
+}

package/dist/machine-session-service.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Daemon-owned application service for the first Remote Runtime Session slice.
+ *
+ * This service deliberately has no HTTP, Koa, WebSocket, or Direct-binding
+ * knowledge. Durable records, live state, events, and interruption remain owned
+ * by the daemon process and arrive through narrow injected ports. Local and
+ * Direct adapters can therefore expose the same behavior without copying state
+ * into a Control Plane database.
+ */
+import { type AgentRuntimeId, type AgentSpec, type ConversationRuntime, type SessionProviderId, type ReasoningEffort, type RuntimeUserInput, type SessionBus, type SessionLogStore, type SessionRegistry } from "@rynx-ai/core";
+import type { SequencedSessionEvent, SessionInteractionResolution, SessionItem, UserContentPart } from "@rynx-ai/protocol";
+import type { RemoteRuntimeSessionResourceDeleteParams, RemoteRuntimeSessionResourceDeleteResult, RemoteRuntimeSessionResourceGetParams, RemoteRuntimeSessionResourceGetResult, RemoteRuntimeSessionResourcePolicyResult, RemoteRuntimeSessionResourceReadParams, RemoteRuntimeSessionResourceReadResult, RemoteRuntimeSessionResourceUploadBeginParams, RemoteRuntimeSessionResourceUploadBeginResult, RemoteRuntimeSessionResourceUploadChunkParams, RemoteRuntimeSessionResourceUploadChunkResult, RemoteRuntimeSessionResourceUploadCommitParams, RemoteRuntimeSessionResourceUploadCommitResult } from "@rynx-ai/protocol/remote-runtime-rpc";
+import type { ControlAgentSummary, ControlSessionInteractionResolveDisposition, ControlSessionRuntimeSnapshot } from "@rynx-ai/protocol/control";
+import { type RemoteRuntimeSessionInterruptResult, type RemoteRuntimeSessionLaunchOptionsListResult, type RemoteRuntimeSessionListParams, type RemoteRuntimeSessionListResult, type RemoteRuntimeSessionSnapshotParams } from "@rynx-ai/protocol/remote-runtime-rpc";
+import { type CodexRuntimeStatus, type CodexSessionStore, type InjectOutcome } from "@rynx-ai/runtime";
+export interface MachineSessionRuntimeStatePort {
+    snapshot(sessionId: string): ControlSessionRuntimeSnapshot;
+    remove?(sessionId: string): void;
+}
+export interface MachineSessionInterruptPort {
+    interrupt(sessionId: string): Promise<boolean>;
+}
+export interface MachineSessionAgentCatalogPort {
+    list(): Promise<ControlAgentSummary[]>;
+}
+export interface MachineSessionPendingMessage {
+    sessionId: string;
+    message: string;
+    createdAt: string;
+    state: "queued" | "outcome_unknown";
+}
+/** Durable one-message admission queue used while a Provider needs setup. */
+export interface MachineSessionPendingMessagePort {
+    put(message: Omit<MachineSessionPendingMessage, "state">): boolean | Promise<boolean>;
+    get(sessionId: string): MachineSessionPendingMessage | undefined | Promise<MachineSessionPendingMessage | undefined>;
+    list(): MachineSessionPendingMessage[] | Promise<MachineSessionPendingMessage[]>;
+    markOutcomeUnknown(sessionId: string): void | Promise<void>;
+    delete(sessionId: string): void | Promise<void>;
+}
+export type MachineSessionMessageOperationState = "prepared" | "injecting" | "injected" | "mirrored" | "outcome_unknown" | "failed_not_started";
+export interface MachineSessionPreparedInput {
+    input: RuntimeUserInput;
+    title: string;
+    operationState?: MachineSessionMessageOperationState;
+}
+/** Target-daemon resource authority. Transfer methods are deliberately chunked
+ * below the 64 KiB Direct Runtime frame; `prepareInput` is the only method that
+ * can turn opaque browser-visible ids into runtime-local file paths. */
+export interface MachineSessionResourcePort {
+    policy(sessionId: string): RemoteRuntimeSessionResourcePolicyResult;
+    beginUpload(input: RemoteRuntimeSessionResourceUploadBeginParams): Promise<RemoteRuntimeSessionResourceUploadBeginResult>;
+    writeUploadChunk(input: RemoteRuntimeSessionResourceUploadChunkParams): Promise<RemoteRuntimeSessionResourceUploadChunkResult>;
+    commitUpload(input: RemoteRuntimeSessionResourceUploadCommitParams): Promise<RemoteRuntimeSessionResourceUploadCommitResult>;
+    getResource(input: RemoteRuntimeSessionResourceGetParams): Promise<RemoteRuntimeSessionResourceGetResult>;
+    readResource(input: RemoteRuntimeSessionResourceReadParams): Promise<RemoteRuntimeSessionResourceReadResult>;
+    deleteResource(input: RemoteRuntimeSessionResourceDeleteParams): Promise<RemoteRuntimeSessionResourceDeleteResult>;
+    prepareInput(sessionId: string, content: UserContentPart[], clientMessageId?: string): Promise<MachineSessionPreparedInput>;
+    markMessageInjecting(sessionId: string, clientMessageId: string): void | Promise<void>;
+    markMessageInjected(sessionId: string, clientMessageId: string): void | Promise<void>;
+    markMessageOutcomeUnknown(sessionId: string, clientMessageId: string, reason: string): void | Promise<void>;
+    markMessageFailedNotStarted(sessionId: string, clientMessageId: string, reason: string): void | Promise<void>;
+    deleteSession(sessionId: string): void | Promise<void>;
+}
+export interface MachineSessionRunnerPort {
+    ensureLiveSession(sessionId: string, options?: {
+        cwd?: string;
+        cols?: number;
+        rows?: number;
+        runtime?: AgentRuntimeId;
+        reasoningEffort?: ReasoningEffort;
+        agentName?: string;
+        agentSpec?: AgentSpec;
+    }): Promise<boolean>;
+    /** Start the Provider TUI pane without waiting for its native thread to bind. */
+    startLiveSession?(sessionId: string, options?: {
+        cwd?: string;
+        cols?: number;
+        rows?: number;
+        runtime?: AgentRuntimeId;
+        reasoningEffort?: ReasoningEffort;
+        agentName?: string;
+        agentSpec?: AgentSpec;
+    }): Promise<boolean>;
+    lastLiveSessionError?(sessionId: string): string | undefined;
+    injectMessage(sessionId: string, input: RuntimeUserInput | string): Promise<InjectOutcome>;
+    stopRunner(sessionId: string): void;
+    resolveInteraction(sessionId: string, interactionId: string, resolution: SessionInteractionResolution): Promise<{
+        disposition: ControlSessionInteractionResolveDisposition;
+    }>;
+    /** Backend-free readiness probe for launch options and direct Provider creation. */
+    getStatus?(options: {
+        runtime: AgentRuntimeId;
+    }): Promise<CodexRuntimeStatus>;
+}
+export interface MachineSessionServicePorts {
+    registry: Pick<SessionRegistry, "create" | "get" | "list" | "setTitle" | "remove">;
+    log: Pick<SessionLogStore, "list" | "listSessions" | "snapshot" | "deleteSession">;
+    events: Pick<SessionBus, "subscribe"> & Partial<Pick<SessionBus, "close">>;
+    runtimeState: MachineSessionRuntimeStatePort;
+    interruption: MachineSessionInterruptPort;
+    /** External Session-owned resources fenced before and finalized after deletion. */
+    lifecycle?: {
+        beforeDelete?(sessionId: string): void | Promise<void>;
+        afterDelete?(sessionId: string): void | Promise<void>;
+    };
+    /** Target-daemon catalog. Exposed only as bounded Session creation options. */
+    agents?: MachineSessionAgentCatalogPort;
+    /** Durable first messages that must not reach a Provider setup prompt. */
+    pendingMessages?: MachineSessionPendingMessagePort;
+    resources?: MachineSessionResourcePort;
+    /** Native Session execution belongs to the target daemon, never the caller. */
+    execution?: {
+        runtime: Pick<ConversationRuntime, "resolveRuntime">;
+        runner: MachineSessionRunnerPort;
+        sessionStore?: Pick<CodexSessionStore, "get">;
+    };
+}
+export interface MachineSessionServiceOptions {
+    /** Maximum summaries returned in one list page. */
+    maxListLimit?: number;
+    /** JSON byte budget for one complete list page. */
+    listPageMaxBytes?: number;
+    /** Maximum items returned in one transcript page. */
+    maxSnapshotItemLimit?: number;
+    /** JSON byte budget for one complete transcript page. */
+    snapshotPageMaxBytes?: number;
+    /** Bound for the current registry/log merge until storage offers keyset paging. */
+    directoryScanLimit?: number;
+    /** Delay between setup-readiness retries for durable pending messages. */
+    pendingMessageRetryMs?: number;
+}
+export type MachineSessionListInput = RemoteRuntimeSessionListParams;
+export interface MachineSessionListPage extends RemoteRuntimeSessionListResult {
+    /** True when the storage-side directory exceeded the bounded merge window. */
+    directoryTruncated: boolean;
+}
+export type MachineSessionSnapshotInput = RemoteRuntimeSessionSnapshotParams;
+export interface MachineSessionSnapshotPage {
+    sessionId: string;
+    /** Canonical daemon-owned items; the Direct adapter projects payloads later. */
+    items: SessionItem[];
+    runtime: ControlSessionRuntimeSnapshot;
+    hasMore: boolean;
+    nextAfterId?: string;
+}
+export type MachineSessionInterruptResult = RemoteRuntimeSessionInterruptResult;
+interface MachineSessionCreateOptions {
+    model?: string;
+    reasoningEffort?: ReasoningEffort;
+    title?: string;
+}
+export type MachineSessionCreateInput = MachineSessionCreateOptions & ({
+    agent: string;
+    provider?: never;
+} | {
+    provider: SessionProviderId;
+    agent?: never;
+});
+export interface MachineSessionCreateResult {
+    sessionId: string;
+}
+export interface MachineSessionMessageResult {
+    ok: true;
+    injected: true;
+}
+export interface MachineSessionMessageInput {
+    message?: string;
+    content?: UserContentPart[];
+    clientMessageId?: string;
+}
+export interface MachineSessionMessageEnqueueResult {
+    ok: true;
+    queued: true;
+}
+export interface MachineSessionTerminalStartResult {
+    ok: true;
+}
+export interface MachineSessionDeleteResult {
+    ok: true;
+}
+export interface MachineSessionInteractionResult {
+    disposition: ControlSessionInteractionResolveDisposition;
+}
+/**
+ * A process-live event tail. `cancel` is idempotent and settles a pending
+ * consumer read even when the underlying bus iterator does not settle its own
+ * pending `next()` on `return()`.
+ */
+export interface MachineSessionWatch extends AsyncIterable<SequencedSessionEvent> {
+    readonly sessionId: string;
+    cancel(): Promise<void>;
+}
+export declare class MachineSessionServiceInputError extends Error {
+    constructor(message: string);
+}
+export type MachineSessionServiceFailureCode = "not_found" | "failed_precondition" | "conflict" | "outcome_unknown";
+/** Expected application failure; adapters decide how to represent it on the wire. */
+export declare class MachineSessionServiceFailure extends Error {
+    readonly code: MachineSessionServiceFailureCode;
+    readonly detail?: string | undefined;
+    constructor(code: MachineSessionServiceFailureCode, message: string, detail?: string | undefined);
+}
+/** Application boundary shared by an in-process Local adapter and Direct RPC. */
+export declare class MachineSessionService {
+    private readonly ports;
+    private readonly maxListLimit;
+    private readonly listPageMaxBytes;
+    private readonly maxSnapshotItemLimit;
+    private readonly snapshotPageMaxBytes;
+    private readonly directoryScanLimit;
+    private readonly pendingMessageRetryMs;
+    private readonly pendingDeliveries;
+    private readonly cancelledPendingDeliveries;
+    constructor(ports: MachineSessionServicePorts, options?: MachineSessionServiceOptions);
+    list(input?: MachineSessionListInput): Promise<MachineSessionListPage>;
+    snapshot(input: MachineSessionSnapshotInput): Promise<MachineSessionSnapshotPage>;
+    /**
+     * Install a live subscriber synchronously, before returning control to an
+     * adapter. The adapter may now acknowledge readiness and request snapshot
+     * pages while buffering this tail, closing the subscribe/snapshot race.
+     */
+    watch(sessionIdInput: string, options?: {
+        signal?: AbortSignal;
+    }): MachineSessionWatch;
+    interrupt(sessionIdInput: string): Promise<MachineSessionInterruptResult>;
+    /** Session-scoped projection of the target daemon's own Agent catalog. */
+    agentOptions(): Promise<{
+        agents: ControlAgentSummary[];
+    }>;
+    /** Target-owned Provider readiness plus the existing Agent preset catalog. */
+    launchOptions(): Promise<RemoteRuntimeSessionLaunchOptionsListResult>;
+    /** Create target-owned Session identity from one Agent preset or direct Provider. */
+    create(input: MachineSessionCreateInput): Promise<MachineSessionCreateResult>;
+    /** Inject one turn through the target daemon's native single-writer runner. */
+    sendMessage(sessionIdInput: string, messageInput: string | MachineSessionMessageInput): Promise<MachineSessionMessageResult>;
+    resourcePolicy(sessionIdInput: string): RemoteRuntimeSessionResourcePolicyResult;
+    beginResourceUpload(input: RemoteRuntimeSessionResourceUploadBeginParams): Promise<RemoteRuntimeSessionResourceUploadBeginResult>;
+    writeResourceUploadChunk(input: RemoteRuntimeSessionResourceUploadChunkParams): Promise<RemoteRuntimeSessionResourceUploadChunkResult>;
+    commitResourceUpload(input: RemoteRuntimeSessionResourceUploadCommitParams): Promise<RemoteRuntimeSessionResourceUploadCommitResult>;
+    getResource(input: RemoteRuntimeSessionResourceGetParams): Promise<RemoteRuntimeSessionResourceGetResult>;
+    readResource(input: RemoteRuntimeSessionResourceReadParams): Promise<RemoteRuntimeSessionResourceReadResult>;
+    deleteResource(input: RemoteRuntimeSessionResourceDeleteParams): Promise<RemoteRuntimeSessionResourceDeleteResult>;
+    /** Persist the first task while login/onboarding owns the Provider TUI. The
+     * delivery worker starts the pane now, waits for a real native thread, then
+     * injects exactly once. `failed` is fenced as outcome_unknown and never retried. */
+    enqueueMessage(sessionIdInput: string, messageInput: string): Promise<MachineSessionMessageEnqueueResult>;
+    /** Explicitly restore the target daemon's live runner without starting a turn. */
+    startTerminal(sessionIdInput: string): Promise<MachineSessionTerminalStartResult>;
+    private ensureLiveSession;
+    private liveSessionRequest;
+    resolveInteraction(sessionIdInput: string, interactionIdInput: string, resolution: SessionInteractionResolution): Promise<MachineSessionInteractionResult>;
+    delete(sessionIdInput: string): Promise<MachineSessionDeleteResult>;
+    private requireAgents;
+    private requireResources;
+    private requireResourceSession;
+    private resumePendingDeliveries;
+    private schedulePendingDelivery;
+    private deliverPendingMessage;
+    private runtimeReadiness;
+    private probeRuntimeReadiness;
+    private requireExecution;
+}
+/** One-line title derived from the first user message; no model call. */
+export declare function synthesizeSessionTitle(message: string, limit?: number): string;
+export {};