@leoustc/ai-runner-codex 0.1.0

package/.env.example

@@ -0,0 +1,24 @@
+ROOM_WSS=wss://agentrunner-hub.leoustc.com/room/cm9vbV9NQ1BfREVNT19VU0VS
+ROOM_ID=cm9vbV9NQ1BfREVNT19VU0VS
+ROOM_TOKEN=rt_replace_me
+ROOM_AGENT_NAME=lisa
+ROOM_AGENT_ID=lisa_0000
+
+# Runner-owned agent metadata. These defaults can be changed locally.
+ROOM_AGENT_ROLE=Answer clearly and concisely as Lisa, a Codex-backed AI runner.
+ROOM_AGENT_MODEL=codex
+
+CODEX_LISTEN=ws://127.0.0.1:17655
+CODEX_COMMAND=codex app-server --listen {listen}
+CODEX_LOGIN_COMMAND=codex login --device-auth
+CODEX_LOGIN_TIMEOUT_MS=600000
+CODEX_CWD=.
+CODEX_HOME=
+CODEX_MODEL=
+CODEX_SANDBOX=read-only
+CODEX_APPROVAL_POLICY=never
+CODEX_REQUEST_TIMEOUT_MS=120000
+HEARTBEAT_INTERVAL_MS=60000
+RECONNECT_MIN_MS=2000
+RECONNECT_MAX_MS=60000
+LOG_LEVEL=info

package/AGENTS.md

@@ -0,0 +1,193 @@
+# AI Runner Codex Instructions
+
+This folder is the Node/npm Codex runner package. Its package name is
+`@leoustc/ai-runner-codex`.
+
+The runner is separate from the Cloudflare Worker projects:
+
+- `../agentrunner-hub/` owns the public Hub, MCP endpoint, dashboard, room
+  Durable Object, OAuth/session auth, room registry, logs, and room WebSocket.
+- `../agentrunner-ai/` is the older standalone Cloudflare Workers AI connector.
+- `runner/` is the npm Codex runner that connects to the public Hub and relays work
+  to a hot local Codex app-server over WebSocket.
+
+Do not move Hub dashboard, MCP, OAuth, room registry, or Cloudflare Worker logic
+into this folder.
+
+## Runtime Model
+
+The npm runner loads configuration from `.env` by default, connects to the Hub
+WebSocket, and relays messages between the Hub and a hot local Codex app-server
+WebSocket.
+
+The CLI command is:
+
+```sh
+ai-runner-codex -f config
+```
+
+`-f` selects the config/env file path. If `-f` is omitted, the runner defaults
+to `.env` in the current working directory.
+
+The intended flow is:
+
+1. Load the config file selected by `-f`, defaulting to `.env`.
+2. Spawn a hot Codex app-server listening on local `CODEX_LISTEN`
+   (`ws://127.0.0.1:PORT`).
+3. Connect to the Hub WebSocket:
+
+   ```text
+   {ROOM_WSS}?connector={ROOM_AGENT_ID}
+   ```
+
+4. Authenticate to the Hub with the room token using WebSocket subprotocols:
+
+   ```text
+   ["room-auth", "room-token.${ROOM_TOKEN}"]
+   ```
+
+5. On WebSocket open, register the agent with the Hub:
+
+   ```json
+   { "type": "agent_register", "name": "agent-name", "role": "agent role prompt", "model": "codex" }
+   ```
+
+6. For each valid Hub room payload, send `start` to the Hub, relay the payload
+   to Codex, then send Codex output back to the Hub as `message` and finish
+   with `end`.
+
+7. On errors, send an `error` reply for the matching `requestId`, then send
+   `end` when appropriate.
+
+The runner is a relay. The Hub remains authoritative for routing, target-agent
+selection, room auth, token revocation, and room audit events.
+
+## Environment
+
+Local configuration lives in `runner/.env`.
+
+Run with the default config:
+
+```sh
+ai-runner-codex
+```
+
+Run with an explicit config file:
+
+```sh
+ai-runner-codex -f .env
+```
+
+Expected variables:
+
+```sh
+ROOM_WSS=wss://agentrunner-hub.leoustc.com/room/...
+ROOM_ID=...
+ROOM_TOKEN=rt_...
+ROOM_AGENT_NAME=...
+ROOM_AGENT_ID=...
+```
+
+`ROOM_AGENT_ROLE` and `ROOM_AGENT_MODEL` are runner-owned optional settings.
+The runner supplies defaults and uses these values when registering with the
+Hub. They are not issued by the Hub and can be changed per runner.
+
+Optional variables may also be added for the Codex app-server command,
+`CODEX_LISTEN`, reconnect behavior, and timeouts. Do not add exec mode or Unix
+socket mode; this runner is intended to keep Codex hot through app-server
+WebSocket.
+
+If Codex app-server returns an auth/login error, start `CODEX_LOGIN_COMMAND`
+(`codex login --device-auth` by default), relay the device login URL/code back
+to the Hub as an agent message, wait for login completion, and retry the Codex
+request once.
+
+
+Do not commit real `.env` secrets. If examples are needed, use `.env.example`.
+
+## Connector Contract
+
+The runner receives strict Hub room payloads shaped like:
+
+```json
+{
+  "requestId": "...",
+  "room": "Room of user",
+  "userId": "dashboard",
+  "tool": "ask",
+  "systemInstruction": "You are handling the ask tool...",
+  "message": "{\"message\":\"hello\"}"
+}
+```
+
+Agent-to-agent messages use `tool: "agent_message"` and include an
+agent-to-agent system instruction from the Hub. Treat them the same as other
+room payloads: relay to Codex and return the reply to the Hub.
+
+Runner-side Codex instructions must distinguish user-facing action types:
+
+- `ask` and compatibility alias `chat`: answer from workspace knowledge, do not
+  edit files or modify the workspace, and be explicit when the workspace does
+  not provide enough evidence.
+- `task`: focus on doing the requested work. Inspect files, run appropriate
+  commands, and edit code when needed. Return a concise step-by-step account of
+  what was done, followed by a short outcome summary and any tests/checks run.
+
+For each valid payload, reply to the Hub as:
+
+```json
+{ "requestId": "...", "type": "start", "name": "agent-name" }
+{ "requestId": "...", "type": "message", "name": "agent-name", "message": { "text": "..." } }
+{ "requestId": "...", "type": "end", "name": "agent-name" }
+```
+
+Errors use:
+
+```json
+{ "requestId": "...", "type": "error", "name": "agent-name", "message": { "error": "..." } }
+```
+
+The runner should send periodic heartbeats while connected:
+
+```json
+{ "type": "agent_heartbeat", "name": "agent-name", "agentId": "agent_id", "model": "codex" }
+```
+
+## Reconnect Behavior
+
+The Hub enforces single-active-use for generated `rt_...` room tokens. If the
+same token is already connected, a second connection is rejected. The runner
+should reconnect only after the previous socket closes, using bounded backoff
+and jitter.
+
+Deleting an agent token from the Hub dashboard revokes that token and forces the
+agent offline. Muting an agent does not revoke its token; it only prevents Hub
+delivery to that agent.
+
+## Development
+
+This folder is a normal npm package with a `package.json` named
+`@leoustc/ai-runner-codex`.
+
+On startup, check that the `codex` CLI is installed and available on `PATH`
+before starting Codex app-server. Fail with a clear install/PATH error if it is
+missing.
+
+Prefer small modules:
+
+- `.env` loading and validation
+- Hub WebSocket connection and reconnect loop
+- Codex app-server process lifecycle
+- Codex app-server WebSocket client
+- Hub payload parsing and reply formatting
+
+Run package commands from `runner/`:
+
+```sh
+make build
+make local
+make publish
+```
+
+`make local` runs the CLI with `-f .env`. `make publish` must run the build
+check before `npm publish --access public`.

