agent-relay-codex 0.4.39 → 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

@@ -21,6 +21,7 @@ interface Config {
   profileName?: string;
   profileMeta: Record<string, unknown>;
   statePath: string;
+  contextPath?: string;
   pollIntervalMs: number;
   heartbeatIntervalMs: number;
   threadCheckIntervalMs: number;
@@ -699,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,
@@ -712,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 {
@@ -768,9 +785,9 @@ export function formatRelayPrompt(
     "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.`,
+    "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.`,
     "",
   ];
 
@@ -790,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");
@@ -823,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, "", "---", "");
@@ -840,13 +859,13 @@ 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.type !== "system") return null;
-  const control = message.meta?.agentControl;
+  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;
@@ -929,6 +948,7 @@ 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),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-codex",
-  "version": "0.4.39",
+  "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.39",
+  "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;
 }