agent-relay-server 0.32.3 → 0.33.0

package/src/cli/introspect.ts

@@ -0,0 +1,73 @@
+// Introspect command — auto-split from cli.ts (#294). Captures the agent's
+// end-of-session self-view as a bounded, structured Insights observation (#185).
+import { apiRequest, readStdin } from "./_shared";
+import { detectAgentId } from "./agent-detect";
+
+// Insights #185: capture the agent's end-of-session self-view as a bounded, structured
+// artifact (epic #183, docs/self-improvement.md). Manual rail in v0 — the agent or
+// operator runs this; the auto-trigger is chosen later on real data. The relay drops it
+// (409) if Insights or the introspection feature is toggled off.
+const INTROSPECT_FIELD_MAX = 600;
+
+export async function handleIntrospectCommand(args: string[]): Promise<void> {
+  let from = await detectAgentId();
+  let project: string | undefined;
+  let sessionId: string | undefined;
+  let thin: string | undefined;
+  let workedAround: string | undefined;
+  let wouldHaveHelped: string | undefined;
+  let stdin = false;
+  let json = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--from" && i + 1 < args.length) from = args[++i];
+    else if (arg === "--project" && i + 1 < args.length) project = args[++i];
+    else if (arg === "--session" && i + 1 < args.length) sessionId = args[++i];
+    else if (arg === "--thin" && i + 1 < args.length) thin = args[++i];
+    else if (arg === "--worked-around" && i + 1 < args.length) workedAround = args[++i];
+    else if (arg === "--would-have-helped" && i + 1 < args.length) wouldHaveHelped = args[++i];
+    else if (arg === "--stdin") stdin = true;
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown introspect option "${arg}"`);
+  }
+
+  // --stdin reads a JSON object { thin, workedAround, wouldHaveHelped } — lets agents
+  // pipe a file without shell-quoting three multi-line fields.
+  if (stdin) {
+    const raw = (await readStdin()).trim();
+    if (!raw) throw new Error("--stdin given but no input received.");
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new Error('--stdin must be JSON: { "thin": "...", "workedAround": "...", "wouldHaveHelped": "..." }');
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("--stdin JSON must be an object");
+    const obj = parsed as Record<string, unknown>;
+    if (typeof obj.thin === "string") thin = obj.thin;
+    if (typeof obj.workedAround === "string") workedAround = obj.workedAround;
+    if (typeof obj.wouldHaveHelped === "string") wouldHaveHelped = obj.wouldHaveHelped;
+  }
+
+  const clip = (v: string | undefined): string => (v ?? "").trim().slice(0, INTROSPECT_FIELD_MAX);
+  const value = { thin: clip(thin), workedAround: clip(workedAround), wouldHaveHelped: clip(wouldHaveHelped) };
+  if (!value.thin && !value.workedAround && !value.wouldHaveHelped) {
+    throw new Error(
+      "Usage: agent-relay /introspect [--thin TEXT] [--worked-around TEXT] [--would-have-helped TEXT] [--stdin] [--from AGENT_ID]\n" +
+        "At least one field is required. The three fields: what context was thin, what you worked around, what would've helped.",
+    );
+  }
+  if (!from) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
+
+  const observation = await apiRequest("POST", "/api/insights/observations", {
+    sessionId: sessionId || process.env.AGENT_RELAY_PROVIDER_SESSION_ID || `manual-${from}`,
+    project: project || process.env.AGENT_RELAY_PROJECT || process.cwd().split("/").filter(Boolean).at(-1) || process.cwd(),
+    agentId: from,
+    signal: "introspection",
+    source: "agent",
+    value,
+  });
+  if (json) console.log(JSON.stringify(observation, null, 2));
+  else console.log("Introspection recorded.");
+}

package/src/cli/memory.ts

@@ -0,0 +1,37 @@
+// Memory command — auto-split from cli.ts (#294). Runs the memory-broker smoke test.
+import { formatMemoryBrokerSmokeResult, runMemoryBrokerSmoke } from "../memory-broker-smoke";
+
+export async function handleMemoryCommand(args: string[]): Promise<void> {
+  const section = args[0];
+  const action = args[1];
+  if (section !== "broker" || action !== "smoke") {
+    throw new Error("Usage: agent-relay memory broker smoke [--relay-url URL] [--token TOKEN] [--agent-id ID] [--scope SCOPE] [--tag TAG] [--no-cleanup] [--json]");
+  }
+  let baseUrl: string | undefined;
+  let token: string | undefined;
+  let agentId: string | undefined;
+  let scope: string | undefined;
+  let tag: string | undefined;
+  let cleanup = true;
+  let json = false;
+  for (let i = 2; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--relay-url" && i + 1 < args.length) baseUrl = args[++i];
+    else if (arg === "--token" && i + 1 < args.length) token = args[++i];
+    else if (arg === "--agent-id" && i + 1 < args.length) agentId = args[++i];
+    else if (arg === "--scope" && i + 1 < args.length) scope = args[++i];
+    else if (arg === "--tag" && i + 1 < args.length) tag = args[++i];
+    else if (arg === "--no-cleanup") cleanup = false;
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown memory broker smoke option "${arg}"`);
+  }
+  const result = await runMemoryBrokerSmoke({
+    ...(baseUrl ? { baseUrl } : {}),
+    ...(token ? { token } : {}),
+    ...(agentId ? { agentId } : {}),
+    ...(scope ? { scope } : {}),
+    ...(tag ? { tag } : {}),
+    cleanup,
+  });
+  console.log(json ? JSON.stringify(result, null, 2) : formatMemoryBrokerSmokeResult(result));
+}

