agent-relay-server 0.4.15 → 0.4.17

package/src/cli.ts

@@ -1,5 +1,7 @@
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
 import {
   createDaemonPlan,
   detectDaemonEnvironment,
@@ -23,8 +25,25 @@ Usage:
   agent-relay [start]
   agent-relay setup [--yes] [--dry-run] [--force] [--env-file PATH] [--host HOST] [--port PORT] [--db-path PATH] [--token TOKEN|--no-token]
   agent-relay daemon <install|uninstall|start|stop|restart|enable|disable|status|logs> [options]
+  agent-relay pair <target|create|status|accept|reject|hangup|send> [options]
+  agent-relay /pair <target|accept|reject|send|status> [...]
+  agent-relay /disconnect [PAIR_ID]
+  agent-relay /status
+  agent-relay /label [LABEL]
+  agent-relay /tags [TAG ...]
   agent-relay --help
 
+Pair examples:
+  agent-relay pair codex --objective "Debug flaky tests"
+  agent-relay /pair codex "Debug flaky tests"
+  agent-relay pair status
+  agent-relay pair accept PAIR_ID --agent AGENT_ID
+  agent-relay pair send PAIR_ID --from AGENT_ID --body "What do you see?"
+  agent-relay /disconnect
+  agent-relay /status
+  agent-relay /label backend-fixer
+  agent-relay /tags backend tests urgent
+
 Daemon options:
   --env-file PATH   Env file sourced by the daemon (default: platform user config dir)
   --binary PATH     Stable agent-relay binary/script path for the service
@@ -71,9 +90,41 @@ export async function handleCli(args: string[]): Promise<"start" | "handled"> {
     await handleDaemonCommand(args.slice(1));
     return "handled";
   }
+  if (command === "pair" || command === "/pair" || command === "/disconnect") {
+    await handleSlashOrPairCommand(command, args.slice(1));
+    return "handled";
+  }
+  if (command === "/status" || command === "status") {
+    await handleStatusCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "/label" || command === "label") {
+    await handleLabelCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "/tags" || command === "tags") {
+    await handleTagsCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "/reconnect") {
+    console.log("Reconnect is handled automatically by provider sidecars; use `agent-relay pair status` to inspect current pair state.");
+    return "handled";
+  }
   throw new Error(`Unknown command "${command}". Run agent-relay --help.`);
 }
 
