@indigoai-us/hq-cli 5.224.0 → 5.225.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [5.225.0] — 2026-09-26
+
+### Changed
+
+- Local bots can use the default-off `agents.inbox-poll-backoff-local-cli`
+  gate to increase idle inbox polling from 2 seconds to a capped 30-second
+  backoff. New messages and completed turns reset the cadence.
+
 ## [5.224.0] — 2026-09-26
 
 ### Added

package/dist/lib/bot/inbox-poll-backoff-flag.d.ts

@@ -0,0 +1,24 @@
+import { type FlagClient, type FlagClientOptions } from "@indigoai-us/hq-flags-client";
+import { type BotConfig } from "./config.js";
+export declare const INBOX_POLL_BACKOFF_FLAG = "agents.inbox-poll-backoff-local-cli";
+export declare const INBOX_POLL_BACKOFF_FLAG_FALLBACK = false;
+export declare const INBOX_POLL_BACKOFF_FLAG_TIMEOUT_MS = 150;
+export declare const INBOX_POLL_BACKOFF_FLAG_CACHE_MS: number;
+type InboxPollBackoffFlagClient = Pick<FlagClient, "ready" | "isEnabled" | "close">;
+export interface InboxPollBackoffFlagReaderDependencies {
+    env?: NodeJS.ProcessEnv;
+    createClient?: (options: FlagClientOptions) => InboxPollBackoffFlagClient;
+    getToken?: FlagClientOptions["getToken"];
+    fetch?: typeof fetch;
+    now?: () => number;
+    reportFailure?: (error: unknown) => void;
+}
+export declare function safeErrorClass(error: unknown): string;
+/**
+ * Create a per-bot reader. The flag client is opened at most once per three
+ * minutes; a missing identity, failed request, or malformed snapshot keeps
+ * idle polling at its existing two-second interval.
+ */
+export declare function createInboxPollBackoffFlagReader(config: Pick<BotConfig, "kind" | "workerId" | "companies" | "companySlug" | "hqRoot">, dependencies?: InboxPollBackoffFlagReaderDependencies): () => Promise<boolean>;
+export {};
+//# sourceMappingURL=inbox-poll-backoff-flag.d.ts.map

package/dist/lib/bot/inbox-poll-backoff-flag.js

