@rynx-ai/runtime 0.1.0

package/dist/codex-app-server/ws-channel.js

@@ -0,0 +1,233 @@
+/**
+ * WebSocket {@link RpcChannel} for a codex `app-server --listen ws://IP:PORT`.
+ *
+ * Why a WebSocket and not the default stdio: stdio admits exactly one client
+ * (the process that spawned it), so it cannot be co-driven. omnigent's working
+ * codex-native uses a multi-client transport (ws / uds) so a separate `codex
+ * --remote` TUI can attach to the SAME app-server and resume the SAME thread.
+ * This channel owns that app-server child on a loopback ws port and connects a
+ * client to it; the TUI attaches to {@link WsRpcChannel.url}.
+ *
+ * Framing matches codex (verified from omnigent): one JSON-RPC object per
+ * WebSocket text frame — no newline delimiting. So `send` writes one frame per
+ * message and every inbound frame is one complete JSON object.
+ */
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { WebSocket } from "ws";
+import { createCodexChildEnv } from "../codex-child-env.js";
+/** Reserve a free loopback TCP port (best-effort; racy but fine for local use). */
+async function freeLoopbackPort() {
+    return await new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.on("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            srv.close(() => (port ? resolve(port) : reject(new Error("no port"))));
+        });
+    });
+}
+export class WsRpcChannel {
+    opts;
+    child = null;
+    ws = null;
+    lineCb = null;
+    closeCb = null;
+    closedEmitted = false;
+    readyTimeoutMs;
+    /** The `ws://IP:PORT` the app-server listens on — pass to the TUI's `--remote`. */
+    url = "";
+    constructor(opts) {
+        this.opts = opts;
+        this.readyTimeoutMs = opts.readyTimeoutMs ?? 15_000;
+    }
+    onLine(cb) {
+        this.lineCb = cb;
+    }
+    onClose(cb) {
+        this.closeCb = cb;
+    }
+    isOpen() {
+        return this.ws?.readyState === WebSocket.OPEN;
+    }
+    async start() {
+        const port = await freeLoopbackPort();
+        this.url = `ws://127.0.0.1:${port}`;
+        const args = [...this.opts.baseArgs, "--listen", this.url];
+        this.child = spawn(this.opts.cliPath, args, {
+            stdio: ["ignore", "ignore", "pipe"],
+            env: { ...createCodexChildEnv(process.env), ...(this.opts.extraEnv ?? {}) },
+        });
+        this.child.on("exit", (code, signal) => this.emitClose(code, signal, null));
+        this.child.on("error", (error) => this.emitClose(null, null, error));
+        this.ws = await this.connectWithRetry(this.url);
+        this.ws.on("message", (data) => {
+            // One JSON-RPC object per frame (codex ws framing).
+            this.lineCb?.(data.toString());
+        });
+        this.ws.on("close", (code) => this.emitClose(code ?? null, null, null));
+        this.ws.on("error", (error) => this.emitClose(null, null, error));
+    }
+    send(line) {
+        if (this.ws?.readyState !== WebSocket.OPEN) {
+            throw new Error("codex ws channel is not open");
+        }
+        // Codex expects one JSON object per frame; drop the NDJSON newline.
+        this.ws.send(line.endsWith("\n") ? line.slice(0, -1) : line);
+    }
+    async stop(signal = "SIGTERM") {
+        try {
+            this.ws?.close();
+        }
+        catch {
+            /* already closing */
+        }
+        const child = this.child;
+        if (child) {
+            try {
+                child.kill(signal);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+    emitClose(code, signal, error) {
+        if (this.closedEmitted)
+            return;
+        this.closedEmitted = true;
+        this.closeCb?.({ code, signal, error });
+    }
+    async connectWithRetry(url) {
+        const deadline = Date.now() + this.readyTimeoutMs;
+        let lastError;
+        // The app-server needs a moment to bind; retry the connect until it accepts.
+        // eslint-disable-next-line no-constant-condition
+        while (Date.now() < deadline) {
+            try {
+                return await this.tryConnect(url);
+            }
+            catch (error) {
+                lastError = error;
+                await new Promise((r) => setTimeout(r, 150));
+            }
+        }
+        throw new Error(`codex app-server ws did not become ready at ${url}: ${lastError?.message ?? "timeout"}`);
+    }
+    tryConnect(url) {
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(url);
+            const onOpen = () => {
+                ws.off("error", onError);
+                resolve(ws);
+            };
+            const onError = (error) => {
+                ws.off("open", onOpen);
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* noop */
+                }
+                reject(error);
+            };
+            ws.once("open", onOpen);
+            ws.once("error", onError);
+        });
+    }
+}
+/**
+ * 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 class ExternalWsChannel {
+    url;
+    ws = null;
+    lineCb = null;
+    closeCb = null;
+    closedEmitted = false;
+    readyTimeoutMs;
+    constructor(
+    /** The `ws://IP:PORT` of the already-running app-server to attach to. */
+    url, opts = {}) {
+        this.url = url;
+        this.readyTimeoutMs = opts.readyTimeoutMs ?? 15_000;
+    }
+    onLine(cb) {
+        this.lineCb = cb;
+    }
+    onClose(cb) {
+        this.closeCb = cb;
+    }
+    isOpen() {
+        return this.ws?.readyState === WebSocket.OPEN;
+    }
+    async start() {
+        const deadline = Date.now() + this.readyTimeoutMs;
+        let lastError;
+        while (Date.now() < deadline) {
+            try {
+                this.ws = await this.connect(this.url);
+                break;
+            }
+            catch (error) {
+                lastError = error;
+                await new Promise((r) => setTimeout(r, 150));
+            }
+        }
+        if (!this.ws) {
+            throw new Error(`could not attach to app-server ws ${this.url}: ${lastError?.message ?? "timeout"}`);
+        }
+        this.ws.on("message", (data) => this.lineCb?.(data.toString()));
+        this.ws.on("close", (code) => this.emitClose(code ?? null, null, null));
+        this.ws.on("error", (error) => this.emitClose(null, null, error));
+    }
+    send(line) {
+        if (this.ws?.readyState !== WebSocket.OPEN) {
+            throw new Error("external codex ws channel is not open");
+        }
+        this.ws.send(line.endsWith("\n") ? line.slice(0, -1) : line);
+    }
+    async stop() {
+        try {
+            this.ws?.close();
+        }
+        catch {
+            /* already closing */
+        }
+    }
+    emitClose(code, signal, error) {
+        if (this.closedEmitted)
+            return;
+        this.closedEmitted = true;
+        this.closeCb?.({ code, signal, error });
+    }
+    connect(url) {
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(url);
+            const onOpen = () => {
+                ws.off("error", onError);
+                resolve(ws);
+            };
+            const onError = (error) => {
+                ws.off("open", onOpen);
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* noop */
+                }
+                reject(error);
+            };
+            ws.once("open", onOpen);
+            ws.once("error", onError);
+        });
+    }
+}

