@leoustc/ai-runner-codex 0.1.0 → 0.1.2

package/.env.example

@@ -19,6 +19,9 @@ CODEX_SANDBOX=read-only
 CODEX_APPROVAL_POLICY=never
 CODEX_REQUEST_TIMEOUT_MS=120000
 HEARTBEAT_INTERVAL_MS=60000
+HUB_STALE_TIMEOUT_MS=180000
+HUB_WATCHDOG_INTERVAL_MS=30000
+OUTBOUND_QUEUE_MAX=100
 RECONNECT_MIN_MS=2000
 RECONNECT_MAX_MS=60000
 LOG_LEVEL=info

package/AGENTS.md

@@ -141,6 +141,11 @@ For each valid payload, reply to the Hub as:
 { "requestId": "...", "type": "end", "name": "agent-name" }
 ```
 
+Large Codex reply text must be split into multiple `message` frames before the
+matching `end`. Each `message.text` chunk should be at most 8 KiB encoded as
+UTF-8. Include `message.chunk` metadata with `index`, `total`, and `maxBytes`
+when a reply has more than one chunk.
+
 Errors use:
 
 ```json

package/README.md

@@ -65,6 +65,9 @@ CODEX_SANDBOX=read-only
 CODEX_APPROVAL_POLICY=never
 CODEX_REQUEST_TIMEOUT_MS=120000
 HEARTBEAT_INTERVAL_MS=60000
+HUB_STALE_TIMEOUT_MS=180000
+HUB_WATCHDOG_INTERVAL_MS=30000
+OUTBOUND_QUEUE_MAX=100
 RECONNECT_MIN_MS=2000
 RECONNECT_MAX_MS=60000
 LOG_LEVEL=info
@@ -85,6 +88,15 @@ 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.
 
+Hub WebSocket behavior:
+
+- `HEARTBEAT_INTERVAL_MS` defaults to `60000`, so the runner sends a heartbeat
+  every 60 seconds while connected.
+- If the socket closes or is detected stale, the runner reconnects with bounded
+  exponential backoff between `RECONNECT_MIN_MS` and `RECONNECT_MAX_MS`.
+- Agent replies produced while the Hub socket is briefly down are queued up to
+  `OUTBOUND_QUEUE_MAX` and flushed after reconnect.
+
 Prompt behavior:
 
 - `ask`/`chat`: answer from workspace knowledge without editing files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leoustc/ai-runner-codex",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "Codex app-server backed Agent Runner Hub CLI connector",
   "license": "MIT",

package/src/codex.js