@@ -0,0 +1,132 @@
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
+import { createFlagClient, } from "@indigoai-us/hq-flags-client";
+import { resolveFlagGate, resolveProcessFlagCompanyContext } from "../flag-registry.js";
+import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
+import { effectiveBotCompanies, effectiveBotKind } from "./config.js";
+export const INBOX_POLL_BACKOFF_FLAG = "agents.inbox-poll-backoff-local-cli";
+export const INBOX_POLL_BACKOFF_FLAG_FALLBACK = false;
+export const INBOX_POLL_BACKOFF_FLAG_TIMEOUT_MS = 150;
+export const INBOX_POLL_BACKOFF_FLAG_CACHE_MS = 3 * 60_000;
+const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+export function safeErrorClass(error) {
+    const name = error instanceof Error ? error.name : "UnknownError";
+    return /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(name) ? name : "UnknownError";
+}
+function reportFlagFailure(error) {
+    process.stderr.write(`HQ local bot inbox poll backoff flag lookup failed (${safeErrorClass(error)}); using default off.\n`);
+}
+function companyContexts(config, env) {
+    if (effectiveBotKind(config) !== "company")
+        return [{}];
+    const slugs = effectiveBotCompanies(config);
+    const fallbackSlug = config.companySlug?.trim();
+    if (slugs.length === 0 && fallbackSlug)
+        slugs.push(fallbackSlug);
+    if (slugs.length === 0)
+        return null;
+    const contexts = [];
+    for (const slug of slugs) {
+        const company = resolveProcessFlagCompanyContext({
+            ...env,
+            HQ_COMPANY_UID: "",
+            HQ_COMPANY_SLUG: slug,
+            HQ_ROOT: config.hqRoot,
+        });
+        if (!company.companyUid || !COMPANY_UID_RE.test(company.companyUid))
+            return null;
+        contexts.push({ companyUid: company.companyUid, companyIdentifiers: [slug] });
+    }
+    return contexts;
+}
+/**
+ * Create a per-bot reader. The flag client is opened at most once per three
+ * minutes; a missing identity, failed request, or malformed snapshot keeps
+ * idle polling at its existing two-second interval.
+ */
+export function createInboxPollBackoffFlagReader(config, dependencies = {}) {
+    const env = dependencies.env ?? process.env;
+    const contexts = companyContexts(config, env);
+    const endpoint = resolveFlagRegistryEndpoint(undefined, env);
+    const now = dependencies.now ?? Date.now;
+    const createClient = dependencies.createClient ?? createFlagClient;
+    const getToken = dependencies.getToken ?? (() => loadCachedTokens()?.idToken ?? "");
+    const doFetch = dependencies.fetch ?? globalThis.fetch;
+    const report = dependencies.reportFailure ?? reportFlagFailure;
+    let cachedValue = INBOX_POLL_BACKOFF_FLAG_FALLBACK;
+    let lastReadAt = Number.NEGATIVE_INFINITY;
+    let pending = null;
+    const readContext = async (context) => {
+        let client;
+        let failed = false;
+        let failureReported = false;
+        let enabled = INBOX_POLL_BACKOFF_FLAG_FALLBACK;
+        const reportFailureOnce = (error) => {
+            failed = true;
+            if (failureReported)
+                return;
+            failureReported = true;
+            report(error);
+        };
+        try {
+            client = createClient({
+                endpoint,
+                ...(context.companyUid ? { companyUid: context.companyUid } : {}),
+                ...(context.companyIdentifiers ? { companyIdentifiers: context.companyIdentifiers } : {}),
+                env: {},
+                getToken,
+                ...(doFetch ? { fetch: doFetch } : {}),
+                refreshIntervalMs: 0,
+                requestTimeoutMs: INBOX_POLL_BACKOFF_FLAG_TIMEOUT_MS,
+                onError: reportFailureOnce,
+            });
+            await client.ready();
+            if (!failed) {
+                enabled = resolveFlagGate(client, INBOX_POLL_BACKOFF_FLAG, { fallback: INBOX_POLL_BACKOFF_FLAG_FALLBACK }, () => INBOX_POLL_BACKOFF_FLAG_FALLBACK);
+            }
+        }
+        catch (error) {
+            reportFailureOnce(error);
+        }
+        finally {
+            try {
+                client?.close();
+            }
+            catch (error) {
+                reportFailureOnce(error);
+            }
+        }
+        return failed ? INBOX_POLL_BACKOFF_FLAG_FALLBACK : enabled;
+    };
+    const read = async () => {
+        if (!contexts || contexts.length === 0) {
+            report(new Error("local bot inbox poll backoff flag has no resolvable company identity"));
+            return INBOX_POLL_BACKOFF_FLAG_FALLBACK;
+        }
+        const values = await Promise.all(contexts.map(readContext));
+        return values.every(Boolean);
+    };
+    return () => {
+        const currentTime = now();
+        if (pending)
+            return pending;
+        if (currentTime - lastReadAt < INBOX_POLL_BACKOFF_FLAG_CACHE_MS) {
+            return Promise.resolve(cachedValue);
+        }
+        lastReadAt = currentTime;
+        pending = read()
+            .then((value) => {
+            cachedValue = value;
+            return value;
+        })
+            .catch((error) => {
+            report(error);
+            cachedValue = INBOX_POLL_BACKOFF_FLAG_FALLBACK;
+            return cachedValue;
+        })
+            .finally(() => {
+            pending = null;
+        });
+        return pending;
+    };
+}
+//# sourceMappingURL=inbox-poll-backoff-flag.js.map

package/dist/lib/bot/run.d.ts

@@ -104,7 +104,7 @@ export declare const UNDELIVERABLE_JOB_REPORT_TEXT = "This scheduled run finishe
  * instead of waiting, with no explanation, behind two long jobs.
  */
 export declare const MAX_PARALLEL_JOB_TURNS = 1;
