agent-relay-codex 0.4.28 → 0.4.33

package/README.md

@@ -80,6 +80,7 @@ Run with `AGENT_RELAY_PROFILE=frontend-developer agent-relay-codex start`.
 | `CODEX_THREAD_ID` | — | Pin to a specific thread |
 | `CODEX_APP_SERVER_URL` | `ws://127.0.0.1:4501` | App-server WebSocket URL |
 | `AGENT_RELAY_CODEX_HEADLESS` | — | Set to `1` to run without opening a TUI |
+| `AGENT_RELAY_DISABLED` | — | Set to `1` to bypass Agent Relay hooks and launcher shims |
 
 ### Advanced tuning
 

package/bin/agent-relay-codex.ts

@@ -259,6 +259,75 @@ function findCodexBinary(): string {
   return codex;
 }
 
+function isRelayDisabled(env: Record<string, string | undefined> = process.env): boolean {
+  return env.AGENT_RELAY_DISABLED === "1";
+}
+
+const relayBypassSubcommands = new Set([
+  "a",
+  "app-server",
+  "apply",
+  "cloud",
+  "completion",
+  "debug",
+  "e",
+  "exec",
+  "exec-server",
+  "features",
+  "login",
+  "logout",
+  "mcp",
+  "mcp-server",
+  "plugin",
+  "remote-control",
+  "review",
+  "sandbox",
+  "update",
+]);
+
+function codexSubcommand(args: string[]): string {
+  const optionsWithValues = new Set([
+    "-c",
+    "--config",
+    "-m",
+    "--model",
+    "-p",
+    "--profile",
+    "-s",
+    "--sandbox",
+    "-C",
+    "--cd",
+    "--add-dir",
+  ]);
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]!;
+    if (arg === "--") return "";
+    if (optionsWithValues.has(arg)) {
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("-")) continue;
+    return arg;
+  }
+
+  return "";
+}
+
+export function shouldBypassRelay(args: string[], env: Record<string, string | undefined> = process.env): boolean {
+  return isRelayDisabled(env) || relayBypassSubcommands.has(codexSubcommand(args));
+}
+
+async function runCodexPassthrough(args: string[]): Promise<void> {
+  const codex = Bun.spawn([findCodexBinary(), ...args], {
+    env: { ...process.env, AGENT_RELAY_DISABLED: "1" },
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  process.exit(await codex.exited);
+}
+
 function installMarketplace(quiet = false): void {
   syncInstalledPackage();
 
@@ -1061,6 +1130,7 @@ function uninstall(args: string[] = []): void {
 
 async function main(): Promise<void> {
   const [command, ...args] = process.argv.slice(2);
+  const codexArgs = command ? [command, ...args] : [];
   if (command === "help" || command === "--help" || command === "-h") usage(0);
   if (command === "install") return install(args);
   if (command === "uninstall") return uninstall(args);
@@ -1072,7 +1142,8 @@ async function main(): Promise<void> {
   if (command === "doctor") return doctor();
   if (command === "upgrade") return upgrade(args);
   if (command === "start") return start(args);
-  return start(command ? [command, ...args] : []);
+  if (shouldBypassRelay(codexArgs)) return runCodexPassthrough(codexArgs);
+  return start(codexArgs);
 }
 
 if (import.meta.main) {

package/hooks/session-start.ts

@@ -46,6 +46,11 @@ function outputContext(context: string): never {
   process.exit(0);
 }
 
+function outputContinue(): never {
+  console.log(JSON.stringify({ continue: true }));
+  process.exit(0);
+}
+
 function handshakePath(runtimeDir: string): string {
   return join(runtimeDir, "session-start-handshake.json");
 }
@@ -74,6 +79,10 @@ const project = cwd.split("/").filter(Boolean).at(-1) || "unknown";
 const profile = loadAgentRelayProfile(process.env, { provider: "codex", rig, project });
 const approvalMode = profile.approval ?? parseApprovalMode(process.env.AGENT_RELAY_APPROVAL);
 
+if (process.env.AGENT_RELAY_DISABLED === "1") {
+  outputContinue();
+}
+
 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);

package/live-sidecar.ts

@@ -85,6 +85,7 @@ class CodexLiveSidecar {
   private draining = false;
   private drainDueAt = 0;
   private reconnecting: Promise<void> | null = null;
+  private relayPrimerDelivered = false;
   private readonly pendingMessages = new Map<number, RelayMessage>();
   private readonly activeClaimedMessageIds = new Set<number>();
 
@@ -529,7 +530,7 @@ class CodexLiveSidecar {
     }
 
     const delivery = this.pickDeliveryMode(batch.messages);
-    const prompt = formatRelayPrompt(batch.messages);
+    const prompt = formatRelayPrompt(batch.messages, { includePrimer: !this.relayPrimerDelivered });
     const ids = batch.messages.map((message) => message.id).join(", ");
     this.log(`delivering message ${ids} via ${delivery}`);
 
@@ -548,6 +549,7 @@ class CodexLiveSidecar {
       try {
         await this.app.turnSteer(this.threadId, this.activeTurnId, prompt);
         for (const id of claimedMessageIds) this.activeClaimedMessageIds.add(id);
+        this.relayPrimerDelivered = true;
         await this.markBatchRead(batch.messages);
         this.advanceCursor(batch.messages);
         this.writeState();
@@ -559,6 +561,7 @@ class CodexLiveSidecar {
 
     await this.app.turnStart(this.threadId, prompt);
     for (const id of claimedMessageIds) this.activeClaimedMessageIds.add(id);
+    this.relayPrimerDelivered = true;
     await this.markBatchRead(batch.messages);
     this.advanceCursor(batch.messages);
     this.writeState();
@@ -654,10 +657,25 @@ function shouldIsolateMessage(message: RelayMessage): boolean {
   return delivery === "interrupt" || delivery === "start" || delivery === "steer" || priority === "urgent";
 }
 
-export function formatRelayPrompt(messages: RelayMessage[]): string {
+export function formatRelayPrompt(
+  messages: RelayMessage[],
+  opts: { includePrimer?: 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.`,
+    "",
+  ];
+
   if (messages.length === 1) {
     const message = messages[0]!;
     const lines = [
+      ...(includePrimer ? primer : []),
       "Agent Relay message received.",
       "",
       formatMessageSummary(message),
@@ -678,16 +696,15 @@ export function formatRelayPrompt(messages: RelayMessage[]): string {
       "Body:",
       message.body,
       "",
-      "Treat this as a live incoming message from another agent. Respond or act on it as appropriate.",
-      "If AGENT_RELAY_TOKEN is set, include it as the X-Agent-Relay-Token header when calling the relay API.",
       typeof message.meta?.pairId === "string"
-        ? `For pair chat, POST JSON to ${process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850"}/api/pairs/${message.meta.pairId}/messages with from set to your Agent Relay ID and body set to your response.`
-        : `To reply, POST JSON to ${process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850"}/api/messages with from set to your Agent Relay ID, to set to ${JSON.stringify(message.from)}, and replyTo set to ${message.id}.`,
+        ? `Reply routing: pairId=${JSON.stringify(message.meta.pairId)}.`
+        : `Reply routing: to=${JSON.stringify(message.from)}, replyTo=${message.id}.`,
     );
     return lines.join("\n");
   }
 
   const lines = [
+    ...(includePrimer ? primer : []),
     "Agent Relay message batch received.",
     "",
     `Count: ${messages.length}`,
@@ -705,13 +722,16 @@ export function formatRelayPrompt(messages: RelayMessage[]): string {
     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}`);
+    lines.push(
+      typeof message.meta?.pairId === "string"
+        ? `Reply routing: pairId=${JSON.stringify(message.meta.pairId)}.`
+        : `Reply routing: to=${JSON.stringify(message.from)}, replyTo=${message.id}.`,
+    );
     lines.push("Body:", message.body, "", "---", "");
   }
 
   lines.push(
-    "Treat these as live incoming messages from other agents. Synthesize them into one coherent response or action.",
-    "If AGENT_RELAY_TOKEN is set, include it as the X-Agent-Relay-Token header when calling the relay API.",
-    `To reply, POST JSON to ${process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850"}/api/messages with from set to your Agent Relay ID and replyTo set to the message you are answering.`,
+    "Synthesize these messages into one coherent response or action. Use each message's Reply routing line when replying.",
   );
   return lines.join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-codex",
-  "version": "0.4.28",
+  "version": "0.4.33",
   "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.28",
+  "version": "0.4.33",
   "description": "Agent Relay integration for Codex sessions",
   "author": {
     "name": "Edin Mujkanovic"