@indigoai-us/hq-cli 5.345.187 → 5.345.188

package/dist/hq-cloud-sync-runner/package.json

@@ -1 +1 @@
-{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.106","bundleSha256":"ae4c7a7b3040977faff6e9ea7f302bc9e46cf77675347788642e362c3337e3fe","formatVersion":1}
+{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.107","bundleSha256":"0df48ddf2618cac4801b8abefa1d2a4b4a915f368bf7d1b2823bcdd104044325","formatVersion":1}

package/dist/lib/agent-kit/inbox-fetch.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Bounded, once-retried read of the agent's server inbox.
+ *
+ * `hq agent inbox` and the `hq_inbox_read` MCP tool used to do one token mint
+ * and one GET with no deadline and no retry, so three transient conditions
+ * each showed up as a local-mirror fallback that cleared minutes later
+ * (feedback 3e376c49, DEV-4065):
+ *
+ *   - the machine-token cache is shared with the kit poller and heartbeat,
+ *     which re-mint in the same minute each hour; hq-cloud serialises mints
+ *     behind a 20 s lock and throws "... held by another process ..." when it
+ *     gives up waiting;
+ *   - the server bounds its inbox pull at 18 s and answers 503 with
+ *     `Retry-After: 2` when the listing stalls;
+ *   - a half-open socket can hang the GET until the OS drops it.
+ *
+ * Each attempt (mint plus GET) runs under one deadline. A first attempt that
+ * fails for one of those reasons is retried exactly once after a short delay
+ * (the server's `Retry-After`, capped, when it sent one). The second attempt
+ * mints a fresh token, because the first failure may have been the mint. Auth
+ * and not-found answers, and a 200 whose body is invalid, are never retried.
+ * Pure apart from the injected `sleep`/`random`, so tests drive it with fake
+ * timers.
+ */
+import type { MergedInbox } from "./inbox-state.js";
+/** Env override for the per-attempt deadline; values under the floor are raised to it. */
+export declare const AGENT_INBOX_TIMEOUT_ENV = "HQ_AGENT_INBOX_TIMEOUT_MS";
+/** Delay before the one retry when the server sent no usable `Retry-After`. */
+export declare const AGENT_INBOX_RETRY_BASE_MS = 1500;
+/** Jitter added to the base delay, so clients that fail together do not retry together. */
+export declare const AGENT_INBOX_RETRY_JITTER_MS = 500;
+/** Longest wait honoured from a `Retry-After` header. */
+export declare const AGENT_INBOX_RETRY_AFTER_CAP_MS = 5000;
+/** Total attempts: the first read plus one retry. */
+export declare const AGENT_INBOX_MAX_ATTEMPTS = 2;
+export interface InboxFetchResponse {
+    status: number;
+    /** Decoded JSON body, or `undefined` when it did not decode. Never a raw string of response bytes. */
+    body: unknown;
+    /** Parsed numeric `Retry-After` header in seconds, when the server sent one. */
+    retryAfterSeconds?: number;
+}
+export interface FetchServerInboxDeps {
+    /** Mint (or fetch from cache) the machine token. Called again for the retry. */
+    mint: (signal: AbortSignal) => Promise<string>;
+    /** GET the inbox with `token`. Must not throw on a non-2xx status. */
+    fetch: (token: string, signal: AbortSignal) => Promise<InboxFetchResponse>;
+    sleep?: (ms: number) => Promise<void>;
+    /** Uniform [0, 1) source for the jitter. */
+    random?: () => number;
+    /** Per-attempt deadline covering mint plus GET. */
+    timeoutMs?: number;
+}
+export type FetchServerInboxOutcome = {
+    ok: true;
+    response: {
+        status: number;
+        body: unknown;
+    };
+    attempts: number;
+} | {
+    ok: false;
+    error: unknown;
+    attempts: number;
+};
+/** Per-attempt deadline from the env, defaulting to the kit's request timeout. */
+export declare function resolveAgentInboxTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/** Whether a thrown first attempt is worth one more try. */
+export declare function isRetryableInboxError(err: unknown): boolean;
+export declare function isRetryableInboxStatus(status: number): boolean;
+/** `Retry-After` as seconds, or undefined for a missing, non-numeric or negative value. */
+export declare function parseRetryAfterSeconds(header: string | null | undefined): number | undefined;
+/**
+ * Read the server inbox with at most AGENT_INBOX_MAX_ATTEMPTS attempts, each
+ * bounded by `timeoutMs`. Never throws: the outcome carries either the last
+ * response or the last error, plus how many attempts were made.
+ */
+export declare function fetchServerInboxWithRetry(deps: FetchServerInboxDeps): Promise<FetchServerInboxOutcome>;
+/** Suffix added to the degradation note when the retry also failed. */
+export declare const AGENT_INBOX_AFTER_ATTEMPTS_SUFFIX = " (after 2 attempts)";
+export interface AnnotatedInbox extends MergedInbox {
+    /** True whenever the answer is not a complete server read. */
+    stale: boolean;
+    /** Present when more than one attempt was made, so a hard failure is distinct from a single blip. */
+    attempts?: number;
+}
+/**
+ * Add `stale` and, when a retry happened, `attempts` to a merged inbox. A
+ * degraded note after a retry also says so in words.
+ */
+export declare function annotateInboxAttempts(merged: MergedInbox, attempts: number): AnnotatedInbox;
+//# sourceMappingURL=inbox-fetch.d.ts.map

package/dist/lib/agent-kit/inbox-fetch.js

@@ -0,0 +1,135 @@
+/**
+ * Bounded, once-retried read of the agent's server inbox.
+ *
+ * `hq agent inbox` and the `hq_inbox_read` MCP tool used to do one token mint
+ * and one GET with no deadline and no retry, so three transient conditions
+ * each showed up as a local-mirror fallback that cleared minutes later
+ * (feedback 3e376c49, DEV-4065):
+ *
+ *   - the machine-token cache is shared with the kit poller and heartbeat,
+ *     which re-mint in the same minute each hour; hq-cloud serialises mints
+ *     behind a 20 s lock and throws "... held by another process ..." when it
+ *     gives up waiting;
+ *   - the server bounds its inbox pull at 18 s and answers 503 with
+ *     `Retry-After: 2` when the listing stalls;
+ *   - a half-open socket can hang the GET until the OS drops it.
+ *
+ * Each attempt (mint plus GET) runs under one deadline. A first attempt that
+ * fails for one of those reasons is retried exactly once after a short delay
+ * (the server's `Retry-After`, capped, when it sent one). The second attempt
+ * mints a fresh token, because the first failure may have been the mint. Auth
+ * and not-found answers, and a 200 whose body is invalid, are never retried.
+ * Pure apart from the injected `sleep`/`random`, so tests drive it with fake
+ * timers.
+ */
+import { networkTransportErrorCode } from "../../utils/network-transport-error.js";
+import { KIT_REQUEST_TIMEOUT_MIN_MS, KIT_REQUEST_TIMEOUT_MS, KitRequestTimeoutError, withRequestTimeout } from "./run/request-timeout.js";
+/** Env override for the per-attempt deadline; values under the floor are raised to it. */
+export const AGENT_INBOX_TIMEOUT_ENV = "HQ_AGENT_INBOX_TIMEOUT_MS";
+/** Delay before the one retry when the server sent no usable `Retry-After`. */
+export const AGENT_INBOX_RETRY_BASE_MS = 1_500;
+/** Jitter added to the base delay, so clients that fail together do not retry together. */
+export const AGENT_INBOX_RETRY_JITTER_MS = 500;
+/** Longest wait honoured from a `Retry-After` header. */
+export const AGENT_INBOX_RETRY_AFTER_CAP_MS = 5_000;
+/** Total attempts: the first read plus one retry. */
+export const AGENT_INBOX_MAX_ATTEMPTS = 2;
+// 504 is absent on purpose: vaultApiFetch already retries a 504 once
+// (Lambda invoke errors), and a second outer retry would make three GETs.
+const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503]);
+const LOCK_HELD_RE = /held by another process/i;
+const TRANSPORT_MESSAGE_RE = /\b(fetch failed|ECONNRESET|ETIMEDOUT|EAI_AGAIN)\b/;
+/** Per-attempt deadline from the env, defaulting to the kit's request timeout. */
+export function resolveAgentInboxTimeoutMs(env = process.env) {
+    const raw = env[AGENT_INBOX_TIMEOUT_ENV]?.trim();
+    if (!raw)
+        return KIT_REQUEST_TIMEOUT_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        return KIT_REQUEST_TIMEOUT_MS;
+    return Math.max(KIT_REQUEST_TIMEOUT_MIN_MS, Math.floor(n));
+}
+/** Whether a thrown first attempt is worth one more try. */
+export function isRetryableInboxError(err) {
+    if (err instanceof KitRequestTimeoutError)
+        return true;
+    if (!(err instanceof Error))
+        return false;
+    if (LOCK_HELD_RE.test(err.message))
+        return true;
+    if (networkTransportErrorCode(err) !== null)
+        return true;
+    if (err instanceof TypeError && err.message === "fetch failed")
+        return true;
+    return TRANSPORT_MESSAGE_RE.test(err.message);
+}
+export function isRetryableInboxStatus(status) {
+    return RETRYABLE_STATUSES.has(status);
+}
+/** `Retry-After` as seconds, or undefined for a missing, non-numeric or negative value. */
+export function parseRetryAfterSeconds(header) {
+    if (header === null || header === undefined)
+        return undefined;
+    const trimmed = header.trim();
+    if (!/^\d+(\.\d+)?$/.test(trimmed))
+        return undefined;
+    const n = Number(trimmed);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+function retryDelayMs(retryAfterSeconds, random) {
+    if (retryAfterSeconds !== undefined) {
+        return Math.min(AGENT_INBOX_RETRY_AFTER_CAP_MS, Math.round(retryAfterSeconds * 1000));
+    }
+    return AGENT_INBOX_RETRY_BASE_MS + Math.floor(random() * AGENT_INBOX_RETRY_JITTER_MS);
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Read the server inbox with at most AGENT_INBOX_MAX_ATTEMPTS attempts, each
+ * bounded by `timeoutMs`. Never throws: the outcome carries either the last
+ * response or the last error, plus how many attempts were made.
+ */
+export async function fetchServerInboxWithRetry(deps) {
+    const sleep = deps.sleep ?? defaultSleep;
+    const random = deps.random ?? Math.random;
+    const timeoutMs = deps.timeoutMs ?? KIT_REQUEST_TIMEOUT_MS;
+    let attempts = 0;
+    for (;;) {
+        attempts += 1;
+        const last = attempts >= AGENT_INBOX_MAX_ATTEMPTS;
+        let retryAfterSeconds;
+        try {
+            const res = await withRequestTimeout(timeoutMs, undefined, async (signal) => {
+                const token = await deps.mint(signal);
+                return deps.fetch(token, signal);
+            });
+            if (last || !isRetryableInboxStatus(res.status)) {
+                return { ok: true, response: { status: res.status, body: res.body }, attempts };
+            }
+            retryAfterSeconds = res.retryAfterSeconds;
+        }
+        catch (err) {
+            if (last || !isRetryableInboxError(err))
+                return { ok: false, error: err, attempts };
+        }
+        await sleep(retryDelayMs(retryAfterSeconds, random));
+    }
+}
+/** Suffix added to the degradation note when the retry also failed. */
+export const AGENT_INBOX_AFTER_ATTEMPTS_SUFFIX = ` (after ${AGENT_INBOX_MAX_ATTEMPTS} attempts)`;
+/**
+ * Add `stale` and, when a retry happened, `attempts` to a merged inbox. A
+ * degraded note after a retry also says so in words.
+ */
+export function annotateInboxAttempts(merged, attempts) {
+    const stale = merged.source !== "server";
+    const retried = attempts > 1;
+    const note = merged.note && retried && stale ? `${merged.note}${AGENT_INBOX_AFTER_ATTEMPTS_SUFFIX}` : merged.note;
+    return {
+        entries: merged.entries,
+        source: merged.source,
+        stale,
+        ...(note ? { note } : {}),
+        ...(retried ? { attempts } : {}),
+    };
+}
+//# sourceMappingURL=inbox-fetch.js.map

package/dist/lib/agent-kit/mcp/tools.d.ts

@@ -16,6 +16,7 @@
  * tool result.
  */
 import type { ExternalMachineCreds } from "../creds.js";
+import { type FetchServerInboxDeps } from "../inbox-fetch.js";
 import type { AgentKitPaths } from "../paths.js";
 import { type McpTool } from "./jsonrpc.js";
 export interface HqRunResult {
@@ -32,7 +33,8 @@ export interface McpToolClients {
     paths: Pick<AgentKitPaths, "inboxDir" | "attachmentsDir">;
     /** Run `hq <args…>` as the machine identity; never throws. */
     runHq: (args: string[]) => Promise<HqRunResult>;
-    getToken: () => Promise<string>;
+    /** Machine token; `signal` cancels this caller's wait on a shared mint. */
+    getToken: (signal?: AbortSignal) => Promise<string>;
     /**
      * Whether this kit mirrors the vault to disk. Off by default, and it decides
      * what `hq_search` can honestly do: the local qmd index only exists when
@@ -47,15 +49,22 @@ export interface McpToolClients {
      * key through the presign API, as the machine identity.
      */
     downloadVaultObject: (scopeUid: string, key: string) => Promise<Buffer>;
-    /** Authenticated JSON call against the control plane. */
+    /**
+     * Authenticated JSON call against the control plane. `retryAfterSeconds` is
+     * the server's numeric `Retry-After`, when it sent one.
+     */
     apiJson: (token: string, path: string, init?: {
         method?: string;
         body?: Record<string, unknown>;
         query?: Record<string, string>;
+        signal?: AbortSignal;
     }) => Promise<{
         status: number;
         body: unknown;
+        retryAfterSeconds?: number;
     }>;
+    /** Test seam for hq_inbox_read's bounded retry (sleep, jitter source, per-attempt deadline). */
+    inboxRetry?: Pick<FetchServerInboxDeps, "sleep" | "random" | "timeoutMs">;
 }
 export declare function clampOutput(text: string, max?: number): string;
 /** Vault paths are company-anchored and must not escape. */

package/dist/lib/agent-kit/mcp/tools.js

@@ -19,6 +19,7 @@ import { CLI_VERSION } from "../../../cli-version.js";
 import { peekIdToken } from "../../../utils/id-token.js";
 import { PERSON_AGENT_AUDIENCE_MESSAGE, callerMayUseAudience, defaultAudienceFor, isAgentUid, isRecipientUid } from "../../../lib/notify-recipient.js";
 import { tokenIsMachinePrincipal } from "../../../lib/caller-principal.js";
+import { annotateInboxAttempts, fetchServerInboxWithRetry, resolveAgentInboxTimeoutMs } from "../inbox-fetch.js";
 import { redactAgentInboxItem } from "../inbox-redact.js";
 import { markInboxDone, mergeAgentInbox, readDoneIds, summarizeInboxEntry } from "../inbox-state.js";
 import { AttachmentCompanyUnresolvedError, fetchChatAttachment } from "./attachments.js";
@@ -286,10 +287,21 @@ export function buildAgentMcpTools(clients) {
                 const limit = int(args, "limit", { min: 1, max: 100, fallback: 20 });
                 const includeDone = args.include_done === true;
                 const done = readDoneIds(clients.paths);
-                const { entries, note: serverNote, source } = await mergeAgentInbox(clients.paths, async () => {
-                    const token = await clients.getToken();
-                    return clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`);
+                // Same bounded, once-retried server read as `hq agent inbox`.
+                let attempts = 1;
+                const merged = await mergeAgentInbox(clients.paths, async () => {
+                    const outcome = await fetchServerInboxWithRetry({
+                        timeoutMs: resolveAgentInboxTimeoutMs(process.env),
+                        ...clients.inboxRetry,
+                        mint: (signal) => clients.getToken(signal),
+                        fetch: (token, signal) => clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`, { signal }),
+                    });
+                    attempts = outcome.attempts;
+                    if (!outcome.ok)
+                        throw outcome.error;
+                    return outcome.response;
                 });
+                const { entries, note: serverNote, source, stale, attempts: attemptsMade } = annotateInboxAttempts(merged, attempts);
                 const byId = new Map(entries.map((e) => [e.id, e]));
                 const rows = [...byId.values()]
                     .filter((e) => includeDone || !done.has(e.id))
@@ -299,6 +311,8 @@ export function buildAgentMcpTools(clients) {
                 return textResult(clampOutput(JSON.stringify({
                     count: rows.length,
                     source,
+                    stale,
+                    ...(attemptsMade !== undefined ? { attempts: attemptsMade } : {}),
                     messages: rows,
                     ...(serverNote ? { note: serverNote } : {}),
                     ...(hasFiles ? { attachmentsHint: ATTACHMENTS_HINT } : {}),

package/dist/utils/cognito-session.d.ts

@@ -267,7 +267,7 @@ export declare function buildVaultConfig(authToken: string): VaultServiceConfig;
  * means no valid session could be ensured non-interactively; the caller gets a
  * reason string and can decide what to do next. Never opens a browser.
  */
-type MachineRefreshOptions = Pick<EnsureCognitoTokenOptions, "tokenSource"> & MachineTokenValidityOptions & {
+type MachineRefreshOptions = Pick<EnsureCognitoTokenOptions, "tokenSource" | "signal"> & MachineTokenValidityOptions & {
     /** Refresh the person session even when the cached token is still valid. */
     force?: boolean;
 };

package/dist/utils/cognito-session.js

@@ -780,11 +780,21 @@ function withTokenStateDirSection(fn) {
     return run;
 }
 const MAX_MACHINE_TOKEN_MIN_VALIDITY_SECONDS = 1800;
-async function ensureMachineTokens(minValiditySeconds) {
+/**
+ * `signal` cancels only this caller's wait inside hq-cloud (a mint shared with
+ * other callers keeps running). Without it a bounded caller such as `hq agent
+ * inbox` timed out, retried, and its retry queued behind the orphaned first
+ * mint, which still held the lock.
+ */
+async function ensureMachineTokens(minValiditySeconds, signal) {
     const resolverMinimum = minValiditySeconds === undefined
         ? undefined
         : Math.min(minValiditySeconds, MAX_MACHINE_TOKEN_MIN_VALIDITY_SECONDS);
-    return withMachineTokenStateDir(() => getValidMachineTokens(DEFAULT_COGNITO, resolverMinimum === undefined ? undefined : { minValiditySeconds: resolverMinimum }));
+    const resolverOptions = {
+        ...(resolverMinimum === undefined ? {} : { minValiditySeconds: resolverMinimum }),
+        ...(signal ? { signal } : {}),
+    };
+    return withMachineTokenStateDir(() => getValidMachineTokens(DEFAULT_COGNITO, Object.keys(resolverOptions).length === 0 ? undefined : resolverOptions));
 }
 /**
  * Ensure the current machine identity has a valid session and return only the
@@ -803,7 +813,7 @@ async function ensureMachineTokensMaybeFallback(options = {}) {
     if (isDefaultMachineCredsFallback(options)) {
         logDefaultMachineCredsFallback();
     }
-    return ensureMachineTokens(options.minValiditySeconds);
+    return ensureMachineTokens(options.minValiditySeconds, options.signal);
 }
 /**
  * After a person-cache miss or refresh failure: if the default machine-creds
@@ -818,7 +828,7 @@ async function tryDefaultMachineCredsFallback(options = {}) {
     if (!isMachineIdentity())
         return null;
     logDefaultMachineCredsFallback();
-    return ensureMachineTokens(options.minValiditySeconds);
+    return ensureMachineTokens(options.minValiditySeconds, options.signal);
 }
 /**
  * True when a person-token refresh failed with a definitive Cognito auth
@@ -880,6 +890,8 @@ function resolvePersonSessionAfterRefreshRejection(cached) {
  * a browser.
  */
 export async function ensureCognitoToken(options = {}) {
+    if (options.signal?.aborted)
+        throw options.signal.reason ?? new Error("Token acquisition was aborted");
     if (wantsMachineCognitoTokens(options))
         return ensureCognitoTokenUnserialized(options);
     return withTokenStateDirSection(() => ensureCognitoTokenUnserialized(options));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.187",
+  "version": "5.345.188",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -52,7 +52,7 @@
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
     "@aws-sdk/dsql-signer": "^3.1146.0",
-    "@indigoai-us/hq-cloud": "6.18.106",
+    "@indigoai-us/hq-cloud": "6.18.107",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@sentry/node": "^10.49.0",
@@ -114,11 +114,11 @@
     "*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}": "eslint --cache --no-error-on-unmatched-pattern"
   },
   "optionalDependencies": {
-    "@indigoai-us/hq-hook-win32-x64": "5.345.187",
-    "@indigoai-us/hq-hook-win32-arm64": "5.345.187",
-    "@indigoai-us/hq-hook-darwin-x64": "5.345.187",
-    "@indigoai-us/hq-hook-darwin-arm64": "5.345.187",
-    "@indigoai-us/hq-hook-linux-x64": "5.345.187",
-    "@indigoai-us/hq-hook-linux-arm64": "5.345.187"
+    "@indigoai-us/hq-hook-win32-x64": "5.345.188",
+    "@indigoai-us/hq-hook-win32-arm64": "5.345.188",
+    "@indigoai-us/hq-hook-darwin-x64": "5.345.188",
+    "@indigoai-us/hq-hook-darwin-arm64": "5.345.188",
+    "@indigoai-us/hq-hook-linux-x64": "5.345.188",
+    "@indigoai-us/hq-hook-linux-arm64": "5.345.188"
   }
 }