agent-relay-codex 0.4.14

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "agent-relay-codex",
+  "version": "0.4.14",
+  "description": "Codex integration for Agent Relay — auto-registers sessions as agents and enables inter-agent messaging",
+  "type": "module",
+  "bin": {
+    "agent-relay-codex": "bin/agent-relay-codex.ts",
+    "codex-relay": "bin/agent-relay-codex.ts"
+  },
+  "files": [
+    "bin/**/*.ts",
+    "hooks/**/*.ts",
+    "plugin/**",
+    "*.ts",
+    "*.sh",
+    "*.ps1",
+    "!**/*.test.ts",
+    "!smoke/**",
+    "!runtime/**"
+  ],
+  "license": "AGPL-3.0-or-later",
+  "author": "Edin Mujkanovic <edin@exelerus.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/edimuj/agent-relay.git",
+    "directory": "codex"
+  },
+  "bugs": {
+    "url": "https://github.com/edimuj/agent-relay/issues"
+  },
+  "homepage": "https://github.com/edimuj/agent-relay/tree/main/codex#readme",
+  "keywords": [
+    "codex",
+    "codex-plugin",
+    "agent-relay",
+    "ai-agents",
+    "coding-agents",
+    "multi-agent",
+    "inter-agent-communication",
+    "agent-communication",
+    "message-bus",
+    "automation",
+    "developer-tools"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

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

@@ -0,0 +1,40 @@
+{
+  "name": "agent-relay",
+  "version": "0.4.11",
+  "description": "Agent Relay integration for Codex sessions",
+  "author": {
+    "name": "Edin Mujkanovic"
+  },
+  "repository": "https://github.com/edimuj/agent-relay",
+  "license": "AGPL-3.0-or-later",
+  "keywords": [
+    "agent-relay",
+    "multi-agent",
+    "codex",
+    "codex-plugin",
+    "ai-agents",
+    "coding-agents",
+    "inter-agent-communication",
+    "agent-communication",
+    "message-bus",
+    "automation",
+    "developer-tools"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Agent Relay",
+    "shortDescription": "Connect Codex sessions to Agent Relay",
+    "longDescription": "Adds Codex-facing instructions for Agent Relay and pairs with the agent-relay-codex launcher for live incoming messages.",
+    "developerName": "Edin Mujkanovic",
+    "category": "Productivity",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "Use Agent Relay to message another coding agent.",
+      "Check how this Codex session is connected to Agent Relay."
+    ],
+    "brandColor": "#10A37F"
+  }
+}

package/plugin/skills/agent-relay/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: agent-relay
+description: Use Agent Relay from Codex to understand live relay messages, reply to other agents, or send inter-agent messages through the local relay server.
+---
+
+# Agent Relay
+
+Agent Relay is a local HTTP message bus for coding-agent sessions. When this Codex session is launched with `agent-relay-codex start`, a sidecar registers the session and injects incoming relay messages as live user turns.
+
+## Incoming messages
+
+Treat prompts beginning with `Agent Relay message received` or `Agent Relay message batch received` as live messages from another agent. Act on the request if appropriate, and reply through the relay when a response is useful.
+
+## Send a message
+
+Use the relay API at `${AGENT_RELAY_URL:-http://127.0.0.1:4850}`:
+
+```bash
+curl -sS -X POST "${AGENT_RELAY_URL:-http://127.0.0.1:4850}/api/messages" \
+  ${AGENT_RELAY_TOKEN:+-H "X-Agent-Relay-Token: ${AGENT_RELAY_TOKEN}"} \
+  -H 'Content-Type: application/json' \
+  -d '{"from":"<this-agent-id>","to":"<target>","subject":"<subject>","body":"<message>"}'
+```
+
+Targets can be an agent id, `broadcast`, `cap:<capability>`, `tag:<tag>`, or `label:<label>`.
+
+## Claimable tasks
+
+If an incoming relay message is described as claimable, only one matching agent should act on it. The Codex sidecar attempts to claim before delivery; if the claim fails, the message is skipped.

package/relay.ts

