agent-relay-server 0.32.4 → 0.33.0

package/src/cli/upgrade.ts

@@ -0,0 +1,193 @@
+// Upgrade commands — auto-split from cli.ts (#294). Local runtime upgrade plus
+// remote-host fan-out over the relay command bus (#210).
+import {
+  createUpgradePlan,
+  detectUpgradeSnapshot,
+  executeUpgradePlan,
+  formatUpgradePlan,
+  resolveLocalOrchestratorId,
+  type UpgradeProvider,
+} from "../upgrade";
+import { VERSION } from "../config";
+import { errMessage } from "agent-relay-sdk";
+import { apiRequest, confirm } from "./_shared";
+
+export async function handleUpgradeCommand(args: string[]): Promise<void> {
+  let targetVersion: string | undefined;
+  let dryRun = false;
+  let noRestart = false;
+  let restartDeferred = false;
+  let yes = false;
+  let json = false;
+  let runtimePrefix: string | undefined;
+  const pathPrefix: string[] = [];
+  const providers: UpgradeProvider[] = [];
+  const hosts: string[] = [];
+  let allHosts = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--version" && i + 1 < args.length) targetVersion = args[++i];
+    else if (arg === "--runtime-prefix" && i + 1 < args.length) runtimePrefix = args[++i];
+    else if (arg === "--providers" && i + 1 < args.length) {
+      for (const provider of args[++i]!.split(",")) providers.push(parseUpgradeProvider(provider));
+    } else if (arg === "--provider" && i + 1 < args.length) providers.push(parseUpgradeProvider(args[++i]!));
+    else if (arg === "--host" && i + 1 < args.length) hosts.push(args[++i]!);
+    else if (arg === "--all-hosts") allHosts = true;
+    else if (arg === "--codex") providers.push("codex");
+    else if (arg === "--claude") providers.push("claude");
+    else if (arg === "--orchestrator") providers.push("orchestrator");
+    else if (arg === "--all") providers.push("all");
+    else if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--no-restart") noRestart = true;
+    else if (arg === "--restart-deferred") restartDeferred = true;
+    else if (arg === "--yes" || arg === "-y") yes = true;
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown upgrade option "${arg}"`);
+  }
+
+  // Remote-only: drive named hosts' self-upgrade over the relay command bus and
+  // skip the local upgrade entirely (#210). `--all-hosts` instead upgrades this
+  // host first, then fans out to every behind remote (handled after the local run).
+  if (hosts.length && !allHosts) {
+    await runRemoteOrchestratorUpgrades({ hosts, targetVersion, providers, json, dryRun, yes });
+    return;
+  }
+
+  const snapshot = await detectUpgradeSnapshot({
+    ...(targetVersion ? { targetVersion } : {}),
+    ...(runtimePrefix ? { runtimePrefix } : {}),
+    providers,
+    noRestart,
+  });
+  const plan = createUpgradePlan(snapshot, {
+    ...(targetVersion ? { targetVersion } : {}),
+    ...(runtimePrefix ? { runtimePrefix } : {}),
+    providers,
+    noRestart,
+    restartDeferred,
+  });
+
+  if (json) {
+    console.log(JSON.stringify({ plan }, null, 2));
+    if (allHosts) await runRemoteOrchestratorUpgrades({ allBehind: true, targetVersion: plan.targetVersion, providers, json, dryRun: true });
+    return;
+  }
+
+  if (dryRun) {
+    console.log(formatUpgradePlan(plan, { dryRun: true }));
+    if (allHosts) await runRemoteOrchestratorUpgrades({ allBehind: true, targetVersion: plan.targetVersion, providers, dryRun: true });
+    return;
+  }
+
+  if (!yes) {
+    console.log(formatUpgradePlan(plan));
+    const ok = await confirm("Run this upgrade plan?");
+    if (!ok) {
+      console.log("Upgrade cancelled.");
+      return;
+    }
+  }
+
+  console.log(await executeUpgradePlan(plan));
+
+  if (allHosts) {
+    await runRemoteOrchestratorUpgrades({ allBehind: true, targetVersion: plan.targetVersion, providers, json, yes: true });
+  }
+}
+
+/**
+ * Trigger orchestrator self-upgrade on remote hosts via the relay command bus
+ * (#210). Each host installs its own runtime + self-restarts; the relay settles
+ * the version when it re-registers. Replaces the manual ssh + npm install dance.
+ */
+async function runRemoteOrchestratorUpgrades(opts: {
+  hosts?: string[];
+  allBehind?: boolean;
+  targetVersion?: string;
+  providers: UpgradeProvider[];
+  json?: boolean;
+  dryRun?: boolean;
+  yes?: boolean;
+}): Promise<void> {
+  const targetVersion = opts.targetVersion ?? VERSION;
+  const orchestrators = (await apiRequest("GET", "/api/orchestrators")) as Array<{
+    id: string;
+    version?: string;
+  }>;
+  const byId = new Map(orchestrators.map((orch) => [orch.id, orch]));
+  const localId = resolveLocalOrchestratorId();
+  // Default to "all" so a remote host's provider runner is upgraded too, not just
+  // the orchestrator package (matters for hosts running claude/codex agents).
+  const remoteProviders: UpgradeProvider[] = opts.providers.length ? opts.providers : ["all"];
+
+  let targets: string[];
+  if (opts.allBehind) {
+    targets = orchestrators
+      .filter((orch) => orch.id !== localId && orch.version && orch.version !== targetVersion)
+      .map((orch) => orch.id);
+    if (!targets.length) {
+      if (opts.json) console.log(JSON.stringify({ remoteUpgrades: [] }, null, 2));
+      else console.log(`No remote orchestrators behind ${targetVersion}.`);
+      return;
+    }
+  } else {
+    targets = opts.hosts ?? [];
+  }
+
+  if (opts.dryRun) {
+    const lines = targets.map((id) => {
+      const orch = byId.get(id);
+      const from = orch ? orch.version ?? "unknown" : "(not connected)";
+      return `  ${id}: ${from} → ${targetVersion} (providers: ${remoteProviders.join(",")})`;
+    });
+    if (opts.json) console.log(JSON.stringify({ remoteUpgrades: targets.map((id) => ({ id, targetVersion, providers: remoteProviders, dryRun: true })) }, null, 2));
+    else console.log(`Remote orchestrator upgrade plan → ${targetVersion}:\n${lines.join("\n")}`);
+    return;
+  }
+
+  if (!opts.yes && !opts.json) {
+    console.log(`Trigger remote orchestrator upgrade → ${targetVersion} for: ${targets.join(", ")}`);
+    const ok = await confirm("Send remote upgrade command(s)?");
+    if (!ok) {
+      console.log("Remote upgrade cancelled.");
+      return;
+    }
+  }
+
+  const results: Array<{ id: string; ok: boolean; message: string }> = [];
+  for (const id of targets) {
+    if (!byId.has(id)) {
+      results.push({ id, ok: false, message: "not connected to the relay" });
+      continue;
+    }
+    try {
+      const res = (await apiRequest("POST", `/api/orchestrators/${encodeURIComponent(id)}/actions`, {
+        action: "upgrade",
+        targetVersion,
+        providers: remoteProviders,
+      })) as { command?: { id?: string } };
+      const from = byId.get(id)?.version;
+      results.push({ id, ok: true, message: `queued ${from ?? "?"} → ${targetVersion} (command ${res?.command?.id ?? "?"})` });
+    } catch (err) {
+      results.push({ id, ok: false, message: errMessage(err) });
+    }
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify({ remoteUpgrades: results }, null, 2));
+    return;
+  }
+  console.log(`\nRemote orchestrator upgrades → ${targetVersion}:`);
+  for (const result of results) console.log(`  ${result.ok ? "✓" : "✗"} ${result.id}: ${result.message}`);
+  console.log("\nEach host installs and self-restarts; the relay reconciles the version when it re-registers.");
+  console.log("Track progress in the dashboard Orchestrators view or via GET /api/orchestrators.");
+  if (results.some((result) => !result.ok)) {
+    process.exitCode = 1;
+  }
+}
+
+function parseUpgradeProvider(value: string): UpgradeProvider {
+  if (value === "auto" || value === "all" || value === "codex" || value === "claude" || value === "orchestrator") return value;
+  throw new Error(`Unknown upgrade provider "${value}". Expected auto, all, codex, claude, or orchestrator.`);
+}

package/src/cli/workspace.ts

@@ -0,0 +1,215 @@
+// Workspace commands — auto-split from cli.ts (#294). Self-service lifecycle for
+// agents in isolated worktrees (#205): status/ready/land/claim/release/diagnostics/
+// deps/list/cleanup-stale.
+import { apiRequest } from "./_shared";
+import { detectAgentId } from "./agent-detect";
+import { describeWorkspacePhase, readyContract, type WorkspacePhaseView } from "../workspace-phase";
+import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
+
+export const WORKSPACE_USAGE = "Usage: 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]";
+
+// The agent's own isolated-workspace id, published in AGENT_RELAY_WORKSPACE_JSON
+// by the orchestrator at spawn. Undefined for shared-workspace / non-managed agents.
+function currentWorkspaceId(): string | undefined {
+  const json = process.env.AGENT_RELAY_WORKSPACE_JSON;
+  if (!json) return undefined;
+  try {
+    const parsed = JSON.parse(json) as { id?: string };
+    return typeof parsed.id === "string" && parsed.id ? parsed.id : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function formatWorkspaceStatus(ws: any, extra?: { guidance?: WorkspacePhaseView; landed?: string | null }): string {
+  // Render the directive projection so the agent gets "what does this mean / what
+  // do I do next" inline, not a bare enum it has to decode (#235). Computed
+  // client-side from the record (the projection is pure) unless the wait response
+  // already carried it.
+  const guidance = extra?.guidance ?? describeWorkspacePhase(ws);
+  const lines = [
+    `Workspace ${ws.id}`,
+    `  status:   ${ws.status}  (${guidance.phase}${guidance.actionNeeded ? "" : " — no action needed"})`,
+    `  branch:   ${ws.branch ?? "(none)"}`,
+    `  base:     ${ws.baseRef ?? "(none)"}`,
+    `  worktree: ${ws.worktreePath ?? "(none)"}`,
+    "",
+    `  ${guidance.headline}`,
+    `  ${guidance.hint}`,
+  ];
+  if (guidance.blockers.length) {
+    lines.push("", "  Blockers:");
+    for (const b of guidance.blockers) lines.push(`    - ${b}`);
+  }
+  if (guidance.nextActions.length) {
+    lines.push("", "  Next:");
+    for (const a of guidance.nextActions) lines.push(`    - ${a.cli ?? a.tool} — ${a.when}`);
+  }
+  if (extra?.landed) lines.push("", `  ${extra.landed}`);
+  return lines.join("\n");
+}
+
+// Poll a command to a terminal state (succeeded/failed). Returns undefined on
+// timeout so the caller can degrade to "dispatched, check later".
+async function pollCommand(id: string, timeoutMs: number): Promise<{ status?: string; result?: unknown; error?: string } | undefined> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const cmd = await apiRequest("GET", `/api/commands/${encodeURIComponent(id)}`) as { status?: string; result?: unknown; error?: string };
+    if (cmd.status === "succeeded" || cmd.status === "failed") return cmd;
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return undefined;
+}
+
+function formatDepsRefresh(result: WorkspaceDepsRefreshResult, checkOnly: boolean): string {
+  if (result.error && (!result.dirs || result.dirs.length === 0)) return `Deps ${checkOnly ? "check" : "refresh"}: ${result.error}`;
+  const lines: string[] = [];
+  for (const d of result.dirs) {
+    const icon = d.status === "installed" ? "↻" : d.status === "stale" ? "✗" : d.status === "failed" ? "!" : "✓";
+    const detail = d.status === "ok" ? "up to date"
+      : d.status === "installed" ? `reinstalled${d.wasSymlink ? " (was symlinked)" : ""}`
+      : d.status === "stale" ? `stale — missing ${d.missing?.join(", ") ?? "?"}`
+      : `failed — ${d.error ?? "unknown"}`;
+    lines.push(`  ${icon} ${d.dir}: ${detail}`);
+  }
+  const header = checkOnly
+    ? (result.stale ? "Deps check: stale dirs found — run `agent-relay workspace deps` to refresh" : "Deps check: all dirs up to date")
+    : (result.refreshed ? "Deps refreshed" : result.error ? "Deps refresh hit errors" : "Deps already up to date");
+  return [header, ...lines].join("\n");
+}
+
+// Self-service workspace lifecycle for agents in isolated worktrees (#205) plus
+// steward coordination (#208).
+//   status — read your workspace row     ready — hand off for review/landing
+//   land   — request a base merge (operator)   list — all workspaces
+//   diagnostics — joined briefing + recommended action
+//   claim/release — TTL'd steward lease auto-merge yields to
+//   cleanup-stale — guarded batch cleanup of stale worktrees (dry-run by default)
+export async function handleWorkspaceCommand(args: string[]): Promise<void> {
+  const action = args[0];
+  const valid = new Set(["status", "ready", "land", "list", "diagnostics", "diag", "claim", "release", "cleanup-stale", "deps"]);
+  if (action === "--help" || action === "-h" || action === "help") {
+    console.log(WORKSPACE_USAGE);
+    return;
+  }
+  if (!action || !valid.has(action)) {
+    throw new Error(WORKSPACE_USAGE);
+  }
+
+  let id = currentWorkspaceId(), idExplicit = false; // idExplicit: --id was passed, not the ambient default (#307)
+  let strategy: string | undefined;
+  let purpose: string | undefined;
+  let repo: string | undefined;
+  let execute = false;
+  let check = false;
+  let json = false;
+  let wait = false;
+  let timeoutSeconds: number | undefined;
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--id" && i + 1 < args.length) { id = args[++i]; idExplicit = true; }
+    else if (arg === "--strategy" && i + 1 < args.length) strategy = args[++i];
+    else if (arg === "--purpose" && i + 1 < args.length) purpose = args[++i];
+    else if (arg === "--repo" && i + 1 < args.length) repo = args[++i];
+    else if (arg === "--execute") execute = true;
+    else if (arg === "--check") check = true;
+    else if (arg === "--refresh") check = false; // explicit no-op default for clarity
+    else if (arg === "--wait") wait = true;
+    else if (arg === "--timeout" && i + 1 < args.length) {
+      const parsed = Number.parseInt(args[++i]!, 10);
+      if (!Number.isFinite(parsed) || parsed <= 0) throw new Error("--timeout must be a positive number of seconds");
+      timeoutSeconds = parsed;
+    }
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown workspace option "${arg}".`);
+  }
+
+  if (action === "list") {
+    console.log(JSON.stringify(await apiRequest("GET", "/api/workspaces"), null, 2));
+    return;
+  }
+
+  if (action === "cleanup-stale") {
+    const result = await apiRequest("POST", "/api/workspaces/actions/cleanup-stale", { repoRoot: repo, dryRun: !execute, ...(idExplicit && id ? { workspaceId: id } : {}) });
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (!id) throw new Error("No current workspace detected (AGENT_RELAY_WORKSPACE_JSON unset). Pass --id WORKSPACE_ID — only isolated-workspace agents have one.");
+
+  if (action === "status") {
+    // --wait long-polls via the action endpoint (server blocks until the status
+    // changes — the blessed way to wait for an auto-merge to land, #235), and the
+    // response carries the directive projection + land receipt. Plain status is a
+    // bare GET; the projection is computed client-side for rendering.
+    if (wait) {
+      const res = await apiRequest("POST", `/api/workspaces/${encodeURIComponent(id)}/actions`, {
+        action: "status",
+        wait: true,
+        ...(timeoutSeconds ? { timeoutSeconds } : {}),
+      }) as { workspace?: any; guidance?: WorkspacePhaseView; landed?: string | null };
+      if (json) { console.log(JSON.stringify(res, null, 2)); return; }
+      console.log(formatWorkspaceStatus(res.workspace ?? res, { guidance: res.guidance, landed: res.landed }));
+      return;
+    }
+    const ws = await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}`);
+    if (json) console.log(JSON.stringify(ws, null, 2));
+    else console.log(formatWorkspaceStatus(ws));
+    return;
+  }
+
+  if (action === "diagnostics" || action === "diag") {
+    console.log(JSON.stringify(await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}/diagnostics`), null, 2));
+    return;
+  }
+
+  // Refresh (or --check) deps the shared symlinked node_modules has gone stale on
+  // (#51). Emits a host command; poll it to a terminal state so the agent gets a
+  // synchronous result and knows when to re-run typecheck.
+  if (action === "deps") {
+    const from = await detectAgentId();
+    const res = await apiRequest("POST", `/api/workspaces/${encodeURIComponent(id)}/actions`, { action: "deps-refresh", agentId: from, checkOnly: check }) as { command?: { id?: string } };
+    const commandId = res.command?.id;
+    const settled = commandId ? await pollCommand(commandId, 180_000) : undefined;
+    const result = (settled?.result ?? null) as WorkspaceDepsRefreshResult | null;
+    if (json) {
+      console.log(JSON.stringify(settled ?? res, null, 2));
+      return;
+    }
+    if (settled?.status === "failed") {
+      console.error(`Deps ${check ? "check" : "refresh"} failed: ${settled.error ?? "unknown error"}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (!result) {
+      console.log(`Deps ${check ? "check" : "refresh"} dispatched (command ${commandId ?? "?"}) — host did not report back in time. Check \`agent-relay workspace deps --json\`.`);
+      return;
+    }
+    console.log(formatDepsRefresh(result, check));
+    return;
+  }
+
+  const from = await detectAgentId();
+  const actionBody: Record<string, unknown> =
+    action === "ready" ? { action: "request-review", agentId: from }
+    : action === "claim" ? { action: "claim", agentId: from, purpose }
+    : action === "release" ? { action: "release-claim", agentId: from }
+    : { action: "merge", agentId: from, ...(strategy ? { strategy } : {}) };
+  const result = await apiRequest("POST", `/api/workspaces/${encodeURIComponent(id)}/actions`, actionBody);
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (action === "ready") {
+    // Print the whole contract up front so the agent isn't left decoding status
+    // enums over the next minutes (#235). `result.workspace` is the post-ready row.
+    const ws = (result as { workspace?: any }).workspace ?? { status: "review_requested" };
+    console.log(`Workspace ${id} marked ready.\n\n${readyContract(ws)}`);
+    return;
+  }
+  console.log(
+    action === "claim" ? `Workspace ${id} claimed${purpose ? ` (${purpose})` : ""} — auto-merge will yield until released or the claim expires.`
+    : action === "release" ? `Workspace ${id} claim released.`
+    : `Workspace ${id} merge requested (${strategy ?? "auto"}).`,
+  );
+}