agent-relay-orchestrator 0.19.2 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-orchestrator",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "description": "Agent Relay orchestrator — manages agent lifecycle across hosts",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.10"
+    "agent-relay-sdk": "0.2.11"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/self-upgrade.ts

@@ -6,6 +6,31 @@ import { detectSelfSupervision, type SelfSupervision } from "./self-supervision"
 const VALID_PROVIDERS = new Set(["auto", "all", "codex", "claude", "orchestrator"]);
 const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 
+/**
+ * Stale-packument cache race: right after a publish, a remote host's cached npm
+ * metadata may not yet list the new version, so `npm install ...@X` fails with
+ * ETARGET / "No matching version found" even though it IS published (#211). The
+ * packument refreshes within seconds; `--prefer-online` + retry recovers it.
+ */
+const CACHE_RACE_RE = /ETARGET|No matching version found|notarget/i;
+const DEFAULT_INSTALL_RETRIES = 4;
+const DEFAULT_INSTALL_RETRY_BASE_MS = 2000;
+
+export interface SelfUpgradeOptions {
+  /** Sleep between install retries (injectable for tests). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Max extra install attempts after the first on a cache-race error. */
+  installRetries?: number;
+  /** Base backoff (doubles per attempt: base, 2×, 4×, …). */
+  installRetryBaseMs?: number;
+  /** Override self-supervision detection (injectable for tests). */
+  supervision?: SelfSupervision;
+}
+
+function isCacheRaceError(output: string): boolean {
+  return CACHE_RACE_RE.test(output);
+}
+
 export interface SelfUpgradeRunner {
   run(cmd: string[]): Promise<{ exitCode: number; stdout: string; stderr: string }>;
   commandExists(name: string): boolean;
@@ -96,8 +121,9 @@ export async function handleSelfUpgrade(
   _config: OrchestratorConfig,
   relay: RelayClient,
   runner: SelfUpgradeRunner = defaultRunner,
+  opts: SelfUpgradeOptions = {},
 ): Promise<void> {
-  const plan = planSelfUpgrade(command.params, detectSelfSupervision(), runner);
+  const plan = planSelfUpgrade(command.params, opts.supervision ?? detectSelfSupervision(), runner);
   await relay.updateCommand(command.id, "running", {
     phase: "installing",
     targetVersion: plan.targetVersion,
@@ -105,7 +131,17 @@ export async function handleSelfUpgrade(
     unit: plan.unit,
   });
 
-  const install = await runner.run(plan.installCmd);
+  const install = await runInstallWithRetry(plan, runner, opts, async (attempt, delayMs) => {
+    await relay.updateCommand(command.id, "running", {
+      phase: "installing",
+      targetVersion: plan.targetVersion,
+      unit: plan.unit,
+      retry: attempt,
+      retryDelayMs: delayMs,
+      note: `target ${plan.targetVersion} not yet visible to this host's npm cache; retrying (attempt ${attempt})`,
+    });
+    console.error(`[orchestrator] self-upgrade install hit a stale-cache race for ${plan.targetVersion}; retry ${attempt} in ${delayMs}ms`);
+  });
   if (install.exitCode !== 0) {
     throw new Error(`install failed (exit ${install.exitCode}): ${(install.stderr || install.stdout).trim().slice(-500)}`);
   }
@@ -125,6 +161,32 @@ export async function handleSelfUpgrade(
   console.error(`[orchestrator] self-upgrade to ${plan.targetVersion} installed; restart dispatched for ${plan.unit}`);
 }
 
+/**
+ * Run the install, retrying with exponential backoff when it fails on a
+ * stale-packument cache race (#211). Non-cache-race failures return immediately
+ * so genuine errors aren't masked by retries.
+ */
+async function runInstallWithRetry(
+  plan: SelfUpgradePlan,
+  runner: SelfUpgradeRunner,
+  opts: SelfUpgradeOptions,
+  onRetry: (attempt: number, delayMs: number) => Promise<void>,
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const retries = opts.installRetries ?? DEFAULT_INSTALL_RETRIES;
+  const baseMs = opts.installRetryBaseMs ?? DEFAULT_INSTALL_RETRY_BASE_MS;
+  const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+  let result = await runner.run(plan.installCmd);
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    if (result.exitCode === 0 || !isCacheRaceError(result.stderr || result.stdout)) break;
+    const delayMs = baseMs * 2 ** (attempt - 1);
+    await onRetry(attempt, delayMs);
+    await sleep(delayMs);
+    result = await runner.run(plan.installCmd);
+  }
+  return result;
+}
+
 function normalizeProviders(value: unknown): string[] {
   const list = Array.isArray(value)
     ? value.filter((v): v is string => typeof v === "string").map((v) => v.trim()).filter(Boolean)
@@ -147,6 +209,9 @@ function buildInstallCommand(
     return [
       "npm",
       "install",
+      // Revalidate the packument instead of trusting a stale cache, so a
+      // just-published version is visible to this host's npm right away (#211).
+      "--prefer-online",
       "--prefix",
       supervision.runtimePrefix,
       ...packagesForProviders(targetVersion, providers),