@@ -0,0 +1,145 @@
+import { hostname } from "node:os";
+
+export type RelayAgentStatus = "online" | "idle" | "busy" | "offline";
+
+export interface RelayMessage {
+  id: number;
+  from: string;
+  to: string;
+  subject?: string;
+  body: string;
+  replyTo?: number;
+  claimable?: boolean;
+  type?: string;
+  meta?: Record<string, unknown>;
+  createdAt: number;
+}
+
+export interface RelayConfig {
+  relayUrl: string;
+  cwd: string;
+  rig: string;
+  capabilities: string[];
+  tags: string[];
+  threadId: string;
+  model?: string;
+  appServerUrl: string;
+  approvalMode?: string;
+}
+
+export function buildAgentIdentity(config: RelayConfig): { id: string; name: string; machine: string; project: string } {
+  const machine = hostname();
+  const project = config.cwd.split("/").filter(Boolean).at(-1) || "unknown";
+  const shortThread = config.threadId.replace(/[^a-zA-Z0-9]/g, "").slice(0, 8) || "thread";
+  const id = `${machine}-${config.rig}-${project}-${shortThread}`;
+  const name = `${project} (${config.rig} @ ${machine})`;
+  return { id, name, machine, project };
+}
+
+export class RelayClient {
+  constructor(private readonly baseUrl: string, private readonly log: (msg: string) => void = () => {}) {}
+
+  async registerAgent(config: RelayConfig): Promise<{ agentId: string; project: string }> {
+    const identity = buildAgentIdentity(config);
+    const payload = {
+      id: identity.id,
+      name: identity.name,
+      machine: identity.machine,
+      rig: config.rig,
+      tags: config.tags,
+      capabilities: config.capabilities,
+      status: "online",
+      meta: {
+        client: "codex-live",
+        threadId: config.threadId,
+        appServerUrl: config.appServerUrl,
+        cwd: config.cwd,
+        model: config.model || null,
+        approvalMode: config.approvalMode || "open",
+      },
+    };
+
+    await this.json("POST", "/api/agents", payload);
+    return { agentId: identity.id, project: identity.project };
+  }
+
+  async heartbeat(agentId: string): Promise<void> {
+    await this.json("POST", `/api/agents/${encodeURIComponent(agentId)}/heartbeat`);
+  }
+
+  async getCursor(): Promise<number> {
+    const result = await this.json("GET", "/api/messages/cursor") as { latestId?: unknown } | null;
+    return typeof result?.latestId === "number" && Number.isSafeInteger(result.latestId) ? result.latestId : 0;
+  }
+
+  async setStatus(agentId: string, status: RelayAgentStatus): Promise<void> {
+    await this.json("PATCH", `/api/agents/${encodeURIComponent(agentId)}/status`, { status });
+  }
+
+  async setReady(agentId: string, ready: boolean): Promise<void> {
+    await this.json("PATCH", `/api/agents/${encodeURIComponent(agentId)}/ready`, { ready });
+  }
+
+  async pollMessages(agentId: string, sinceId: number): Promise<RelayMessage[]> {
+    const url = new URL(`/api/messages`, this.baseUrl);
+    url.searchParams.set("for", agentId);
+    url.searchParams.set("unread", "true");
+    if (sinceId > 0) url.searchParams.set("sinceId", String(sinceId));
+    const response = await fetch(url, { headers: this.headers() });
+    if (!response.ok) {
+      throw new RelayHttpError("GET", "/api/messages", response.status, response.statusText, await response.text());
+    }
+    return (await response.json()) as RelayMessage[];
+  }
+
+  async claimMessage(messageId: number, agentId: string): Promise<boolean> {
+    const response = await fetch(new URL(`/api/messages/${messageId}/claim`, this.baseUrl), {
+      method: "POST",
+      headers: this.headers({ "Content-Type": "application/json" }),
+      body: JSON.stringify({ agentId }),
+    });
+
+    if (response.ok) return true;
+    if (response.status === 409) return false;
+    if (response.status === 400 || response.status === 404) return false;
+    throw new RelayHttpError("POST", `/api/messages/${messageId}/claim`, response.status, response.statusText, await response.text());
+  }
+
+  async markRead(messageId: number, agentId: string): Promise<void> {
+    await this.json("PATCH", `/api/messages/${messageId}`, { readBy: agentId });
+  }
+
+  private async json(method: string, path: string, body?: unknown): Promise<unknown> {
+    const response = await fetch(new URL(path, this.baseUrl), {
+      method,
+      headers: this.headers({ "Content-Type": "application/json" }),
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      this.log(`relay error ${method} ${path}: ${response.status} ${text}`);
+      throw new RelayHttpError(method, path, response.status, response.statusText, text);
+    }
+
+    if (response.status === 204) return null;
+    return response.json().catch(() => null);
+  }
+
+  private headers(base: Record<string, string> = {}): Record<string, string> {
+    const token = process.env.AGENT_RELAY_TOKEN;
+    return token ? { ...base, "X-Agent-Relay-Token": token } : base;
+  }
+}
+
+export class RelayHttpError extends Error {
+  constructor(
+    readonly method: string,
+    readonly path: string,
+    readonly status: number,
+    readonly statusText: string,
+    readonly body: string,
+  ) {
+    super(`relay ${method} ${path} failed: ${status}`);
+  }
+}

package/start-live.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR=$(cd "$(dirname "$0")/.." && pwd)
+CODEX_DIR="$ROOT_DIR/codex"
+RUNTIME_DIR="$CODEX_DIR/runtime"
+APP_LOG="$RUNTIME_DIR/app-server.log"
+APP_PID="$RUNTIME_DIR/app-server.pid"
+APP_URL_FILE="$RUNTIME_DIR/app-server.url"
+STATE_FILE="${AGENT_RELAY_CODEX_STATE_PATH:-$RUNTIME_DIR/live-state.json}"
+CODEX_APP_SERVER_URL="${CODEX_APP_SERVER_URL:-ws://127.0.0.1:4501}"
+STARTED_APP_SERVER=0
+
+mkdir -p "$RUNTIME_DIR"
+
+cleanup() {
+  if [ "$STARTED_APP_SERVER" = "1" ] && [ -f "$APP_PID" ]; then
+    pid=$(cat "$APP_PID" 2>/dev/null || true)
+    if [ -n "${pid:-}" ] && kill -0 "$pid" 2>/dev/null; then
+      kill "$pid" 2>/dev/null || true
+    fi
+    rm -f "$APP_PID"
+  fi
+}
+trap cleanup EXIT INT TERM
+
+if [ -f "$APP_PID" ]; then
+  pid=$(cat "$APP_PID" 2>/dev/null || true)
+  if [ -n "${pid:-}" ] && kill -0 "$pid" 2>/dev/null; then
+    echo "app-server already running (pid=$pid) at $(cat "$APP_URL_FILE" 2>/dev/null || echo "$CODEX_APP_SERVER_URL")"
+  else
+    rm -f "$APP_PID"
+  fi
+fi
+
+if [ ! -f "$APP_PID" ]; then
+  setsid bash -lc "exec codex app-server --listen '$CODEX_APP_SERVER_URL' >>'$APP_LOG' 2>&1 < /dev/null" &
+  pid=$!
+  STARTED_APP_SERVER=1
+  printf '%s\n' "$pid" > "$APP_PID"
+  printf '%s\n' "$CODEX_APP_SERVER_URL" > "$APP_URL_FILE"
+
+  for _ in $(seq 1 50); do
+    if grep -qiE 'listening|ws://' "$APP_LOG" 2>/dev/null; then
+      break
+    fi
+    if ! kill -0 "$pid" 2>/dev/null; then
+      echo "app-server exited early; see $APP_LOG" >&2
+      exit 1
+    fi
+    sleep 0.2
+  done
+
+  echo "started app-server pid=$pid url=$CODEX_APP_SERVER_URL"
+fi
+
+echo "state file: $STATE_FILE"
+echo "connect Codex TUI with: codex --remote $CODEX_APP_SERVER_URL"
+echo "if sidecar creates a new thread first, inspect $STATE_FILE for threadId and use: codex resume <threadId> --remote $CODEX_APP_SERVER_URL"
+
+export CODEX_APP_SERVER_URL
+export AGENT_RELAY_CODEX_CWD="${AGENT_RELAY_CODEX_CWD:-$ROOT_DIR}"
+export AGENT_RELAY_CODEX_STATE_PATH="$STATE_FILE"
+exec bun run "$CODEX_DIR/live-sidecar.ts"