+async function handleSlashOrPairCommand(command: string, args: string[]): Promise<void> {
+  if (command === "/disconnect") {
+    await handlePairCommand(["hangup", ...args]);
+    return;
+  }
+  if (command === "/pair") {
+    await handlePairCommand(args);
+    return;
+  }
+  await handlePairCommand(args);
+}
+
 async function handleSetupCommand(args: string[]): Promise<void> {
   let envFile: string | undefined;
   let host: string | undefined;
@@ -205,6 +256,339 @@ function parseDaemonAction(value: string | undefined): DaemonAction {
   return value as DaemonAction;
 }
 
+async function handlePairCommand(args: string[]): Promise<void> {
+  if (!args.length) throw new Error("Usage: agent-relay pair <target|create|status|accept|reject|hangup|send> [options]");
+  const knownActions = new Set(["create", "status", "list", "accept", "reject", "hangup", "disconnect", "send"]);
+  const action = knownActions.has(args[0]!) ? args[0]! : "create";
+  const rest = action === "create" && args[0] !== "create" ? args : args.slice(1);
+
+  if (action === "status" || action === "list") {
+    let agent: string | undefined = await detectAgentId();
+    let status: string | undefined;
+    let json = false;
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--agent" && i + 1 < rest.length) agent = rest[++i];
+      else if (arg === "--status" && i + 1 < rest.length) status = rest[++i];
+      else if (arg === "--json") json = true;
+      else throw new Error(`Unknown pair status option "${arg}"`);
+    }
+    const query = new URLSearchParams();
+    if (agent) query.set("agent", agent);
+    if (status) query.set("status", status);
+    const pairs = await apiRequest("GET", `/api/pairs${query.size ? `?${query}` : ""}`);
+    if (json) console.log(JSON.stringify(pairs, null, 2));
+    else console.log(formatPairs(pairs as any[]));
+    return;
+  }
+
+  if (action === "create") {
+    const target = rest[0];
+    if (!target || target.startsWith("--")) throw new Error("Usage: agent-relay pair <target> [--from AGENT_ID] [--objective TEXT]");
+    let from = await detectAgentId();
+    let objective: string | undefined;
+    let ttlMs: number | undefined;
+    let json = false;
+    const objectiveParts: string[] = [];
+    for (let i = 1; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--from" && i + 1 < rest.length) from = rest[++i];
+      else if (arg === "--objective" && i + 1 < rest.length) objective = rest[++i];
+      else if (arg === "--ttl-ms" && i + 1 < rest.length) ttlMs = parseInt(rest[++i]!, 10);
+      else if (arg === "--json") json = true;
+      else objectiveParts.push(arg!);
+    }
+    objective ??= objectiveParts.length ? objectiveParts.join(" ") : undefined;
+    if (!from) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
+    const result = await apiRequest("POST", "/api/pairs", { from, target, objective, ttlMs });
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else {
+      const pair = (result as any).pair;
+      console.log(`Pair invite ${pair.id} sent: ${pair.requesterId} -> ${pair.targetId}`);
+    }
+    return;
+  }
+
+  if (action === "accept" || action === "reject" || action === "hangup" || action === "disconnect") {
+    const pairId = rest[0];
+    let agentId = await detectAgentId();
+    let reason: string | undefined;
+    let json = false;
+    let startIndex = 0;
+    if (pairId && !pairId.startsWith("--")) startIndex = 1;
+    for (let i = startIndex; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--agent" && i + 1 < rest.length) agentId = rest[++i];
+      else if (arg === "--reason" && i + 1 < rest.length) reason = rest[++i];
+      else if (arg === "--json") json = true;
+      else throw new Error(`Unknown pair ${action} option "${arg}"`);
+    }
+    if (!agentId) throw new Error("Could not detect current Agent Relay ID. Pass --agent AGENT_ID or set AGENT_RELAY_ID.");
+    const resolvedPairId = pairId && !pairId.startsWith("--") ? pairId : await detectActivePairId(agentId);
+    if (!resolvedPairId) throw new Error(`Usage: agent-relay pair ${action} PAIR_ID --agent AGENT_ID`);
+    const endpoint = action === "disconnect" ? "hangup" : action;
+    const pair = await apiRequest("POST", `/api/pairs/${encodeURIComponent(resolvedPairId)}/${endpoint}`, { agentId, reason });
+    if (json) console.log(JSON.stringify(pair, null, 2));
+    else console.log(`Pair ${resolvedPairId}: ${(pair as any).status}`);
+    return;
+  }
+
+  if (action === "send") {
+    const pairId = rest[0];
+    if (!pairId || pairId.startsWith("--")) throw new Error("Usage: agent-relay pair send PAIR_ID --from AGENT_ID --body TEXT");
+    let from = await detectAgentId();
+    let body: string | undefined;
+    let subject: string | undefined;
+    let json = false;
+    for (let i = 1; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--from" && i + 1 < rest.length) from = rest[++i];
+      else if (arg === "--body" && i + 1 < rest.length) body = rest[++i];
+      else if (arg === "--subject" && i + 1 < rest.length) subject = rest[++i];
+      else if (arg === "--json") json = true;
+      else throw new Error(`Unknown pair send option "${arg}"`);
+    }
+    if (!from) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
+    if (!body) throw new Error("--body TEXT required");
+    const result = await apiRequest("POST", `/api/pairs/${encodeURIComponent(pairId)}/messages`, { from, body, subject });
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else console.log(`Pair message sent: ${(result as any).message.id}`);
+    return;
+  }
+}
+
+async function handleStatusCommand(args: string[]): Promise<void> {
+  let agentId = await detectAgentId();
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--agent" && i + 1 < args.length) agentId = args[++i];
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown status option "${arg}"`);
+  }
+
+  const [stats, health, pairs, agent] = await Promise.all([
+    apiRequest("GET", "/api/stats"),
+    apiRequest("GET", "/api/health"),
+    agentId ? apiRequest("GET", `/api/pairs?agent=${encodeURIComponent(agentId)}`) : Promise.resolve([]),
+    agentId ? apiRequest("GET", `/api/agents/${encodeURIComponent(agentId)}`).catch(() => null) : Promise.resolve(null),
+  ]);
+  const payload = { agent, stats, health, pairs };
+  if (json) console.log(JSON.stringify(payload, null, 2));
+  else console.log(formatStatus(payload));
+}
+
+async function handleLabelCommand(args: string[]): Promise<void> {
+  let agentId = await detectAgentId();
+  let label: string | null | undefined;
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--agent" && i + 1 < args.length) agentId = args[++i];
+    else if (arg === "--clear") label = null;
+    else if (arg === "--json") json = true;
+    else if (label === undefined) label = args.slice(i).join(" ");
+  }
+  if (!agentId) throw new Error("Could not detect current Agent Relay ID. Pass --agent AGENT_ID or set AGENT_RELAY_ID.");
+  if (label === undefined) {
+    const agent = await apiRequest("GET", `/api/agents/${encodeURIComponent(agentId)}`) as { label?: string };
+    console.log(agent.label ?? "(no label)");
+    return;
+  }
+  const result = await apiRequest("PATCH", `/api/agents/${encodeURIComponent(agentId)}/label`, { label });
+  if (json) console.log(JSON.stringify(result, null, 2));
+  else console.log(label ? `Label set: ${label}` : "Label cleared.");
+}
+
+async function handleTagsCommand(args: string[]): Promise<void> {
+  let agentId = await detectAgentId();
+  let json = false;
+  let listOnly = false;
+  let add: string[] = [];
+  let remove: string[] = [];
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--agent" && i + 1 < args.length) agentId = args[++i];
+    else if (arg === "--json") json = true;
+    else if (arg === "--list") listOnly = true;
+    else if (arg === "--add" && i + 1 < args.length) add = add.concat(splitTagArgs(args[++i]!));
+    else if (arg === "--remove" && i + 1 < args.length) remove = remove.concat(splitTagArgs(args[++i]!));
+    else positional.push(...splitTagArgs(arg!));
+  }
+  if (!agentId) throw new Error("Could not detect current Agent Relay ID. Pass --agent AGENT_ID or set AGENT_RELAY_ID.");
+  const current = await apiRequest("GET", `/api/agents/${encodeURIComponent(agentId)}`) as { tags?: string[] };
+  if (listOnly || (positional.length === 0 && add.length === 0 && remove.length === 0)) {
+    console.log((current.tags ?? []).join(", ") || "(no tags)");
+    return;
+  }
+  const next = positional.length > 0
+    ? uniqueStrings(positional)
+    : uniqueStrings([...(current.tags ?? []), ...add]).filter((tag) => !remove.includes(tag));
+  const updated = await apiRequest("PATCH", `/api/agents/${encodeURIComponent(agentId)}/tags`, { tags: next });
+  if (json) console.log(JSON.stringify(updated, null, 2));
+  else console.log(`Tags: ${next.join(", ") || "(none)"}`);
+}
+
+async function apiRequest(method: string, path: string, body?: unknown): Promise<unknown> {
+  const baseUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
+  const headers: Record<string, string> = {};
+  const token = process.env.AGENT_RELAY_TOKEN;
+  if (token) headers["X-Agent-Relay-Token"] = token;
+  if (body !== undefined) headers["Content-Type"] = "application/json";
+  const response = await fetch(new URL(path, baseUrl), {
+    method,
+    headers,
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await response.text();
+  const payload = text ? JSON.parse(text) : null;
+  if (!response.ok) {
+    const message = payload && typeof payload === "object" && "error" in payload ? String((payload as any).error) : text;
+    throw new Error(`agent-relay ${method} ${path} failed (${response.status}): ${message}`);
+  }
+  return payload;
+}
+
+function splitTagArgs(raw: string): string[] {
+  return raw.split(",").map((tag) => tag.trim()).filter(Boolean);
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}
+
+async function detectActivePairId(agentId: string): Promise<string | undefined> {
+  const pairs = await apiRequest("GET", `/api/pairs?agent=${encodeURIComponent(agentId)}&status=active`) as Array<{ id?: string }>;
+  return Array.isArray(pairs) && typeof pairs[0]?.id === "string" ? pairs[0].id : undefined;
+}
+
+async function detectAgentId(): Promise<string | undefined> {
+  const explicit = process.env.AGENT_RELAY_ID;
+  if (explicit) return explicit;
+
+  const cwd = process.cwd();
+  const stateCandidates = [
+    process.env.AGENT_RELAY_CODEX_STATE_PATH,
+    resolve(cwd, "codex/runtime/live-state.json"),
+    ...collectCodexStateFiles(),
+  ].filter((path): path is string => Boolean(path));
+
+  const codexMatch = newestCodexAgentId(stateCandidates, cwd);
+  if (codexMatch) return codexMatch;
+
+  const claudeMatch = newestClaudeAgentId();
+  if (claudeMatch) return claudeMatch;
+
+  try {
+    const agents = await apiRequest("GET", "/api/agents") as Array<{ id?: string; status?: string; ready?: boolean; meta?: { cwd?: unknown }; lastSeen?: number }>;
+    const cwdAgents = agents
+      .filter((agent) => agent.status !== "offline" && agent.ready !== false && agent.meta?.cwd === cwd && typeof agent.id === "string")
+      .sort((a, b) => (b.lastSeen ?? 0) - (a.lastSeen ?? 0));
+    return cwdAgents[0]?.id;
+  } catch {
+    return undefined;
+  }
+}
+
+function newestCodexAgentId(paths: string[], cwd: string): string | undefined {
+  const states = paths
+    .map((path) => readCodexState(path))
+    .filter((state): state is { agentId: string; cwd?: string; updatedAtMs: number } => Boolean(state))
+    .sort((a, b) => b.updatedAtMs - a.updatedAtMs);
+  return states.find((state) => state.cwd === cwd)?.agentId ?? states[0]?.agentId;
+}
+
+function readCodexState(path: string): { agentId: string; cwd?: string; updatedAtMs: number } | null {
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as { agentId?: unknown; cwd?: unknown; updatedAt?: unknown };
+    if (typeof parsed.agentId !== "string" || !parsed.agentId) return null;
+    const stat = statSync(path);
+    const updatedAt = typeof parsed.updatedAt === "string" ? Date.parse(parsed.updatedAt) : Number.NaN;
+    return {
+      agentId: parsed.agentId,
+      cwd: typeof parsed.cwd === "string" ? parsed.cwd : undefined,
+      updatedAtMs: Number.isFinite(updatedAt) ? updatedAt : stat.mtimeMs,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function collectCodexStateFiles(): string[] {
+  const roots = [
+    join(process.env.HOME || "", ".agent-relay", "codex", "runtime"),
+    resolve(process.cwd(), "codex", "runtime"),
+  ].filter((root) => root && existsSync(root));
+  const files: string[] = [];
+  for (const root of roots) collectFiles(root, "live-state.json", files, 4);
+  return files;
+}
+
+function collectFiles(dir: string, name: string, output: string[], depth: number): void {
+  if (depth < 0) return;
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const path = join(dir, entry);
+    try {
+      const stat = statSync(path);
+      if (stat.isDirectory()) collectFiles(path, name, output, depth - 1);
+      else if (entry === name) output.push(path);
+    } catch {
+      // Ignore state files that disappear while scanning.
+    }
+  }
+}
+
+function newestClaudeAgentId(): string | undefined {
+  if (!existsSync("/tmp")) return undefined;
+  try {
+    const candidates = readdirSync("/tmp")
+      .filter((entry) => entry.startsWith("agent-relay-instance-") && entry.endsWith(".state"))
+      .map((entry) => join("/tmp", entry))
+      .map((path) => ({ path, mtimeMs: statSync(path).mtimeMs }))
+      .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    for (const candidate of candidates) {
+      const id = readFileSync(candidate.path, "utf8").split(/\r?\n/)[0]?.trim();
+      if (id) return id;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+function formatPairs(pairs: any[]): string {
+  if (!pairs.length) return "No pair sessions.";
+  return pairs
+    .map((pair) => `${pair.id}  ${pair.status}  ${pair.requesterId} <-> ${pair.targetId}${pair.objective ? `  ${pair.objective}` : ""}`)
+    .join("\n");
+}
+
+function formatStatus(payload: any): string {
+  const agent = payload.agent;
+  const stats = payload.stats ?? {};
+  const health = payload.health ?? {};
+  const pairs = Array.isArray(payload.pairs) ? payload.pairs : [];
+  const activePair = pairs.find((pair: any) => pair.status === "active") ?? pairs.find((pair: any) => pair.status === "pending");
+  return [
+    `Relay: ${health.status ?? "unknown"}  version=${stats.version ?? "unknown"}`,
+    `Agents: ${stats.online ?? "?"}/${stats.agents ?? "?"} online  Messages: ${stats.messages ?? "?"}  Tasks: ${stats.openTasks ?? "?"}/${stats.tasks ?? "?"} open`,
+    agent
+      ? `Current: ${agent.id}  status=${agent.status}  ready=${agent.ready ? "yes" : "no"}  label=${agent.label ?? "(none)"}  tags=${(agent.tags ?? []).join(", ") || "(none)"}`
+      : "Current: unknown",
+    activePair
+      ? `Pair: ${activePair.id}  ${activePair.status}  ${activePair.requesterId} <-> ${activePair.targetId}`
+      : "Pair: none active",
+  ].join("\n");
+}
+
 async function confirm(message: string): Promise<boolean> {
   if (!input.isTTY) return false;
   const rl = createInterface({ input, output });

package/src/config.ts

@@ -20,6 +20,7 @@ function envPositiveInt(name: string, fallback: number): number {
 export const STALE_TTL_MS = envPositiveInt("STALE_TTL_MS", 120_000); // 2min without heartbeat → offline
 export const OFFLINE_PRUNE_MS = envPositiveInt("OFFLINE_PRUNE_MS", DAY_MS); // 24h offline → delete
 export const REAP_INTERVAL_MS = envPositiveInt("REAP_INTERVAL_MS", 60_000); // reaper cadence
+export const CLAIM_LEASE_MS = envPositiveInt("AGENT_RELAY_CLAIM_LEASE_MS", 1_800_000); // 30min claim lease
 
 // Max body size for any POST/PATCH request (64 KiB).
 export const MAX_BODY_BYTES = 64 * 1024;