agent-relay-server 0.18.0 → 0.19.0

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

@@ -4,7 +4,8 @@ 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,38 @@ 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"]>;
+};
+
+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,16 +290,17 @@ 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 orchestrators = await pollUntil(
+      async () => (await probeOrchestrators()) ?? [],
+      (list) => list.length > 0 && list.every((orch) => !orch.version || orch.version === plan.targetVersion),
+    );
     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}`);
@@ -494,7 +525,7 @@ function runCommand(command: string[]): CommandResult {
     return {
       exitCode: 127,
       stdout: "",
-      stderr: error instanceof Error ? error.message : String(error),
+      stderr: errMessage(error),
     };
   }
 }
@@ -536,8 +567,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)];
+}