agent-relay-codex 0.4.35 → 0.6.0

package/bin/agent-relay-codex.ts

@@ -952,6 +952,7 @@ async function start(args: string[]): Promise<void> {
     AGENT_RELAY_CODEX_PACKAGE_ROOT: activePackageRoot(),
     AGENT_RELAY_CODEX_RUN_ID: runId,
     AGENT_RELAY_CODEX_RUNTIME_DIR: runDir,
+    AGENT_RELAY_CONTEXT_PATH: join(runDir, "agent-context.json"),
     CODEX_APP_SERVER_URL: listenUrl,
     CODEX_THREAD_MODE: threadMode,
     CODEX_THREAD_ID: threadId || undefined,

package/hooks/session-start.ts

@@ -2,9 +2,8 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { describeApprovalMode, parseApprovalMode } from "../approval.ts";
+import { parseApprovalMode } from "../approval.ts";
 import { loadAgentRelayProfile } from "../profile.ts";
-import { buildAgentIdentity } from "../relay.ts";
 import { pickThreadId, type HookInput } from "./session-start-lib.ts";
 
 type HookHandshake = {
@@ -84,8 +83,7 @@ if (process.env.AGENT_RELAY_DISABLED === "1") {
 }
 
 if (process.env.AGENT_RELAY_CODEX_MANAGED === "1") {
-  outputContext("Agent Relay is managed by codex-relay for this session; the launcher attached Relay and TUI to the same Codex App Server thread.");
-  process.exit(0);
+  outputContinue();
 }
 
 if (!appServerUrl || !runId) {
@@ -99,6 +97,7 @@ const sessionKey = sanitize(threadId || "auto");
 const sessionDir = join(runtimeDir, sessionKey);
 const pidPath = join(sessionDir, "sidecar.pid");
 const statePath = join(sessionDir, "live-state.json");
+const contextPath = join(sessionDir, "agent-context.json");
 const logPath = join(sessionDir, "sidecar.log");
 mkdirSync(sessionDir, { recursive: true });
 mkdirSync(runtimeDir, { recursive: true });
@@ -114,24 +113,7 @@ if (activePid !== null) {
     threadId: threadId || undefined,
     timestamp: new Date().toISOString(),
   });
-  if (threadId) {
-    const identity = buildAgentIdentity({
-      relayUrl,
-      cwd,
-      rig,
-      label: profile.label,
-      capabilities: profile.capabilities,
-      tags: profile.tags,
-      channels: profile.channels,
-      profileName: profile.profileName,
-      profileMeta: profile.meta,
-      threadId,
-      model: input.model,
-      appServerUrl,
-    });
-    outputContext(buildStartupContext(identity.id, relayUrl, approvalMode));
-  }
-  outputContext(`Agent Relay sidecar already running (pid ${activePid}). Relay URL: ${relayUrl}. Approval mode: ${approvalMode} (${describeApprovalMode(approvalMode)}).`);
+  outputContinue();
 }
 
 const spawnEnv: Record<string, string | undefined> = {
@@ -141,6 +123,7 @@ const spawnEnv: Record<string, string | undefined> = {
   CODEX_THREAD_MODE: threadId ? "resume" : process.env.CODEX_THREAD_MODE || "start",
   AGENT_RELAY_CODEX_CWD: cwd,
   AGENT_RELAY_CODEX_STATE_PATH: statePath,
+  AGENT_RELAY_CONTEXT_PATH: process.env.AGENT_RELAY_CONTEXT_PATH || contextPath,
   CODEX_MODEL: input.model || process.env.CODEX_MODEL || "",
   AGENT_RELAY_APPROVAL: process.env.AGENT_RELAY_APPROVAL || profile.approval || "",
   AGENT_RELAY_CODEX_PARENT_PID: String(process.ppid),
@@ -183,45 +166,4 @@ try {
   throw error;
 }
 
-if (!threadId) {
-  outputContext(`Agent Relay sidecar started in auto-thread mode. Relay URL: ${relayUrl}. Incoming messages will arrive as live user turns once the sidecar resolves the active thread.`);
-}
-
-const identity = buildAgentIdentity({
-  relayUrl,
-  cwd,
-  rig,
-  label: profile.label,
-  capabilities: profile.capabilities,
-  tags: profile.tags,
-  channels: profile.channels,
-  profileName: profile.profileName,
-  profileMeta: profile.meta,
-  threadId,
-  model: input.model,
-  appServerUrl,
-});
-
-outputContext(buildStartupContext(identity.id, relayUrl, approvalMode, profile));
-
-function buildStartupContext(agentId: string, url: string, mode: string, resolvedProfile = profile): string {
-  return [
-    "Agent Relay active.",
-    `Agent ID: ${agentId}`,
-    `Relay URL: ${url}`,
-    resolvedProfile.profileName ? `Profile: ${resolvedProfile.profileName}` : "",
-    resolvedProfile.label ? `Label: ${resolvedProfile.label}` : "",
-    resolvedProfile.tags.length ? `Tags: ${resolvedProfile.tags.join(", ")}` : "",
-    resolvedProfile.capabilities.length ? `Capabilities: ${resolvedProfile.capabilities.join(", ")}` : "",
-    resolvedProfile.channels.length ? `Channels: ${resolvedProfile.channels.join(", ")}` : "",
-    `Approval mode: ${mode} (${describeApprovalMode(parseApprovalMode(mode))})`,
-    "Incoming messages will arrive as live user turns.",
-    `To send a message, POST JSON to ${url}/api/messages with from="${agentId}", to, subject, and body.`,
-    "Targets can be an agent id, tag:name, cap:name, label:name, or broadcast.",
-    `To pair with one available session, POST JSON to ${url}/api/pairs with from="${agentId}", target, and optional objective; pair chat uses /api/pairs/{id}/messages.`,
-    "To reply to a specific incoming message, include replyTo set to that message id.",
-    "If AGENT_RELAY_TOKEN is set, include it as the X-Agent-Relay-Token header.",
-    "Message etiquette: acknowledge incoming agent messages briefly unless they are obvious noise.",
-    "Anti-loop rule: do not auto-reply to pure acknowledgements/thanks/received messages; acknowledge once, then follow up only when there is new work, a decision, or a deliverable.",
-  ].filter(Boolean).join(" ");
-}
+outputContinue();

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;
@@ -19,8 +21,10 @@ interface Config {
   profileName?: string;
   profileMeta: Record<string, unknown>;
   statePath: string;
+  contextPath?: string;
   pollIntervalMs: number;
   heartbeatIntervalMs: number;
+  threadCheckIntervalMs: number;
   relayBackoffInitialMs: number;
   relayBackoffMaxMs: number;
   coalesceWindowMs: number;
@@ -34,6 +38,7 @@ interface Config {
   approvalMode: ApprovalMode;
   parentPid?: number;
   assumeLoadedThread: boolean;
+  headless: boolean;
 }
 
 interface RuntimeState {
@@ -56,6 +61,8 @@ interface DeliveryBatch {
   messages: RelayMessage[];
 }
 
+class ThreadLostError extends Error {}
+
 export function activeClaimRenewalIds(
   messageIds: Iterable<number>,
   activeTurnId: string | null,
@@ -65,6 +72,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 +88,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 +117,7 @@ class CodexLiveSidecar {
     process.on("SIGTERM", () => void this.stop("SIGTERM"));
 
     await this.ensureAppReady();
+    if (this.stopping) return;
 
     await this.registerRelayAgent();
 
@@ -116,6 +129,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 +168,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 +265,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 +292,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 +331,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 +409,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 +455,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 +583,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 +605,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 +642,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);
@@ -598,6 +700,7 @@ class CodexLiveSidecar {
 
   private writeState(): void {
     if (!this.threadId) return;
+    const updatedAt = new Date().toISOString();
     const state: RuntimeState = {
       agentId: this.agentId,
       agentInstanceId: this.agentInstanceId,
@@ -611,9 +714,24 @@ class CodexLiveSidecar {
       appServerUrl: this.config.appServerUrl,
       relayUrl: this.config.relayUrl,
       cwd: this.config.cwd,
-      updatedAt: new Date().toISOString(),
+      updatedAt,
     };
     writeFileSync(this.config.statePath, JSON.stringify(state, null, 2));
+    if (this.config.contextPath) {
+      mkdirSync(dirname(this.config.contextPath), { recursive: true });
+      writeFileSync(this.config.contextPath, JSON.stringify({
+        version: 1,
+        agentId: this.agentId,
+        provider: "codex",
+        relayUrl: this.config.relayUrl,
+        cwd: this.config.cwd,
+        statePath: this.config.statePath,
+        matchEnv: [
+          { name: "AGENT_RELAY_CONTEXT_PATH", value: this.config.contextPath },
+        ],
+        updatedAt,
+      }, null, 2));
+    }
   }
 
   private log(message: string): void {
@@ -659,16 +777,17 @@ 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.",
-    "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.`,
+    ...(opts.headless ? ["This Codex session is running headless; Agent Relay is the primary user and agent communication surface."] : []),
+    "For normal replies, prefer `agent-relay /message TARGET BODY --reply-to MSG_ID`; the CLI detects this session's Agent Relay ID.",
+    "For pair chat replies, prefer `agent-relay /pair send PAIR_ID BODY`.",
+    `If the CLI is unavailable, call ${relayUrl}/api/messages or /api/pairs/{pairId}/messages directly and include AGENT_RELAY_TOKEN as X-Agent-Relay-Token when set.`,
     "",
   ];
 
@@ -688,16 +807,17 @@ export function formatRelayPrompt(
 
     if (message.subject) lines.push(`Subject: ${message.subject}`);
     if (message.replyTo) lines.push(`Reply To: ${message.replyTo}`);
-    if (typeof message.meta?.pairId === "string") {
-      lines.push(`Pair ID: ${message.meta.pairId}`);
+    const pairId = typeof message.payload?.pairId === "string" ? message.payload.pairId : undefined;
+    if (pairId) {
+      lines.push(`Pair ID: ${pairId}`);
     }
     lines.push(
       "",
       "Body:",
       message.body,
       "",
-      typeof message.meta?.pairId === "string"
-        ? `Reply routing: pairId=${JSON.stringify(message.meta.pairId)}.`
+      pairId
+        ? `Reply routing: pairId=${JSON.stringify(pairId)}.`
         : `Reply routing: to=${JSON.stringify(message.from)}, replyTo=${message.id}.`,
     );
     return lines.join("\n");
@@ -721,10 +841,11 @@ export function formatRelayPrompt(
     );
     if (message.subject) lines.push(`Subject: ${message.subject}`);
     if (message.replyTo) lines.push(`Reply To: ${message.replyTo}`);
-    if (typeof message.meta?.pairId === "string") lines.push(`Pair ID: ${message.meta.pairId}`);
+    const pairId = typeof message.payload?.pairId === "string" ? message.payload.pairId : undefined;
+    if (pairId) lines.push(`Pair ID: ${pairId}`);
     lines.push(
-      typeof message.meta?.pairId === "string"
-        ? `Reply routing: pairId=${JSON.stringify(message.meta.pairId)}.`
+      pairId
+        ? `Reply routing: pairId=${JSON.stringify(pairId)}.`
         : `Reply routing: to=${JSON.stringify(message.from)}, replyTo=${message.id}.`,
     );
     lines.push("Body:", message.body, "", "---", "");
@@ -738,10 +859,26 @@ export function formatRelayPrompt(
 
 function formatMessageSummary(message: RelayMessage): string {
   const subject = message.subject || "message";
-  if (message.type === "system") return `SYSTEM [msg:${message.id}]: ${message.body}`;
+  if (message.kind === "system" || message.kind === "control") return `SYSTEM [msg:${message.id}]: ${message.body}`;
   return `[msg:${message.id}] ${message.from} -> ${message.to} | ${subject}: ${message.body}`;
 }
 
+export function agentControlActionForMessage(message: RelayMessage): AgentControlAction | null {
+  if (message.kind !== "control") return null;
+  const control = message.payload?.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,
@@ -811,8 +948,10 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
     profileName: profile.profileName,
     profileMeta: profile.meta,
     statePath: env.AGENT_RELAY_CODEX_STATE_PATH || resolve(cwd, "codex/runtime/live-state.json"),
+    contextPath: env.AGENT_RELAY_CONTEXT_PATH || undefined,
     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 +970,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.6.0",
   "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.6.0",
   "description": "Agent Relay integration for Codex sessions",
   "author": {
     "name": "Edin Mujkanovic"

package/relay.ts

@@ -6,6 +6,7 @@ export interface RelayMessage {
   id: number;
   from: string;
   to: string;
+  kind: string;
   channel?: string;
   subject?: string;
   body: string;
@@ -14,7 +15,7 @@ export interface RelayMessage {
   claimedBy?: string;
   claimedAt?: number;
   claimExpiresAt?: number;
-  type?: string;
+  payload?: Record<string, unknown>;
   meta?: Record<string, unknown>;
   createdAt: number;
 }
@@ -105,6 +106,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);