agent-relay-server 0.18.0 → 0.19.1

package/src/setup.ts

@@ -1,4 +1,5 @@
 import { randomBytes } from "node:crypto";
+import { shellQuote } from "agent-relay-sdk/shell-utils";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
 import { homedir } from "node:os";
@@ -191,10 +192,6 @@ function normalizePort(port: number | undefined): number {
   return value;
 }
 
-function shellQuote(value: string): string {
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}
-
 function redactEnv(content: string): string {
   return content.replace(/^(AGENT_RELAY_TOKEN=).+$/m, "$1'<generated-token>'");
 }

package/src/spawn-command.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type { SpawnProvider } from "agent-relay-sdk";
+import { errMessage } from "agent-relay-sdk";
 import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { workspaceSpawnParams } from "./config-store";
 import { ValidationError } from "./db";
@@ -60,7 +61,7 @@ export function resolveSpawnModelParams(
         ...(effort ? { effort } : {}),
       };
     }
-    throw new ValidationError(error instanceof Error ? error.message : String(error));
+    throw new ValidationError(errMessage(error));
   }
 }
 

package/src/steward.ts

@@ -25,7 +25,8 @@ export function buildStewardPrompt(repoRoot: string): string {
     "",
     "Multiple agents work this repo in isolated git worktrees. The relay auto-merges any branch that rebases cleanly — including ones whose base moved on; it hands YOU only what it can't land deterministically: real merge conflicts, or an unknown/ambiguous merge state. Your job is to land that work with no human in the loop whenever you safely can.",
     "",
-    "Use the `agent-relay` CLI — it wraps the relay API and is the supported toolkit. Your session token carries the scopes for it. Handle ONE workspace at a time — the relay's per-repo merge lease serializes you with any other merger.",
+    "Use the `agent-relay` CLI for EVERY relay interaction — it wraps the relay API and is the supported toolkit, and it already attaches your session token with the right scopes. Do NOT hand-curl the HTTP API (`/api/workspaces`, …): the CLI exists so you never have to. If you ever truly must call the API directly, authenticate with the `X-Agent-Relay-Token: <your session token>` header — NOT `Authorization: Bearer $AGENT_RELAY_TOKEN`; the admin env token is not present in your environment, so Bearer will 401.",
+    "Handle ONE workspace at a time — the relay's per-repo merge lease serializes you with any other merger.",
     "",
     "1. See the queue: `agent-relay steward queue` (workspaces in conflict / review_requested / merge_planned for this repo). The wake message(s) also name a `workspaceId`.",
     "2. CLAIM it FIRST: `agent-relay workspace claim --id <id> --purpose steward`. This stops the deterministic auto-merge from racing you while you validate. The claim auto-expires, so a crash never blocks the repo.",

package/src/upgrade.ts

@@ -1,10 +1,11 @@
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, hostname as osHostname } from "node:os";
 import { join, resolve } from "node:path";
 import { VERSION } from "./config";
 import type { RuntimeContracts, RuntimePackageMetadata } from "./contracts";
 import { defaultRuntimePrefix, runtimeBinPath } from "./runtime-prefix";
-import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import { shellEscape as shellQuote } from "agent-relay-sdk/shell-utils";
 
 export type UpgradeProvider = "auto" | "all" | "codex" | "claude" | "orchestrator";
 
@@ -245,9 +246,40 @@ export function createUpgradePlan(snapshot: UpgradeSnapshot, options: UpgradeOpt
   };
 }
 
