agent-relay-server 0.4.13 → 0.4.14

package/codex/live-sidecar.ts

@@ -1,626 +0,0 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { setTimeout as delay } from "node:timers/promises";
-import { CodexAppClient, type ClientEvent, type Thread, type ThreadStatus } from "./app-client";
-import { RelayClient, type RelayAgentStatus, type RelayMessage } from "./relay";
-
-interface Config {
-  relayUrl: string;
-  appServerUrl: string;
-  cwd: string;
-  rig: string;
-  capabilities: string[];
-  tags: string[];
-  statePath: string;
-  pollIntervalMs: number;
-  heartbeatIntervalMs: number;
-  coalesceWindowMs: number;
-  reconnectInitialDelayMs: number;
-  reconnectMaxDelayMs: number;
-  threadMode: "auto" | "resume" | "start";
-  threadId?: string;
-  model?: string;
-  approvalPolicy?: string;
-  sandbox?: string;
-}
-
-interface RuntimeState {
-  agentId: string;
-  threadId: string;
-  activeTurnId: string | null;
-  threadStatus: ThreadStatus["type"];
-  lastSeenMessageId: number;
-  pendingMessageCount: number;
-  appConnected: boolean;
-  appServerUrl: string;
-  relayUrl: string;
-  cwd: string;
-  updatedAt: string;
-}
-
-interface DeliveryBatch {
-  messages: RelayMessage[];
-}
-
-class CodexLiveSidecar {
-  private readonly relay: RelayClient;
-  private readonly logPrefix = "[codex-live]";
-  private app: CodexAppClient;
-  private agentId = "";
-  private threadId = "";
-  private activeTurnId: string | null = null;
-  private threadStatus: ThreadStatus["type"] = "notLoaded";
-  private lastSeenMessageId = 0;
-  private lastHeartbeatAt = 0;
-  private stopping = false;
-  private appConnected = false;
-  private draining = false;
-  private drainDueAt = 0;
-  private reconnecting: Promise<void> | null = null;
-  private readonly pendingMessages = new Map<number, RelayMessage>();
-
-  constructor(private readonly config: Config) {
-    this.relay = new RelayClient(config.relayUrl, (msg) => this.log(msg));
-    this.app = this.createAppClient();
-  }
-
-  async run(): Promise<void> {
-    mkdirSync(dirname(this.config.statePath), { recursive: true });
-
-    process.on("SIGINT", () => void this.stop("SIGINT"));
-    process.on("SIGTERM", () => void this.stop("SIGTERM"));
-
-    await this.ensureAppReady();
-
-    const registration = await this.relay.registerAgent({
-      relayUrl: this.config.relayUrl,
-      cwd: this.config.cwd,
-      rig: this.config.rig,
-      capabilities: this.config.capabilities,
-      tags: this.config.tags,
-      threadId: this.threadId,
-      model: this.config.model,
-      appServerUrl: this.config.appServerUrl,
-    });
-    this.agentId = registration.agentId;
-
-    this.log(`registered agent ${this.agentId}`);
-    this.log(`using thread ${this.threadId}`);
-    this.writeState();
-    await this.refreshRelayStatus();
-
-    while (!this.stopping) {
-      try {
-        const now = Date.now();
-        if (now - this.lastHeartbeatAt >= this.config.heartbeatIntervalMs) {
-          await this.relay.heartbeat(this.agentId);
-          this.lastHeartbeatAt = now;
-        }
-
-        const messages = await this.relay.pollMessages(this.agentId, this.lastSeenMessageId);
-        if (messages.length > 0) {
-          this.addPendingMessages(messages);
-          this.writeState();
-        }
-
-        if (this.pendingMessages.size > 0 && now >= this.drainDueAt && !this.draining) {
-          await this.drainPendingMessages();
-        }
-      } catch (error) {
-        this.log(`loop error: ${describeError(error)}`);
-      }
-      await delay(this.config.pollIntervalMs);
-    }
-  }
-
-  private createAppClient(): CodexAppClient {
-    const app = new CodexAppClient(this.config.appServerUrl, (msg) => this.log(msg));
-    app.onEvent((event) => this.handleAppEvent(event));
-    app.onConnectionChange((connected) => {
-      this.appConnected = connected;
-      if (!connected) {
-        this.activeTurnId = null;
-        this.threadStatus = "notLoaded";
-        if (!this.stopping) void this.ensureAppReady();
-      }
-      void this.refreshRelayStatus();
-      this.writeState();
-    });
-    return app;
-  }
-
-  private async ensureAppReady(force = false): Promise<void> {
-    if (this.stopping) return;
-    if (this.appConnected && !force) return;
-    if (this.reconnecting) return this.reconnecting;
-
-    this.reconnecting = this.connectWithRetry(force).finally(() => {
-      this.reconnecting = null;
-    });
-    return this.reconnecting;
-  }
-
-  private async connectWithRetry(force: boolean): Promise<void> {
-    let waitMs = this.config.reconnectInitialDelayMs;
-
-    while (!this.stopping) {
-      try {
-        if (force) {
-          try {
-            this.app.close();
-          } catch {
-            // Ignore close failures during forced reconnect.
-          }
-          this.appConnected = false;
-        }
-
-        if (!this.app.isConnected()) {
-          this.app = this.createAppClient();
-          await this.app.connect();
-          await this.app.initialize();
-        }
-
-        const thread = this.threadId
-          ? await this.resumeKnownThread(this.threadId)
-          : await this.resolveThread();
-        this.threadId = thread.id;
-        this.syncThreadState(thread);
-        if (this.agentId) {
-          this.log(`app connection restored for thread ${thread.id}`);
-        }
-        return;
-      } catch (error) {
-        this.appConnected = false;
-        this.log(`app connection failed: ${describeError(error)}; retrying in ${waitMs}ms`);
-        await delay(waitMs);
-        waitMs = Math.min(this.config.reconnectMaxDelayMs, waitMs * 2);
-      }
-    }
-  }
-
-  private async stop(signal: string): Promise<void> {
-    if (this.stopping) return;
-    this.stopping = true;
-    this.log(`stopping on ${signal}`);
-    if (this.agentId) {
-      try {
-        await this.relay.setStatus(this.agentId, "offline");
-      } catch {
-        // Best effort during shutdown.
-      }
-    }
-    this.writeState();
-    this.app.close();
-  }
-
-  private async resumeKnownThread(threadId: string): Promise<Thread> {
-    try {
-      const resumed = await this.app.threadResume({
-        threadId,
-        cwd: this.config.cwd,
-        ...this.threadPermissions(),
-        persistExtendedHistory: false,
-      });
-      return normalizeThread(resumed.thread);
-    } catch (error) {
-      this.log(`resume failed for thread ${threadId}: ${describeError(error)}; falling back to thread resolution`);
-      this.threadId = "";
-      return this.resolveThread();
-    }
-  }
-
-  private async resolveThread(): Promise<Thread> {
-    if (this.config.threadId && this.config.threadMode !== "start") {
-      const resumed = await this.app.threadResume({
-        threadId: this.config.threadId,
-        cwd: this.config.cwd,
-        ...this.threadPermissions(),
-        persistExtendedHistory: false,
-      });
-      return normalizeThread(resumed.thread);
-    }
-
-    if (this.config.threadMode !== "start") {
-      const loaded = await this.app.threadLoadedList(20);
-      const loadedThreads: Thread[] = [];
-      for (const loadedThreadId of loaded.data) {
-        const thread = await this.readThreadWithFallback(loadedThreadId);
-        if (thread.cwd === this.config.cwd) loadedThreads.push(thread);
-      }
-      const activeLoaded = loadedThreads
-        .sort((a, b) => b.updatedAt - a.updatedAt)
-        .find((thread) => thread.status.type === "active") ?? loadedThreads.sort((a, b) => b.updatedAt - a.updatedAt)[0];
-      if (activeLoaded) return activeLoaded;
-
-      const listed = await this.app.threadList({ cwd: this.config.cwd, limit: 10, archived: false });
-      const latest = [...listed.data].sort((a, b) => b.updatedAt - a.updatedAt)[0];
-      if (latest) {
-        const resumed = await this.app.threadResume({
-          threadId: latest.id,
-          cwd: this.config.cwd,
-          ...this.threadPermissions(),
-          persistExtendedHistory: false,
-        });
-        return normalizeThread(resumed.thread);
-      }
-    }
-
-    const started = await this.app.threadStart({
-      cwd: this.config.cwd,
-      ...this.threadPermissions(),
-      ephemeral: false,
-      sessionStartSource: "startup",
-      model: this.config.model ?? null,
-    });
-    return normalizeThread(started.thread);
-  }
-
-  private threadPermissions(): Record<string, string> {
-    const payload: Record<string, string> = {};
-    if (this.config.approvalPolicy) payload.approvalPolicy = this.config.approvalPolicy;
-    if (this.config.sandbox) payload.sandbox = this.config.sandbox;
-    return payload;
-  }
-
-  private async readThreadWithFallback(threadId: string): Promise<Thread> {
-    try {
-      const read = await this.app.threadRead(threadId, true);
-      return normalizeThread(read.thread);
-    } catch (error) {
-      if (!isThreadMaterializationError(error)) throw error;
-      const read = await this.app.threadRead(threadId, false);
-      return normalizeThread(read.thread);
-    }
-  }
-
-  private syncThreadState(thread: Thread): void {
-    this.threadStatus = thread.status.type;
-    const turns = thread.turns ?? [];
-    const activeTurn = [...turns].reverse().find((turn) => turn.status === "inProgress");
-    this.activeTurnId = activeTurn?.id ?? null;
-    void this.refreshRelayStatus();
-    this.writeState();
-  }
-
-  private handleAppEvent(event: ClientEvent): void {
-    if (event.type !== "notification") return;
-    const { method, params } = event.message;
-
-    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"];
-        void this.refreshRelayStatus();
-        this.writeState();
-      }
-      return;
-    }
-
-    if (method === "turn/started") {
-      if (params?.threadId === this.threadId && params.turn && typeof params.turn === "object" && "id" in params.turn) {
-        this.activeTurnId = String(params.turn.id);
-        this.threadStatus = "active";
-        void this.refreshRelayStatus();
-        this.writeState();
-      }
-      return;
-    }
-
-    if (method === "turn/completed") {
-      if (params?.threadId === this.threadId && params.turn && typeof params.turn === "object") {
-        const completedId = "id" in params.turn ? String(params.turn.id) : null;
-        if (completedId && this.activeTurnId === completedId) this.activeTurnId = null;
-        this.threadStatus = "idle";
-        void this.refreshRelayStatus();
-        this.writeState();
-      }
-    }
-  }
-
-  private async refreshRelayStatus(): Promise<void> {
-    if (!this.agentId) return;
-
-    const status: RelayAgentStatus = !this.appConnected
-      ? "online"
-      : this.activeTurnId || this.threadStatus === "active"
-        ? "busy"
-        : "idle";
-    const ready = this.appConnected && Boolean(this.threadId);
-
-    try {
-      await Promise.all([
-        this.relay.setStatus(this.agentId, status),
-        this.relay.setReady(this.agentId, ready),
-      ]);
-    } catch {
-      // Best-effort status sync.
-    }
-  }
-
-  private addPendingMessages(messages: RelayMessage[]): void {
-    let added = false;
-    for (const message of messages) {
-      if (this.pendingMessages.has(message.id)) continue;
-      this.pendingMessages.set(message.id, message);
-      this.lastSeenMessageId = Math.max(this.lastSeenMessageId, message.id);
-      added = true;
-    }
-
-    if (added && this.drainDueAt === 0) {
-      this.drainDueAt = Date.now() + this.config.coalesceWindowMs;
-    }
-  }
-
-  private async drainPendingMessages(): Promise<void> {
-    if (this.draining || this.pendingMessages.size === 0) return;
-
-    this.draining = true;
-    const sorted = [...this.pendingMessages.values()].sort((a, b) => a.id - b.id);
-    this.pendingMessages.clear();
-    this.drainDueAt = 0;
-
-    try {
-      await this.ensureAppReady();
-      const batches = createDeliveryBatches(sorted);
-      for (let index = 0; index < batches.length; index += 1) {
-        const batch = batches[index]!;
-        try {
-          await this.deliverBatch(batch);
-        } catch (error) {
-          this.requeueBatches(batches.slice(index));
-          this.log(`delivery error: ${describeError(error)}`);
-          await this.ensureAppReady(true);
-          break;
-        }
-      }
-    } finally {
-      this.draining = false;
-      this.writeState();
-    }
-  }
-
-  private requeueBatches(batches: DeliveryBatch[]): void {
-    for (const batch of batches) {
-      for (const message of batch.messages) {
-        this.pendingMessages.set(message.id, message);
-      }
-    }
-    if (this.pendingMessages.size > 0) {
-      this.drainDueAt = Date.now() + Math.min(this.config.coalesceWindowMs, 250);
-    }
-  }
-
-  private async deliverBatch(batch: DeliveryBatch): Promise<void> {
-    await this.ensureAppReady();
-
-    for (const message of batch.messages) {
-      if (!message.claimable) continue;
-      const claimed = await this.relay.claimMessage(message.id, this.agentId);
-      if (!claimed) {
-        this.log(`skipping unclaimed message ${message.id}`);
-        return;
-      }
-    }
-
-    const delivery = this.pickDeliveryMode(batch.messages);
-    const prompt = formatRelayPrompt(batch.messages);
-    const ids = batch.messages.map((message) => message.id).join(", ");
-    this.log(`delivering message ${ids} via ${delivery}`);
-
-    if (delivery === "interrupt" && this.activeTurnId) {
-      try {
-        await this.app.turnInterrupt(this.threadId, this.activeTurnId);
-        this.activeTurnId = null;
-        this.threadStatus = "idle";
-        await this.app.settle(200);
-      } catch (error) {
-        this.log(`interrupt failed for messages ${ids}: ${describeError(error)}`);
-      }
-    }
-
-    if (delivery === "steer" && this.activeTurnId) {
-      try {
-        await this.app.turnSteer(this.threadId, this.activeTurnId, prompt);
-        await this.markBatchRead(batch.messages);
-        this.writeState();
-        return;
-      } catch (error) {
-        this.log(`steer failed for messages ${ids}, falling back to start: ${describeError(error)}`);
-      }
-    }
-
-    await this.app.turnStart(this.threadId, prompt);
-    await this.markBatchRead(batch.messages);
-    this.writeState();
-  }
-
-  private async markBatchRead(messages: RelayMessage[]): Promise<void> {
-    for (const message of messages) {
-      await this.relay.markRead(message.id, this.agentId);
-    }
-  }
-
-  private pickDeliveryMode(messages: RelayMessage[]): "start" | "steer" | "interrupt" {
-    const first = messages[0]!;
-    const meta = first.meta ?? {};
-    const requested = typeof meta.delivery === "string" ? meta.delivery : null;
-    const priority = typeof meta.priority === "string" ? meta.priority : null;
-
-    if (requested === "interrupt") return "interrupt";
-    if (requested === "start") return "start";
-    if (requested === "steer") return this.activeTurnId ? "steer" : "start";
-    if (priority === "urgent") return this.activeTurnId ? "interrupt" : "start";
-    return this.activeTurnId ? "steer" : "start";
-  }
-
-  private writeState(): void {
-    if (!this.threadId) return;
-    const state: RuntimeState = {
-      agentId: this.agentId,
-      threadId: this.threadId,
-      activeTurnId: this.activeTurnId,
-      threadStatus: this.threadStatus,
-      lastSeenMessageId: this.lastSeenMessageId,
-      pendingMessageCount: this.pendingMessages.size,
-      appConnected: this.appConnected,
-      appServerUrl: this.config.appServerUrl,
-      relayUrl: this.config.relayUrl,
-      cwd: this.config.cwd,
-      updatedAt: new Date().toISOString(),
-    };
-    writeFileSync(this.config.statePath, JSON.stringify(state, null, 2));
-  }
-
-  private log(message: string): void {
-    console.error(`${this.logPrefix} ${message}`);
-  }
-}
-
-function createDeliveryBatches(messages: RelayMessage[]): DeliveryBatch[] {
-  const batches: DeliveryBatch[] = [];
-  let current: RelayMessage[] = [];
-
-  for (const message of messages) {
-    if (shouldIsolateMessage(message)) {
-      if (current.length > 0) {
-        batches.push({ messages: current });
-        current = [];
-      }
-      batches.push({ messages: [message] });
-      continue;
-    }
-
-    current.push(message);
-  }
-
-  if (current.length > 0) batches.push({ messages: current });
-  return batches;
-}
-
-function shouldIsolateMessage(message: RelayMessage): boolean {
-  if (message.claimable) return true;
-  const meta = message.meta ?? {};
-  const delivery = typeof meta.delivery === "string" ? meta.delivery : null;
-  const priority = typeof meta.priority === "string" ? meta.priority : null;
-  return delivery === "interrupt" || delivery === "start" || delivery === "steer" || priority === "urgent";
-}
-
-function formatRelayPrompt(messages: RelayMessage[]): string {
-  if (messages.length === 1) {
-    const message = messages[0]!;
-    const lines = [
-      "Agent Relay message received.",
-      "",
-      `Message ID: ${message.id}`,
-      `From: ${message.from}`,
-      `To: ${message.to}`,
-      `Created: ${new Date(message.createdAt).toISOString()}`,
-    ];
-
-    if (message.subject) lines.push(`Subject: ${message.subject}`);
-    if (message.replyTo) lines.push(`Reply To: ${message.replyTo}`);
-    lines.push(
-      "",
-      "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.",
-      `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}.`,
-    );
-    return lines.join("\n");
-  }
-
-  const lines = [
-    "Agent Relay message batch received.",
-    "",
-    `Count: ${messages.length}`,
-    "",
-  ];
-
-  for (const message of messages) {
-    lines.push(
-      `Message ID: ${message.id}`,
-      `From: ${message.from}`,
-      `To: ${message.to}`,
-      `Created: ${new Date(message.createdAt).toISOString()}`,
-    );
-    if (message.subject) lines.push(`Subject: ${message.subject}`);
-    if (message.replyTo) lines.push(`Reply To: ${message.replyTo}`);
-    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.`,
-  );
-  return lines.join("\n");
-}
-
-function normalizeThread(thread: Thread): Thread {
-  return {
-    ...thread,
-    turns: thread.turns ?? [],
-  };
-}
-
-function isThreadMaterializationError(error: unknown): boolean {
-  return describeError(error).includes("not materialized yet");
-}
-
-function describeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function envNumber(env: NodeJS.ProcessEnv, name: string, fallback: number): number {
-  const raw = env[name];
-  if (!raw) return fallback;
-  const parsed = Number(raw);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
-}
-
-export function parseThreadMode(raw: string | undefined): Config["threadMode"] {
-  if (raw === "auto" || raw === "resume" || raw === "start") return raw;
-  return "start";
-}
-
-export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
-  const cwd = env.CODEX_LIVE_CWD || process.cwd();
-  const capabilities = (env.AGENT_RELAY_CAPS || "chat")
-    .split(",")
-    .map((value) => value.trim())
-    .filter(Boolean);
-
-  return {
-    relayUrl: env.AGENT_RELAY_URL || "http://127.0.0.1:4850",
-    appServerUrl: env.CODEX_APP_SERVER_URL || "ws://127.0.0.1:4501",
-    cwd,
-    rig: env.CODEX_LIVE_RIG || "codex-live",
-    capabilities,
-    tags: ["codex", env.CODEX_LIVE_RIG || "codex-live", cwd.split("/").filter(Boolean).at(-1) || "unknown"],
-    statePath: env.CODEX_LIVE_STATE_PATH || resolve(cwd, "codex/runtime/live-state.json"),
-    pollIntervalMs: envNumber(env, "CODEX_LIVE_POLL_INTERVAL_MS", 2000),
-    heartbeatIntervalMs: envNumber(env, "CODEX_LIVE_HEARTBEAT_INTERVAL_MS", 30000),
-    coalesceWindowMs: envNumber(env, "CODEX_LIVE_COALESCE_WINDOW_MS", 600),
-    reconnectInitialDelayMs: envNumber(env, "CODEX_LIVE_RECONNECT_INITIAL_MS", 1000),
-    reconnectMaxDelayMs: envNumber(env, "CODEX_LIVE_RECONNECT_MAX_MS", 10000),
-    threadMode: parseThreadMode(env.CODEX_THREAD_MODE),
-    threadId: env.CODEX_THREAD_ID || undefined,
-    model: env.CODEX_MODEL || undefined,
-    approvalPolicy: env.CODEX_LIVE_APPROVAL_POLICY || undefined,
-    sandbox: env.CODEX_LIVE_SANDBOX || undefined,
-  };
-}
-
-async function main(): Promise<void> {
-  const config = loadConfig();
-  const sidecar = new CodexLiveSidecar(config);
-  await sidecar.run();
-}
-
-if (import.meta.main) {
-  main().catch((error) => {
-    console.error(error instanceof Error ? error.stack || error.message : String(error));
-    process.exit(1);
-  });
-}

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

@@ -1,40 +0,0 @@
-{
-  "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/codex/plugin/skills/agent-relay/SKILL.md

@@ -1,29 +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>`.
-
-## 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.