@@ -100,7 +100,7 @@ class CodexWsClient {
       clientInfo: {
         name: "ai-runner-codex",
         title: "AI Runner Codex",
-        version: "0.1.0",
+        version: "0.1.1",
       },
       capabilities: {
         experimentalApi: true,

package/src/config.js

@@ -64,8 +64,11 @@ export async function loadConfig(configPath) {
     codexSandbox: env.CODEX_SANDBOX || "read-only",
     codexApprovalPolicy: env.CODEX_APPROVAL_POLICY || "never",
     heartbeatIntervalMs: numberValue(env.HEARTBEAT_INTERVAL_MS, 60_000),
+    hubStaleTimeoutMs: numberValue(env.HUB_STALE_TIMEOUT_MS, 180_000),
+    hubWatchdogIntervalMs: numberValue(env.HUB_WATCHDOG_INTERVAL_MS, 30_000),
     logLevel: env.LOG_LEVEL || "info",
     model: env.ROOM_AGENT_MODEL || "codex",
+    outboundQueueMax: numberValue(env.OUTBOUND_QUEUE_MAX, 100),
     reconnectMaxMs: numberValue(env.RECONNECT_MAX_MS, 60_000),
     reconnectMinMs: numberValue(env.RECONNECT_MIN_MS, 2_000),
     role:

package/src/hub.js

@@ -1,4 +1,4 @@
-import { codexRequest, codexText, heartbeat, isRoomPayload, registration, reply } from "./protocol.js";
+import { codexRequest, codexText, heartbeat, isRoomPayload, messageReplies, registration, reply } from "./protocol.js";
 import { requestCodex } from "./codex.js";
 import { ensureCodexLogin, isCodexAuthError } from "./login.js";
 
@@ -7,9 +7,13 @@ export class HubClient {
     this.config = config;
     this.log = log;
     this.heartbeatTimer = null;
+    this.lastSocketActivity = 0;
+    this.outboundQueue = [];
     this.reconnectAttempt = 0;
+    this.reconnectTimer = null;
     this.stopped = false;
     this.socket = null;
+    this.watchdogTimer = null;
   }
 
   start() {
@@ -19,10 +23,13 @@ export class HubClient {
   stop() {
     this.stopped = true;
     this.stopHeartbeat();
+    this.stopWatchdog();
+    this.clearReconnectTimer();
     this.socket?.close();
   }
 
   connect() {
+    this.clearReconnectTimer();
     const url = new URL(this.config.roomWss);
     url.protocol = url.protocol === "https:" ? "wss:" : url.protocol;
     url.searchParams.set("connector", this.config.agentId);
@@ -35,23 +42,41 @@ export class HubClient {
     this.socket = socket;
 
     socket.addEventListener("open", () => {
+      if (this.socket !== socket) {
+        socket.close();
+        return;
+      }
+
       this.reconnectAttempt = 0;
+      this.markSocketActivity();
       this.log.info("hub websocket connected");
-      this.send(registration(this.config));
+      this.sendNow(registration(this.config));
+      this.flushOutboundQueue();
       this.startHeartbeat();
+      this.startWatchdog();
     });
 
     socket.addEventListener("message", (event) => {
+      this.markSocketActivity();
       void this.handleMessage(event.data);
     });
 
     socket.addEventListener("close", (event) => {
+      if (this.socket !== socket) {
+        return;
+      }
+
       this.log.info(`hub websocket closed code=${event.code} reason=${event.reason || ""}`);
       this.stopHeartbeat();
+      this.stopWatchdog();
       this.scheduleReconnect();
     });
 
     socket.addEventListener("error", () => {
+      if (this.socket !== socket) {
+        return;
+      }
+
       this.log.info("hub websocket error");
     });
   }
@@ -69,10 +94,10 @@ export class HubClient {
     try {
       const response = await this.requestCodexWithLogin(value);
       const text = codexText(response) || "Codex returned no text.";
-      this.send(reply(value, this.config, "message", {
+      this.sendMessages(value, {
         model: this.config.model,
         text,
-      }));
+      });
     } catch (error) {
       this.send(reply(value, this.config, "error", {
         error: error instanceof Error ? error.message : String(error),
@@ -93,10 +118,10 @@ export class HubClient {
       }
 
       await ensureCodexLogin(this.config, this.log, async (text) => {
-        this.send(reply(value, this.config, "message", {
+        this.sendMessages(value, {
           codexLogin: true,
           text,
-        }));
+        });
       });
 
       return await requestCodex(this.config, request);
@@ -105,7 +130,7 @@ export class HubClient {
 
   startHeartbeat() {
     this.stopHeartbeat();
-    const send = () => this.send(heartbeat(this.config));
+    const send = () => this.sendNow(heartbeat(this.config));
     send();
     this.heartbeatTimer = setInterval(send, this.config.heartbeatIntervalMs);
   }
@@ -117,6 +142,30 @@ export class HubClient {
     }
   }
 
+  startWatchdog() {
+    this.stopWatchdog();
+    this.watchdogTimer = setInterval(() => {
+      if (this.socket?.readyState !== WebSocket.OPEN) {
+        return;
+      }
+
+      const idleMs = Date.now() - this.lastSocketActivity;
+      if (idleMs < this.config.hubStaleTimeoutMs) {
+        return;
+      }
+
+      this.log.info(`hub websocket stale for ${idleMs}ms; reconnecting`);
+      this.socket.close();
+    }, this.config.hubWatchdogIntervalMs);
+  }
+
+  stopWatchdog() {
+    if (this.watchdogTimer) {
+      clearInterval(this.watchdogTimer);
+      this.watchdogTimer = null;
+    }
+  }
+
   scheduleReconnect() {
     if (this.stopped) {
       return;
@@ -131,19 +180,71 @@ export class HubClient {
     const delay = base + jitter;
 
     this.log.info(`reconnecting in ${delay}ms`);
-    setTimeout(() => {
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
       if (!this.stopped) {
         this.connect();
       }
     }, delay);
   }
 
+  clearReconnectTimer() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  markSocketActivity() {
+    this.lastSocketActivity = Date.now();
+  }
+
   send(value) {
     if (this.socket?.readyState !== WebSocket.OPEN) {
+      this.queueOutbound(value);
       return;
     }
 
-    this.socket.send(JSON.stringify(value));
+    if (!this.sendNow(value)) {
+      this.queueOutbound(value);
+    }
+  }
+
+  sendMessages(payload, message) {
+    for (const value of messageReplies(payload, this.config, message)) {
+      this.send(value);
+    }
+  }
+
+  sendNow(value) {
+    if (this.socket?.readyState !== WebSocket.OPEN) {
+      return false;
+    }
+
+    try {
+      this.socket.send(JSON.stringify(value));
+      this.markSocketActivity();
+      return true;
+    } catch (error) {
+      this.log.info(`hub websocket send failed: ${error instanceof Error ? error.message : String(error)}`);
+      this.socket.close();
+      return false;
+    }
+  }
+
+  queueOutbound(value) {
+    if (this.outboundQueue.length >= this.config.outboundQueueMax) {
+      this.outboundQueue.shift();
+    }
+
+    this.outboundQueue.push(value);
+  }
+
+  flushOutboundQueue() {
+    while (this.outboundQueue.length > 0 && this.socket?.readyState === WebSocket.OPEN) {
+      const value = this.outboundQueue.shift();
+      this.sendNow(value);
+    }
   }
 }
 

package/src/protocol.js

@@ -36,6 +36,30 @@ export function reply(payload, config, type, message) {
   };
 }
 
+export function messageReplies(payload, config, message, maxBytes = 8 * 1024) {
+  if (typeof message?.text !== "string") {
+    return [reply(payload, config, "message", message)];
+  }
+
+  const chunks = splitUtf8Chunks(message.text, maxBytes);
+
+  return chunks.map((chunk, index) =>
+    reply(payload, config, "message", {
+      ...message,
+      text: chunk,
+      ...(chunks.length > 1
+        ? {
+            chunk: {
+              index,
+              total: chunks.length,
+              maxBytes,
+            },
+          }
+        : {}),
+    }),
+  );
+}
+
 export function codexRequest(payload, config) {
   return {
     requestId: payload.requestId,
@@ -80,3 +104,28 @@ function parseMessage(message) {
   }
 }
 
+function splitUtf8Chunks(text, maxBytes) {
+  const encoder = new TextEncoder();
+  const chunks = [];
+  let current = "";
+  let currentBytes = 0;
+
+  for (const character of text) {
+    const characterBytes = encoder.encode(character).byteLength;
+
+    if (current && currentBytes + characterBytes > maxBytes) {
+      chunks.push(current);
+      current = "";
+      currentBytes = 0;
+    }
+
+    current += character;
+    currentBytes += characterBytes;
+  }
+
+  if (current || chunks.length === 0) {
+    chunks.push(current);
+  }
+
+  return chunks;
+}