agent-relay-codex 0.4.35 → 0.4.39

package/live-sidecar.ts

@@ -7,6 +7,8 @@ import { CodexAppClient, type ClientEvent, type Thread, type ThreadStatus } from
 import { loadAgentRelayProfile, messageMatchesProfileChannels } from "./profile";
 import { RelayClient, RelayHttpError, type RelayAgentSession, type RelayAgentStatus, type RelayMessage } from "./relay";
 
+type AgentControlAction = "restart" | "shutdown";
+
 interface Config {
   relayUrl: string;
   appServerUrl: string;
@@ -21,6 +23,7 @@ interface Config {
   statePath: string;
   pollIntervalMs: number;
   heartbeatIntervalMs: number;
+  threadCheckIntervalMs: number;
   relayBackoffInitialMs: number;
   relayBackoffMaxMs: number;
   coalesceWindowMs: number;
@@ -34,6 +37,7 @@ interface Config {
   approvalMode: ApprovalMode;
   parentPid?: number;
   assumeLoadedThread: boolean;
+  headless: boolean;
 }
 
 interface RuntimeState {
@@ -56,6 +60,8 @@ interface DeliveryBatch {
   messages: RelayMessage[];
 }
 
+class ThreadLostError extends Error {}
+
 export function activeClaimRenewalIds(
   messageIds: Iterable<number>,
   activeTurnId: string | null,
@@ -65,6 +71,10 @@ export function activeClaimRenewalIds(
   return [...messageIds];
 }
 
+export function canUseSyntheticLoadedThread(threadId: string, loadedThreadIds: readonly string[]): boolean {
+  return loadedThreadIds.includes(threadId);
+}
+
 class CodexLiveSidecar {
   private readonly relay: RelayClient;
   private readonly logPrefix = "[codex-live]";
@@ -77,6 +87,7 @@ class CodexLiveSidecar {
   private threadStatus: ThreadStatus["type"] = "notLoaded";
   private lastSeenMessageId = 0;
   private lastHeartbeatAt = 0;
+  private lastThreadCheckAt = 0;
   private hasSuccessfulPoll = false;
   private relayBackoffMs = 0;
   private lastClaimRenewalAt = 0;
@@ -105,6 +116,7 @@ class CodexLiveSidecar {
     process.on("SIGTERM", () => void this.stop("SIGTERM"));
 
     await this.ensureAppReady();
+    if (this.stopping) return;
 
     await this.registerRelayAgent();
 
@@ -116,6 +128,10 @@ class CodexLiveSidecar {
           break;
         }
         const now = Date.now();
+        if (now - this.lastThreadCheckAt >= this.config.threadCheckIntervalMs) {
+          this.lastThreadCheckAt = now;
+          await this.verifyCurrentThread();
+        }
         if (now - this.lastHeartbeatAt >= this.config.heartbeatIntervalMs) {
           await this.relay.heartbeat(this.agentId, this.agentSession());
           this.lastHeartbeatAt = now;
@@ -151,6 +167,8 @@ class CodexLiveSidecar {
           this.stopping = true;
           this.writeState();
           this.app.close();
+        } else if (error instanceof ThreadLostError) {
+          await this.stopAndUnregister(error.message);
         } else {
           sleepMs = this.nextRelayBackoffMs();
           this.log(`loop error: ${describeError(error)}; retrying in ${sleepMs}ms`);
@@ -246,6 +264,10 @@ class CodexLiveSidecar {
         }
         return;
       } catch (error) {
+        if (error instanceof ThreadLostError) {
+          await this.stopAndUnregister(error.message);
+          return;
+        }
         this.appConnected = false;
         this.log(`app connection failed: ${describeError(error)}; retrying in ${waitMs}ms`);
         await delay(waitMs);
@@ -269,6 +291,28 @@ class CodexLiveSidecar {
     this.app.close();
   }
 
+  private async stopAndUnregister(reason: string): Promise<void> {
+    if (this.stopping) return;
+    this.stopping = true;
+    this.log(`${reason}; unregistering relay agent and stopping sidecar`);
+    if (this.agentId) {
+      try {
+        await this.relay.unregisterAgent(this.agentId);
+      } catch (error) {
+        this.log(`failed to unregister relay agent ${this.agentId}: ${describeError(error)}`);
+        try {
+          await this.relay.setStatus(this.agentId, "offline", this.agentSession());
+        } catch {
+          // Best effort after unregister failure.
+        }
+      }
+    }
+    this.threadStatus = "notLoaded";
+    this.activeTurnId = null;
+    this.writeState();
+    this.app.close();
+  }
+
   private parentExited(): boolean {
     return Boolean(this.config.parentPid && !isAlive(this.config.parentPid));
   }
@@ -286,7 +330,7 @@ class CodexLiveSidecar {
 
   private async attachKnownThread(threadId: string): Promise<Thread> {
     if (this.config.assumeLoadedThread) {
-      return this.readThreadWithFallback(threadId).catch(() => syntheticLoadedThread(threadId, this.config.cwd));
+      return this.readAssumedLoadedThread(threadId);
     }
 
     try {
@@ -364,6 +408,25 @@ class CodexLiveSidecar {
     return payload;
   }
 
+  private async readAssumedLoadedThread(threadId: string): Promise<Thread> {
+    try {
+      return await this.readThreadWithFallback(threadId);
+    } catch {
+      const loaded = await this.app.threadLoadedList(100);
+      if (canUseSyntheticLoadedThread(threadId, loaded.data)) {
+        return syntheticLoadedThread(threadId, this.config.cwd);
+      }
+      throw new ThreadLostError(`codex thread ${threadId} is no longer loaded`);
+    }
+  }
+
+  private async verifyCurrentThread(): Promise<void> {
+    if (!this.threadId || !this.appConnected) return;
+    if (!this.config.assumeLoadedThread) return;
+    const thread = await this.readAssumedLoadedThread(this.threadId);
+    this.syncThreadState(thread);
+  }
+
   private async readThreadWithFallback(threadId: string): Promise<Thread> {
     try {
       const read = await this.app.threadRead(threadId, true);
@@ -391,7 +454,12 @@ class CodexLiveSidecar {
 
     if (method === "thread/status/changed") {
       if (params?.threadId === this.threadId && params.status && typeof params.status === "object" && "type" in params.status) {
-        this.threadStatus = String(params.status.type) as ThreadStatus["type"];
+        const nextStatus = String(params.status.type) as ThreadStatus["type"];
+        if (this.config.assumeLoadedThread && nextStatus === "notLoaded") {
+          void this.stopAndUnregister(`codex thread ${this.threadId} reported notLoaded`);
+          return;
+        }
+        this.threadStatus = nextStatus;
         void this.refreshRelayStatus();
         this.writeState();
       }
@@ -514,6 +582,12 @@ class CodexLiveSidecar {
   }
 
   private async deliverBatch(batch: DeliveryBatch): Promise<void> {
+    const control = firstAgentControlMessage(batch.messages);
+    if (control) {
+      await this.handleAgentControl(control.message, control.action);
+      return;
+    }
+
     await this.ensureAppReady();
 
     const claimedMessageIds: number[] = [];
@@ -530,7 +604,7 @@ class CodexLiveSidecar {
     }
 
     const delivery = this.pickDeliveryMode(batch.messages);
-    const prompt = formatRelayPrompt(batch.messages, { includePrimer: !this.relayPrimerDelivered });
+    const prompt = formatRelayPrompt(batch.messages, { includePrimer: !this.relayPrimerDelivered, headless: this.config.headless });
     const ids = batch.messages.map((message) => message.id).join(", ");
     this.log(`delivering message ${ids} via ${delivery}`);
 
@@ -567,6 +641,33 @@ class CodexLiveSidecar {
     this.writeState();
   }
 
+  private async handleAgentControl(message: RelayMessage, action: AgentControlAction): Promise<void> {
+    this.log(`agent control ${action} requested by message ${message.id}`);
+    await this.relay.markRead(message.id, this.agentId);
+    this.advanceCursor([message]);
+
+    if (action === "shutdown") {
+      await this.stopAndUnregister(`dashboard shutdown requested by message ${message.id}`);
+      return;
+    }
+
+    if (this.agentId) {
+      try {
+        await this.relay.unregisterAgent(this.agentId);
+      } catch (error) {
+        this.log(`failed to unregister before restart: ${describeError(error)}`);
+      }
+    }
+    this.agentEpoch = 0;
+    this.activeTurnId = null;
+    this.activeClaimedMessageIds.clear();
+    this.app.close();
+    this.appConnected = false;
+    await this.ensureAppReady(true);
+    await this.registerRelayAgent();
+    this.writeState();
+  }
+
   private advanceCursor(messages: RelayMessage[]): void {
     for (const message of messages) {
       this.lastSeenMessageId = Math.max(this.lastSeenMessageId, message.id);
@@ -659,13 +760,14 @@ function shouldIsolateMessage(message: RelayMessage): boolean {
 
 export function formatRelayPrompt(
   messages: RelayMessage[],
-  opts: { includePrimer?: boolean } = {},
+  opts: { includePrimer?: boolean; headless?: boolean } = {},
 ): string {
   const includePrimer = opts.includePrimer === true;
   const relayUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
   const primer = [
     "Agent Relay live-message primer:",
     "Treat Agent Relay deliveries as live incoming messages from other agents. Respond or act on them as appropriate.",
+    ...(opts.headless ? ["This Codex session is running headless; Agent Relay is the primary user and agent communication surface."] : []),
     "When calling the relay API, include AGENT_RELAY_TOKEN as the X-Agent-Relay-Token header if that environment variable is set.",
     `For normal replies, POST JSON to ${relayUrl}/api/messages with from set to your Agent Relay ID, to set to the sender Agent Relay ID, body set to your response, and replyTo set to the incoming message id.`,
     `For pair chat replies, POST JSON to ${relayUrl}/api/pairs/{pairId}/messages with from set to your Agent Relay ID and body set to your response.`,
@@ -742,6 +844,22 @@ function formatMessageSummary(message: RelayMessage): string {
   return `[msg:${message.id}] ${message.from} -> ${message.to} | ${subject}: ${message.body}`;
 }
 
+export function agentControlActionForMessage(message: RelayMessage): AgentControlAction | null {
+  if (message.type !== "system") return null;
+  const control = message.meta?.agentControl;
+  if (!control || typeof control !== "object" || Array.isArray(control)) return null;
+  const action = (control as { action?: unknown }).action;
+  return action === "restart" || action === "shutdown" ? action : null;
+}
+
+function firstAgentControlMessage(messages: RelayMessage[]): { message: RelayMessage; action: AgentControlAction } | null {
+  for (const message of messages) {
+    const action = agentControlActionForMessage(message);
+    if (action) return { message, action };
+  }
+  return null;
+}
+
 function normalizeThread(thread: Thread): Thread {
   return {
     ...thread,
@@ -813,6 +931,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
     statePath: env.AGENT_RELAY_CODEX_STATE_PATH || resolve(cwd, "codex/runtime/live-state.json"),
     pollIntervalMs: envNumber(env, "AGENT_RELAY_CODEX_POLL_INTERVAL_MS", 2000),
     heartbeatIntervalMs: envNumber(env, "AGENT_RELAY_CODEX_HEARTBEAT_INTERVAL_MS", 30000),
+    threadCheckIntervalMs: envNumber(env, "AGENT_RELAY_CODEX_THREAD_CHECK_INTERVAL_MS", 30000),
     relayBackoffInitialMs: envNumber(env, "AGENT_RELAY_CODEX_RELAY_BACKOFF_INITIAL_MS", 2000),
     relayBackoffMaxMs: envNumber(env, "AGENT_RELAY_CODEX_RELAY_BACKOFF_MAX_MS", 60000),
     coalesceWindowMs: envNumber(env, "AGENT_RELAY_CODEX_COALESCE_WINDOW_MS", 600),
@@ -831,6 +950,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
       }),
     parentPid: envNumber(env, "AGENT_RELAY_CODEX_PARENT_PID", 0) || undefined,
     assumeLoadedThread: env.AGENT_RELAY_CODEX_ASSUME_LOADED_THREAD === "1" || env.AGENT_RELAY_CODEX_ASSUME_LOADED_THREAD === "true",
+    headless: env.AGENT_RELAY_CODEX_HEADLESS === "1" || env.AGENT_RELAY_CODEX_HEADLESS === "true",
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-codex",
-  "version": "0.4.35",
+  "version": "0.4.39",
   "description": "Codex integration for Agent Relay — auto-registers sessions as agents and enables inter-agent messaging",
   "type": "module",
   "bin": {

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay",
-  "version": "0.4.35",
+  "version": "0.4.39",
   "description": "Agent Relay integration for Codex sessions",
   "author": {
     "name": "Edin Mujkanovic"

package/relay.ts

@@ -105,6 +105,10 @@ export class RelayClient {
     await this.json("PATCH", `/api/agents/${encodeURIComponent(agentId)}/ready`, { ready, ...session });
   }
 
+  async unregisterAgent(agentId: string): Promise<void> {
+    await this.json("DELETE", `/api/agents/${encodeURIComponent(agentId)}`);
+  }
+
   async pollMessages(agentId: string, sinceId: number): Promise<RelayMessage[]> {
     const url = new URL(`/api/messages`, this.baseUrl);
     url.searchParams.set("for", agentId);