@indigoai-us/hq-cli 5.60.0 → 5.61.0

package/src/utils/sandbox-runner-client.test.ts

@@ -39,6 +39,100 @@ describe("SandboxRunnerClient", () => {
     });
   });
 
+  it("retries startJob after fetch rejects twice then succeeds", async () => {
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockRejectedValueOnce(new TypeError("fetch failed"))
+      .mockRejectedValueOnce(new Error("ECONNRESET"))
+      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "queued" }));
+    const sleep = vi.fn(async () => {});
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+      sleep,
+    });
+
+    await expect(
+      client.startJob("jwt-token", {
+        companyUid: "cmp_123",
+        secretNames: ["API_KEY"],
+        command: "node script.js",
+      }),
+    ).resolves.toEqual({ jobId: "job_1", status: "queued" });
+    expect(fetchImpl).toHaveBeenCalledTimes(3);
+    expect(sleep).toHaveBeenCalledTimes(2);
+  });
+
+  it("retries startJob after a retryable 503 response", async () => {
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(jsonRes({ message: "warming up" }, 503))
+      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "queued" }));
+    const sleep = vi.fn(async () => {});
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+      sleep,
+    });
+
+    await expect(
+      client.startJob("jwt-token", {
+        companyUid: "cmp_123",
+        secretNames: ["API_KEY"],
+        command: "node script.js",
+      }),
+    ).resolves.toEqual({ jobId: "job_1", status: "queued" });
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+    expect(sleep).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([400, 401])("does not retry startJob on %i responses", async (status) => {
+    const fetchImpl = vi.fn<typeof fetch>(async () =>
+      jsonRes({ message: "bad request" }, status),
+    );
+    const sleep = vi.fn(async () => {});
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+      sleep,
+    });
+
+    await expect(
+      client.startJob("jwt-token", {
+        companyUid: "cmp_123",
+        secretNames: ["API_KEY"],
+        command: "node script.js",
+      }),
+    ).rejects.toThrow("Sandbox Runner rejected job: bad request");
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    expect(sleep).not.toHaveBeenCalled();
+  });
+
+  it("throws a clear exhaustion error after maxAttempts transient failures", async () => {
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockRejectedValue(new TypeError("fetch failed"));
+    const sleep = vi.fn(async () => {});
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+      retry: { maxAttempts: 3 },
+      sleep,
+    });
+
+    await expect(
+      client.startJob("jwt-token", {
+        companyUid: "cmp_123",
+        secretNames: ["API_KEY"],
+        command: "node script.js",
+      }),
+    ).rejects.toThrow(
+      "Sandbox Runner did not respond after 3 attempts (cold start or transient network); last error: fetch failed",
+    );
+    expect(fetchImpl).toHaveBeenCalledTimes(3);
+    expect(sleep).toHaveBeenCalledTimes(2);
+  });
+
   it("polls queued and running states until succeeded", async () => {
     const fetchImpl = vi
       .fn<typeof fetch>()
@@ -77,6 +171,40 @@ describe("SandboxRunnerClient", () => {
     );
   });
 
+  it("tolerates one transient fetch rejection while polling", async () => {
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "queued" }))
+      .mockRejectedValueOnce(new TypeError("fetch failed"))
+      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "running" }))
+      .mockResolvedValueOnce(
+        jsonRes({
+          jobId: "job_1",
+          status: "succeeded",
+          output: "ok\n",
+          exitCode: 0,
+          success: true,
+        }),
+      );
+    const sleep = vi.fn(async () => {});
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+      sleep,
+    });
+
+    await expect(
+      client.pollJob("jwt-token", "job_1", { intervalMs: 0 }),
+    ).resolves.toMatchObject({
+      jobId: "job_1",
+      status: "succeeded",
+      output: "ok\n",
+      exitCode: 0,
+      success: true,
+    });
+    expect(fetchImpl).toHaveBeenCalledTimes(4);
+  });
+
   it("returns failed terminal jobs with error details", async () => {
     const fetchImpl = vi.fn<typeof fetch>(async () =>
       jsonRes({

package/src/utils/sandbox-runner-client.ts

@@ -22,6 +22,8 @@ export interface SandboxRunnerJob {
 export interface SandboxRunnerClientOptions {
   baseUrl?: string;
   fetchImpl?: typeof fetch;
+  retry?: SandboxRunnerRetryOptions;
+  sleep?: (ms: number) => Promise<void>;
 }
 
 export interface SandboxRunnerPollOptions {
@@ -29,7 +31,21 @@ export interface SandboxRunnerPollOptions {
   maxPolls?: number;
 }
 
+export interface SandboxRunnerRetryOptions {
+  maxAttempts?: number;
+  maxElapsedMs?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+}
+
 const DEFAULT_SANDBOX_RUNNER_URL = "https://hqapi.getindigo.ai/sandbox";
+const RETRYABLE_STATUS_CODES = new Set([408, 425, 429, 500, 502, 503, 504]);
+const DEFAULT_RETRY_OPTIONS: Required<SandboxRunnerRetryOptions> = {
+  maxAttempts: 8,
+  maxElapsedMs: 90_000,
+  baseDelayMs: 500,
+  maxDelayMs: 5_000,
+};
 
 function normalizeBaseUrl(baseUrl: string): string {
   return baseUrl.replace(/\/+$/, "");
@@ -82,20 +98,100 @@ function delay(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  return String(error);
+}
+
+function parseRetryAfterMs(value: string | null): number | undefined {
+  if (!value) return undefined;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return seconds * 1000;
+  }
+  const dateMs = Date.parse(value);
+  if (!Number.isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now());
+  }
+  return undefined;
+}
+
 export class SandboxRunnerClient {
   private readonly baseUrl: string;
   private readonly fetchImpl: typeof fetch;
+  private readonly retry: Required<SandboxRunnerRetryOptions>;
+  private readonly sleep: (ms: number) => Promise<void>;
 
   constructor(options: SandboxRunnerClientOptions = {}) {
     this.baseUrl = normalizeBaseUrl(options.baseUrl ?? getSandboxRunnerBaseUrl());
     this.fetchImpl = options.fetchImpl ?? fetch;
+    this.retry = { ...DEFAULT_RETRY_OPTIONS, ...options.retry };
+    this.sleep = options.sleep ?? delay;
+  }
+
+  private async fetchWithRetry(
+    url: string,
+    init: RequestInit,
+  ): Promise<Response> {
+    const startedAt = Date.now();
+    let lastError = "unknown error";
+    let attempts = 0;
+
+    for (let attempt = 1; attempt <= this.retry.maxAttempts; attempt += 1) {
+      attempts = attempt;
+      try {
+        const res = await this.fetchImpl(url, init);
+        if (!RETRYABLE_STATUS_CODES.has(res.status)) {
+          return res;
+        }
+        lastError = `HTTP ${res.status} ${res.statusText}`.trim();
+        if (!this.shouldRetry(attempt, startedAt)) {
+          break;
+        }
+        await this.sleep(this.nextDelayMs(attempt, res));
+      } catch (error) {
+        lastError = getErrorMessage(error);
+        if (!this.shouldRetry(attempt, startedAt)) {
+          break;
+        }
+        await this.sleep(this.nextDelayMs(attempt));
+      }
+    }
+
+    throw new Error(
+      `Sandbox Runner did not respond after ${attempts} attempts ` +
+        `(cold start or transient network); last error: ${lastError}`,
+    );
+  }
+
+  private shouldRetry(attempt: number, startedAt: number): boolean {
+    if (attempt >= this.retry.maxAttempts) {
+      return false;
+    }
+    return Date.now() - startedAt < this.retry.maxElapsedMs;
+  }
+
+  private nextDelayMs(attempt: number, res?: Response): number {
+    const retryAfterMs = parseRetryAfterMs(res?.headers.get("Retry-After") ?? null);
+    if (retryAfterMs !== undefined) {
+      return Math.min(retryAfterMs, this.retry.maxDelayMs);
+    }
+    const exponential = this.retry.baseDelayMs * 2 ** (attempt - 1);
+    const capped = Math.min(exponential, this.retry.maxDelayMs);
+    const jitter = Math.floor(Math.random() * Math.max(1, capped * 0.25));
+    return Math.min(capped + jitter, this.retry.maxDelayMs);
   }
 
   async startJob(
     token: string,
     request: SandboxRunnerStartRequest,
   ): Promise<SandboxRunnerStartResponse> {
-    const res = await this.fetchImpl(`${this.baseUrl}/jobs`, {
+    const res = await this.fetchWithRetry(`${this.baseUrl}/jobs`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${token}`,
@@ -124,7 +220,7 @@ export class SandboxRunnerClient {
   }
 
   async getJob(token: string, jobId: string): Promise<SandboxRunnerJob> {
-    const res = await this.fetchImpl(
+    const res = await this.fetchWithRetry(
       `${this.baseUrl}/jobs/${encodeURIComponent(jobId)}`,
       {
         headers: { Authorization: `Bearer ${token}` },
@@ -155,7 +251,7 @@ export class SandboxRunnerClient {
       if (job.status === "succeeded" || job.status === "failed") {
         return job;
       }
-      await delay(intervalMs);
+      await this.sleep(intervalMs);
     }
     throw new Error(`Sandbox Runner job '${jobId}' did not finish before the poll limit.`);
   }

package/src/utils/version-check.test.ts

@@ -120,6 +120,36 @@ describe("refreshVersionCache", () => {
     expect(typeof written.fetchedAt).toBe("number");
   });
 
+  it("returns without fetching when the cached version is still within the TTL", async () => {
+    writeCache("5.99.0", 60 * 1000);
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+
+    const mod = await loadModule();
+    await mod.refreshVersionCache();
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    const cachePath = path.join(tmpHome, ".hq", "version-check.json");
+    const written = JSON.parse(fs.readFileSync(cachePath, "utf-8"));
+    expect(written.latest).toBe("5.99.0");
+  });
+
+  it("skips passive refresh for noninteractive status probes", async () => {
+    const originalArgv = process.argv;
+    process.argv = ["node", "hq", "mcp", "status", "--json"];
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+
+    try {
+      const mod = await loadModule();
+      await mod.refreshVersionCache();
+    } finally {
+      process.argv = originalArgv;
+    }
+
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("does not throw or write a cache when fetch fails", async () => {
     const fetchMock = vi.fn().mockRejectedValue(new Error("network down"));
     vi.stubGlobal("fetch", fetchMock);

package/src/utils/version-check.ts

@@ -8,7 +8,9 @@ import { CLI_VERSION } from "../cli-version.js";
 const PACKAGE_NAME = "@indigoai-us/hq-cli";
 const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`;
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const CACHE_TTL_JITTER_MS = 60 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 3_000;
+const REFRESH_LOCK_STALE_MS = 10 * 60 * 1000;
 
 interface CacheEntry {
   latest: string;
@@ -19,6 +21,10 @@ function cachePath(): string {
   return path.join(os.homedir(), ".hq", "version-check.json");
 }
 
+function lockPath(): string {
+  return path.join(os.homedir(), ".hq", "version-check.lock");
+}
+
 function isOptedOut(): boolean {
   return process.env.HQ_NO_UPDATE_CHECK === "1";
 }
@@ -49,6 +55,58 @@ function writeCache(entry: CacheEntry): void {
   }
 }
 
+function freshEnough(entry: CacheEntry, now = Date.now()): boolean {
+  const jitter = Math.floor(Math.random() * CACHE_TTL_JITTER_MS);
+  return now - entry.fetchedAt <= CACHE_TTL_MS - jitter;
+}
+
+function isKnownNoninteractiveStatusProbe(argv: readonly string[] = process.argv): boolean {
+  const args = argv.slice(2);
+  const positional = args.filter((arg) => !arg.startsWith("-"));
+  const json = args.includes("--json") || !process.stdout.isTTY;
+  if (!json) return false;
+  if (positional[0] === "mcp" && positional[1] === "status") return true;
+  if (positional[0] === "packs" && (positional[1] === "list" || positional[1] === "ls")) return true;
+  if (
+    positional[0] === "packages" &&
+    positional[1] === "packs" &&
+    (positional[2] === "list" || positional[2] === "ls")
+  ) {
+    return true;
+  }
+  if ((positional[0] === "sources" || positional[0] === "signals") && positional[1] === "list") {
+    return true;
+  }
+  return false;
+}
+
+function acquireRefreshLock(now = Date.now()): (() => void) | null {
+  const dir = lockPath();
+  try {
+    fs.mkdirSync(path.dirname(dir), { recursive: true });
+    fs.mkdirSync(dir);
+    fs.writeFileSync(path.join(dir, "owner"), `${process.pid}\n${now}\n`);
+    return () => {
+      try {
+        fs.rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // best-effort lock cleanup
+      }
+    };
+  } catch {
+    try {
+      const stat = fs.statSync(dir);
+      if (now - stat.mtimeMs > REFRESH_LOCK_STALE_MS) {
+        fs.rmSync(dir, { recursive: true, force: true });
+        return acquireRefreshLock(now);
+      }
+    } catch {
+      // ignore lock inspection failures
+    }
+    return null;
+  }
+}
+
 export function maybeWarnNewVersion(): void {
   if (isOptedOut()) return;
   const entry = readCache();
@@ -68,7 +126,14 @@ export function maybeWarnNewVersion(): void {
 
 export async function refreshVersionCache(): Promise<void> {
   if (isOptedOut()) return;
+  if (isKnownNoninteractiveStatusProbe()) return;
+  const existing = readCache();
+  if (existing && freshEnough(existing)) return;
+  const releaseLock = acquireRefreshLock();
+  if (!releaseLock) return;
   try {
+    const lockedExisting = readCache();
+    if (lockedExisting && freshEnough(lockedExisting)) return;
     const res = await fetch(REGISTRY_URL, {
       headers: { Accept: "application/json" },
       signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
@@ -79,5 +144,12 @@ export async function refreshVersionCache(): Promise<void> {
     writeCache({ latest: body.version, fetchedAt: Date.now() });
   } catch {
     // best-effort; offline / registry down / timeout — silent
+  } finally {
+    releaseLock();
   }
 }
+
+export const __test__ = {
+  CACHE_TTL_MS,
+  isKnownNoninteractiveStatusProbe,
+};