package/dist/codex-child-env.d.ts

@@ -0,0 +1 @@
+export declare function createCodexChildEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/codex-child-env.js

@@ -0,0 +1,27 @@
+const CODEX_CHILD_ENV_ALLOWLIST = [
+    "PATH",
+    "HOME",
+    "USER",
+    "SHELL",
+    "TMPDIR",
+    "CODEX_HOME",
+    "TRAE_HOME",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "NO_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "all_proxy",
+    "no_proxy",
+];
+export function createCodexChildEnv(env) {
+    const childEnv = {};
+    for (const key of CODEX_CHILD_ENV_ALLOWLIST) {
+        const value = env[key];
+        if (typeof value === "string" && value.length > 0) {
+            childEnv[key] = value;
+        }
+    }
+    return childEnv;
+}

package/dist/codex-home.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The deterministic private CODEX_HOME path for a rynx session. PER-SESSION
+ * (uid-scoped + `sha256(sessionId)[:32]`), mirroring omnigent's per-session
+ * `bridge_dir/codex-home` and rynx's own `claudeBridgeDir`. Pure — computes the
+ * path without touching disk, so the daemon (rollout-synth) and the runner child
+ * (app-server) both locate the SAME session's home from `sessionId` alone.
+ */
+export declare function codexHomePath(sessionId: string): string;
+/** The OLD uid-scoped shared home (pre per-session). Kept ONLY for back-compat
+ *  resume fallback — a session's rollout may still live under here. */
+export declare function legacyCodexHomePath(): string;
+/**
+ * Prepare a private CODEX_HOME that inherits the user's login (symlinked
+ * `auth.json`) and settings (copied `config.toml`) but NOT the real home's pending
+ * update / first-run (NUX) state — so a co-driven `codex` app-server + `--remote`
+ * TUI never block on an "Update now / Press enter to continue" prompt (which would
+ * wedge terminal injection). Ports omnigent's `_CODEX_HOME_SYMLINK_FILES` /
+ * `_CODEX_HOME_COPY_FILES`.
+ *
+ * PER-SESSION: one private home per rynx session (matching omnigent), so concurrent
+ * agents never share a `skills/` dir. Idempotent: the symlink/copy are refreshed each
+ * call so a re-login/config change propagates. Returns the private home dir.
+ */
+export declare function prepareCodexHome(sessionId: string, realHome?: string): string;
+/**
+ * Link a resolved skill set into `<codexHome>/skills/<name>/` so the native Codex
+ * discovers them at `$CODEX_HOME/skills/` — the SAME filesystem mechanism omnigent
+ * uses (`populate_codex_skills_from_bundle` → `_populate_codex_skills`), NOT a
+ * `<skills_instructions>` block injected into the prompt. Codex's app-server
+ * watches this dir and re-scans on change, so a live `codex --remote` TUI — whose
+ * thread rynx never creates, so it can't carry `threadStart.developerInstructions`
+ * — still sees the agent's skills.
+ *
+ * Each skill is a symlink to its source dir; a filesystem without symlink support
+ * falls back to a recursive copy (matches omnigent's fallback).
+ *
+ * omnigent boots a fresh per-session CODEX_HOME, so it only ever links into an
+ * empty dir. rynx shares ONE private home per runtime (see {@link prepareCodexHome}),
+ * so this CONVERGES the dir to `skills`: it links the missing ones and removes
+ * entries no longer selected, honouring the agent spec's gating. (Concurrent
+ * sessions of DIFFERENT agents on one runtime share this dir — the same shared-home
+ * tradeoff already accepted for auth/config.)
+ */
+export declare function populateCodexSkills(codexHome: string, skills: {
+    name: string;
+    dir: string;
+}[]): void;

package/dist/codex-home.js

@@ -0,0 +1,135 @@
+import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, rmSync, symlinkSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+/** Inherit the user's LIVE login by symlink (stays in sync). */
+const SYMLINK_FILES = ["auth.json"];
+/** Inherit the user's settings by snapshot copy (not the mutable NUX/update state). */
+const COPY_FILES = ["config.toml"];
+/** The user's real CODEX_HOME (env override, else `~/.codex`). */
+function realCodexHome() {
+    return process.env.CODEX_HOME?.trim() || join(homedir(), ".codex");
+}
+/** Uid-scoped root so other users on a shared host can't read the tree. */
+function rynxUidRoot() {
+    const uid = typeof process.getuid === "function" ? process.getuid() : "nouid";
+    return join(tmpdir(), `rynx-${uid}`);
+}
+/**
+ * The deterministic private CODEX_HOME path for a rynx session. PER-SESSION
+ * (uid-scoped + `sha256(sessionId)[:32]`), mirroring omnigent's per-session
+ * `bridge_dir/codex-home` and rynx's own `claudeBridgeDir`. Pure — computes the
+ * path without touching disk, so the daemon (rollout-synth) and the runner child
+ * (app-server) both locate the SAME session's home from `sessionId` alone.
+ */
+export function codexHomePath(sessionId) {
+    const digest = createHash("sha256").update(sessionId).digest("hex").slice(0, 32);
+    return join(rynxUidRoot(), "codex-native", digest, "codex-home");
+}
+/** The OLD uid-scoped shared home (pre per-session). Kept ONLY for back-compat
+ *  resume fallback — a session's rollout may still live under here. */
+export function legacyCodexHomePath() {
+    return join(rynxUidRoot(), "codex-home");
+}
+/**
+ * Prepare a private CODEX_HOME that inherits the user's login (symlinked
+ * `auth.json`) and settings (copied `config.toml`) but NOT the real home's pending
+ * update / first-run (NUX) state — so a co-driven `codex` app-server + `--remote`
+ * TUI never block on an "Update now / Press enter to continue" prompt (which would
+ * wedge terminal injection). Ports omnigent's `_CODEX_HOME_SYMLINK_FILES` /
+ * `_CODEX_HOME_COPY_FILES`.
+ *
+ * PER-SESSION: one private home per rynx session (matching omnigent), so concurrent
+ * agents never share a `skills/` dir. Idempotent: the symlink/copy are refreshed each
+ * call so a re-login/config change propagates. Returns the private home dir.
+ */
+export function prepareCodexHome(sessionId, realHome = realCodexHome()) {
+    const dir = codexHomePath(sessionId);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    for (const name of SYMLINK_FILES) {
+        const src = join(realHome, name);
+        const dst = join(dir, name);
+        try {
+            rmSync(dst, { force: true });
+        }
+        catch {
+            // absent — fine
+        }
+        if (existsSync(src)) {
+            try {
+                symlinkSync(src, dst);
+            }
+            catch {
+                // best-effort: a missing link just means codex re-prompts login (not worse than today)
+            }
+        }
+    }
+    for (const name of COPY_FILES) {
+        const src = join(realHome, name);
+        if (existsSync(src)) {
+            try {
+                copyFileSync(src, join(dir, name));
+            }
+            catch {
+                // best-effort
+            }
+        }
+    }
+    return dir;
+}
+/**
+ * Link a resolved skill set into `<codexHome>/skills/<name>/` so the native Codex
+ * discovers them at `$CODEX_HOME/skills/` — the SAME filesystem mechanism omnigent
+ * uses (`populate_codex_skills_from_bundle` → `_populate_codex_skills`), NOT a
+ * `<skills_instructions>` block injected into the prompt. Codex's app-server
+ * watches this dir and re-scans on change, so a live `codex --remote` TUI — whose
+ * thread rynx never creates, so it can't carry `threadStart.developerInstructions`
+ * — still sees the agent's skills.
+ *
+ * Each skill is a symlink to its source dir; a filesystem without symlink support
+ * falls back to a recursive copy (matches omnigent's fallback).
+ *
+ * omnigent boots a fresh per-session CODEX_HOME, so it only ever links into an
+ * empty dir. rynx shares ONE private home per runtime (see {@link prepareCodexHome}),
+ * so this CONVERGES the dir to `skills`: it links the missing ones and removes
+ * entries no longer selected, honouring the agent spec's gating. (Concurrent
+ * sessions of DIFFERENT agents on one runtime share this dir — the same shared-home
+ * tradeoff already accepted for auth/config.)
+ */
+export function populateCodexSkills(codexHome, skills) {
+    const skillsDir = join(codexHome, "skills");
+    const want = new Map(skills.map((s) => [s.name, s.dir]));
+    // Converge: drop entries no longer selected (shared-home adaptation; omnigent's
+    // per-session home never needs this). `.system` holds codex's own embedded system
+    // skills (the app-server installs them into `$CODEX_HOME/skills/.system`) — never
+    // rynx-managed, so leave it untouched; only converge the entries we linked.
+    if (existsSync(skillsDir)) {
+        for (const name of readdirSync(skillsDir)) {
+            if (name === ".system")
+                continue;
+            if (!want.has(name))
+                rmSync(join(skillsDir, name), { recursive: true, force: true });
+        }
+    }
+    if (want.size === 0)
+        return;
+    mkdirSync(skillsDir, { recursive: true });
+    for (const [name, src] of want) {
+        const link = join(skillsDir, name);
+        if (existsSync(link))
+            continue; // already linked (a skill's dir for a name is stable)
+        try {
+            symlinkSync(src, link);
+        }
+        catch {
+            // no symlink support (e.g. some Windows configs) → copy. A skill-link failure
+            // must not break the terminal launch, so swallow a copy failure too.
+            try {
+                cpSync(src, link, { recursive: true });
+            }
+            catch {
+                // best-effort
+            }
+        }
+    }
+}

package/dist/codex-session-store.d.ts

@@ -0,0 +1,42 @@
+import { type AgentRuntimeId } from "@rynx-ai/core";
+import type { AppConfig } from "@rynx-ai/core";
+export interface CodexSessionRecord {
+    localThreadId: string;
+    codexSessionId: string;
+    cwd: string;
+    model: string;
+    /** Runtime this thread is bound to. Legacy records backfill to `codex`. */
+    runtime: AgentRuntimeId;
+    /** Declarative agent spec name bound to this thread, if any. */
+    agent?: string;
+    /** The source rynx session this one was derived from (claude `/fork`). */
+    parentSessionId?: string;
+    updatedAt: string;
+}
+export interface CodexSessionStore {
+    readonly filePath: string;
+    get(localThreadId: string): Promise<CodexSessionRecord | null>;
+    set(record: CodexSessionRecord): Promise<void>;
+    delete(localThreadId: string): Promise<void>;
+    isWritable(): Promise<boolean>;
+    /** All stored records (newest-first not guaranteed). Used by the CLI mirror
+     *  to enumerate conversations bound to a Codex thread. */
+    listAll(): Promise<CodexSessionRecord[]>;
+    /** Reverse lookup by Codex thread id (the rollout-file UUID). */
+    findByCodexSessionId(codexSessionId: string): Promise<CodexSessionRecord | null>;
+}
+export declare class FileCodexSessionStore implements CodexSessionStore {
+    readonly filePath: string;
+    private tail;
+    constructor(filePath: string);
+    get(localThreadId: string): Promise<CodexSessionRecord | null>;
+    set(record: CodexSessionRecord): Promise<void>;
+    delete(localThreadId: string): Promise<void>;
+    listAll(): Promise<CodexSessionRecord[]>;
+    findByCodexSessionId(codexSessionId: string): Promise<CodexSessionRecord | null>;
+    isWritable(): Promise<boolean>;
+    private readAll;
+    private writeAll;
+    private runExclusive;
+}
+export declare function resolveCodexSessionStorePath(config: AppConfig): string;

package/dist/codex-session-store.js

@@ -0,0 +1,126 @@
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { access, mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { normalizeRuntimeId } from "@rynx-ai/core";
+export class FileCodexSessionStore {
+    filePath;
+    tail = Promise.resolve();
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async get(localThreadId) {
+        const data = await this.readAll();
+        return data.sessions?.[localThreadId] ?? null;
+    }
+    async set(record) {
+        await this.runExclusive(async () => {
+            const data = await this.readAll();
+            data.sessions ??= {};
+            data.sessions[record.localThreadId] = record;
+            await this.writeAll(data);
+        });
+    }
+    async delete(localThreadId) {
+        await this.runExclusive(async () => {
+            const data = await this.readAll();
+            if (!data.sessions?.[localThreadId]) {
+                return;
+            }
+            delete data.sessions[localThreadId];
+            await this.writeAll(data);
+        });
+    }
+    async listAll() {
+        const data = await this.readAll();
+        return Object.values(data.sessions ?? {});
+    }
+    async findByCodexSessionId(codexSessionId) {
+        const data = await this.readAll();
+        for (const record of Object.values(data.sessions ?? {})) {
+            if (record.codexSessionId === codexSessionId) {
+                return record;
+            }
+        }
+        return null;
+    }
+    async isWritable() {
+        try {
+            await mkdir(path.dirname(this.filePath), { recursive: true });
+            if (await pathExists(this.filePath)) {
+                await access(this.filePath, fsConstants.R_OK | fsConstants.W_OK);
+            }
+            else {
+                await access(path.dirname(this.filePath), fsConstants.R_OK | fsConstants.W_OK);
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async readAll() {
+        try {
+            const content = await readFile(this.filePath, "utf8");
+            const parsed = JSON.parse(content);
+            if (!parsed || typeof parsed !== "object") {
+                return {};
+            }
+            // Backfill the runtime on legacy records written before multi-runtime
+            // support (default to codex), and normalize the renamed `traecli` runtime
+            // to `traex` so routing and thread-binding checks stay consistent.
+            if (parsed.sessions) {
+                for (const record of Object.values(parsed.sessions)) {
+                    if (record) {
+                        record.runtime = normalizeRuntimeId(record.runtime) ?? "codex";
+                    }
+                }
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (isMissingFileError(error)) {
+                return {};
+            }
+            throw error;
+        }
+    }
+    async writeAll(data) {
+        await mkdir(path.dirname(this.filePath), { recursive: true });
+        const tempPath = path.join(path.dirname(this.filePath), `.${path.basename(this.filePath)}.${process.pid}.${randomUUID()}.tmp`);
+        await writeFile(tempPath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+        await rename(tempPath, this.filePath);
+    }
+    async runExclusive(task) {
+        const previous = this.tail;
+        let release;
+        this.tail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous.catch(() => undefined);
+        try {
+            return await task();
+        }
+        finally {
+            release();
+        }
+    }
+}
+export function resolveCodexSessionStorePath(config) {
+    return path.resolve(config.AGENT_SESSION_STORE_PATH ?? path.join(process.cwd(), ".codex-proxy", "sessions.json"));
+}
+async function pathExists(targetPath) {
+    try {
+        await stat(targetPath);
+        return true;
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+function isMissingFileError(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}