@rynx-ai/runtime 0.1.0

package/dist/codex-app-server/transport.d.ts

@@ -0,0 +1,139 @@
+import { EventEmitter } from "node:events";
+import type { SandboxMode } from "./protocol.js";
+export declare function buildAppServerSpawnArgs(sandboxMode: SandboxMode, listen?: string): string[];
+/** app-server args WITHOUT `--listen` — for a channel that appends its own
+ *  transport endpoint (e.g. {@link import("./ws-channel.js").WsRpcChannel}). */
+export declare function buildAppServerBaseArgs(sandboxMode: SandboxMode): string[];
+export interface TransportLogger {
+    log(entry: Record<string, unknown>): void;
+}
+export interface CodexAppServerProcess {
+    readonly stdin: NodeJS.WritableStream;
+    readonly stdout: NodeJS.ReadableStream;
+    readonly stderr: NodeJS.ReadableStream | null;
+    kill(signal?: NodeJS.Signals | number): boolean;
+    on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+    on(event: "error", listener: (error: Error) => void): void;
+}
+export interface CodexAppServerProcessSpawner {
+    spawn(): CodexAppServerProcess;
+}
+/**
+ * A line-delimited JSON-RPC byte channel. Abstracts the transport's I/O so the
+ * same framing/dispatch drives either the default stdio child (single client)
+ * or a WebSocket connection to an `app-server --listen ws://…` (multi-client,
+ * required for the codex-native TUI to co-drive the same thread — see
+ * {@link import("./ws-channel.js").WsRpcChannel}).
+ */
+export interface RpcChannel {
+    /** Establish the channel (connect / await readiness). */
+    start(): Promise<void>;
+    /** Write one framed message (already newline-terminated). */
+    send(line: string): void;
+    /** Register the inbound-line handler (one framed message per call). */
+    onLine(cb: (line: string) => void): void;
+    /** Register the close/error handler. */
+    onClose(cb: (info: {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+        error: Error | null;
+    }) => void): void;
+    stop(signal?: NodeJS.Signals): Promise<void>;
+    isOpen(): boolean;
+}
+export declare class DefaultCodexAppServerProcessSpawner implements CodexAppServerProcessSpawner {
+    private readonly cliPath;
+    private readonly args;
+    private readonly extraEnv;
+    constructor({ cliPath, args, extraEnv, }: {
+        cliPath: string;
+        args?: string[];
+        /**
+         * Extra env merged on top of the allowlisted child env (see
+         * {@link createCodexChildEnv}). Used to inject a per-agent retry budget
+         * (`OPENAI_MAX_RETRIES` / `OPENAI_TIMEOUT`) into a dedicated app-server.
+         * Merged after the allowlist, so it is intentionally exempt from it — only
+         * the specific keys the caller computed are added, never arbitrary env.
+         */
+        extraEnv?: Record<string, string>;
+    });
+    spawn(): CodexAppServerProcess;
+}
+export declare class CodexTransportError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(message: string, code?: number, data?: unknown);
+}
+export type ServerRequestHandler = (method: string, params: unknown) => Promise<unknown> | unknown;
+export type ServerNotificationHandler = (method: string, params: unknown) => void;
+export interface CodexAppServerTransportOptions {
+    /** Default stdio transport: spawns `app-server --listen stdio://`. Mutually
+     *  exclusive with {@link channel}; provide exactly one. */
+    spawner?: CodexAppServerProcessSpawner;
+    /** Alternate I/O channel (e.g. a WebSocket to a multi-client app-server). */
+    channel?: RpcChannel;
+    logger?: TransportLogger;
+    /**
+     * Called for every server-initiated request. Must return the JSON result.
+     * Returning a rejected promise produces a JSON-RPC error response.
+     */
+    onServerRequest?: ServerRequestHandler;
+    /**
+     * Called for every server notification. Errors thrown are logged but not
+     * propagated back to the server.
+     */
+    onNotification?: ServerNotificationHandler;
+}
+interface TransportEvents {
+    exit: [code: number | null, signal: NodeJS.Signals | null];
+    error: [error: Error];
+}
+/**
+ * Wraps the Codex `app-server` subprocess and exposes a typed JSON-RPC API
+ * over its stdio. Frames are line-delimited NDJSON (no Content-Length
+ * headers — matches what the binary emits today).
+ *
+ * Lifecycle:
+ *   - `ensureStarted()` spawns the child once and resolves when stdin is
+ *     usable. Subsequent calls reuse the running child.
+ *   - `sendRequest(method, params)` returns a typed Promise. Pending requests
+ *     are rejected if the child exits before responding.
+ *   - The child exiting unexpectedly marks the transport as down; the next
+ *     `ensureStarted()` will respawn. Callers that hold long-running
+ *     subscriptions should listen for the `exit` event.
+ */
+export declare class CodexAppServerTransport extends EventEmitter {
+    private readonly spawner;
+    private readonly channel;
+    private channelWired;
+    private readonly logger;
+    private readonly onServerRequest?;
+    private readonly onNotification?;
+    private child;
+    private rl;
+    private stderrRl;
+    private nextId;
+    private readonly pending;
+    private startPromise;
+    private exited;
+    constructor({ spawner, channel, logger, onServerRequest, onNotification, }: CodexAppServerTransportOptions);
+    emit<K extends keyof TransportEvents>(event: K, ...args: TransportEvents[K]): boolean;
+    on<K extends keyof TransportEvents>(event: K, listener: (...args: TransportEvents[K]) => void): this;
+    off<K extends keyof TransportEvents>(event: K, listener: (...args: TransportEvents[K]) => void): this;
+    isRunning(): boolean;
+    ensureStarted(): Promise<void>;
+    sendRequest<TResult = unknown>(method: string, params?: unknown): Promise<TResult>;
+    sendNotification(method: string, params?: unknown): void;
+    stop(signal?: NodeJS.Signals): Promise<void>;
+    private startTransport;
+    private startChild;
+    private handleExit;
+    private writeLine;
+    private handleLine;
+    private handleResponse;
+    private handleErrorEnvelope;
+    private handleServerRequest;
+    private respondToServerRequest;
+    private handleNotification;
+}
+export {};

