agent-relay-codex 0.4.16 → 0.4.18

package/README.md

@@ -42,7 +42,31 @@ bunx -p agent-relay-codex@latest codex-relay
 | `AGENT_RELAY_CAPS` | `chat` | Comma-separated capabilities |
 | `AGENT_RELAY_APPROVAL` | `open` | Approval mode: `open`, `guarded`, `read-only` |
 
-These four env vars are shared with the [Claude plugin](https://www.npmjs.com/package/agent-relay-plugin).
+These env vars are shared with the [Claude plugin](https://www.npmjs.com/package/agent-relay-plugin). Agent profiles are also shared:
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `AGENT_RELAY_PROFILE` | — | Profile name from the profiles file |
+| `AGENT_RELAY_PROFILES_FILE` | `~/.config/agent-relay/profiles.json` | JSON profile file |
+| `AGENT_RELAY_TAGS` | — | Extra comma-separated tags |
+| `AGENT_RELAY_LABEL` | — | Human-friendly label |
+| `AGENT_RELAY_CHANNELS` | all | Comma-separated channel subscriptions |
+
+Example profile:
+
+```json
+{
+  "frontend-developer": {
+    "label": "frontend dev",
+    "tags": ["frontend", "ui"],
+    "capabilities": ["chat", "review", "frontend"],
+    "channels": ["frontend"],
+    "approval": "guarded"
+  }
+}
+```
+
+Run with `AGENT_RELAY_PROFILE=frontend-developer agent-relay-codex start`.
 
 ### Codex-specific
 
@@ -110,6 +134,25 @@ agent-relay-codex uninstall --purge  # also remove runtime state and PATH entrie
 
 Message delivery adapts to thread state: `turn/start` when idle, `turn/steer` when active, `turn/interrupt` for urgent messages.
 
+## Command Skills
+
+The Codex plugin ships command skills for Agent Relay slash commands:
+
+```bash
+/pair codex "Debug flaky tests"
+/message codex "Can you look at that failing action?"
+/send-claimable tag:backend "Please claim and fix the failing API test"
+/disconnect
+/status
+/label backend-fixer
+/tags backend tests urgent
+```
+
+If another installed skill uses the same name, invoke the prefixed form such as
+`/agent-relay:pair`, `/agent-relay:message`,
+`/agent-relay:send-claimable`, `/agent-relay:disconnect`,
+`/agent-relay:status`, `/agent-relay:label`, or `/agent-relay:tags`.
+
 ## Development
 
 ```bash

package/bin/agent-relay-codex.ts

@@ -6,6 +6,7 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import net from "node:net";
 import { approvalModeFromPermissions, codexArgsForApprovalMode, parseApprovalMode } from "../approval";
+import { loadAgentRelayProfile } from "../profile";
 
 type HooksJson = {
   hooks?: Record<string, Array<{ matcher?: string; hooks?: Array<Record<string, unknown>> }>>;
@@ -772,8 +773,12 @@ async function start(args: string[]): Promise<void> {
   let relayUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
   let listenUrl = process.env.CODEX_APP_SERVER_URL || "";
   let threadMode = process.env.CODEX_THREAD_MODE || "start";
-  const requestedApprovalMode = parseApprovalMode(process.env.AGENT_RELAY_APPROVAL);
-  const hasApprovalEnv = process.env.AGENT_RELAY_APPROVAL !== undefined;
+  const cwd = process.cwd();
+  const rig = process.env.AGENT_RELAY_CODEX_RIG || "codex-live";
+  const project = cwd.split("/").filter(Boolean).at(-1) || "unknown";
+  const profile = loadAgentRelayProfile(process.env, { provider: "codex", rig, project });
+  const requestedApprovalMode = profile.approval ?? parseApprovalMode(process.env.AGENT_RELAY_APPROVAL);
+  const hasApprovalEnv = process.env.AGENT_RELAY_APPROVAL !== undefined || profile.approval !== undefined;
   const codexArgs: string[] = [];
 
   for (let index = 0; index < args.length; index += 1) {

package/hooks/session-start.ts

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } fr
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { describeApprovalMode, parseApprovalMode } from "../approval.ts";
+import { loadAgentRelayProfile } from "../profile.ts";
 import { buildAgentIdentity } from "../relay.ts";
 import { pickThreadId, type HookInput } from "./session-start-lib.ts";
 
@@ -69,7 +70,9 @@ const cwd = input.cwd || process.cwd();
 const threadId = pickThreadId(input);
 const relayUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
 const rig = process.env.AGENT_RELAY_CODEX_RIG || "codex-live";
-const approvalMode = parseApprovalMode(process.env.AGENT_RELAY_APPROVAL);
+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 (!appServerUrl || !runId) {
   outputContext(
@@ -102,8 +105,12 @@ if (activePid !== null) {
       relayUrl,
       cwd,
       rig,
-      capabilities: (process.env.AGENT_RELAY_CAPS || "chat").split(",").map((value) => value.trim()).filter(Boolean),
-      tags: ["codex", rig, cwd.split("/").filter(Boolean).at(-1) || "unknown"],
+      label: profile.label,
+      capabilities: profile.capabilities,
+      tags: profile.tags,
+      channels: profile.channels,
+      profileName: profile.profileName,
+      profileMeta: profile.meta,
       threadId,
       model: input.model,
       appServerUrl,
@@ -121,6 +128,7 @@ const spawnEnv: Record<string, string | undefined> = {
   AGENT_RELAY_CODEX_CWD: cwd,
   AGENT_RELAY_CODEX_STATE_PATH: statePath,
   CODEX_MODEL: input.model || process.env.CODEX_MODEL || "",
+  AGENT_RELAY_APPROVAL: process.env.AGENT_RELAY_APPROVAL || profile.approval || "",
 };
 if (threadId) {
   spawnEnv.CODEX_THREAD_ID = threadId;
@@ -168,27 +176,37 @@ const identity = buildAgentIdentity({
   relayUrl,
   cwd,
   rig,
-  capabilities: (process.env.AGENT_RELAY_CAPS || "chat").split(",").map((value) => value.trim()).filter(Boolean),
-  tags: ["codex", rig, cwd.split("/").filter(Boolean).at(-1) || "unknown"],
+  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(buildStartupContext(identity.id, relayUrl, approvalMode, profile));
 
-function buildStartupContext(agentId: string, url: string, mode: string): string {
+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.",
-  ].join(" ");
+  ].filter(Boolean).join(" ");
 }

package/live-sidecar.ts

@@ -1,17 +1,23 @@
 import { mkdirSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { dirname, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
-import { approvalModeFromPermissions, parseApprovalMode, type ApprovalMode } from "./approval";
+import { approvalModeFromPermissions, type ApprovalMode } from "./approval";
 import { CodexAppClient, type ClientEvent, type Thread, type ThreadStatus } from "./app-client";
-import { RelayClient, RelayHttpError, type RelayAgentStatus, type RelayMessage } from "./relay";
+import { loadAgentRelayProfile, messageMatchesProfileChannels } from "./profile";
+import { RelayClient, RelayHttpError, type RelayAgentSession, type RelayAgentStatus, type RelayMessage } from "./relay";
 
 interface Config {
   relayUrl: string;
   appServerUrl: string;
   cwd: string;
   rig: string;
+  label?: string;
   capabilities: string[];
   tags: string[];
+  channels: string[];
+  profileName?: string;
+  profileMeta: Record<string, unknown>;
   statePath: string;
   pollIntervalMs: number;
   heartbeatIntervalMs: number;
@@ -30,6 +36,8 @@ interface Config {
 
 interface RuntimeState {
   agentId: string;
+  agentInstanceId: string;
+  agentEpoch: number;
   threadId: string;
   activeTurnId: string | null;
   threadStatus: ThreadStatus["type"];
@@ -46,11 +54,22 @@ interface DeliveryBatch {
   messages: RelayMessage[];
 }
 
+export function activeClaimRenewalIds(
+  messageIds: Iterable<number>,
+  activeTurnId: string | null,
+  threadStatus: ThreadStatus["type"],
+): number[] {
+  if (!activeTurnId && threadStatus !== "active") return [];
+  return [...messageIds];
+}
+
 class CodexLiveSidecar {
   private readonly relay: RelayClient;
   private readonly logPrefix = "[codex-live]";
   private app: CodexAppClient;
   private agentId = "";
+  private readonly agentInstanceId = randomUUID();
+  private agentEpoch = 0;
   private threadId = "";
   private activeTurnId: string | null = null;
   private threadStatus: ThreadStatus["type"] = "notLoaded";
@@ -58,12 +77,14 @@ class CodexLiveSidecar {
   private lastHeartbeatAt = 0;
   private hasSuccessfulPoll = false;
   private relayBackoffMs = 0;
+  private lastClaimRenewalAt = 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>();
+  private readonly activeClaimedMessageIds = new Set<number>();
 
   constructor(private readonly config: Config) {
     this.relay = new RelayClient(config.relayUrl, (msg) => this.log(msg));
@@ -85,9 +106,13 @@ class CodexLiveSidecar {
       try {
         const now = Date.now();
         if (now - this.lastHeartbeatAt >= this.config.heartbeatIntervalMs) {
-          await this.relay.heartbeat(this.agentId);
+          await this.relay.heartbeat(this.agentId, this.agentSession());
           this.lastHeartbeatAt = now;
         }
+        if (now - this.lastClaimRenewalAt >= this.config.heartbeatIntervalMs) {
+          await this.renewActiveClaims();
+          this.lastClaimRenewalAt = now;
+        }
 
         const messages = await this.relay.pollMessages(this.agentId, this.lastSeenMessageId);
         if (!this.hasSuccessfulPoll) {
@@ -95,7 +120,10 @@ class CodexLiveSidecar {
           await this.refreshRelayStatus();
         }
         if (messages.length > 0) {
-          this.addPendingMessages(messages);
+          const deliverableMessages = messages.filter((message) => messageMatchesProfileChannels(message, this.config.channels));
+          const skippedMessages = messages.filter((message) => !messageMatchesProfileChannels(message, this.config.channels));
+          if (skippedMessages.length > 0) this.advanceCursor(skippedMessages);
+          this.addPendingMessages(deliverableMessages);
           this.writeState();
         }
 
@@ -107,6 +135,11 @@ class CodexLiveSidecar {
         if (error instanceof RelayHttpError && error.status === 404 && error.path.includes("/heartbeat")) {
           this.log("heartbeat returned 404; re-registering relay agent");
           await this.registerRelayAgent();
+        } else if (error instanceof RelayHttpError && error.status === 409) {
+          this.log("relay rejected this stale agent instance; stopping sidecar");
+          this.stopping = true;
+          this.writeState();
+          this.app.close();
         } else {
           sleepMs = this.nextRelayBackoffMs();
           this.log(`loop error: ${describeError(error)}; retrying in ${sleepMs}ms`);
@@ -121,14 +154,20 @@ class CodexLiveSidecar {
       relayUrl: this.config.relayUrl,
       cwd: this.config.cwd,
       rig: this.config.rig,
+      label: this.config.label,
       capabilities: this.config.capabilities,
       tags: this.config.tags,
+      channels: this.config.channels,
+      profileName: this.config.profileName,
+      profileMeta: this.config.profileMeta,
       threadId: this.threadId,
       model: this.config.model,
       appServerUrl: this.config.appServerUrl,
       approvalMode: this.config.approvalMode,
+      instanceId: this.agentInstanceId,
     });
     this.agentId = registration.agentId;
+    this.agentEpoch = registration.session?.epoch ?? 0;
     this.lastSeenMessageId = await this.relay.getCursor();
     this.lastHeartbeatAt = 0;
     this.hasSuccessfulPoll = false;
@@ -210,7 +249,7 @@ class CodexLiveSidecar {
     this.log(`stopping on ${signal}`);
     if (this.agentId) {
       try {
-        await this.relay.setStatus(this.agentId, "offline");
+        await this.relay.setStatus(this.agentId, "offline", this.agentSession());
       } catch {
         // Best effort during shutdown.
       }
@@ -304,6 +343,7 @@ class CodexLiveSidecar {
     const turns = thread.turns ?? [];
     const activeTurn = [...turns].reverse().find((turn) => turn.status === "inProgress");
     this.activeTurnId = activeTurn?.id ?? null;
+    if (!this.activeTurnId && this.threadStatus !== "active") this.activeClaimedMessageIds.clear();
     void this.refreshRelayStatus();
     this.writeState();
   }
@@ -336,6 +376,7 @@ class CodexLiveSidecar {
         const completedId = "id" in params.turn ? String(params.turn.id) : null;
         if (completedId && this.activeTurnId === completedId) this.activeTurnId = null;
         this.threadStatus = "idle";
+        this.activeClaimedMessageIds.clear();
         void this.refreshRelayStatus();
         this.writeState();
       }
@@ -354,14 +395,35 @@ class CodexLiveSidecar {
 
     try {
       await Promise.all([
-        this.relay.setStatus(this.agentId, status),
-        this.relay.setReady(this.agentId, ready),
+        this.relay.setStatus(this.agentId, status, this.agentSession()),
+        this.relay.setReady(this.agentId, ready, this.agentSession()),
       ]);
     } catch {
       // Best-effort status sync.
     }
   }
 
+  private async renewActiveClaims(): Promise<void> {
+    if (!this.agentId || this.activeClaimedMessageIds.size === 0) return;
+    const renewals = activeClaimRenewalIds(this.activeClaimedMessageIds, this.activeTurnId, this.threadStatus);
+    if (renewals.length === 0) {
+      this.activeClaimedMessageIds.clear();
+      return;
+    }
+
+    for (const messageId of renewals) {
+      try {
+        const renewed = await this.relay.renewMessageClaim(messageId, this.agentId, this.agentSession());
+        if (!renewed) {
+          this.activeClaimedMessageIds.delete(messageId);
+          this.log(`claim renewal rejected for message ${messageId}`);
+        }
+      } catch (error) {
+        this.log(`claim renewal failed for message ${messageId}: ${describeError(error)}`);
+      }
+    }
+  }
+
   private addPendingMessages(messages: RelayMessage[]): void {
     let added = false;
     for (const message of messages) {
@@ -417,15 +479,17 @@ class CodexLiveSidecar {
   private async deliverBatch(batch: DeliveryBatch): Promise<void> {
     await this.ensureAppReady();
 
+    const claimedMessageIds: number[] = [];
     for (const message of batch.messages) {
       if (!message.claimable) continue;
-      const claimed = await this.relay.claimMessage(message.id, this.agentId);
+      const claimed = await this.relay.claimMessage(message.id, this.agentId, this.agentSession());
       if (!claimed) {
         this.log(`skipping unclaimed message ${message.id}`);
         this.advanceCursor([message]);
         this.writeState();
         return;
       }
+      claimedMessageIds.push(message.id);
     }
 
     const delivery = this.pickDeliveryMode(batch.messages);
@@ -447,6 +511,7 @@ class CodexLiveSidecar {
     if (delivery === "steer" && this.activeTurnId) {
       try {
         await this.app.turnSteer(this.threadId, this.activeTurnId, prompt);
+        for (const id of claimedMessageIds) this.activeClaimedMessageIds.add(id);
         await this.markBatchRead(batch.messages);
         this.advanceCursor(batch.messages);
         this.writeState();
@@ -457,6 +522,7 @@ class CodexLiveSidecar {
     }
 
     await this.app.turnStart(this.threadId, prompt);
+    for (const id of claimedMessageIds) this.activeClaimedMessageIds.add(id);
     await this.markBatchRead(batch.messages);
     this.advanceCursor(batch.messages);
     this.writeState();
@@ -474,6 +540,10 @@ class CodexLiveSidecar {
     }
   }
 
+  private agentSession(): RelayAgentSession | undefined {
+    return this.agentEpoch > 0 ? { instanceId: this.agentInstanceId, epoch: this.agentEpoch } : undefined;
+  }
+
   private pickDeliveryMode(messages: RelayMessage[]): "start" | "steer" | "interrupt" {
     const first = messages[0]!;
     const meta = first.meta ?? {};
@@ -491,6 +561,8 @@ class CodexLiveSidecar {
     if (!this.threadId) return;
     const state: RuntimeState = {
       agentId: this.agentId,
+      agentInstanceId: this.agentInstanceId,
+      agentEpoch: this.agentEpoch,
       threadId: this.threadId,
       activeTurnId: this.activeTurnId,
       threadStatus: this.threadStatus,
@@ -562,6 +634,9 @@ 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(
       "",
       "Body:",
@@ -569,7 +644,9 @@ export function formatRelayPrompt(messages: RelayMessage[]): string {
       "",
       "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}.`,
+      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}.`,
     );
     return lines.join("\n");
   }
@@ -591,6 +668,7 @@ 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("Body:", message.body, "", "---", "");
   }
 
@@ -637,18 +715,21 @@ export function parseThreadMode(raw: string | undefined): Config["threadMode"] {
 
 export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
   const cwd = env.AGENT_RELAY_CODEX_CWD || process.cwd();
-  const capabilities = (env.AGENT_RELAY_CAPS || "chat")
-    .split(",")
-    .map((value) => value.trim())
-    .filter(Boolean);
+  const rig = env.AGENT_RELAY_CODEX_RIG || "codex-live";
+  const project = cwd.split("/").filter(Boolean).at(-1) || "unknown";
+  const profile = loadAgentRelayProfile(env, { provider: "codex", rig, project });
 
   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.AGENT_RELAY_CODEX_RIG || "codex-live",
-    capabilities,
-    tags: ["codex", env.AGENT_RELAY_CODEX_RIG || "codex-live", cwd.split("/").filter(Boolean).at(-1) || "unknown"],
+    rig,
+    label: profile.label,
+    capabilities: profile.capabilities,
+    tags: profile.tags,
+    channels: profile.channels,
+    profileName: profile.profileName,
+    profileMeta: profile.meta,
     statePath: env.AGENT_RELAY_CODEX_STATE_PATH || resolve(cwd, "codex/runtime/live-state.json"),
     pollIntervalMs: envNumber(env, "AGENT_RELAY_CODEX_POLL_INTERVAL_MS", 2000),
     heartbeatIntervalMs: envNumber(env, "AGENT_RELAY_CODEX_HEARTBEAT_INTERVAL_MS", 30000),
@@ -662,8 +743,8 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): Config {
     model: env.CODEX_MODEL || undefined,
     approvalPolicy: env.AGENT_RELAY_CODEX_APPROVAL_POLICY || undefined,
     sandbox: env.AGENT_RELAY_CODEX_SANDBOX || undefined,
-    approvalMode: env.AGENT_RELAY_APPROVAL
-      ? parseApprovalMode(env.AGENT_RELAY_APPROVAL)
+    approvalMode: profile.approval
+      ? profile.approval
       : approvalModeFromPermissions({
         approvalPolicy: env.AGENT_RELAY_CODEX_APPROVAL_POLICY,
         sandbox: env.AGENT_RELAY_CODEX_SANDBOX,

package/package.json

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

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

@@ -24,6 +24,40 @@ curl -sS -X POST "${AGENT_RELAY_URL:-http://127.0.0.1:4850}/api/messages" \
 
 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

@@ -0,0 +1,16 @@
+---
+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

@@ -0,0 +1,23 @@
+---
+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

@@ -0,0 +1,24 @@
+---
+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

@@ -0,0 +1,26 @@
+---
+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

@@ -0,0 +1,24 @@
+---
+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

@@ -0,0 +1,16 @@
+---
+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

@@ -0,0 +1,25 @@
+---
+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

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseApprovalMode, type ApprovalMode } from "./approval";
+
+export interface AgentRelayProfile {
+  label?: string;
+  tags?: string[];
+  capabilities?: string[];
+  channels?: string[];
+  approval?: ApprovalMode;
+  meta?: Record<string, unknown>;
+}
+
+export interface ResolvedAgentProfile {
+  profileName?: string;
+  label?: string;
+  tags: string[];
+  capabilities: string[];
+  channels: string[];
+  approval?: ApprovalMode;
+  meta: Record<string, unknown>;
+}
+
+export 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

@@ -6,10 +6,14 @@ export interface RelayMessage {
   id: number;
   from: string;
   to: string;
+  channel?: string;
   subject?: string;
   body: string;
   replyTo?: number;
   claimable?: boolean;
+  claimedBy?: string;
+  claimedAt?: number;
+  claimExpiresAt?: number;
   type?: string;
   meta?: Record<string, unknown>;
   createdAt: number;
@@ -19,12 +23,22 @@ export 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 } {
@@ -39,16 +53,18 @@ export function buildAgentIdentity(config: RelayConfig): { id: string; name: str
 export class RelayClient {
   constructor(private readonly baseUrl: string, private readonly log: (msg: string) => void = () => {}) {}
 
-  async registerAgent(config: RelayConfig): Promise<{ agentId: string; project: string }> {
+  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: {
         client: "codex-live",
         threadId: config.threadId,
@@ -56,15 +72,23 @@ export class RelayClient {
         cwd: config.cwd,
         model: config.model || null,
         approvalMode: config.approvalMode || "open",
+        channels: config.channels ?? [],
+        profile: config.profileName || null,
+        ...(config.profileMeta ?? {}),
       },
     };
 
-    await this.json("POST", "/api/agents", payload);
-    return { agentId: identity.id, project: identity.project };
+    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): Promise<void> {
-    await this.json("POST", `/api/agents/${encodeURIComponent(agentId)}/heartbeat`);
+  async heartbeat(agentId: string, session?: RelayAgentSession): Promise<void> {
+    await this.json("POST", `/api/agents/${encodeURIComponent(agentId)}/heartbeat`, session);
   }
 
   async getCursor(): Promise<number> {
@@ -72,12 +96,12 @@ export class RelayClient {
     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 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): Promise<void> {
-    await this.json("PATCH", `/api/agents/${encodeURIComponent(agentId)}/ready`, { ready });
+  async setReady(agentId: string, ready: boolean, session?: RelayAgentSession): Promise<void> {
+    await this.json("PATCH", `/api/agents/${encodeURIComponent(agentId)}/ready`, { ready, ...session });
   }
 
   async pollMessages(agentId: string, sinceId: number): Promise<RelayMessage[]> {
@@ -92,11 +116,11 @@ export class RelayClient {
     return (await response.json()) as RelayMessage[];
   }
 
-  async claimMessage(messageId: number, agentId: string): Promise<boolean> {
+  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 }),
+      body: JSON.stringify({ agentId, ...session }),
     });
 
     if (response.ok) return true;
@@ -105,6 +129,19 @@ export class RelayClient {
     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 });
   }