agent-relay-server 0.32.4 → 0.33.1

package/src/cli/daemon.ts

@@ -0,0 +1,111 @@
+// Daemon command — auto-split from cli.ts (#294). Installs/manages the relay
+// server as a user/system service.
+import {
+  createDaemonPlan,
+  detectDaemonEnvironment,
+  executeDaemonPlan,
+  formatDaemonPlan,
+  type DaemonAction,
+  type DaemonScope,
+} from "../daemon";
+import { createSetupPlan, executeSetupPlan, pathExists } from "../setup";
+import { confirm } from "./_shared";
+
+const DAEMON_ACTIONS = new Set<DaemonAction>([
+  "install",
+  "uninstall",
+  "start",
+  "stop",
+  "restart",
+  "enable",
+  "disable",
+  "status",
+  "logs",
+]);
+
+export async function handleDaemonCommand(args: string[]): Promise<void> {
+  const action = parseDaemonAction(args[0]);
+  let name: string | undefined;
+  let envFile: string | undefined;
+  let port: number | undefined;
+  let host: string | undefined;
+  let scope: DaemonScope | undefined;
+  let binaryPath: string | undefined;
+  let runtimePrefix: string | undefined;
+  const pathPrefix: string[] = [];
+  let start = false;
+  let enable = false;
+  let dryRun = false;
+  let force = false;
+  let yes = false;
+  let json = false;
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--name" && i + 1 < args.length) name = args[++i];
+    else if (arg === "--env-file" && i + 1 < args.length) envFile = args[++i];
+    else if (arg === "--port" && i + 1 < args.length) port = parseInt(args[++i]!, 10);
+    else if (arg === "--host" && i + 1 < args.length) host = args[++i];
+    else if (arg === "--user") scope = "user";
+    else if (arg === "--system") scope = "system";
+    else if (arg === "--binary" && i + 1 < args.length) binaryPath = args[++i];
+    else if (arg === "--runtime-prefix" && i + 1 < args.length) runtimePrefix = args[++i];
+    else if (arg === "--path-prefix" && i + 1 < args.length) pathPrefix.push(args[++i]!);
+    else if (arg === "--start") start = true;
+    else if (arg === "--enable") enable = true;
+    else if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--force") force = true;
+    else if (arg === "--yes") yes = true;
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown daemon option "${arg}"`);
+  }
+
+  if (action === "install" && !dryRun && !envFile && !(await pathExists(createSetupPlan().envFile))) {
+    const setupPlan = createSetupPlan({
+      ...(host ? { host } : {}),
+      ...(port !== undefined ? { port } : {}),
+      ...(runtimePrefix ? { runtimePrefix } : {}),
+    });
+    const ok = yes || await confirm(`Create daemon env file at ${setupPlan.envFile}?`);
+    if (!ok) throw new Error("Daemon install needs an env file. Run `agent-relay setup` first.");
+    console.log(await executeSetupPlan(setupPlan, { force }));
+  }
+
+  const env = await detectDaemonEnvironment();
+  const plan = createDaemonPlan({
+    action,
+    ...(name ? { name } : {}),
+    ...(envFile ? { envFile } : {}),
+    ...(port !== undefined ? { port } : {}),
+    ...(host ? { host } : {}),
+    ...(scope ? { scope } : {}),
+    ...(binaryPath ? { binaryPath } : {}),
+    ...(runtimePrefix ? { runtimePrefix } : {}),
+    ...(pathPrefix.length ? { pathPrefix } : {}),
+    start,
+    enable,
+  }, env);
+
+  if (!dryRun && !json && (action === "install" || action === "uninstall") && !yes) {
+    const ok = await confirm(
+      action === "install"
+        ? `Install ${plan.kind} ${plan.scope} daemon "${plan.name}"?`
+        : `Uninstall daemon "${plan.name}"?`,
+    );
+    if (!ok) {
+      console.log("Daemon command cancelled.");
+      return;
+    }
+  }
+
+  const result = await executeDaemonPlan(plan, { dryRun, force });
+  if (json) console.log(JSON.stringify({ plan: result.plan, output: result.output }, null, 2));
+  else console.log(dryRun ? formatDaemonPlan(plan) : result.output);
+}
+
+function parseDaemonAction(value: string | undefined): DaemonAction {
+  if (!value || !DAEMON_ACTIONS.has(value as DaemonAction)) {
+    throw new Error("Usage: agent-relay daemon <install|uninstall|start|stop|restart|enable|disable|status|logs> [options]");
+  }
+  return value as DaemonAction;
+}

package/src/cli/dev.ts

@@ -0,0 +1,173 @@
+// Dev commands — auto-split from cli.ts (#294). Local pack/install/service/smoke
+// harness for testing relay packages without an npm publish.
+import {
+  createDevInstallPlan,
+  createDevPackPlan,
+  createDevServicePlan,
+  defaultDevRoot,
+  executeDevInstallPlan,
+  executeDevPackPlan,
+  executeDevServicePlan,
+  executeDevSmoke,
+  formatDevInstallPlan,
+  formatDevPackPlan,
+  formatDevServicePlan,
+  parseDevPackages,
+  type DevServiceAction,
+} from "../dev";
+import { confirm } from "./_shared";
+
+export async function handleDevCommand(args: string[]): Promise<void> {
+  const action = args[0];
+  if (!action) throw new Error("Usage: agent-relay dev <pack|install|service|smoke> [options]");
+  if (action === "pack") {
+    let packages: string | undefined;
+    let outDir: string | undefined;
+    let dryRun = false;
+    let json = false;
+    for (let i = 1; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "--packages" && i + 1 < args.length) packages = args[++i];
+      else if (arg === "--out" && i + 1 < args.length) outDir = args[++i];
+      else if (arg === "--dry-run") dryRun = true;
+      else if (arg === "--json") json = true;
+      else throw new Error(`Unknown dev pack option "${arg}"`);
+    }
+    const plan = createDevPackPlan({
+      ...(packages ? { packages: parseDevPackages(packages) } : {}),
+      ...(outDir ? { outDir } : {}),
+    });
+    const result = await executeDevPackPlan(plan, { dryRun });
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else console.log(dryRun ? formatDevPackPlan(plan) : result.output);
+    return;
+  }
+
+  if (action === "install") {
+    let packages: string | undefined;
+    let outDir: string | undefined;
+    let prefix: string | undefined;
+    let dryRun = false;
+    let json = false;
+    for (let i = 1; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "--packages" && i + 1 < args.length) packages = args[++i];
+      else if (arg === "--out" && i + 1 < args.length) outDir = args[++i];
+      else if (arg === "--prefix" && i + 1 < args.length) prefix = args[++i];
+      else if (arg === "--dry-run") dryRun = true;
+      else if (arg === "--json") json = true;
+      else throw new Error(`Unknown dev install option "${arg}"`);
+    }
+    const plan = createDevInstallPlan({
+      ...(packages ? { packages: parseDevPackages(packages) } : {}),
+      ...(outDir ? { outDir } : {}),
+      ...(prefix ? { prefix } : {}),
+    });
+    const result = await executeDevInstallPlan(plan, { dryRun });
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else console.log(dryRun ? formatDevInstallPlan(plan) : result.output);
+    return;
+  }
+
+  if (action === "service") {
+    await handleDevServiceCommand(args.slice(1));
+    return;
+  }
+
+  if (action === "smoke") {
+    let rootDir: string | undefined;
+    let providers: string | undefined;
+    let cwd: string | undefined;
+    let orchestratorId: string | undefined;
+    let timeoutMs: number | undefined;
+    for (let i = 1; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "--root" && i + 1 < args.length) rootDir = args[++i];
+      else if (arg === "--providers" && i + 1 < args.length) providers = args[++i];
+      else if (arg === "--cwd" && i + 1 < args.length) cwd = args[++i];
+      else if (arg === "--orchestrator" && i + 1 < args.length) orchestratorId = args[++i];
+      else if (arg === "--timeout" && i + 1 < args.length) timeoutMs = parseInt(args[++i]!, 10);
+      else throw new Error(`Unknown dev smoke option "${arg}"`);
+    }
+    const result = await executeDevSmoke({
+      ...(rootDir ? { rootDir } : {}),
+      ...(providers ? { providers } : {}),
+      ...(cwd ? { cwd } : {}),
+      ...(orchestratorId ? { orchestratorId } : {}),
+      ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    });
+    console.log(result.output);
+    return;
+  }
+
+  throw new Error("Usage: agent-relay dev <pack|install|service|smoke> [options]");
+}
+
+async function handleDevServiceCommand(args: string[]): Promise<void> {
+  const action = parseDevServiceAction(args[0]);
+  let prefix: string | undefined;
+  let rootDir: string | undefined;
+  let port: number | undefined;
+  let apiPort: number | undefined;
+  let baseDir: string | undefined;
+  let orchestratorId: string | undefined;
+  let token: string | undefined;
+  let start = false;
+  let enable = false;
+  let dryRun = false;
+  let force = false;
+  let yes = false;
+  let json = false;
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--prefix" && i + 1 < args.length) prefix = args[++i];
+    else if (arg === "--root" && i + 1 < args.length) rootDir = args[++i];
+    else if (arg === "--port" && i + 1 < args.length) port = parseInt(args[++i]!, 10);
+    else if (arg === "--api-port" && i + 1 < args.length) apiPort = parseInt(args[++i]!, 10);
+    else if (arg === "--base-dir" && i + 1 < args.length) baseDir = args[++i];
+    else if (arg === "--orchestrator-id" && i + 1 < args.length) orchestratorId = args[++i];
+    else if (arg === "--token" && i + 1 < args.length) token = args[++i];
+    else if (arg === "--start") start = true;
+    else if (arg === "--enable") enable = true;
+    else if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--force") force = true;
+    else if (arg === "--yes") yes = true;
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown dev service option "${arg}"`);
+  }
+
+  const root = rootDir ?? defaultDevRoot();
+  const plan = createDevServicePlan({
+    action,
+    ...(prefix ? { prefix } : {}),
+    rootDir: root,
+    ...(port !== undefined ? { port } : {}),
+    ...(apiPort !== undefined ? { apiPort } : {}),
+    ...(baseDir ? { baseDir } : {}),
+    ...(orchestratorId ? { orchestratorId } : {}),
+    ...(token ? { token } : {}),
+    start,
+    enable,
+  });
+
+  if (!dryRun && !json && (action === "install" || action === "uninstall") && !yes) {
+    const ok = await confirm(action === "install" ? `Install dev service profile under ${root}?` : `Uninstall dev service profile under ${root}?`);
+    if (!ok) {
+      console.log("Dev service command cancelled.");
+      return;
+    }
+  }
+
+  const result = await executeDevServicePlan(plan, { dryRun, force });
+  if (json) console.log(JSON.stringify({ plan: result.plan, output: result.output }, null, 2));
+  else console.log(dryRun ? formatDevServicePlan(plan) : result.output);
+}
+
+function parseDevServiceAction(value: string | undefined): DevServiceAction {
+  const allowed = new Set<DevServiceAction>(["install", "uninstall", "start", "stop", "restart", "status", "logs"]);
+  if (!value || !allowed.has(value as DevServiceAction)) {
+    throw new Error("Usage: agent-relay dev service <install|uninstall|start|stop|restart|status|logs> [options]");
+  }
+  return value as DevServiceAction;
+}