-export async function executeUpgradePlan(plan: UpgradePlan, options: { dryRun?: boolean; runner?: Runner } = {}): Promise<string> {
+export type ExecuteUpgradeOptions = {
+  dryRun?: boolean;
+  runner?: Runner;
+  /** Re-register grace window for post-restart version checks (default 30s). */
+  verifyTimeoutMs?: number;
+  /** Poll interval while waiting for re-register (default 1s). */
+  verifyIntervalMs?: number;
+  sleep?: (ms: number) => Promise<void>;
+  probeServerVersion?: () => Promise<string | undefined>;
+  probeOrchestrators?: () => Promise<UpgradeSnapshot["runningOrchestrators"]>;
+  /** Override the local orchestrator id (defaults to the resolved host id). */
+  localOrchestratorId?: string;
+};
+
+export async function executeUpgradePlan(plan: UpgradePlan, options: ExecuteUpgradeOptions = {}): Promise<string> {
   if (options.dryRun) return formatUpgradePlan(plan, { dryRun: true });
   const runner = options.runner ?? runCommand;
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const probeServerVersion = options.probeServerVersion ?? runningServerVersion;
+  const probeOrchestrators = options.probeOrchestrators ?? runningOrchestrators;
+  const verifyTimeoutMs = options.verifyTimeoutMs ?? 30000;
+  const verifyIntervalMs = options.verifyIntervalMs ?? 1000;
+  // Restarted services drop their old registration and re-register asynchronously.
+  // Poll until the reported version reaches the target (or the grace window expires)
+  // so a slow re-register is not mistaken for a failed upgrade (vent #49).
+  const pollUntil = async <T>(probe: () => Promise<T>, done: (value: T) => boolean): Promise<T> => {
+    const deadline = Date.now() + verifyTimeoutMs;
+    let value = await probe();
+    while (!done(value) && Date.now() < deadline) {
+      await sleep(verifyIntervalMs);
+      value = await probe();
+    }
+    return value;
+  };
   const lines = [`Upgrading Agent Relay to ${plan.targetVersion}`];
   for (const action of plan.actions) {
     lines.push(`\n${action.label}`);
@@ -260,21 +292,42 @@ export async function executeUpgradePlan(plan: UpgradePlan, options: { dryRun?:
     }
   }
   if (plan.actions.some((action) => action.command.join(" ") === "systemctl --user restart agent-relay.service")) {
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-    const serverVersion = await runningServerVersion();
+    const serverVersion = await pollUntil(probeServerVersion, (version) => version === plan.targetVersion);
     if (serverVersion && serverVersion !== plan.targetVersion) {
       throw new Error(`agent-relay.service restarted but /api/stats reports ${serverVersion}, expected ${plan.targetVersion}`);
     }
     if (serverVersion) lines.push(`Running server: ${serverVersion}`);
   }
   if (plan.actions.some((action) => action.command.join(" ") === "systemctl --user restart agent-relay-orchestrator.service")) {
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-    const orchestrators = await runningOrchestrators() ?? [];
-    const mismatched = orchestrators.filter((orch) => orch.version && orch.version !== plan.targetVersion);
-    if (mismatched.length > 0) {
-      throw new Error(`agent-relay-orchestrator.service restarted but ${mismatched.map((orch) => `${orch.id} reports ${orch.version}`).join(", ")}, expected ${plan.targetVersion}`);
+    // This command only upgrades the LOCAL runtime. Remote hosts run their own
+    // orchestrator runtime and upgrade separately, so the success check asserts
+    // the local orchestrator only — a behind remote host is advisory, never a
+    // failure (#210). Wait for the local one to re-register at the target.
+    const localId = options.localOrchestratorId ?? resolveLocalOrchestratorId();
+    const orchestrators = await pollUntil(
+      async () => (await probeOrchestrators()) ?? [],
+      (list) => {
+        const local = list.find((orch) => orch.id === localId);
+        return Boolean(local && (!local.version || local.version === plan.targetVersion));
+      },
+    );
+    const local = orchestrators.find((orch) => orch.id === localId);
+    if (local?.version && local.version !== plan.targetVersion) {
+      throw new Error(`agent-relay-orchestrator.service restarted but ${local.id} reports ${local.version}, expected ${plan.targetVersion}`);
+    }
+    if (local) {
+      lines.push(`Running orchestrator: ${local.id}${local.version ? ` ${local.version}` : ""}`);
+    } else {
+      lines.push(`Local orchestrator ${localId} has not re-registered with the relay yet; it should appear shortly.`);
+    }
+    const remoteBehind = orchestrators.filter((orch) => orch.id !== localId && orch.version && orch.version !== plan.targetVersion);
+    if (remoteBehind.length > 0) {
+      lines.push("");
+      lines.push(`Remote orchestrator(s) behind ${plan.targetVersion} (each host upgrades its own runtime):`);
+      for (const orch of remoteBehind) {
+        lines.push(`- ${orch.id} ${orch.version} → upgrade with: agent-relay upgrade --host ${orch.id}`);
+      }
     }
-    if (orchestrators.length > 0) lines.push(`Running orchestrator(s): ${orchestrators.map((orch) => `${orch.id}${orch.version ? ` ${orch.version}` : ""}`).join(", ")}`);
   }
   lines.push("\nUpgrade commands completed.");
   if (plan.warnings.length > 0) {
@@ -494,7 +547,7 @@ function runCommand(command: string[]): CommandResult {
     return {
       exitCode: 127,
       stdout: "",
-      stderr: error instanceof Error ? error.message : String(error),
+      stderr: errMessage(error),
     };
   }
 }
@@ -503,6 +556,29 @@ function homeDir(): string {
   return process.env.HOME || process.env.USERPROFILE || homedir();
 }
 
+/**
+ * Resolve the LOCAL host's orchestrator id the same way the orchestrator runtime
+ * does (orchestrator/src/config.ts): explicit config id, then
+ * AGENT_RELAY_ORCHESTRATOR_ID, then the hostname with dots hyphenated. The
+ * upgrade command only ever touches the local runtime, so this is the only
+ * orchestrator whose post-restart version it can legitimately assert (#210).
+ */
+export function resolveLocalOrchestratorId(homeDirOverride?: string): string {
+  const home = homeDirOverride ?? homeDir();
+  const configPath = join(home, ".agent-relay", "orchestrator.json");
+  if (existsSync(configPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(configPath, "utf8")) as { id?: string };
+      if (typeof parsed.id === "string" && parsed.id.trim()) return parsed.id.trim();
+    } catch {
+      // Unparsable config — fall through to env/hostname.
+    }
+  }
+  const envId = process.env.AGENT_RELAY_ORCHESTRATOR_ID?.trim();
+  if (envId) return envId;
+  return osHostname().replace(/\./g, "-");
+}
+
 function uniqueStrings(values: string[]): string[] {
   return [...new Set(values.filter(Boolean))];
 }
@@ -536,8 +612,3 @@ function formatContracts(contracts: RuntimeContracts | undefined): string {
     .map(([name, version]) => `${name}=${version}`)
     .join(" ");
 }
-
-function shellQuote(value: string): string {
-  if (/^[a-zA-Z0-9_@%+=:,./-]+$/.test(value)) return value;
-  return `'${value.replaceAll("'", "'\\''")}'`;
-}

package/src/validation.ts

@@ -6,8 +6,6 @@ import { ValidationError } from "./db";
  * Returns `undefined` for absent/blank non-required values.
  *
  * Single home — was byte-identical in config-store, automations, and routes.
- * The divergent `cleanEnum`/`cleanStringArray` copies (different per-context
- * limits + throw/fallback semantics) are intentionally NOT folded here yet.
  */
 export function cleanString(
   value: unknown,
@@ -26,3 +24,57 @@ export function cleanString(
   }
   return trimmed || undefined;
 }
+
+/**
+ * Validate a REQUIRED enum value: throws `ValidationError` if missing or not one
+ * of `valid`. Use when the field must be present. (config-store + automations
+ * no-fallback semantics.) For optional/defaulted enums use {@link optionalEnum}.
+ */
+export function cleanEnum<T extends readonly string[]>(value: unknown, field: string, valid: T): T[number] {
+  if (typeof value !== "string" || !valid.includes(value)) {
+    throw new ValidationError(`${field} must be one of: ${valid.join(", ")}`);
+  }
+  return value as T[number];
+}
+
+/**
+ * Validate an OPTIONAL enum value. Absent (`undefined`/`null`) → returns
+ * `fallback` (which may itself be undefined). A present-but-invalid value still
+ * throws. (routes + automations with-fallback semantics.) The overloads keep the
+ * return type non-undefined when a concrete `fallback` is supplied.
+ */
+export function optionalEnum<T extends readonly string[]>(value: unknown, field: string, valid: T, fallback: T[number]): T[number];
+export function optionalEnum<T extends readonly string[]>(value: unknown, field: string, valid: T, fallback?: T[number]): T[number] | undefined;
+export function optionalEnum<T extends readonly string[]>(value: unknown, field: string, valid: T, fallback?: T[number]): T[number] | undefined {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value !== "string" || !valid.includes(value)) {
+    throw new ValidationError(`${field} must be one of: ${valid.join(", ")}`);
+  }
+  return value as T[number];
+}
+
+/**
+ * Validate an array of strings: trims + dedups each item, drops blanks. Throws
+ * if a present value isn't an array, an item exceeds `itemMax`, or the count
+ * exceeds `maxItems`. Absent → `undefined` (or throws when `required`).
+ *
+ * Callers pass their own per-context limits (`itemMax`/`maxItems`). Sites that
+ * previously returned `[]` for absent input append `?? []`. Single home — folded
+ * the config-store/automations/routes copies that differed only in those limits.
+ */
+export function cleanStringArray(
+  value: unknown,
+  field: string,
+  opts: { required?: boolean; itemMax?: number; maxItems?: number } = {},
+): string[] | undefined {
+  if (value === undefined || value === null) {
+    if (opts.required) throw new ValidationError(`${field} required`);
+    return undefined;
+  }
+  if (!Array.isArray(value)) throw new ValidationError(`${field} must be an array of strings`);
+  const cleaned = value.map((item) => cleanString(item, `${field} item`, { max: opts.itemMax })).filter(Boolean) as string[];
+  if (opts.maxItems && cleaned.length > opts.maxItems) {
+    throw new ValidationError(`${field} can contain at most ${opts.maxItems} values`);
+  }
+  return [...new Set(cleaned)];
+}