agent-relay-codex 0.6.0 → 0.10.0

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

@@ -1,63 +0,0 @@
----
-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>`.
-
-## Pair with another session
-
-Use pair sessions for focused, two-agent live collaboration. Pairing is exclusive: one agent can have only one pending or active pair.
-
-When the user types a slash-style relay instruction such as `/pair codex`,
-`/message codex ...`, `/send-claimable tag:backend ...`, `/pair status`,
-`/pair send <pair-id> ...`, `/disconnect`, `/status`, `/label ...`, or
-`/tags ...`, run the matching `agent-relay` CLI command instead of explaining
-the API. The CLI auto-detects the current agent id from provider state in normal
-plugin installs.
-
-```bash
-agent-relay /pair codex "Debug flaky tests"
-agent-relay /message codex "Can you look at that failing action?"
-agent-relay /send-claimable tag:backend "Please claim and fix the failing API test"
-agent-relay /pair status
-agent-relay /pair send PAIR_ID "What do you see?"
-agent-relay /disconnect
-agent-relay /status
-agent-relay /label backend-fixer
-agent-relay /tags backend tests urgent
-```
-
-Create an invite:
-
-```bash
-curl -sS -X POST "${AGENT_RELAY_URL:-http://127.0.0.1:4850}/api/pairs" \
-  ${AGENT_RELAY_TOKEN:+-H "X-Agent-Relay-Token: ${AGENT_RELAY_TOKEN}"} \
-  -H 'Content-Type: application/json' \
-  -d '{"from":"<this-agent-id>","target":"codex","objective":"<what to solve together>"}'
-```
-
-Accept/reject incoming pair invites with `/api/pairs/<pair-id>/accept` or `/api/pairs/<pair-id>/reject` and `{"agentId":"<this-agent-id>"}`. Send pair chat through `/api/pairs/<pair-id>/messages` with `{"from":"<this-agent-id>","body":"..."}`. Hang up with `/api/pairs/<pair-id>/hangup`.
-
-## 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/plugin/skills/disconnect/SKILL.md

@@ -1,16 +0,0 @@
----
-name: disconnect
-description: End the current Agent Relay pair session. Use when the user invokes /disconnect or asks to hang up, unpair, or disconnect from a paired agent.
-argument-hint: "[PAIR_ID]"
-allowed-tools: [Bash]
----
-
-# Agent Relay Disconnect
-
-Run:
-
-```bash
-agent-relay /disconnect $ARGUMENTS
-```
-
-If no pair id is supplied, the CLI ends the active pair for this session. Report the result briefly.

package/plugin/skills/label/SKILL.md

@@ -1,23 +0,0 @@
----
-name: label
-description: Read, set, or clear the current Agent Relay agent label. Use when the user invokes /label or asks to rename this relay agent.
-argument-hint: "[LABEL|--clear]"
-allowed-tools: [Bash]
----
-
-# Agent Relay Label
-
-Run:
-
-```bash
-agent-relay /label $ARGUMENTS
-```
-
-Examples:
-
-```bash
-agent-relay /label backend-fixer
-agent-relay /label --clear
-```
-
-Report the new label or current label briefly.

package/plugin/skills/message/SKILL.md

@@ -1,24 +0,0 @@
----
-name: message
-description: Send a normal Agent Relay message to another agent, label, tag, capability, or broadcast target. Use when the user invokes /message or asks to send a one-off relay message.
-argument-hint: "<target> <message> [--subject TEXT] [--channel NAME]"
-allowed-tools: [Bash]
----
-
-# Agent Relay Message
-
-Run:
-
-```bash
-agent-relay /message $ARGUMENTS
-```
-
-Examples:
-
-```bash
-agent-relay /message codex "Can you look at that failing action?"
-agent-relay /message tag:backend "Does anyone see the regression?"
-agent-relay /message broadcast "Standup in five minutes"
-```
-
-Report the sent message id briefly.

package/plugin/skills/pair/SKILL.md

@@ -1,26 +0,0 @@
----
-name: pair
-description: Start, inspect, accept, reject, or send messages in an Agent Relay two-agent pair session. Use when the user invokes /pair or asks to pair this agent with Codex, Claude, or another relay agent.
-argument-hint: "<target|status|accept|reject|send> [args]"
-allowed-tools: [Bash]
----
-
-# Agent Relay Pair
-
-Run the Agent Relay CLI with the user's arguments:
-
-```bash
-agent-relay /pair $ARGUMENTS
-```
-
-Use this for pair-session commands such as:
-
-```bash
-agent-relay /pair codex "Debug flaky tests"
-agent-relay /pair status
-agent-relay /pair accept PAIR_ID
-agent-relay /pair reject PAIR_ID
-agent-relay /pair send PAIR_ID "What do you see?"
-```
-
-Report the command output briefly. If the CLI cannot detect this session's agent id, rerun with `--agent AGENT_ID` or `--from AGENT_ID` using the Agent Relay ID shown in session context.

package/plugin/skills/send-claimable/SKILL.md

@@ -1,24 +0,0 @@
----
-name: send-claimable
-description: Send a claimable Agent Relay work item so one matching agent can claim and handle it. Use when the user invokes /send-claimable or wants to enqueue work for another agent.
-argument-hint: "<target> <message> [--subject TEXT] [--channel NAME]"
-allowed-tools: [Bash]
----
-
-# Agent Relay Send Claimable
-
-Run:
-
-```bash
-agent-relay /send-claimable $ARGUMENTS
-```
-
-Examples:
-
-```bash
-agent-relay /send-claimable codex "Claim this and inspect the failing action"
-agent-relay /send-claimable tag:backend "Fix the failing API test"
-agent-relay /send-claimable cap:review "Review the migration patch"
-```
-
-Report the sent claimable message id briefly.

package/plugin/skills/status/SKILL.md

@@ -1,16 +0,0 @@
----
-name: status
-description: Show Agent Relay status for this session, including relay health, current agent id, label, tags, readiness, and active pair state. Use when the user invokes /status or asks for relay connection status.
-argument-hint: "[--json]"
-allowed-tools: [Bash]
----
-
-# Agent Relay Status
-
-Run:
-
-```bash
-agent-relay /status $ARGUMENTS
-```
-
-Summarize the current relay connection, agent identity, label, tags, and active pair state.

package/plugin/skills/tags/SKILL.md

@@ -1,25 +0,0 @@
----
-name: tags
-description: List or update Agent Relay tags for the current session. Use when the user invokes /tags or asks to set, add, remove, or inspect relay tags.
-argument-hint: "[TAG ...|--list|--add TAGS|--remove TAGS]"
-allowed-tools: [Bash]
----
-
-# Agent Relay Tags
-
-Run:
-
-```bash
-agent-relay /tags $ARGUMENTS
-```
-
-Examples:
-
-```bash
-agent-relay /tags
-agent-relay /tags backend tests urgent
-agent-relay /tags --add backend,tests
-agent-relay /tags --remove urgent
-```
-
-Report the resulting tags briefly.

package/profile.ts

@@ -1,96 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { parseApprovalMode, type ApprovalMode } from "./approval";
-
-interface AgentRelayProfile {
-  label?: string;
-  tags?: string[];
-  capabilities?: string[];
-  channels?: string[];
-  approval?: ApprovalMode;
-  meta?: Record<string, unknown>;
-}
-
-interface ResolvedAgentProfile {
-  profileName?: string;
-  label?: string;
-  tags: string[];
-  capabilities: string[];
-  channels: string[];
-  approval?: ApprovalMode;
-  meta: Record<string, unknown>;
-}
-
-function splitCsv(raw: string | undefined): string[] {
-  if (!raw) return [];
-  return [...new Set(raw.split(",").map((value) => value.trim()).filter(Boolean))];
-}
-
-function stringArray(value: unknown): string[] {
-  if (!Array.isArray(value)) return [];
-  return [...new Set(value.filter((item): item is string => typeof item === "string" && item.trim().length > 0).map((item) => item.trim()))];
-}
-
-function cleanLabel(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined;
-  const trimmed = value.trim();
-  return trimmed ? trimmed : undefined;
-}
-
-function cleanMeta(value: unknown): Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : {};
-}
-
-function loadProfileFile(env: NodeJS.ProcessEnv): Record<string, unknown> {
-  const file = env.AGENT_RELAY_PROFILES_FILE || join(env.HOME || "", ".config", "agent-relay", "profiles.json");
-  if (!file || !existsSync(file)) return {};
-  try {
-    const parsed = JSON.parse(readFileSync(file, "utf8")) as unknown;
-    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed as Record<string, unknown> : {};
-  } catch {
-    return {};
-  }
-}
-
-export function loadAgentRelayProfile(
-  env: NodeJS.ProcessEnv,
-  defaults: { provider: string; rig: string; project: string },
-): ResolvedAgentProfile {
-  const profileName = cleanLabel(env.AGENT_RELAY_PROFILE);
-  const rawProfile = profileName ? loadProfileFile(env)[profileName] : undefined;
-  const profile = cleanMeta(rawProfile);
-  const defaultTags = [defaults.provider, defaults.rig, defaults.project].filter(Boolean);
-  const profileTags = stringArray(profile.tags);
-  const envTags = splitCsv(env.AGENT_RELAY_TAGS);
-  const profileCapabilities = stringArray(profile.capabilities);
-  const profileChannels = stringArray(profile.channels);
-  const envChannels = splitCsv(env.AGENT_RELAY_CHANNELS);
-  const profileApproval = cleanLabel(profile.approval);
-
-  return {
-    profileName,
-    label: cleanLabel(env.AGENT_RELAY_LABEL) ?? cleanLabel(profile.label),
-    tags: [...new Set([...defaultTags, ...(envTags.length ? envTags : profileTags)])],
-    capabilities: splitCsv(env.AGENT_RELAY_CAPS).length
-      ? splitCsv(env.AGENT_RELAY_CAPS)
-      : profileCapabilities.length
-        ? profileCapabilities
-        : ["chat"],
-    channels: envChannels.length ? envChannels : profileChannels,
-    approval: env.AGENT_RELAY_APPROVAL
-      ? parseApprovalMode(env.AGENT_RELAY_APPROVAL)
-      : profileApproval
-        ? parseApprovalMode(profileApproval)
-        : undefined,
-    meta: {
-      ...cleanMeta(profile.meta),
-      ...(profileName ? { profile: profileName } : {}),
-    },
-  };
-}
-
-export function messageMatchesProfileChannels(message: { channel?: string }, channels: string[]): boolean {
-  if (channels.length === 0) return true;
-  if (!message.channel) return true;
-  return channels.includes(message.channel);
-}

package/relay.ts

@@ -1,188 +0,0 @@
-import { hostname } from "node:os";
-
-export type RelayAgentStatus = "online" | "idle" | "busy" | "offline";
-
-export interface RelayMessage {
-  id: number;
-  from: string;
-  to: string;
-  kind: string;
-  channel?: string;
-  subject?: string;
-  body: string;
-  replyTo?: number;
-  claimable?: boolean;
-  claimedBy?: string;
-  claimedAt?: number;
-  claimExpiresAt?: number;
-  payload?: Record<string, unknown>;
-  meta?: Record<string, unknown>;
-  createdAt: number;
-}
-
-interface RelayConfig {
-  relayUrl: string;
-  cwd: string;
-  rig: string;
-  label?: string;
-  capabilities: string[];
-  tags: string[];
-  channels?: string[];
-  profileName?: string;
-  profileMeta?: Record<string, unknown>;
-  threadId: string;
-  model?: string;
-  appServerUrl: string;
-  approvalMode?: string;
-  instanceId?: string;
-}
-
-export interface RelayAgentSession {
-  instanceId: string;
-  epoch: number;
-}
-
-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; session?: RelayAgentSession }> {
-    const identity = buildAgentIdentity(config);
-    const payload = {
-      id: identity.id,
-      name: identity.name,
-      label: config.label,
-      machine: identity.machine,
-      rig: config.rig,
-      tags: config.tags,
-      capabilities: config.capabilities,
-      status: "online",
-      instanceId: config.instanceId,
-      meta: {
-        provider: "codex",
-        client: "codex-live",
-        threadId: config.threadId,
-        appServerUrl: config.appServerUrl,
-        cwd: config.cwd,
-        model: config.model || null,
-        approvalMode: config.approvalMode || "open",
-        channels: config.channels ?? [],
-        profile: config.profileName || null,
-        ...(config.profileMeta ?? {}),
-      },
-    };
-
-    const agent = await this.json("POST", "/api/agents", payload) as { epoch?: unknown } | null;
-    const epoch = typeof agent?.epoch === "number" && Number.isSafeInteger(agent.epoch) ? agent.epoch : undefined;
-    return {
-      agentId: identity.id,
-      project: identity.project,
-      session: config.instanceId && epoch !== undefined ? { instanceId: config.instanceId, epoch } : undefined,
-    };
-  }
-
-  async heartbeat(agentId: string, session?: RelayAgentSession): Promise<void> {
-    await this.json("POST", `/api/agents/${encodeURIComponent(agentId)}/heartbeat`, session);
-  }
-
-  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, session?: RelayAgentSession): Promise<void> {
-    await this.json("PATCH", `/api/agents/${encodeURIComponent(agentId)}/status`, { status, ...session });
-  }
-
-  async setReady(agentId: string, ready: boolean, session?: RelayAgentSession): Promise<void> {
-    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);
-    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, session?: RelayAgentSession): 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, ...session }),
-    });
-
-    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 renewMessageClaim(messageId: number, agentId: string, session?: RelayAgentSession): Promise<boolean> {
-    const response = await fetch(new URL(`/api/messages/${messageId}/claim/renew`, this.baseUrl), {
-      method: "POST",
-      headers: this.headers({ "Content-Type": "application/json" }),
-      body: JSON.stringify({ agentId, ...session }),
-    });
-
-    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/renew`, 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

@@ -1,64 +0,0 @@
-#!/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"