@impulselab/hepha 0.2.280 → 0.2.281

package/README.md

@@ -37,7 +37,10 @@ hepha sessions list --json
 ```
 
 `HEPHA_API_KEY` takes precedence over a stored login. `HEPHA_URL` can point the
-CLI at another Hephaistos deployment.
+CLI at another Hephaistos deployment. `HEPHA_TIMEOUT_MS` bounds one request;
+`HEPHA_FOLLOW_MAX_OUTAGE_SECONDS` makes `--follow` give up that long after its
+first failure, exiting with that failure — unset, it waits for the platform to
+come back.
 
 ## Exit codes
 

package/dist/index.js

@@ -122,6 +122,11 @@ var CliOutput = class {
   }
   error(text) {
     process.stderr.write(`${this.paint(`error: ${this.safe(text)}`, "red")}
+`);
+  }
+  // Progress a long command owes the user; stderr keeps `--json` stdout whole.
+  warn(text) {
+    process.stderr.write(`${this.paint(this.safe(text), "yellow")}
 `);
   }
   /**
@@ -387,6 +392,10 @@ ENVIRONMENT
   HEPHA_TOKEN       A device-flow session token, instead of ~/.hepha/config.json.
   HEPHA_URL         Platform base URL.
   HEPHA_TIMEOUT_MS  Per-request timeout in milliseconds (default 30000).
+  HEPHA_FOLLOW_MAX_OUTAGE_SECONDS
+                    Give up this long after --follow's first failure, with that
+                    failure as the exit code. Unset, it waits for the platform
+                    to come back.
 
 GLOBAL FLAGS
   --json          Machine-readable output on stdout. Every command that
@@ -632,7 +641,11 @@ function retryAfterSeconds(response) {
     return void 0;
   }
   const seconds = Number(raw.trim());
-  return Number.isFinite(seconds) && seconds >= 0 ? seconds : void 0;
+  if (Number.isFinite(seconds)) {
+    return seconds >= 0 ? seconds : void 0;
+  }
+  const date = Date.parse(raw.trim());
+  return Number.isNaN(date) ? void 0 : Math.max(0, (date - Date.now()) / 1e3);
 }
 
 // src/lib/response/fetch-response.ts
@@ -841,6 +854,8 @@ function expectShape(payload, endpoint, requirements) {
 // src/lib/is/is.ts
 var is = {
   string: (value) => typeof value === "string",
+  // Absent passes: a field a deployment older than this binary does not send.
+  optionalString: (value) => value === void 0 || typeof value === "string",
   number: (value) => typeof value === "number",
   array: (value) => Array.isArray(value),
   object: (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value)
@@ -1180,7 +1195,7 @@ var deviceTokenError = {
   }
 };
 
-// src/commands/next/next-poll-delay.ts
+// src/lib/retry/next-poll-delay.ts
 function nextPollDelay(interval, remainingSeconds) {
   if (remainingSeconds <= 0) {
     return null;
@@ -1739,28 +1754,224 @@ function consumeSessionEvents(events, cursor, quiet) {
   return cursor;
 }
 
-// src/lib/terminal/terminal-constants.ts
-var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "killed", "abstained"]);
+// src/lib/sleep/sleep.ts
+function sleep2(seconds) {
+  return new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
+}
+
+// src/lib/sleep/sleep-constants.ts
+var MAX_TIMER_MS = 2147483647;
+
+// src/lib/sleep/timer-delay-ms.ts
+function timerDelayMs(seconds) {
+  return Math.min(Math.max(0, seconds) * 1e3, MAX_TIMER_MS);
+}
+
+// src/lib/sleep/interruptible-sleep.ts
+function interruptibleSleep(seconds) {
+  return new Promise((resolve, reject) => {
+    const onInterrupt = () => {
+      clearTimeout(timer);
+      reject(
+        new CliError("Follow interrupted.", 130, {
+          code: CLI_ERROR_CODES.INTERRUPTED
+        })
+      );
+    };
+    const timer = setTimeout(() => {
+      process.removeListener("SIGINT", onInterrupt);
+      resolve();
+    }, timerDelayMs(seconds));
+    process.once("SIGINT", onInterrupt);
+  });
+}
+
+// src/lib/session/default-follow-session-dependencies.ts
+var defaultFollowSessionDependencies = {
+  request: api,
+  pollSleep: sleep2,
+  retrySleep: interruptibleSleep,
+  random: Math.random,
+  // Monotonic: an NTP step backwards must not hand the outage budget more time
+  // to burn, nor mute the periodic reminder until the clock catches up.
+  now: () => performance.now(),
+  warn: (message) => out.warn(message)
+};
+
+// src/lib/session/retry/follow-outage-message.ts
+function followOutageMessage(warned) {
+  return warned ? "Hepha API still unavailable; retrying follow." : "Hepha API unavailable; retrying follow.";
+}
+
+// src/lib/session/retry/follow-retry-constants.ts
+var FOLLOW_RETRY_CAP_SECONDS = 22.5;
+var FOLLOW_OUTAGE_FEEDBACK_MS = 5 * 60 * 1e3;
+var RETRYABLE_FOLLOW_STATUS = /* @__PURE__ */ new Set([
+  408,
+  425,
+  429,
+  500,
+  502,
+  503,
+  504
+]);
+
+// src/lib/session/retry/follow-retry-delay.ts
+function followRetryDelay(error, failures, random) {
+  const exponential = Math.min(
+    FOLLOW_RETRY_CAP_SECONDS,
+    2 ** Math.min(failures - 1, 30)
+  );
+  const jittered = exponential / 2 + random() * (exponential / 2);
+  const retryAfter = Math.max(0, error.details.retryAfterSeconds ?? 0);
+  return Math.max(jittered, retryAfter + random() * (exponential / 2));
+}
+
+// src/lib/session/retry/remaining-outage-seconds.ts
+function remainingOutageSeconds(outageStartedAt, now, maxOutageMs) {
+  if (maxOutageMs === null) {
+    return Number.POSITIVE_INFINITY;
+  }
+  return (maxOutageMs - (now - outageStartedAt)) / 1e3;
+}
+
+// src/lib/session/retry/retryable-follow-error.ts
+function retryableFollowError(error) {
+  return error instanceof CliError && (RETRYABLE_FOLLOW_STATUS.has(error.details.status ?? 0) || error.details.code === CLI_ERROR_CODES.NETWORK || error.details.code === CLI_ERROR_CODES.TIMEOUT);
+}
+
+// src/lib/session/retry/should-report-follow-outage.ts
+function shouldReportFollowOutage(lastWarnedAt, now) {
+  return lastWarnedAt === null || now - lastWarnedAt >= FOLLOW_OUTAGE_FEEDBACK_MS;
+}
+
+// src/lib/session/retry/wait-for-follow-retry.ts
+async function waitForFollowRetry(params) {
+  const { error, retry, dependencies } = params;
+  if (!retryableFollowError(error)) {
+    throw error;
+  }
+  retry.failures += 1;
+  const now = dependencies.now();
+  retry.outageStartedAt ??= now;
+  const delay = nextPollDelay(
+    followRetryDelay(error, retry.failures, dependencies.random),
+    remainingOutageSeconds(retry.outageStartedAt, now, params.maxOutageMs)
+  );
+  if (delay === null) {
+    throw error;
+  }
+  if (shouldReportFollowOutage(retry.lastWarnedAt, now)) {
+    dependencies.warn(followOutageMessage(retry.warned));
+    retry.warned = true;
+    retry.lastWarnedAt = now;
+  }
+  await dependencies.retrySleep(delay);
+  if (remainingOutageSeconds(
+    retry.outageStartedAt,
+    dependencies.now(),
+    params.maxOutageMs
+  ) <= 0) {
+    throw error;
+  }
+}
+
+// src/lib/session/retry/request-with-follow-retry.ts
+async function requestWithFollowRetry(params) {
+  for (; ; ) {
+    try {
+      const result = await params.operation();
+      if (params.retry.warned) {
+        params.dependencies.warn("Hepha API recovered; continuing follow.");
+      }
+      params.retry.failures = 0;
+      params.retry.warned = false;
+      params.retry.lastWarnedAt = null;
+      params.retry.outageStartedAt = null;
+      return result;
+    } catch (error) {
+      await waitForFollowRetry({
+        error,
+        retry: params.retry,
+        maxOutageMs: params.maxOutageMs,
+        dependencies: params.dependencies
+      });
+    }
+  }
+}
 
 // src/lib/blocked/blocked-constants.ts
 var BLOCKED = /* @__PURE__ */ new Set(["waiting_human", "awaiting_approval"]);
 
-// src/lib/sleep/sleep.ts
-function sleep2(seconds) {
-  return new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
+// src/lib/terminal/terminal-constants.ts
+var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "killed", "abstained"]);
+
+// src/lib/session/is-follow-stop-status.ts
+function isFollowStopStatus(status) {
+  return status !== void 0 && (TERMINAL.has(status) || BLOCKED.has(status));
+}
+
+// src/lib/session/retry/resolve-follow-outage-budget.ts
+function resolveFollowOutageBudget() {
+  const raw = process.env.HEPHA_FOLLOW_MAX_OUTAGE_SECONDS?.trim();
+  if (!raw) {
+    return null;
+  }
+  const budgetMs = Number(raw) * 1e3;
+  if (!Number.isFinite(budgetMs) || budgetMs <= 0) {
+    throw new CliError(
+      `HEPHA_FOLLOW_MAX_OUTAGE_SECONDS expects a positive number of seconds, got "${raw}".`,
+      2
+    );
+  }
+  return budgetMs;
+}
+
+// src/lib/session/retry/follow-request-timeout-ms.ts
+function followRequestTimeoutMs(retry, maxOutageMs, now) {
+  if (retry.outageStartedAt === null) {
+    return resolveTimeout();
+  }
+  const remainingMs = remainingOutageSeconds(retry.outageStartedAt, now, maxOutageMs) * 1e3;
+  return Math.max(1, Math.min(resolveTimeout(), remainingMs));
 }
 
 // src/lib/session/follow-session.ts
-async function followSession(sessionId, options = {}) {
+async function followSession(sessionId, options = {}, dependencies = defaultFollowSessionDependencies) {
   let cursor = options.after ?? 0;
+  let emptyPolls = 0;
+  const retry = {
+    failures: 0,
+    warned: false,
+    lastWarnedAt: null,
+    outageStartedAt: null
+  };
+  const maxOutageMs = resolveFollowOutageBudget();
   for (; ; ) {
-    const page = expectShape(
-      await api(path`/sessions/${sessionId}/events`, {
-        query: { after: cursor || void 0, limit: PAGE_SIZE }
-      }),
-      "GET /sessions/{id}/events",
-      { items: is.array }
-    );
+    const page = await requestWithFollowRetry({
+      retry,
+      maxOutageMs,
+      dependencies,
+      operation: async () => expectShape(
+        await dependencies.request(path`/sessions/${sessionId}/events`, {
+          query: { after: cursor || void 0, limit: PAGE_SIZE },
+          timeoutMs: followRequestTimeoutMs(
+            retry,
+            maxOutageMs,
+            dependencies.now()
+          )
+        }),
+        "GET /sessions/{id}/events",
+        {
+          items: is.array,
+          hasMore: (value) => typeof value === "boolean",
+          nextCursor: (value) => value === null || is.number(value),
+          // Optional: a deployment older than this binary omits it, and a
+          // missing field here would be a non-retryable schema mismatch.
+          status: is.optionalString
+        }
+      )
+    });
     cursor = consumeSessionEvents(page.items, cursor, options.quiet);
     if (page.nextCursor !== null) {
       cursor = Math.max(cursor, page.nextCursor);
@@ -1768,11 +1979,30 @@ async function followSession(sessionId, options = {}) {
     if (page.hasMore) {
       continue;
     }
-    const session = await api(path`/sessions/${sessionId}`);
-    if (TERMINAL.has(session.status) || BLOCKED.has(session.status)) {
-      return session;
+    emptyPolls = page.items.length === 0 ? emptyPolls + 1 : 0;
+    if (isFollowStopStatus(page.status) || page.items.length > 0 || emptyPolls >= 3) {
+      const session = await requestWithFollowRetry({
+        retry,
+        maxOutageMs,
+        dependencies,
+        operation: async () => expectShape(
+          await dependencies.request(path`/sessions/${sessionId}`, {
+            timeoutMs: followRequestTimeoutMs(
+              retry,
+              maxOutageMs,
+              dependencies.now()
+            )
+          }),
+          "GET /sessions/{id}",
+          { status: is.string }
+        )
+      });
+      emptyPolls = 0;
+      if (isFollowStopStatus(session.status)) {
+        return session;
+      }
     }
-    await sleep2(POLL_SECONDS);
+    await dependencies.pollSleep(POLL_SECONDS);
   }
 }