package/dist/codex-app-server/transport.js

@@ -0,0 +1,422 @@
+import { spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import readline from "node:readline";
+import { createCodexChildEnv } from "../codex-child-env.js";
+const DEFAULT_SPAWN_ARGS = ["app-server", "--listen", "stdio://"];
+/**
+ * Spawn args for `<cli> app-server`, including a codex config override that
+ * opens the sandbox network when needed.
+ *
+ * codex's `workspace-write` sandbox blocks network access by default, and the
+ * app-server's per-thread sandbox params do not reliably re-enable it, so we
+ * pass codex's NATIVE config override (`-c sandbox_workspace_write.network_access=true`)
+ * on the app-server process itself. This lets sandboxed model commands — e.g.
+ * skills calling internal HTTP APIs — resolve DNS and reach the network.
+ * `read-only` and `danger-full-access` are left untouched (the former has no
+ * network by design; the latter is already unrestricted).
+ */
+function appServerConfigOverrides(sandboxMode) {
+    return sandboxMode === "workspace-write"
+        ? ["-c", "sandbox_workspace_write.network_access=true"]
+        : [];
+}
+export function buildAppServerSpawnArgs(sandboxMode, listen = "stdio://") {
+    return [...appServerConfigOverrides(sandboxMode), "app-server", "--listen", listen];
+}
+/** app-server args WITHOUT `--listen` — for a channel that appends its own
+ *  transport endpoint (e.g. {@link import("./ws-channel.js").WsRpcChannel}). */
+export function buildAppServerBaseArgs(sandboxMode) {
+    return [...appServerConfigOverrides(sandboxMode), "app-server"];
+}
+const defaultLogger = {
+    log(entry) {
+        console.log(JSON.stringify({
+            level: "info",
+            type: "codex_app_server",
+            ...entry,
+        }));
+    },
+};
+export class DefaultCodexAppServerProcessSpawner {
+    cliPath;
+    args;
+    extraEnv;
+    constructor({ cliPath, args = DEFAULT_SPAWN_ARGS, extraEnv = {}, }) {
+        this.cliPath = cliPath;
+        this.args = args;
+        this.extraEnv = extraEnv;
+    }
+    spawn() {
+        const child = spawn(this.cliPath, this.args, {
+            stdio: ["pipe", "pipe", "pipe"],
+            env: { ...createCodexChildEnv(process.env), ...this.extraEnv },
+        });
+        if (!child.stdin || !child.stdout) {
+            throw new Error("Codex app-server child process is missing stdio handles");
+        }
+        return child;
+    }
+}
+export class CodexTransportError extends Error {
+    code;
+    data;
+    constructor(message, code = -32000, data) {
+        super(message);
+        this.name = "CodexTransportError";
+        this.code = code;
+        this.data = data;
+    }
+}
+/**
+ * Wraps the Codex `app-server` subprocess and exposes a typed JSON-RPC API
+ * over its stdio. Frames are line-delimited NDJSON (no Content-Length
+ * headers — matches what the binary emits today).
+ *
+ * Lifecycle:
+ *   - `ensureStarted()` spawns the child once and resolves when stdin is
+ *     usable. Subsequent calls reuse the running child.
+ *   - `sendRequest(method, params)` returns a typed Promise. Pending requests
+ *     are rejected if the child exits before responding.
+ *   - The child exiting unexpectedly marks the transport as down; the next
+ *     `ensureStarted()` will respawn. Callers that hold long-running
+ *     subscriptions should listen for the `exit` event.
+ */
+export class CodexAppServerTransport extends EventEmitter {
+    spawner;
+    channel;
+    channelWired = false;
+    logger;
+    onServerRequest;
+    onNotification;
+    child = null;
+    rl = null;
+    stderrRl = null;
+    nextId = 1;
+    pending = new Map();
+    startPromise = null;
+    exited = false;
+    constructor({ spawner, channel, logger = defaultLogger, onServerRequest, onNotification, }) {
+        super();
+        if (!spawner && !channel) {
+            throw new Error("CodexAppServerTransport requires a spawner or a channel");
+        }
+        this.spawner = spawner ?? null;
+        this.channel = channel ?? null;
+        this.logger = logger;
+        this.onServerRequest = onServerRequest;
+        this.onNotification = onNotification;
+    }
+    emit(event, ...args) {
+        return super.emit(event, ...args);
+    }
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    off(event, listener) {
+        return super.off(event, listener);
+    }
+    isRunning() {
+        if (this.channel) {
+            return this.channel.isOpen() && !this.exited;
+        }
+        return Boolean(this.child) && !this.exited;
+    }
+    async ensureStarted() {
+        if (this.isRunning()) {
+            return;
+        }
+        if (this.startPromise) {
+            await this.startPromise;
+            return;
+        }
+        const startPromise = (async () => {
+            await this.startTransport();
+        })();
+        this.startPromise = startPromise;
+        try {
+            await startPromise;
+        }
+        finally {
+            if (this.startPromise === startPromise) {
+                this.startPromise = null;
+            }
+        }
+    }
+    async sendRequest(method, params) {
+        await this.ensureStarted();
+        const id = this.nextId++;
+        return await new Promise((resolve, reject) => {
+            this.pending.set(id, {
+                resolve: resolve,
+                reject,
+                method,
+            });
+            const envelope = {
+                jsonrpc: "2.0",
+                id,
+                method,
+                ...(params === undefined ? {} : { params }),
+            };
+            try {
+                this.writeLine(envelope);
+            }
+            catch (error) {
+                this.pending.delete(id);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    sendNotification(method, params) {
+        const envelope = {
+            jsonrpc: "2.0",
+            method,
+            ...(params === undefined ? {} : { params }),
+        };
+        this.writeLine(envelope);
+    }
+    async stop(signal = "SIGTERM") {
+        if (this.channel) {
+            this.exited = true;
+            await this.channel.stop(signal);
+            return;
+        }
+        const child = this.child;
+        if (!child) {
+            return;
+        }
+        try {
+            child.kill(signal);
+        }
+        catch (error) {
+            this.logger.log({
+                event: "transport.kill_failed",
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async startTransport() {
+        if (this.channel) {
+            if (!this.channelWired) {
+                this.channel.onLine((line) => this.handleLine(line));
+                this.channel.onClose(({ code, signal, error }) => this.handleExit(code, signal, error));
+                this.channelWired = true;
+            }
+            await this.channel.start();
+            this.exited = false;
+            return;
+        }
+        this.startChild();
+    }
+    startChild() {
+        if (!this.spawner) {
+            throw new CodexTransportError("Codex app-server transport has no stdio spawner");
+        }
+        const child = this.spawner.spawn();
+        this.child = child;
+        this.exited = false;
+        const rl = readline.createInterface({
+            input: child.stdout,
+            crlfDelay: Infinity,
+        });
+        rl.on("line", (line) => {
+            this.handleLine(line);
+        });
+        if (child.stderr) {
+            const stderrRl = readline.createInterface({
+                input: child.stderr,
+                crlfDelay: Infinity,
+            });
+            stderrRl.on("line", (line) => {
+                this.logger.log({ event: "transport.stderr", line });
+            });
+            this.stderrRl = stderrRl;
+        }
+        child.on("error", (error) => {
+            this.logger.log({
+                event: "transport.error",
+                error: error.message,
+            });
+            this.emit("error", error);
+            this.handleExit(null, null, error);
+        });
+        child.on("exit", (code, signal) => {
+            this.handleExit(code, signal, null);
+        });
+        this.rl = rl;
+    }
+    handleExit(code, signal, error) {
+        if (this.exited) {
+            return;
+        }
+        this.exited = true;
+        this.rl?.close();
+        this.rl = null;
+        this.stderrRl?.close();
+        this.stderrRl = null;
+        this.child = null;
+        const reason = error?.message ??
+            `Codex app-server exited (code=${code ?? "null"}, signal=${signal ?? "null"})`;
+        for (const [id, pending] of this.pending) {
+            pending.reject(new CodexTransportError(reason));
+            this.pending.delete(id);
+        }
+        this.logger.log({
+            event: "transport.exited",
+            code,
+            signal,
+            error: error?.message,
+        });
+        this.emit("exit", code, signal);
+    }
+    writeLine(envelope) {
+        const line = `${JSON.stringify(envelope)}\n`;
+        if (this.channel) {
+            if (this.exited) {
+                throw new CodexTransportError("Codex app-server is not running");
+            }
+            this.channel.send(line);
+            return;
+        }
+        const child = this.child;
+        if (!child || this.exited) {
+            throw new CodexTransportError("Codex app-server is not running");
+        }
+        const ok = child.stdin.write(line);
+        if (!ok) {
+            // Don't block — back-pressure on stdin is unlikely with line-sized
+            // messages, but we surface it as a log entry if it ever shows up.
+            this.logger.log({ event: "transport.stdin_backpressure" });
+        }
+    }
+    handleLine(line) {
+        if (!line.trim()) {
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (error) {
+            this.logger.log({
+                event: "transport.invalid_json",
+                line,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return;
+        }
+        if (isSuccessEnvelope(parsed)) {
+            this.handleResponse(parsed);
+            return;
+        }
+        if (isErrorEnvelope(parsed)) {
+            this.handleErrorEnvelope(parsed);
+            return;
+        }
+        if (isRequestEnvelope(parsed)) {
+            void this.handleServerRequest(parsed);
+            return;
+        }
+        if (isNotificationEnvelope(parsed)) {
+            this.handleNotification(parsed);
+            return;
+        }
+        this.logger.log({
+            event: "transport.unknown_envelope",
+            payload: parsed,
+        });
+    }
+    handleResponse(envelope) {
+        const pending = this.pending.get(envelope.id);
+        if (!pending) {
+            this.logger.log({
+                event: "transport.response_without_pending",
+                id: envelope.id,
+            });
+            return;
+        }
+        this.pending.delete(envelope.id);
+        pending.resolve(envelope.result);
+    }
+    handleErrorEnvelope(envelope) {
+        const pending = this.pending.get(envelope.id);
+        if (!pending) {
+            this.logger.log({
+                event: "transport.error_without_pending",
+                id: envelope.id,
+                error: envelope.error,
+            });
+            return;
+        }
+        this.pending.delete(envelope.id);
+        pending.reject(new CodexTransportError(envelope.error?.message ?? "Codex app-server returned an error", envelope.error?.code, envelope.error?.data));
+    }
+    async handleServerRequest(envelope) {
+        if (!this.onServerRequest) {
+            this.respondToServerRequest(envelope.id, undefined, {
+                code: -32601,
+                message: `No handler registered for ${envelope.method}`,
+            });
+            return;
+        }
+        try {
+            const result = await this.onServerRequest(envelope.method, envelope.params);
+            this.respondToServerRequest(envelope.id, result, null);
+        }
+        catch (error) {
+            this.respondToServerRequest(envelope.id, undefined, {
+                code: -32000,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    respondToServerRequest(id, result, error) {
+        const envelope = error
+            ? { jsonrpc: "2.0", id, error }
+            : { jsonrpc: "2.0", id, result };
+        try {
+            this.writeLine(envelope);
+        }
+        catch (writeError) {
+            this.logger.log({
+                event: "transport.server_request_write_failed",
+                error: writeError instanceof Error ? writeError.message : String(writeError),
+            });
+        }
+    }
+    handleNotification(envelope) {
+        if (!this.onNotification) {
+            return;
+        }
+        try {
+            this.onNotification(envelope.method, envelope.params);
+        }
+        catch (error) {
+            this.logger.log({
+                event: "transport.notification_handler_failed",
+                method: envelope.method,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}
+function isSuccessEnvelope(value) {
+    return (isObject(value) &&
+        "id" in value &&
+        "result" in value &&
+        !("method" in value));
+}
+function isErrorEnvelope(value) {
+    return (isObject(value) &&
+        "id" in value &&
+        "error" in value &&
+        !("method" in value));
+}
+function isRequestEnvelope(value) {
+    return isObject(value) && "id" in value && "method" in value;
+}
+function isNotificationEnvelope(value) {
+    return isObject(value) && "method" in value && !("id" in value);
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === "object";
+}

package/dist/codex-app-server/ws-channel.d.ts

@@ -0,0 +1,72 @@
+import type { RpcChannel, TransportLogger } from "./transport.js";
+export interface WsRpcChannelOptions {
+    cliPath: string;
+    /** app-server args WITHOUT `--listen` (the channel appends `--listen ws://…`). */
+    baseArgs: string[];
+    /** Extra env merged over the allowlisted codex child env (retry budget etc.). */
+    extraEnv?: Record<string, string>;
+    logger?: TransportLogger;
+    /** Ms to wait for the app-server to accept a connection. */
+    readyTimeoutMs?: number;
+}
+export declare class WsRpcChannel implements RpcChannel {
+    private readonly opts;
+    private child;
+    private ws;
+    private lineCb;
+    private closeCb;
+    private closedEmitted;
+    private readonly readyTimeoutMs;
+    /** The `ws://IP:PORT` the app-server listens on — pass to the TUI's `--remote`. */
+    url: string;
+    constructor(opts: WsRpcChannelOptions);
+    onLine(cb: (line: string) => void): void;
+    onClose(cb: (info: {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+        error: Error | null;
+    }) => void): void;
+    isOpen(): boolean;
+    start(): Promise<void>;
+    send(line: string): void;
+    stop(signal?: NodeJS.Signals): Promise<void>;
+    private emitClose;
+    private connectWithRetry;
+    private tryConnect;
+}
+/**
+ * Connect-only {@link RpcChannel}: attaches an ADDITIONAL client to an app-server
+ * someone else already started (a {@link WsRpcChannel}'s `url`) — no spawn. This
+ * is how rynx runs omnigent's multi-connection codex-native model: the backend
+ * client owns the app-server + drives injection, while a SEPARATE forwarder
+ * connection `thread/resume`s the same thread to subscribe to its item/turn
+ * notifications (verified: codex delivers a thread's items to every connection
+ * subscribed to it, so the forwarder connection sees turns started by the TUI,
+ * the backend inject client, and anyone else).
+ */
+export declare class ExternalWsChannel implements RpcChannel {
+    /** The `ws://IP:PORT` of the already-running app-server to attach to. */
+    readonly url: string;
+    private ws;
+    private lineCb;
+    private closeCb;
+    private closedEmitted;
+    private readonly readyTimeoutMs;
+    constructor(
+    /** The `ws://IP:PORT` of the already-running app-server to attach to. */
+    url: string, opts?: {
+        readyTimeoutMs?: number;
+    });
+    onLine(cb: (line: string) => void): void;
+    onClose(cb: (info: {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+        error: Error | null;
+    }) => void): void;
+    isOpen(): boolean;
+    start(): Promise<void>;
+    send(line: string): void;
+    stop(): Promise<void>;
+    private emitClose;
+    private connect;
+}