package/src/cli/index.ts

@@ -0,0 +1,361 @@
+// CLI dispatcher — auto-split from cli.ts (#294). handleCli() is a thin switch
+// over the per-domain command modules in this directory; the usage/guide strings
+// live here too. Each command's logic lives in its own module (upgrade.ts,
+// message.ts, workspace.ts, …). Re-exports WORKSPACE_USAGE and
+// removeLegacyCodexSessionStartHookToml for the legacy "./cli" import surface.
+import { VERSION } from "../config";
+import { handleUpgradeCommand } from "./upgrade";
+import { handleProviderCommand } from "./provider";
+import { handleContextProbeCommand } from "./context-probe";
+import { handleSetupCommand } from "./setup";
+import { handleDaemonCommand } from "./daemon";
+import { handleOrchestratorCommand } from "./orchestrator";
+import { handleDevCommand } from "./dev";
+import { handleMemoryCommand } from "./memory";
+import { handleSlashOrPairCommand } from "./pair";
+import { handleWorkspaceCommand } from "./workspace";
+import { handleStewardCommand } from "./steward";
+import { handleMessageCommand, handleGetMessageCommand, handleReactCommand } from "./message";
+import { handleReplyCommand } from "./reply";
+import { handleIntrospectCommand } from "./introspect";
+import { handleStatusCommand, handleLabelCommand, handleTagsCommand } from "./agent-meta";
+import { handleRecipeCommand } from "./recipe";
+import { handleTokenCommand } from "./token";
+
+export { WORKSPACE_USAGE } from "./workspace";
+export { removeLegacyCodexSessionStartHookToml } from "./provider";
+
+const HELP = `
+agent-relay ${VERSION}
+
+Usage:
+  agent-relay [start]
+  agent-relay setup [--yes] [--dry-run] [--force] [--env-file PATH] [--runtime-prefix DIR] [--host HOST] [--port PORT] [--db-path PATH] [--token TOKEN|--no-token]
+  agent-relay upgrade [--dry-run] [--version VERSION] [--runtime-prefix DIR] [--providers auto|all|codex|claude|orchestrator] [--no-restart] [--yes]
+  agent-relay upgrade --host ID [--host ID2 ...] [--version VERSION] [--providers ...]   (upgrade remote orchestrator hosts over the relay)
+  agent-relay upgrade --all-hosts [...]                                                  (upgrade this host, then every behind remote host)
+  agent-relay setup upgrade [same options as upgrade]
+  agent-relay daemon <install|uninstall|start|stop|restart|enable|disable|status|logs> [options]
+  agent-relay orchestrator install [options]
+  agent-relay dev <pack|install|service|smoke> [options]
+  agent-relay memory broker smoke [options]
+  agent-relay recipe <list|show|start|stop|status> [options]
+  agent-relay provider <wrap|unwrap> <claude|codex>
+  agent-relay context-probe [print-status-line] [--wrap COMMAND] [--agent-id ID] [--state-dir DIR] [--standalone]
+  agent-relay token <create|list|revoke|verify> [options]
+  agent-relay pair <target|create|status|accept|reject|hangup|send> [options]
+  agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]
+  agent-relay steward <queue|inspect|checks> [WORKSPACE_ID] [--repo PATH] [--json]
+  agent-relay message <target> <body> [options]
+  agent-relay get-message <messageId> [--json|--body]
+  agent-relay /pair <target|accept|reject|send|status> [...]
+  agent-relay /message <target> <body>
+  agent-relay /reply <messageId> <body|--stdin|--body-file PATH> [--format text|markdown|markdownv2]
+  agent-relay /react <messageId> <emoji> [--remove]
+  agent-relay /send-claimable <target> <body>
+  agent-relay /disconnect [PAIR_ID]
+  agent-relay /status
+  agent-relay /guide
+  agent-relay /label [LABEL]
+  agent-relay /tags [TAG ...]
+  agent-relay /introspect [--thin TEXT] [--worked-around TEXT] [--would-have-helped TEXT] [--stdin]
+  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 /message codex "Can you look at that failing action?"
+  agent-relay /reply 206 "Sounds good, I'll take a look"
+  agent-relay /react 206 👍
+  agent-relay /reply 206 --stdin < result.md
+  agent-relay get-message 206 --json
+  agent-relay /reply 206 --format markdown "Here is **formatted** text"
+  agent-relay /send-claimable tag:backend "Please claim and fix the failing API test"
+  agent-relay /disconnect
+  agent-relay /status
+  agent-relay /guide
+  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)
+  --runtime-prefix DIR  Isolated Agent Relay npm prefix (default: ~/.agent-relay/runtime)
+  --binary PATH     Stable agent-relay binary/script path for the service
+  --path-prefix DIR Prepend a directory to daemon PATH; repeatable
+  --name NAME       Service name (default: agent-relay)
+  --host HOST       Display/listen host for generated plan (default: 127.0.0.1)
+  --port PORT       Display/listen port for generated plan (default: 4850)
+  --user|--system   User service by default, system service when explicitly requested
+  --enable          Enable service at login/boot during install
+  --start           Start service after install
+  --dry-run         Print the plan without writing files or running service commands
+  --yes             Skip confirmation prompts
+  --force           Overwrite/remove managed-file guardrails
+  --json            Print structured output
+
+Orchestrator install options:
+  --relay-url URL   Agent Relay server URL reachable from this host
+  --token TOKEN     Scoped runtime orchestrator token
+  --bootstrap-token TOKEN Short-lived dashboard bootstrap token to exchange during install
+  --id ID           Orchestrator id (default: sanitized hostname)
+  --base-dir PATH   Base directory for agent working directories (default: ~/projects)
+  --providers LIST  Providers to probe/enable (default: claude,codex)
+  --api-port PORT   Orchestrator local API port (default: 4860)
+  --runtime-prefix DIR  Isolated npm prefix (default: ~/.agent-relay/runtime)
+  --path-prefix DIR Prepend a directory to daemon PATH; repeatable
+  --version VERSION Package version to install (default: this CLI version)
+  --dry-run         Print the plan without writing files, installing, or starting
+  --yes             Skip confirmation prompts
+
+Upgrade options:
+  --version VERSION Target version (default: latest published server version)
+  --runtime-prefix DIR  Isolated Agent Relay npm prefix (default: ~/.agent-relay/runtime)
+  --providers LIST  Provider integrations to upgrade: auto, all, codex, claude, orchestrator
+  --host ID         Upgrade a remote orchestrator host over the relay (repeatable). Skips the local upgrade
+  --all-hosts       Upgrade this host, then fan out to every connected remote host that is behind
+  --no-restart      Do not restart agent-relay.service (warns you to restart it manually)
+  --restart-deferred  Like --no-restart, but the caller restarts the services itself; suppresses the manual-restart warning (used by the release script)
+  --dry-run         Print detected state and planned commands
+  --yes             Skip confirmation prompts
+
+Dev options:
+  agent-relay dev pack [--packages LIST] [--out DIR]
+  agent-relay dev install [--packages LIST] [--prefix DIR] [--out DIR] [--dry-run] [--json]
+  agent-relay dev service <install|uninstall|start|stop|restart|status|logs> [--prefix DIR] [--root DIR] [--port PORT] [--api-port PORT] [--base-dir DIR] [--enable] [--start] [--dry-run] [--yes] [--force] [--json]
+  agent-relay dev smoke [--root DIR] [--providers LIST] [--cwd DIR] [--timeout MS]
+
+Memory options:
+  agent-relay memory broker smoke [--relay-url URL] [--token TOKEN] [--agent-id ID] [--scope SCOPE] [--tag TAG] [--no-cleanup] [--json]
+
+Recipe examples:
+  agent-relay recipe list
+  agent-relay recipe start code-review --cwd /repo --orchestrator local
+  agent-relay recipe status
+  agent-relay recipe stop INSTANCE_ID
+
+Token examples:
+  agent-relay token create --role orchestrator --sub macmini --ttl 86400
+  agent-relay token list
+  agent-relay token revoke JTI
+
+Context probe examples:
+  agent-relay context-probe print-status-line --wrap 'ccstatusline'
+  agent-relay context-probe --wrap 'ccstatusline'
+  agent-relay context-probe --standalone
+`.trim();
+
+const AGENT_GUIDE = `
+Agent Relay guide for coding agents
+
+Agent Relay is a message bus between local or managed agents. Use the
+agent-relay CLI for relay communication.
+
+Current session
+  agent-relay /status --json
+    Shows your relay agent id, label, tags, health, and active pair state.
+
+Replying
+  agent-relay /reply <messageId> "<response>"
+  agent-relay /reply <messageId> --stdin < response.md
+  agent-relay /reply <messageId> --body-file response.md
+    Reply to the sender of a relay message. Prefer this over /message when
+    handling an incoming relay message because the server keeps the routing
+    and channel context. Large replies are uploaded as an artifact
+    automatically and sent as a concise attached reply.
+
+Reactions
+  agent-relay /react <messageId> <emoji>
+  agent-relay /react <messageId> <emoji> --remove
+    Use reactions for lightweight acknowledgement, approval, thanks, or
+    "good job" when no text response is needed. Do not use reactions when the
+    sender asked a question, gave a new task, or needs a result in text.
+
+Reading full messages
+  agent-relay get-message <messageId>
+  agent-relay read-message <messageId> --json
+  agent-relay get-message <messageId> --body
+    Fetch the full message body, attachments, metadata, and thread context.
+
+Sending messages
+  agent-relay /message <target> "<message>"
+    Send a direct one-off relay message.
+
+  agent-relay /send-claimable <target> "<work item>"
+    Queue work that one matching agent can claim and handle.
+
+Targets
+  <agent-id>       A specific live agent id.
+  <label>          A registered agent label.
+  tag:<tag>        Any agent with that tag.
+  cap:<capability> Any agent with that capability.
+  policy:<name>    A managed policy target that can survive restarts.
+  broadcast        All reachable agents.
+
+Pair sessions
+  agent-relay /pair <target> "<objective>"
+  agent-relay /pair status
+  agent-relay /pair accept <pairId>
+  agent-relay /pair reject <pairId>
+  agent-relay /pair send <pairId> "<message>"
+  agent-relay /disconnect [pairId]
+
+Labels and tags
+  agent-relay /label [LABEL]
+  agent-relay /tags [TAG ...]
+
+Isolated workspaces
+  If you are working in an isolated workspace (a git worktree on an agent
+  branch, not the main checkout), you do NOT rebase, merge, or push yourself —
+  Relay does. Just commit your work in the worktree, then:
+    agent-relay workspace ready    Hand off: Relay rebases onto the latest base,
+                                   lands your work, and pushes.
+    agent-relay workspace status   Show your workspace's state + what to do next.
+    agent-relay workspace status --wait
+                                   Block until your branch lands (returns the
+                                   moment the auto-merge completes).
+  After "ready", status is "review_requested" — this is NORMAL, not an
+  escalation. Relay auto-merges clean rebases ~every 2 min; a steward agent is
+  spawned only if it can't land deterministically, so no steward = healthy. On
+  landing you move onto a fresh rebased branch (name gains a "--N" suffix).
+  The base branch will move as other agents land in parallel — that is normal,
+  let the merge handle it. Never push, merge, resolve conflicts, or touch the
+  main checkout yourself; it is local-only and Relay (and the steward) own that.
+  If typecheck/build fails on a missing module (a dep added to the base after
+  your worktree was created), do NOT run a clean install — it mutates the shared
+  node_modules. Instead refresh your worktree's deps in isolation:
+    agent-relay workspace deps     Re-provision deps that have gone stale.
+    agent-relay workspace deps --check   Report staleness without installing.
+
+Rules of thumb
+  If you are handling relay message #123, reply with:
+    agent-relay /reply 123 "<response>"
+
+  If the delivered preview says it was truncated, fetch the full message with:
+    agent-relay get-message 123
+
+  If your reply is long, avoid shell quoting and use:
+    agent-relay /reply 123 --stdin < response.md
+
+  If you need to know who you are in Relay, run:
+    agent-relay /status --json
+
+Recording session friction (optional, helps improve your standing context)
+  agent-relay /introspect --thin "..." --worked-around "..." --would-have-helped "..."
+    When a session involved real work, you can record a short 3-field note about
+    where context was thin, what tooling/instruction gaps you routed around, and
+    what would have saved the read-up. Keep each field to a sentence or two. This
+    feeds the relay's self-improvement signal so the operator can close the gaps —
+    it is not a reply and needs no message id. Skip it for trivial sessions.
+
+  Use the HTTP API for integrations and debugging. For normal agent-to-agent
+  communication, use the CLI commands above.
+`.trim();
+
+export async function handleCli(args: string[]): Promise<"start" | "handled"> {
+  const command = args[0];
+  if (!command || command === "start") return "start";
+  if (command === "--help" || command === "-h" || command === "help") {
+    console.log(HELP);
+    return "handled";
+  }
+  if (command === "--version" || command === "-v") {
+    console.log(VERSION);
+    return "handled";
+  }
+  if (command === "guide" || command === "/guide" || command === "agent-guide" || command === "/agent-guide") {
+    console.log(AGENT_GUIDE);
+    return "handled";
+  }
+  if (command === "upgrade" || (command === "setup" && args[1] === "upgrade")) {
+    await handleUpgradeCommand(command === "setup" ? args.slice(2) : args.slice(1));
+    return "handled";
+  }
+  if (command === "setup" || command === "init") {
+    await handleSetupCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "daemon") {
+    await handleDaemonCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "orchestrator" || command === "orchestrators") {
+    await handleOrchestratorCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "dev") {
+    await handleDevCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "memory") {
+    await handleMemoryCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "recipe" || command === "recipes") {
+    await handleRecipeCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "provider" || command === "providers") {
+    await handleProviderCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "context-probe") {
+    await handleContextProbeCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "token" || command === "tokens") {
+    await handleTokenCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "pair" || command === "/pair" || command === "/disconnect") {
+    await handleSlashOrPairCommand(command, args.slice(1));
+    return "handled";
+  }
+  if (command === "message" || command === "send" || command === "/message" || command === "/send" || command === "/send-claimable") {
+    await handleMessageCommand(args.slice(1), { claimable: command === "/send-claimable" });
+    return "handled";
+  }
+  if (command === "get-message" || command === "read-message" || command === "/get-message" || command === "/read-message") {
+    await handleGetMessageCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "reply" || command === "/reply") {
+    await handleReplyCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "react" || command === "/react" || command === "reaction" || command === "/reaction") {
+    await handleReactCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "introspect" || command === "/introspect") {
+    await handleIntrospectCommand(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 === "workspace" || command === "workspaces") {
+    await handleWorkspaceCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "steward" || command === "stewards") {
+    await handleStewardCommand(args.slice(1));
+    return "handled";
+  }
+  if (command === "/reconnect") {
+    console.log("Reconnect is handled automatically by provider runners; use `agent-relay pair status` to inspect current pair state.");
+    return "handled";
+  }
+  throw new Error(`Unknown command "${command}". Run agent-relay --help.`);
+}