-export type SleepFn = (ms: number) => Promise<void>;
+export type SleepFn = (ms: number, signal?: AbortSignal) => Promise<void>;
 export interface BotRunDeps {
     dir: string;
     config: BotConfig;
@@ -118,6 +118,8 @@ export interface BotRunDeps {
     pid?: number;
     isProcessAlive?: (pid: number) => boolean;
     inboxIntervalMs?: number;
+    /** Cached, default-off reader for the local inbox polling gate. */
+    inboxPollBackoffEnabled?: () => Promise<boolean>;
     heartbeatIntervalMs?: number;
     /** Override the rendered system prompt (tests). */
     systemPromptOverride?: string;

package/dist/lib/bot/run.js

@@ -76,6 +76,7 @@ import { clearBotSession, readBotSession, writeBotSession } from "./session.js";
 import { defaultBotStatus, patchBotStatus, readBotStatus } from "./status.js";
 import { CLI_VERSION } from "../../cli-version.js";
 import { CLI_UPDATE_RESTART_EXIT_CODE } from "./cli-update.js";
+import { createInboxPollBackoffFlagReader, safeErrorClass } from "./inbox-poll-backoff-flag.js";
 export const INBOX_POLL_INTERVAL_MS = 2_000;
 export const HEARTBEAT_INTERVAL_MS = 30_000;
 /** First 429/5xx wait when Retry-After is absent (inbox polls at 2s). */
@@ -224,8 +225,20 @@ class FailureWindow {
         return this.count(nowMs) >= this.limit;
     }
 }
-function defaultSleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function defaultSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
 }
 /**
  * A body posted as several parts where an early part got through and a later
@@ -262,6 +275,7 @@ export async function runBot(deps) {
     const { dir, config, api, runtime } = deps;
     const runTurn = deps.runTurn ?? ((rt, input) => runRuntimeTurn(rt, input));
     const inboxIntervalMs = deps.inboxIntervalMs ?? INBOX_POLL_INTERVAL_MS;
+    const inboxPollBackoffEnabled = deps.inboxPollBackoffEnabled ?? createInboxPollBackoffFlagReader(config);
     const heartbeatIntervalMs = deps.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
     const exit = deps.exit ?? ((code) => process.exit(code));
     const fallback = () => defaultBotStatus(pid, config.runtime, now);
@@ -312,6 +326,16 @@ export async function runBot(deps) {
     const cliVersion = deps.cliUpdate?.runningVersion ?? CLI_VERSION;
     /** Set once an update restart is due: no new turns, then exit for the supervisor. */
     let cliUpdatePending = null;
+    const pollForCliUpdate = () => {
+        const update = deps.cliUpdate?.poll(log) ?? null;
+        if (!update)
+            return false;
+        cliUpdatePending = update;
+        stopping = true;
+        const busy = running.size;
+        log("info", `hq-cli updated ${update.from} -> ${update.to}; restarting to load it${busy ? ` after ${busy} running turn${busy === 1 ? "" : "s"} finish${busy === 1 ? "es" : ""}` : ""}`);
+        return true;
+    };
     // ── Preflight: creds, pid lock, owner verification ─────────────────────────
     const credsProblem = preflightCreds(dir, config);
     if (credsProblem) {
@@ -506,6 +530,45 @@ export async function runBot(deps) {
     })();
     // ── Inbox loop ─────────────────────────────────────────────────────────────
     const attempts = new Map();