package/src/cli/message.ts

@@ -0,0 +1,201 @@
+// Message commands — auto-split from cli.ts (#294). Send a message (or claimable
+// task), fetch a full message, and add/remove reactions.
+import { apiRequest } from "./_shared";
+import { detectAgentId } from "./agent-detect";
+
+export async function handleMessageCommand(args: string[], defaults: { claimable?: boolean } = {}): Promise<void> {
+  const target = args[0];
+  if (!target || target.startsWith("--")) {
+    throw new Error("Usage: agent-relay message <target> <body> [--from AGENT_ID] [--subject TEXT] [--channel NAME] [--reply-to ID] [--claimable]");
+  }
+
+  let from = await detectAgentId();
+  let subject: string | undefined;
+  let channel: string | undefined;
+  let replyTo: number | undefined;
+  let idempotencyKey: string | undefined;
+  let json = false;
+  let claimable = defaults.claimable ?? false;
+  const bodyParts: string[] = [];
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--from" && i + 1 < args.length) from = args[++i];
+    else if (arg === "--subject" && i + 1 < args.length) subject = args[++i];
+    else if (arg === "--channel" && i + 1 < args.length) channel = args[++i];
+    else if (arg === "--reply-to" && i + 1 < args.length) {
+      const parsed = Number.parseInt(args[++i]!, 10);
+      if (!Number.isFinite(parsed) || parsed <= 0) throw new Error("--reply-to must be a positive message id");
+      replyTo = parsed;
+    } else if (arg === "--idempotency-key" && i + 1 < args.length) idempotencyKey = args[++i];
+    else if (arg === "--claimable") claimable = true;
+    else if (arg === "--json") json = true;
+    else bodyParts.push(arg!);
+  }
+
+  const body = bodyParts.join(" ").trim();
+  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("Message body required.");
+
+  const message = await apiRequest("POST", "/api/messages", {
+    from,
+    to: target,
+    kind: claimable ? "task" : "chat",
+    subject,
+    channel,
+    body,
+    replyTo,
+    claimable,
+    payload: claimable ? { title: subject || "Claimable task" } : undefined,
+    idempotencyKey,
+  });
+  if (json) console.log(JSON.stringify(message, null, 2));
+  else console.log(`${claimable ? "Claimable message" : "Message"} sent: ${(message as any).id} -> ${target}`);
+}
+
+export async function handleGetMessageCommand(args: string[]): Promise<void> {
+  const msgIdRaw = args[0];
+  if (!msgIdRaw || msgIdRaw.startsWith("--")) {
+    throw new Error("Usage: agent-relay get-message <messageId> [--json] [--body]");
+  }
+  const messageId = Number.parseInt(msgIdRaw, 10);
+  if (!Number.isFinite(messageId) || messageId <= 0) throw new Error("messageId must be a positive integer");
+
+  let json = false;
+  let bodyOnly = false;
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--json") json = true;
+    else if (arg === "--body") bodyOnly = true;
+    else throw new Error(`Unknown get-message option "${arg}".`);
+  }
+
+  const [message, artifacts, thread] = await Promise.all([
+    apiRequest("GET", `/api/messages/${messageId}`),
+    apiRequest("GET", `/api/messages/${messageId}/artifacts`).catch(() => []),
+    apiRequest("GET", `/api/messages/${messageId}/thread`).catch(() => []),
+  ]);
+  if (bodyOnly) {
+    console.log(String((message as any).body ?? ""));
+    return;
+  }
+
+  const msg = message as any;
+  const attachments = Array.isArray(msg.payload?.attachments)
+    ? msg.payload.attachments
+    : Array.isArray(msg.attachments)
+    ? msg.attachments
+    : [];
+  const payload = {
+    id: msg.id,
+    from: msg.from,
+    to: msg.to,
+    kind: msg.kind,
+    body: msg.body,
+    subject: msg.subject,
+    channel: msg.channel,
+    replyToId: msg.replyTo,
+    threadId: msg.threadId,
+    createdAt: msg.createdAt,
+    payload: msg.payload,
+    meta: msg.meta,
+    attachments,
+    message,
+    artifacts,
+    thread,
+    replyTo: msg.replyTo ? (thread as any[]).find((item) => item.id === msg.replyTo) ?? null : null,
+  };
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(formatMessageDetails(payload));
+}
+
+export async function handleReactCommand(args: string[]): Promise<void> {
+  const msgIdRaw = args[0];
+  const emoji = args[1];
+  if (!msgIdRaw || msgIdRaw.startsWith("--") || !emoji || emoji.startsWith("--")) {
+    throw new Error("Usage: agent-relay /react <messageId> <emoji> [--from AGENT_ID] [--remove] [--json]");
+  }
+  const messageId = Number.parseInt(msgIdRaw, 10);
+  if (!Number.isFinite(messageId) || messageId <= 0) throw new Error("messageId must be a positive integer");
+
+  let actorId = await detectAgentId();
+  let action: "add" | "remove" = "add";
+  let json = false;
+  for (let i = 2; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--from" && i + 1 < args.length) actorId = args[++i];
+    else if (arg === "--remove") action = "remove";
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown react option "${arg}"`);
+  }
+  if (!actorId) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
+
+  const message = await apiRequest("POST", `/api/messages/${messageId}/reactions`, {
+    actorId,
+    emoji,
+    action,
+  });
+  if (json) console.log(JSON.stringify(message, null, 2));
+  else console.log(`${action === "remove" ? "Reaction removed" : "Reaction sent"}: ${emoji} on #${messageId}`);
+}
+
+function formatMessageDetails(payload: {
+  message: any;
+  artifacts: any;
+  thread: any;
+  replyTo: any;
+}): string {
+  const message = payload.message;
+  const lines = [
+    `Message #${message.id}`,
+    `From: ${message.from}`,
+    `To: ${message.to}`,
+    `Kind: ${message.kind}`,
+  ];
+  if (message.subject) lines.push(`Subject: ${message.subject}`);
+  if (message.channel) lines.push(`Channel: ${message.channel}`);
+  if (message.replyTo) lines.push(`Reply-to: #${message.replyTo}`);
+  if (message.threadId) lines.push(`Thread: #${message.threadId}`);
+  if (message.createdAt) lines.push(`Created: ${new Date(message.createdAt).toISOString()}`);
+  if (message.deliveryStatus) lines.push(`Delivery: ${message.deliveryStatus}`);
+  if (message.resolvedToAgent) lines.push(`Resolved-to: ${message.resolvedToAgent}`);
+  lines.push("", "Body:", String(message.body ?? ""));
+
+  if (message.payload && Object.keys(message.payload).length) {
+    lines.push("", "Payload:", JSON.stringify(message.payload, null, 2));
+  }
+  if (message.meta && Object.keys(message.meta).length) {
+    lines.push("", "Meta:", JSON.stringify(message.meta, null, 2));
+  }
+
+  const artifacts = Array.isArray(payload.artifacts) ? payload.artifacts : [];
+  if (artifacts.length) {
+    lines.push("", "Attachments:");
+    for (const artifact of artifacts) {
+      lines.push(`- ${artifact.id ?? artifact.artifactId} ${artifact.filename ? `(${artifact.filename}) ` : ""}${artifact.mediaType ?? artifact.kind ?? ""}`.trim());
+    }
+  } else if (Array.isArray(message.payload?.attachments) && message.payload.attachments.length) {
+    lines.push("", "Attachments:");
+    for (const attachment of message.payload.attachments) {
+      lines.push(`- ${attachment.artifactId}${attachment.title ? ` (${attachment.title})` : ""}`);
+    }
+  }
+
+  if (payload.replyTo) {
+    lines.push("", "Reply Context:", `Parent: #${payload.replyTo.id} from ${payload.replyTo.from} to ${payload.replyTo.to}`);
+  }
+
+  const thread = Array.isArray(payload.thread) ? payload.thread : [];
+  if (thread.length) {
+    lines.push("", "Thread:");
+    for (const item of thread) {
+      const subject = item.subject ? ` ${item.subject}` : "";
+      lines.push(`- #${item.id} ${item.from} -> ${item.to}${subject}`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/cli/orchestrator.ts

@@ -0,0 +1,227 @@
+// Orchestrator install command — auto-split from cli.ts (#294). Writes the
+// orchestrator env file, installs the runtime packages, and registers the daemon.
+import { chmodSync, existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { hostname as osHostname, homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import {
+  createDaemonPlan,
+  detectDaemonEnvironment,
+  executeDaemonPlan,
+  formatDaemonPlan,
+} from "../daemon";
+import { renderEnvFile } from "../setup";
+import { defaultRuntimePrefix, runtimeBinPath } from "../runtime-prefix";
+import { VERSION } from "../config";
+import { shellQuote } from "agent-relay-sdk/shell-utils";
+import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import { expandTilde } from "../utils";
+import { confirm } from "./_shared";
+
+export async function handleOrchestratorCommand(args: string[]): Promise<void> {
+  const subcommand = args[0];
+  if (subcommand !== "install") {
+    throw new Error("Usage: agent-relay orchestrator install --relay-url URL --token TOKEN|--bootstrap-token TOKEN [options]");
+  }
+
+  let relayUrl = "";
+  let token = "";
+  let bootstrapToken = "";
+  let id = sanitizeOrchestratorId(osHostname());
+  let baseDir = join(homedir(), "projects");
+  let providers = "claude,codex";
+  let apiPort = 4860;
+  let runtimePrefix = defaultRuntimePrefix();
+  let serviceName = "agent-relay-orchestrator";
+  let version = VERSION;
+  const pathPrefix: string[] = [];
+  let dryRun = false;
+  let yes = false;
+  let force = false;
+  let json = false;
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--relay-url" && i + 1 < args.length) relayUrl = args[++i]!;
+    else if (arg === "--token" && i + 1 < args.length) token = args[++i]!;
+    else if (arg === "--bootstrap-token" && i + 1 < args.length) bootstrapToken = args[++i]!;
+    else if (arg === "--id" && i + 1 < args.length) id = sanitizeOrchestratorId(args[++i]!);
+    else if (arg === "--base-dir" && i + 1 < args.length) baseDir = resolve(expandTilde(args[++i]!));
+    else if (arg === "--providers" && i + 1 < args.length) providers = args[++i]!;
+    else if (arg === "--api-port" && i + 1 < args.length) apiPort = parseInt(args[++i]!, 10);
+    else if (arg === "--runtime-prefix" && i + 1 < args.length) runtimePrefix = resolve(expandTilde(args[++i]!));
+    else if (arg === "--service-name" && i + 1 < args.length) serviceName = args[++i]!;
+    else if (arg === "--version" && i + 1 < args.length) version = args[++i]!;
+    else if (arg === "--path-prefix" && i + 1 < args.length) pathPrefix.push(resolve(expandTilde(args[++i]!)));
+    else if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--yes" || arg === "-y") yes = true;
+    else if (arg === "--force") force = true;
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown orchestrator install option "${arg}"`);
+  }
+
+  if (!relayUrl) throw new Error("--relay-url is required");
+  if (!token && !bootstrapToken) throw new Error("--token or --bootstrap-token is required");
+  if (!Number.isInteger(apiPort) || apiPort < 1 || apiPort > 65535) throw new Error("--api-port must be an integer from 1 to 65535");
+
+  const providerList = providers.split(",").map((p) => p.trim()).filter(Boolean);
+  for (const provider of providerList) {
+    if (provider !== "claude" && provider !== "codex") throw new Error(`Unknown provider "${provider}". Expected claude or codex.`);
+  }
+  const detectedPathPrefix = [...pathPrefix, ...detectProviderPathPrefixes(providerList as Array<"claude" | "codex">)];
+  const uniquePathPrefix = [...new Set(detectedPathPrefix)];
+  const envToken = token || (dryRun || json ? "<runtime-token-from-bootstrap>" : await exchangeOrchestratorBootstrapToken(relayUrl, bootstrapToken, id, baseDir));
+  const envFile = defaultOrchestratorEnvFile();
+  const binaryPath = runtimeBinPath("agent-relay-orchestrator", runtimePrefix);
+  const envValues: Record<string, string> = {
+    AGENT_RELAY_URL: relayUrl,
+    AGENT_RELAY_TOKEN: envToken,
+    AGENT_RELAY_ORCHESTRATOR_ID: id,
+    AGENT_RELAY_ORCHESTRATOR_HOSTNAME: osHostname(),
+    AGENT_RELAY_ORCHESTRATOR_BASE_DIR: baseDir,
+    AGENT_RELAY_ORCHESTRATOR_PROVIDERS: providerList.join(","),
+    AGENT_RELAY_ORCHESTRATOR_API_PORT: String(apiPort),
+  };
+  if (uniquePathPrefix.length) envValues.AGENT_RELAY_ORCHESTRATOR_PATH_PREFIX = uniquePathPrefix.join(":");
+
+  const daemonEnv = await detectDaemonEnvironment();
+  const daemonPlan = createDaemonPlan({
+    action: "install",
+    name: serviceName,
+    envFile,
+    binaryPath,
+    runtimePrefix,
+    pathPrefix: uniquePathPrefix,
+    enable: true,
+    start: true,
+  }, daemonEnv);
+  const packageCommand = ["npm", "install", "--prefix", runtimePrefix, `agent-relay-runner@${version}`, `agent-relay-orchestrator@${version}`];
+
+  if (json || dryRun) {
+    const plan = {
+      id,
+      relayUrl,
+      baseDir,
+      providers: providerList,
+      apiPort,
+      runtimePrefix,
+      envFile,
+      binaryPath,
+      serviceName,
+      version,
+      pathPrefix: uniquePathPrefix,
+      packageCommand,
+      daemon: daemonPlan,
+    };
+    if (json) console.log(JSON.stringify({ plan }, null, 2));
+    else console.log(formatOrchestratorInstallPlan(plan));
+    return;
+  }
+
+  if (!yes) {
+    const ok = await confirm(`Install orchestrator "${id}" as daemon "${serviceName}"?`);
+    if (!ok) {
+      console.log("Orchestrator install cancelled.");
+      return;
+    }
+  }
+
+  mkdirSync(dirname(envFile), { recursive: true });
+  mkdirSync(baseDir, { recursive: true });
+  writeFileSync(envFile, renderEnvFile(envValues), { mode: 0o600 });
+  chmodSync(envFile, 0o600);
+  console.log(`Wrote ${envFile}`);
+
+  runChecked(packageCommand);
+  const result = await executeDaemonPlan(daemonPlan, { force });
+  console.log(result.output);
+  console.log(`Orchestrator install complete. Verify in Relay: ${relayUrl}`);
+}
+
+function defaultOrchestratorEnvFile(): string {
+  const platform = process.platform;
+  if (platform === "darwin") return join(homedir(), "Library", "Application Support", "agent-relay", "orchestrator.env");
+  return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "agent-relay", "orchestrator.env");
+}
+
+async function exchangeOrchestratorBootstrapToken(relayUrl: string, bootstrapToken: string, id: string, baseDir: string): Promise<string> {
+  const response = await fetch(new URL("/api/orchestrators/bootstrap/exchange", relayUrl), {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      [RELAY_TOKEN_HEADER]: bootstrapToken,
+    },
+    body: JSON.stringify({ id, baseDir }),
+  });
+  const payload = await response.json().catch(() => null) as { token?: string; error?: string } | null;
+  if (!response.ok || !payload?.token) {
+    throw new Error(`bootstrap token exchange failed (${response.status}): ${payload?.error ?? response.statusText}`);
+  }
+  return payload.token;
+}
+
+function sanitizeOrchestratorId(value: string): string {
+  const clean = value.trim().replace(/\./g, "-").replace(/[^A-Za-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!clean) throw new Error("--id must contain at least one letter or number");
+  return clean.slice(0, 120);
+}
+
+function detectProviderPathPrefixes(providers: Array<"claude" | "codex">): string[] {
+  const prefixes: string[] = [];
+  for (const provider of providers) {
+    const path = resolveExecutableOnPath(provider);
+    if (path) prefixes.push(dirname(path));
+  }
+  return prefixes;
+}
+
+function resolveExecutableOnPath(command: string): string | undefined {
+  if (command.includes("/")) return existsSync(command) ? command : undefined;
+  for (const entry of (process.env.PATH ?? "").split(":")) {
+    if (!entry) continue;
+    const candidate = join(entry, command);
+    try {
+      if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+    } catch {}
+  }
+  return undefined;
+}
+
+function runChecked(command: string[]): void {
+  console.log(`$ ${command.map(shellQuote).join(" ")}`);
+  const result = Bun.spawnSync(command, { stdin: "ignore", stdout: "inherit", stderr: "inherit" });
+  if (result.exitCode !== 0) throw new Error(`${command[0]} exited with code ${result.exitCode}`);
+}
+
+function formatOrchestratorInstallPlan(plan: {
+  id: string;
+  relayUrl: string;
+  baseDir: string;
+  providers: string[];
+  apiPort: number;
+  runtimePrefix: string;
+  envFile: string;
+  binaryPath: string;
+  serviceName: string;
+  version: string;
+  pathPrefix: string[];
+  packageCommand: string[];
+  daemon: ReturnType<typeof createDaemonPlan>;
+}): string {
+  const lines = [
+    "Orchestrator install plan",
+    `ID: ${plan.id}`,
+    `Relay: ${plan.relayUrl}`,
+    `Base dir: ${plan.baseDir}`,
+    `Providers: ${plan.providers.join(", ") || "(none)"}`,
+    `API port: ${plan.apiPort}`,
+    `Runtime prefix: ${plan.runtimePrefix}`,
+    `Env file: ${plan.envFile}`,
+    `Binary: ${plan.binaryPath}`,
+    `Service: ${plan.serviceName}`,
+    `Package version: ${plan.version}`,
+  ];
+  if (plan.pathPrefix.length) lines.push(`PATH prefix: ${plan.pathPrefix.join(":")}`);
+  lines.push("", "Package command:", `  ${plan.packageCommand.join(" ")}`);
+  lines.push("", formatDaemonPlan(plan.daemon));
+  return lines.join("\n");
+}

package/src/cli/pair.ts

@@ -0,0 +1,125 @@
+// Pair commands — auto-split from cli.ts (#294). Two-agent pair sessions:
+// create/status/accept/reject/hangup/send, plus the /pair and /disconnect slash
+// aliases.
+import { apiRequest } from "./_shared";
+import { detectActivePairId, detectAgentId } from "./agent-detect";
+
+export 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 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;
+  }
+}
+
+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");
+}