package/README.md

@@ -0,0 +1,101 @@
+# @leoustc/ai-runner-codex
+
+Local npm CLI connector for Agent Runner Hub. It loads a config file, connects
+to the public Hub WebSocket room, starts a local Codex app-server over
+WebSocket, and relays Hub messages to Codex.
+
+## Usage
+
+Create a config from the example:
+
+```sh
+cp .env.example .env
+```
+
+Run with the default `.env`:
+
+```sh
+ai-runner-codex
+```
+
+Run with an explicit config file:
+
+```sh
+ai-runner-codex -f .env
+```
+
+## Make Targets
+
+```sh
+make build
+make local
+make publish
+```
+
+`make local` runs `ai-runner-codex -f .env`. `make publish` runs the build check
+first, then publishes the package to npm with public access.
+
+## Config
+
+Required:
+
+```sh
+ROOM_WSS=wss://agentrunner-hub.leoustc.com/room/...
+ROOM_ID=...
+ROOM_TOKEN=rt_...
+ROOM_AGENT_NAME=lisa
+ROOM_AGENT_ID=lisa_0000
+```
+
+Optional:
+
+```sh
+# Runner-owned agent metadata. Defaults are generated by ai-runner-codex.
+ROOM_AGENT_ROLE=Answer clearly and concisely.
+ROOM_AGENT_MODEL=codex
+
+CODEX_LISTEN=ws://127.0.0.1:17655
+CODEX_COMMAND=codex app-server --listen {listen}
+CODEX_LOGIN_COMMAND=codex login --device-auth
+CODEX_LOGIN_TIMEOUT_MS=600000
+CODEX_CWD=.
+CODEX_HOME=
+CODEX_MODEL=
+CODEX_SANDBOX=read-only
+CODEX_APPROVAL_POLICY=never
+CODEX_REQUEST_TIMEOUT_MS=120000
+HEARTBEAT_INTERVAL_MS=60000
+RECONNECT_MIN_MS=2000
+RECONNECT_MAX_MS=60000
+LOG_LEVEL=info
+```
+
+`ROOM_AGENT_ROLE` and `ROOM_AGENT_MODEL` are not issued by the Hub. They are
+local runner settings used when registering the agent and can be changed per
+runner.
+
+The runner keeps a hot Codex app-server process. `CODEX_LISTEN` must be a local
+`ws://127.0.0.1:PORT` listener. The runner uses one JSON-RPC message per
+WebSocket text frame.
+
+On startup, the runner checks that the `codex` CLI is installed and available
+on `PATH` before starting app-server.
+
+If Codex returns an auth/login error, the runner starts `CODEX_LOGIN_COMMAND`,
+posts the device login URL/code back to the Hub as an agent message, waits for
+login completion, then retries the Codex request once.
+
+Prompt behavior:
+
+- `ask`/`chat`: answer from workspace knowledge without editing files.
+- `task`: do the requested work, then return concise steps, outcome, and checks.
+
+
+The runner authenticates with the Hub using WebSocket subprotocols:
+
+```text
+room-auth
+room-token.${ROOM_TOKEN}
+```
+
+Do not commit real `.env` files.

package/bin/ai-runner-codex.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run } from "../src/runner.js";
+
+run(process.argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.stack || error.message : String(error));
+  process.exitCode = 1;
+});
+

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@leoustc/ai-runner-codex",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Codex app-server backed Agent Runner Hub CLI connector",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ai-runner-codex": "bin/ai-runner-codex.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "AGENTS.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "npm run check",
+    "check": "node --check ./bin/ai-runner-codex.js && node --check ./src/config.js && node --check ./src/codex.js && node --check ./src/hub.js && node --check ./src/login.js && node --check ./src/protocol.js && node --check ./src/runner.js",
+    "local": "node ./bin/ai-runner-codex.js -f .env",
+    "start": "node ./bin/ai-runner-codex.js"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/codex.js

@@ -0,0 +1,443 @@
+import { spawn } from "node:child_process";
+
+export class CodexServer {
+  constructor(config, log) {
+    this.config = config;
+    this.log = log;
+    this.process = null;
+  }
+
+  async start() {
+    assertWsEndpoint(this.config.codexListen);
+    await ensureCodexCli();
+    const command = interpolateCommand(this.config.codexCommand, {
+      listen: this.config.codexListen,
+    });
+    const [program, ...args] = splitCommand(command);
+
+    this.log.info(`starting codex app-server: ${command}`);
+    this.process = spawn(program, args, {
+      env: {
+        ...process.env,
+        ...(this.config.codexHome ? { CODEX_HOME: this.config.codexHome } : {}),
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    this.process.stdout.on("data", (data) => this.log.debug(`[codex stdout] ${String(data).trimEnd()}`));
+    this.process.stderr.on("data", (data) => this.log.info(`[codex stderr] ${String(data).trimEnd()}`));
+    this.process.on("exit", (code, signal) => {
+      this.log.info(`codex app-server exited code=${code ?? "null"} signal=${signal ?? "null"}`);
+    });
+
+    await waitForReady(this.config.codexListen, 15_000);
+  }
+
+  async stop() {
+    this.process?.kill("SIGTERM");
+    this.process = null;
+  }
+}
+
+export async function requestCodex(config, request) {
+  const client = new CodexWsClient(config);
+
+  try {
+    await client.connect();
+    return await client.runTurn(request);
+  } finally {
+    client.close();
+  }
+}
+
+class CodexWsClient {
+  constructor(config) {
+    this.config = config;
+    this.nextRequestId = 1;
+    this.pending = new Map();
+    this.turns = new Map();
+    this.ws = null;
+  }
+
+  async connect() {
+    assertWsEndpoint(this.config.codexListen);
+    this.ws = new WebSocket(this.config.codexListen);
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error("Timed out waiting for Codex app-server WebSocket open"));
+      }, this.config.codexRequestTimeoutMs);
+      const cleanup = () => {
+        clearTimeout(timer);
+        this.ws.removeEventListener("open", onOpen);
+        this.ws.removeEventListener("error", onError);
+      };
+      const onOpen = () => {
+        cleanup();
+        resolve();
+      };
+      const onError = () => {
+        cleanup();
+        reject(new Error("Codex app-server WebSocket failed to open"));
+      };
+
+      this.ws.addEventListener("open", onOpen);
+      this.ws.addEventListener("error", onError);
+    });
+
+    this.ws.addEventListener("message", (event) => {
+      const text = typeof event.data === "string" ? event.data : String(event.data);
+      this.handleJson(text);
+    });
+    this.ws.addEventListener("close", () => {
+      this.rejectAll(new Error("Codex app-server closed the WebSocket"));
+    });
+    this.ws.addEventListener("error", () => {
+      this.rejectAll(new Error("Codex app-server WebSocket error"));
+    });
+
+    await this.request("initialize", {
+      clientInfo: {
+        name: "ai-runner-codex",
+        title: "AI Runner Codex",
+        version: "0.1.0",
+      },
+      capabilities: {
+        experimentalApi: true,
+        requestAttestation: false,
+      },
+    });
+  }
+
+  async runTurn(request) {
+    const thread = await this.request("thread/start", {
+      approvalPolicy: this.config.codexApprovalPolicy,
+      cwd: this.config.codexCwd,
+      developerInstructions: [
+        this.config.role,
+        actionInstruction(request.tool),
+        request.systemInstruction,
+      ].filter(Boolean).join("\n\n"),
+      ephemeral: true,
+      historyMode: "paginated",
+      model: this.config.codexModel || null,
+      sandbox: this.config.codexSandbox,
+    });
+    const threadId = thread?.thread?.id;
+
+    if (!threadId) {
+      throw new Error("Codex app-server did not return a thread id");
+    }
+
+    const state = {
+      reject: null,
+      resolve: null,
+      text: "",
+    };
+    const done = new Promise((resolve, reject) => {
+      state.resolve = resolve;
+      state.reject = reject;
+    });
+    this.turns.set(threadId, state);
+
+    const turn = await this.request("turn/start", {
+      approvalPolicy: this.config.codexApprovalPolicy,
+      cwd: this.config.codexCwd,
+      input: [
+        {
+          type: "text",
+          text: formatPrompt(request),
+          text_elements: [],
+        },
+      ],
+      model: this.config.codexModel || null,
+      sandboxPolicy: sandboxPolicy(this.config.codexSandbox, this.config.codexCwd),
+      threadId,
+    });
+
+    if (turn?.turn?.status === "completed") {
+      this.turns.delete(threadId);
+      return { text: state.text || textFromTurn(turn.turn) };
+    }
+
+    const text = await withTimeout(done, this.config.codexRequestTimeoutMs, "Timed out waiting for Codex turn completion");
+    return { text };
+  }
+
+  async request(method, params) {
+    const id = String(this.nextRequestId);
+    this.nextRequestId += 1;
+    const response = new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+    });
+
+    this.sendJson({ id, method, params });
+    return await withTimeout(response, this.config.codexRequestTimeoutMs, `Timed out waiting for Codex ${method}`);
+  }
+
+  handleJson(text) {
+    let message;
+
+    try {
+      message = JSON.parse(text);
+    } catch {
+      return;
+    }
+
+    if (message.id !== undefined) {
+      const pending = this.pending.get(String(message.id));
+
+      if (!pending) {
+        return;
+      }
+
+      this.pending.delete(String(message.id));
+
+      if (message.error) {
+        pending.reject(new Error(message.error.message || JSON.stringify(message.error)));
+      } else {
+        pending.resolve(message.result);
+      }
+      return;
+    }
+
+    this.handleNotification(message);
+  }
+
+  handleNotification(message) {
+    if (message.method === "item/agentMessage/delta") {
+      const state = this.turns.get(message.params?.threadId);
+
+      if (state && typeof message.params?.delta === "string") {
+        state.text += message.params.delta;
+      }
+      return;
+    }
+
+    if (message.method === "item/completed") {
+      const state = this.turns.get(message.params?.threadId);
+      const item = message.params?.item;
+
+      if (state && item?.type === "agentMessage" && typeof item.text === "string") {
+        state.text = item.text;
+      }
+      return;
+    }
+
+    if (message.method === "turn/completed") {
+      const threadId = message.params?.threadId;
+      const state = this.turns.get(threadId);
+
+      if (!state) {
+        return;
+      }
+
+      this.turns.delete(threadId);
+
+      if (message.params?.turn?.status === "failed") {
+        state.reject?.(new Error(message.params.turn.error?.message || "Codex turn failed"));
+      } else {
+        state.resolve?.(state.text || textFromTurn(message.params?.turn));
+      }
+      return;
+    }
+
+    if (message.method === "error") {
+      const error = new Error(message.params?.message || "Codex app-server error");
+
+      for (const state of this.turns.values()) {
+        state.reject?.(error);
+      }
+      this.turns.clear();
+    }
+  }
+
+  sendJson(value) {
+    this.ws.send(JSON.stringify(value));
+  }
+
+  close() {
+    this.ws?.close();
+    this.ws = null;
+  }
+
+  rejectAll(error) {
+    for (const pending of this.pending.values()) {
+      pending.reject(error);
+    }
+    this.pending.clear();
+
+    for (const state of this.turns.values()) {
+      state.reject?.(error);
+    }
+    this.turns.clear();
+  }
+}
+
+async function waitForReady(listen, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError;
+
+  while (Date.now() < deadline) {
+    try {
+      const readyUrl = new URL("/readyz", listen);
+      readyUrl.protocol = readyUrl.protocol === "wss:" ? "https:" : "http:";
+      const response = await fetch(readyUrl);
+      if (response.ok) {
+        return;
+      }
+      lastError = new Error(`readyz returned ${response.status}`);
+    } catch (error) {
+      lastError = error;
+    }
+
+    await sleep(250);
+  }
+
+  throw new Error(`Codex app-server did not open ${listen}: ${lastError?.message || "timeout"}`);
+}
+
+function assertWsEndpoint(listen) {
+  if (!listen.startsWith("ws://") && !listen.startsWith("wss://")) {
+    throw new Error(`CODEX_LISTEN must be ws:// or wss://, got: ${listen}`);
+  }
+}
+
+function ensureCodexCli() {
+  return new Promise((resolve, reject) => {
+    const child = spawn("codex", ["--version"], {
+      stdio: ["ignore", "ignore", "pipe"],
+    });
+    let stderr = "";
+
+    child.stderr.on("data", (data) => {
+      stderr += String(data);
+    });
+    child.on("error", (error) => {
+      if (error?.code === "ENOENT") {
+        reject(new Error("Codex CLI is not installed or not on PATH. Install it first, then rerun ai-runner-codex."));
+      } else {
+        reject(error);
+      }
+    });
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(stderr.trim() || `codex --version exited with code ${code}`));
+      }
+    });
+  });
+}
+
+function formatPrompt(request) {
+  return [
+    `Room: ${request.room ?? ""}`,
+    `User: ${request.userId ?? ""}`,
+    `Tool: ${request.tool ?? ""}`,
+    "",
+    "Message:",
+    typeof request.message === "string" ? request.message : JSON.stringify(request.message, null, 2),
+  ].join("\n");
+}
+
+function actionInstruction(tool) {
+  const normalized = String(tool || "").toLowerCase();
+
+  if (normalized === "ask" || normalized === "chat") {
+    return [
+      "This is an ask/chat action.",
+      "Answer the user's question using the workspace knowledge available to you.",
+      "Do not edit files, run code-changing commands, or modify the workspace.",
+      "Ground the answer in facts from the workspace when possible. If the workspace does not contain enough evidence, say what is unknown instead of guessing.",
+      "Keep the answer direct, solid, and useful.",
+    ].join(" ");
+  }
+
+  if (normalized === "task") {
+    return [
+      "This is a task action.",
+      "Focus on completing the requested task in the workspace.",
+      "You may inspect files, run appropriate commands, and edit code when needed.",
+      "When finished, return a concise step-by-step account of what you did, then a short summary of the task outcome.",
+      "Mention any tests or checks you ran, and clearly state if something could not be completed.",
+    ].join(" ");
+  }
+
+  return "";
+}
+
+function textFromTurn(turn) {
+  if (!turn?.items) {
+    return "";
+  }
+
+  return turn.items
+    .filter((item) => item?.type === "agentMessage" && typeof item.text === "string")
+    .map((item) => item.text)
+    .join("\n\n")
+    .trim();
+}
+
+function sandboxPolicy(mode, cwd) {
+  if (mode === "danger-full-access") {
+    return { type: "dangerFullAccess" };
+  }
+
+  if (mode === "workspace-write") {
+    return {
+      type: "workspaceWrite",
+      writableRoots: [cwd],
+      networkAccess: false,
+      excludeTmpdirEnvVar: false,
+      excludeSlashTmp: false,
+    };
+  }
+
+  return {
+    type: "readOnly",
+    networkAccess: false,
+  };
+}
+
+function withTimeout(promise, timeoutMs, message) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+function splitCommand(command) {
+  const matches = command.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
+  return matches.map((part) => {
+    if ((part.startsWith('"') && part.endsWith('"')) || (part.startsWith("'") && part.endsWith("'"))) {
+      return part.slice(1, -1);
+    }
+
+    return part;
+  });
+}
+
+function interpolateCommand(command, values) {
+  let next = command;
+
+  for (const [key, value] of Object.entries(values)) {
+    next = next.replaceAll(`{${key}}`, String(value));
+  }
+
+  return next;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/config.js

@@ -0,0 +1,133 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const DEFAULT_CONFIG = ".env";
+const DEFAULT_CODEX_LISTEN = "ws://127.0.0.1:17655";
+const DEFAULT_CODEX_COMMAND = "codex app-server --listen {listen}";
+const DEFAULT_CODEX_LOGIN_COMMAND = "codex login --device-auth";
+
+export function parseArgs(argv) {
+  const args = {
+    configPath: DEFAULT_CONFIG,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+
+    if (value === "-f" || value === "--file" || value === "--config") {
+      const next = argv[index + 1];
+
+      if (!next) {
+        throw new Error(`${value} requires a config path`);
+      }
+
+      args.configPath = next;
+      index += 1;
+      continue;
+    }
+
+    if (value === "-h" || value === "--help") {
+      args.help = true;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${value}`);
+  }
+
+  return args;
+}
+
+export function usage() {
+  return [
+    "Usage: ai-runner-codex [-f config]",
+    "",
+    "Options:",
+    "  -f, --file, --config <path>  Config/env file path. Defaults to .env.",
+    "  -h, --help                   Show this help.",
+  ].join("\n");
+}
+
+export async function loadConfig(configPath) {
+  const absolutePath = resolve(configPath || DEFAULT_CONFIG);
+  const env = parseEnv(await readFile(absolutePath, "utf8"));
+  const config = {
+    agentId: required(env, "ROOM_AGENT_ID"),
+    agentName: required(env, "ROOM_AGENT_NAME"),
+    codexCommand: env.CODEX_COMMAND || DEFAULT_CODEX_COMMAND,
+    codexCwd: resolve(env.CODEX_CWD || process.cwd()),
+    codexHome: env.CODEX_HOME || "",
+    codexListen: env.CODEX_LISTEN || DEFAULT_CODEX_LISTEN,
+    codexLoginCommand: env.CODEX_LOGIN_COMMAND || DEFAULT_CODEX_LOGIN_COMMAND,
+    codexLoginTimeoutMs: numberValue(env.CODEX_LOGIN_TIMEOUT_MS, 10 * 60_000),
+    codexModel: env.CODEX_MODEL || "",
+    codexRequestTimeoutMs: numberValue(env.CODEX_REQUEST_TIMEOUT_MS, 120_000),
+    codexSandbox: env.CODEX_SANDBOX || "read-only",
+    codexApprovalPolicy: env.CODEX_APPROVAL_POLICY || "never",
+    heartbeatIntervalMs: numberValue(env.HEARTBEAT_INTERVAL_MS, 60_000),
+    logLevel: env.LOG_LEVEL || "info",
+    model: env.ROOM_AGENT_MODEL || "codex",
+    reconnectMaxMs: numberValue(env.RECONNECT_MAX_MS, 60_000),
+    reconnectMinMs: numberValue(env.RECONNECT_MIN_MS, 2_000),
+    role:
+      env.ROOM_AGENT_ROLE ||
+      `You are ${env.ROOM_AGENT_NAME || "an AI runner"}, a Codex-backed room agent. Answer clearly and concisely.`,
+    roomId: required(env, "ROOM_ID"),
+    roomToken: required(env, "ROOM_TOKEN"),
+    roomWss: required(env, "ROOM_WSS"),
+  };
+
+  return {
+    ...config,
+    configPath: absolutePath,
+  };
+}
+
+function parseEnv(text) {
+  const env = {};
+
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+
+    const equals = line.indexOf("=");
+
+    if (equals === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, equals).trim();
+    const value = line.slice(equals + 1).trim();
+    env[key] = unquote(value);
+  }
+
+  return env;
+}
+
+function unquote(value) {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+
+  return value;
+}
+
+function required(env, key) {
+  const value = env[key]?.trim();
+
+  if (!value) {
+    throw new Error(`${key} is required in the runner config`);
+  }
+
+  return value;
+}
+
+function numberValue(value, fallback) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric > 0 ? Math.floor(numeric) : fallback;
+}

package/src/hub.js

@@ -0,0 +1,158 @@
+import { codexRequest, codexText, heartbeat, isRoomPayload, registration, reply } from "./protocol.js";
+import { requestCodex } from "./codex.js";
+import { ensureCodexLogin, isCodexAuthError } from "./login.js";
+
+export class HubClient {
+  constructor(config, log) {
+    this.config = config;
+    this.log = log;
+    this.heartbeatTimer = null;
+    this.reconnectAttempt = 0;
+    this.stopped = false;
+    this.socket = null;
+  }
+
+  start() {
+    this.connect();
+  }
+
+  stop() {
+    this.stopped = true;
+    this.stopHeartbeat();
+    this.socket?.close();
+  }
+
+  connect() {
+    const url = new URL(this.config.roomWss);
+    url.protocol = url.protocol === "https:" ? "wss:" : url.protocol;
+    url.searchParams.set("connector", this.config.agentId);
+
+    this.log.info(`connecting to hub ${url.toString()}`);
+    const socket = new WebSocket(url.toString(), [
+      "room-auth",
+      `room-token.${this.config.roomToken}`,
+    ]);
+    this.socket = socket;
+
+    socket.addEventListener("open", () => {
+      this.reconnectAttempt = 0;
+      this.log.info("hub websocket connected");
+      this.send(registration(this.config));
+      this.startHeartbeat();
+    });
+
+    socket.addEventListener("message", (event) => {
+      void this.handleMessage(event.data);
+    });
+
+    socket.addEventListener("close", (event) => {
+      this.log.info(`hub websocket closed code=${event.code} reason=${event.reason || ""}`);
+      this.stopHeartbeat();
+      this.scheduleReconnect();
+    });
+
+    socket.addEventListener("error", () => {
+      this.log.info("hub websocket error");
+    });
+  }
+
+  async handleMessage(data) {
+    const value = parseJson(data);
+
+    if (!isRoomPayload(value)) {
+      this.log.debug(`ignoring non-room payload: ${String(data).slice(0, 200)}`);
+      return;
+    }
+
+    this.send(reply(value, this.config, "start"));
+
+    try {
+      const response = await this.requestCodexWithLogin(value);
+      const text = codexText(response) || "Codex returned no text.";
+      this.send(reply(value, this.config, "message", {
+        model: this.config.model,
+        text,
+      }));
+    } catch (error) {
+      this.send(reply(value, this.config, "error", {
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    } finally {
+      this.send(reply(value, this.config, "end"));
+    }
+  }
+
+  async requestCodexWithLogin(value) {
+    const request = codexRequest(value, this.config);
+
+    try {
+      return await requestCodex(this.config, request);
+    } catch (error) {
+      if (!isCodexAuthError(error)) {
+        throw error;
+      }
+
+      await ensureCodexLogin(this.config, this.log, async (text) => {
+        this.send(reply(value, this.config, "message", {
+          codexLogin: true,
+          text,
+        }));
+      });
+
+      return await requestCodex(this.config, request);
+    }
+  }
+
+  startHeartbeat() {
+    this.stopHeartbeat();
+    const send = () => this.send(heartbeat(this.config));
+    send();
+    this.heartbeatTimer = setInterval(send, this.config.heartbeatIntervalMs);
+  }
+
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  scheduleReconnect() {
+    if (this.stopped) {
+      return;
+    }
+
+    this.reconnectAttempt += 1;
+    const base = Math.min(
+      this.config.reconnectMaxMs,
+      this.config.reconnectMinMs * 2 ** Math.min(8, this.reconnectAttempt - 1),
+    );
+    const jitter = Math.floor(Math.random() * Math.min(1_000, base));
+    const delay = base + jitter;
+
+    this.log.info(`reconnecting in ${delay}ms`);
+    setTimeout(() => {
+      if (!this.stopped) {
+        this.connect();
+      }
+    }, delay);
+  }
+
+  send(value) {
+    if (this.socket?.readyState !== WebSocket.OPEN) {
+      return;
+    }
+
+    this.socket.send(JSON.stringify(value));
+  }
+}
+
+function parseJson(data) {
+  const text = typeof data === "string" ? data : String(data);
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}

package/src/login.js

@@ -0,0 +1,115 @@
+import { spawn } from "node:child_process";
+
+let activeLogin = null;
+
+export function isCodexAuthError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+
+  return /auth|login|sign[ -]?in|unauthori[sz]ed|forbidden|invalid_grant|refresh token|access token/i.test(message);
+}
+
+export async function ensureCodexLogin(config, log, notify) {
+  if (activeLogin) {
+    await notify("Codex login is already in progress. Waiting for it to complete.");
+    return await activeLogin;
+  }
+
+  activeLogin = runCodexLogin(config, log, notify).finally(() => {
+    activeLogin = null;
+  });
+
+  return await activeLogin;
+}
+
+async function runCodexLogin(config, log, notify) {
+  const [program, ...args] = splitCommand(config.codexLoginCommand);
+
+  await notify("Codex login is required. Starting device login.");
+  log.info(`starting codex login: ${config.codexLoginCommand}`);
+
+  return await new Promise((resolve, reject) => {
+    const child = spawn(program, args, {
+      cwd: config.codexCwd,
+      env: {
+        ...process.env,
+        ...(config.codexHome ? { CODEX_HOME: config.codexHome } : {}),
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const state = {
+      buffer: "",
+      sentLoginInfo: false,
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      reject(new Error(`Codex login timed out after ${config.codexLoginTimeoutMs}ms`));
+    }, config.codexLoginTimeoutMs);
+
+    const onData = (data) => {
+      const text = String(data);
+      log.debug(`[codex login] ${text.trimEnd()}`);
+      state.buffer = `${state.buffer}\n${text}`.slice(-8000);
+      void sendLoginInfo(state, notify);
+    };
+
+    child.stdout.on("data", onData);
+    child.stderr.on("data", onData);
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on("exit", (code, signal) => {
+      clearTimeout(timer);
+
+      if (code === 0) {
+        void notify("Codex login completed. Retrying the request.");
+        resolve();
+      } else {
+        reject(new Error(`Codex login exited code=${code ?? "null"} signal=${signal ?? "null"}`));
+      }
+    });
+  });
+}
+
+async function sendLoginInfo(state, notify) {
+  if (state.sentLoginInfo) {
+    return;
+  }
+
+  const info = parseLoginInfo(state.buffer);
+
+  if (!info.url && !info.code) {
+    return;
+  }
+
+  state.sentLoginInfo = true;
+  await notify([
+    "Codex login required.",
+    info.url ? `Open: ${info.url}` : "",
+    info.code ? `Code: ${info.code}` : "",
+    "After login completes, the runner will retry automatically.",
+  ].filter(Boolean).join("\n"));
+}
+
+function parseLoginInfo(text) {
+  const url = text.match(/https?:\/\/[^\s"'<>]+/)?.[0]?.replace(/[),.;]+$/, "") ?? "";
+  const labelledCode =
+    text.match(/(?:user|device|login|verification)?\s*code(?:\s+is)?\s*[:=]?\s*([A-Z0-9][A-Z0-9-]{4,})/i)?.[1] ?? "";
+  const fallbackCode = text.match(/\b[A-Z0-9]{4}-[A-Z0-9]{4}\b/i)?.[0] ?? "";
+
+  return {
+    code: labelledCode || fallbackCode,
+    url,
+  };
+}
+
+function splitCommand(command) {
+  const matches = command.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
+  return matches.map((part) => {
+    if ((part.startsWith('"') && part.endsWith('"')) || (part.startsWith("'") && part.endsWith("'"))) {
+      return part.slice(1, -1);
+    }
+
+    return part;
+  });
+}

package/src/protocol.js

@@ -0,0 +1,82 @@
+export function isRoomPayload(value) {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      typeof value.requestId === "string" &&
+      typeof value.tool === "string" &&
+      typeof value.systemInstruction === "string" &&
+      typeof value.message === "string",
+  );
+}
+
+export function registration(config) {
+  return {
+    type: "agent_register",
+    name: config.agentName,
+    role: config.role,
+    model: config.model,
+  };
+}
+
+export function heartbeat(config) {
+  return {
+    type: "agent_heartbeat",
+    name: config.agentName,
+    agentId: config.agentId,
+    model: config.model,
+  };
+}
+
+export function reply(payload, config, type, message) {
+  return {
+    requestId: payload.requestId,
+    type,
+    name: config.agentName,
+    ...(message === undefined ? {} : { message }),
+  };
+}
+
+export function codexRequest(payload, config) {
+  return {
+    requestId: payload.requestId,
+    agent: {
+      id: config.agentId,
+      name: config.agentName,
+      role: config.role,
+      model: config.model,
+    },
+    room: payload.room,
+    userId: payload.userId,
+    tool: payload.tool,
+    systemInstruction: payload.systemInstruction,
+    message: parseMessage(payload.message),
+    rawMessage: payload.message,
+  };
+}
+
+export function codexText(response) {
+  if (typeof response === "string") {
+    return response;
+  }
+
+  if (!response || typeof response !== "object") {
+    return "";
+  }
+
+  for (const key of ["text", "message", "output", "response"]) {
+    if (typeof response[key] === "string" && response[key].trim()) {
+      return response[key].trim();
+    }
+  }
+
+  return JSON.stringify(response);
+}
+
+function parseMessage(message) {
+  try {
+    return JSON.parse(message);
+  } catch {
+    return message;
+  }
+}
+

package/src/runner.js

@@ -0,0 +1,45 @@
+import { CodexServer } from "./codex.js";
+import { loadConfig, parseArgs, usage } from "./config.js";
+import { HubClient } from "./hub.js";
+
+export async function run(argv) {
+  const args = parseArgs(argv);
+
+  if (args.help) {
+    console.log(usage());
+    return;
+  }
+
+  const config = await loadConfig(args.configPath);
+  const log = logger(config.logLevel);
+  const codex = new CodexServer(config, log);
+  const hub = new HubClient(config, log);
+
+  await codex.start();
+  hub.start();
+
+  const shutdown = async () => {
+    log.info("shutting down");
+    hub.stop();
+    await codex.stop();
+    process.exit(0);
+  };
+
+  process.once("SIGINT", () => void shutdown());
+  process.once("SIGTERM", () => void shutdown());
+}
+
+function logger(level) {
+  const debugEnabled = level === "debug";
+
+  return {
+    debug(message) {
+      if (debugEnabled) {
+        console.error(`[debug] ${message}`);
+      }
+    },
+    info(message) {
+      console.error(`[ai-runner-codex] ${message}`);
+    },
+  };
+}