+    const inboxBackoffSteps = [inboxIntervalMs, 10_000, 20_000, 30_000];
+    let inboxBackoffIndex = 0;
+    let inboxWaitGeneration = 0;
+    let activeInboxWait = null;
+    const resetInboxBackoff = () => {
+        inboxBackoffIndex = 0;
+        inboxWaitGeneration += 1;
+        activeInboxWait?.abort();
+    };
+    const waitForInbox = async (delayMs, adaptive) => {
+        if (!adaptive) {
+            await sleep(delayMs);
+            return;
+        }
+        let remainingMs = delayMs;
+        let observedGeneration = inboxWaitGeneration;
+        while (remainingMs > 0 && !stopping && state === "running") {
+            const controller = new AbortController();
+            activeInboxWait = controller;
+            const chunkMs = Math.min(inboxIntervalMs, remainingMs);
+            await sleep(chunkMs, controller.signal);
+            if (activeInboxWait === controller)
+                activeInboxWait = null;
+            if (stopping || state !== "running")
+                break;
+            if (hasPromotionHold(dir))
+                break;
+            if (observedGeneration !== inboxWaitGeneration || controller.signal.aborted) {
+                observedGeneration = inboxWaitGeneration;
+                remainingMs = inboxIntervalMs;
+                continue;
+            }
+            remainingMs -= chunkMs;
+            // Keep the install watcher at its original two-second cadence even when
+            // the inbox itself is waiting longer between empty polls.
+            if (remainingMs > 0 && pollForCliUpdate())
+                break;
+        }
+    };
     /** Build the user turn for a room trigger: header + recent transcript + the message. */
     const buildRoomTurn = async (item, target, text) => {
         const name = (item.channelName ?? "").trim() || target.channelId;
@@ -1551,6 +1614,7 @@ export async function runBot(deps) {
                 log("warn", `inbox item ${item.messageId} failed: ${err instanceof Error ? err.message : String(err)}`);
             })
                 .finally(() => {
+                resetInboxBackoff();
                 busyLanes.delete(lane);
                 pending.delete(item.messageId);
                 running.delete(task);
@@ -1588,14 +1652,8 @@ export async function runBot(deps) {
             // The install under this process was updated: take nothing new, let the
             // turns already running finish, then exit so the supervisor loads it.
             // Queued items were never started or acked; the next process gets them.
-            const update = deps.cliUpdate?.poll(log) ?? null;
-            if (update) {
-                cliUpdatePending = update;
-                stopping = true;
-                const busy = running.size;
-                log("info", `hq-cli updated ${update.from} -> ${update.to}; restarting to load it${busy ? ` after ${busy} running turn${busy === 1 ? "" : "s"} finish${busy === 1 ? "es" : ""}` : ""}`);
+            if (pollForCliUpdate())
                 break;
-            }
             // A kickoff held for a sign-in retries on the same timer as messages.
             if (busyLanes.size === 0 &&
                 (!signInIssue || now().getTime() >= nextSignInRetryAt) &&
@@ -1609,17 +1667,26 @@ export async function runBot(deps) {
             // Completions the cloud has not accepted yet: re-send the report (never
             // the work), alongside the poll rather than in front of it.
             kickCompletionRetries();
+            const useInboxBackoff = await inboxPollBackoffEnabled().catch((error) => {
+                log("warn", `inbox poll backoff flag lookup failed (${safeErrorClass(error)}); using default-off`);
+                return false;
+            });
+            let items;
             try {
-                const items = await api.pullInbox(config.agentUid);
+                items = await api.pullInbox(config.agentUid);
                 inboxFails = 0;
                 setStatus({ lastInboxPollAt: now().toISOString(), lastInboxPollOk: true, lastInboxError: undefined });
                 // One catch-up per job per wake: when several runs of the same job are
                 // pending, the newest runs and the older ones are reported skipped.
                 for (const id of planJobRuns(items, handledJobFires).superseded)
                     supersededJobRuns.add(id);
+                if (items.length > 0)
+                    resetInboxBackoff();
                 for (const item of items)
                     enqueue(item);
                 pump();
+                if (stopping || state !== "running")
+                    break;
             }
             catch (err) {
                 inboxFails += 1;
@@ -1633,7 +1700,17 @@ export async function runBot(deps) {
             }
             if (stopping || state !== "running")
                 break;
-            await sleep(inboxIntervalMs);
+            if (!useInboxBackoff) {
+                inboxBackoffIndex = 0;
+                await waitForInbox(inboxIntervalMs, false);
+                continue;
+            }
+            const delayMs = items.length > 0
+                ? inboxIntervalMs
+                : inboxBackoffSteps[Math.min(inboxBackoffIndex, inboxBackoffSteps.length - 1)];
+            if (items.length === 0)
+                inboxBackoffIndex = Math.min(inboxBackoffIndex + 1, inboxBackoffSteps.length - 1);
+            await waitForInbox(delayMs, true);
         }
         // Stop, drain and promotion wait for the turns already running. Queued
         // messages were never started or acked, so the inbox delivers them again.
@@ -1655,6 +1732,7 @@ export async function runBot(deps) {
             return;
         }
         stopping = true;
+        activeInboxWait?.abort();
         // End the turn in progress; its message gets "did not finish", not silence.
         // Promotion instead drains that turn, including its reply and ACK, before
         // the coordinator snapshots memory and starts the cloud consumer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.224.0",
+  "version": "5.225.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {