@indigoai-us/hq-cli 5.314.0 → 5.315.0

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

@@ -0,0 +1,135 @@
+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;
+// One read every three minutes on a fresh connection. From a home network the
+// TCP and TLS handshakes plus the resolve call take about 250-400 ms, so a
+// 150 ms budget timed out on every read and kept the gate off.
+export const INBOX_POLL_BACKOFF_FLAG_TIMEOUT_MS = 2_000;
+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/inbox-state.d.ts

@@ -0,0 +1,18 @@
+/**
+ * inbox-state.json — processed messageIds so a DM pulled but not acked
+ * before a crash is answered exactly once after restart (local-bots US-004).
+ */
+export declare const INBOX_STATE_MAX_ENTRIES = 500;
+export interface InboxStateFile {
+    v: 1;
+    /** messageId → ISO time the reply was sent (or the refusal was sent). */
+    processed: Record<string, string>;
+    updatedAt: string;
+}
+export declare function readInboxState(dir: string): InboxStateFile;
+export declare function writeInboxState(dir: string, state: InboxStateFile): void;
+export declare function isProcessed(state: InboxStateFile, messageId: string): boolean;
+/** Record a processed id, trimming the oldest entries past the cap. Pure. */
+export declare function withProcessed(state: InboxStateFile, messageId: string, at: string, cap?: number): InboxStateFile;
+export declare function markProcessed(dir: string, messageId: string, at?: string): InboxStateFile;
+//# sourceMappingURL=inbox-state.d.ts.map

package/dist/lib/bot/inbox-state.js

@@ -0,0 +1,51 @@
+/**
+ * inbox-state.json — processed messageIds so a DM pulled but not acked
+ * before a crash is answered exactly once after restart (local-bots US-004).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { botInboxStatePath } from "./paths.js";
+export const INBOX_STATE_MAX_ENTRIES = 500;
+export function readInboxState(dir) {
+    const p = botInboxStatePath(dir);
+    if (!fs.existsSync(p))
+        return { v: 1, processed: {}, updatedAt: new Date(0).toISOString() };
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+        if (raw.v !== 1 || typeof raw.processed !== "object" || !raw.processed) {
+            return { v: 1, processed: {}, updatedAt: new Date(0).toISOString() };
+        }
+        return raw;
+    }
+    catch {
+        return { v: 1, processed: {}, updatedAt: new Date(0).toISOString() };
+    }
+}
+export function writeInboxState(dir, state) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const dest = botInboxStatePath(dir);
+    const tmp = path.join(dir, `.inbox.tmp.${process.pid}.${Date.now()}`);
+    fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, dest);
+}
+export function isProcessed(state, messageId) {
+    return Object.prototype.hasOwnProperty.call(state.processed, messageId);
+}
+/** Record a processed id, trimming the oldest entries past the cap. Pure. */
+export function withProcessed(state, messageId, at, cap = INBOX_STATE_MAX_ENTRIES) {
+    const processed = { ...state.processed, [messageId]: at };
+    const keys = Object.keys(processed);
+    if (keys.length > cap) {
+        keys
+            .sort((a, b) => processed[a].localeCompare(processed[b]))
+            .slice(0, keys.length - cap)
+            .forEach((k) => delete processed[k]);
+    }
+    return { v: 1, processed, updatedAt: at };
+}
+export function markProcessed(dir, messageId, at = new Date().toISOString()) {
+    const next = withProcessed(readInboxState(dir), messageId, at);
+    writeInboxState(dir, next);
+    return next;
+}
+//# sourceMappingURL=inbox-state.js.map

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

@@ -0,0 +1,23 @@
+export * from "./paths.js";
+export * from "./config.js";
+export * from "./creds.js";
+export * from "./status.js";
+export * from "./log.js";
+export * from "./inbox-state.js";
+export * from "./session.js";
+export * from "./prompt.js";
+export * from "./api.js";
+export * from "./daemon.js";
+export * from "./scaffold.js";
+export * from "./worker-source.js";
+export * from "./company-bind.js";
+export * from "./run.js";
+export * from "./runtime/index.js";
+export * from "./local-config.js";
+export * from "./self-heal.js";
+export * from "./runnable.js";
+export * from "./local-name.js";
+export * from "./job-run.js";
+export * from "./job-completions.js";
+export * from "./inflight.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/bot/index.js

@@ -0,0 +1,23 @@
+export * from "./paths.js";
+export * from "./config.js";
+export * from "./creds.js";
+export * from "./status.js";
+export * from "./log.js";
+export * from "./inbox-state.js";
+export * from "./session.js";
+export * from "./prompt.js";
+export * from "./api.js";
+export * from "./daemon.js";
+export * from "./scaffold.js";
+export * from "./worker-source.js";
+export * from "./company-bind.js";
+export * from "./run.js";
+export * from "./runtime/index.js";
+export * from "./local-config.js";
+export * from "./self-heal.js";
+export * from "./runnable.js";
+export * from "./local-name.js";
+export * from "./job-run.js";
+export * from "./job-completions.js";
+export * from "./inflight.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,119 @@
+/**
+ * inflight.json — the messages model turns are working on right now.
+ *
+ * A marker is written before the model process starts and removed once the
+ * message is answered (or answered with "did not finish"). If the bot restarts
+ * while a marker exists, that turn was cut off: the bot tells the person
+ * instead of running the message again, because the first run may already
+ * have done things outside this Mac (sent something, published something).
+ *
+ * A bot works on up to two conversations at once, so the file holds one marker
+ * per running turn (`v: 2`). A `v: 1` file (a single marker, written before
+ * turns ran in parallel) is still read. Every write is a synchronous
+ * read-modify-rename, so turns in the same process cannot lose each other's
+ * markers.
+ */
+export declare const BOT_INFLIGHT_NAME = "inflight.json";
+export interface InflightTurn {
+    v: 1;
+    /** Inbox message id, or `kickoff` for the first-start kickoff turn. */
+    messageId: string;
+    /** Where replies for this message go. */
+    target: {
+        kind: "dm";
+        peerUid: string;
+    } | {
+        kind: "room";
+        channelId: string;
+    };
+    /**
+     * Scheduled-job runs: the job this message is a run of, so a turn cut off by
+     * a restart is still reported to the cloud (which is the only thing that
+     * clears the job's in-progress flag).
+     */
+    jobId?: string;
+    /**
+     * Set as soon as this run's outcome has been REPORTED to the cloud (accepted,
+     * or durably queued for retry). A recovery pass must not report it again: the
+     * server's complete is last-write-wins, so a second "failed" would overwrite
+     * a recorded "succeeded" after a crash between reporting and acking.
+     */
+    jobCompleted?: "succeeded" | "failed" | "skipped-precondition";
+    /**
+     * The "scheduled job" header this run's FIRST message carries, so a report
+     * posted by the recovery path still reads as a scheduled run rather than an
+     * unsolicited DM.
+     */
+    jobHeader?: string;
+    /**
+     * The bot a scheduled run's marker belongs to. `hq bot adopt` can place a
+     * DIFFERENT bot into a folder that survived (bot.json gone, the rest left);
+     * recovery drops a job marker stamped with another agent instead of posting
+     * its report into this bot's DM and completing it under this identity.
+     * Absent on markers written before it was recorded: those behave as before.
+     */
+    agentUid?: string;
+    /**
+     * The run's own report, as it is recorded with the cloud, kept apart from the
+     * body saved for resending (which may carry the header or earlier progress).
+     */
+    jobOutput?: string;
+    /**
+     * Why a started scheduled run did not finish (the runtime's error, or the
+     * owner stopping it), saved BEFORE the "did not finish" post is attempted. If
+     * that post fails, recovery reports and tells the owner THIS reason rather
+     * than claiming the bot was restarted.
+     */
+    jobFailure?: {
+        reason: string;
+        excerpt?: string;
+    };
+    rootEventId?: string;
+    /** DM message carrying the thinking reaction, so a restart can clear it. */
+    reactionEventId?: string;
+    startedAt: string;
+    /** Progress messages already posted for this turn. */
+    progressPosted?: number;
+    /**
+     * The finished answer, when the turn completed but posting it failed. A
+     * restart posts this instead of "did not finish".
+     */
+    reply?: string;
+    /**
+     * The message to deliver, already cut to the body limit (split.ts). Recovery
+     * resends from `replyPartsDelivered` on, so a part the person has already
+     * read is never posted twice.
+     */
+    replyParts?: string[];
+    /** How many of `replyParts` actually reached the chat. */
+    replyPartsDelivered?: number;
+    /**
+     * Consecutive failed attempts to deliver this marker. A body the server will
+     * never accept must not be retried for ever, so the bot gives up after
+     * RECOVERY_ATTEMPT_LIMIT and says so once (run.ts).
+     */
+    recoveryFailures?: number;
+    /**
+     * True when the interrupted turn was a "silenceable" one: an unmentioned
+     * room message nobody asked the bot to answer. On recovery a silenceable
+     * turn with no saved reply is acked silently — a "I didn't finish that —
+     * I was restarted…" notice in a public room the bot was not addressed in
+     * is noise, and (2026-09-25) had two bots posting it in a channel where
+     * neither had been @-mentioned. A silenceable marker WITH a saved
+     * `reply` still posts: that was a real answer the model produced and only
+     * delivery failed. Absent (older marker) → recover posts the notice, as
+     * before.
+     */
+    silenceable?: boolean;
+}
+export declare function botInflightPath(dir: string): string;
+/** Every turn that was in progress, oldest first. */
+export declare function readInflightTurns(dir: string): InflightTurn[];
+/** The marker for one message, or null. */
+export declare function readInflight(dir: string, messageId?: string): InflightTurn | null;
+/** Add or replace the marker for `turn.messageId`; other turns' markers stay. */
+export declare function writeInflight(dir: string, turn: InflightTurn): void;
+export declare function patchInflight(dir: string, messageId: string, patch: Partial<InflightTurn>): void;
+/** Remove one message's marker, or every marker when no id is given. */
+export declare function clearInflight(dir: string, messageId?: string): void;
+//# sourceMappingURL=inflight.d.ts.map

package/dist/lib/bot/inflight.js

@@ -0,0 +1,83 @@
+/**
+ * inflight.json — the messages model turns are working on right now.
+ *
+ * A marker is written before the model process starts and removed once the
+ * message is answered (or answered with "did not finish"). If the bot restarts
+ * while a marker exists, that turn was cut off: the bot tells the person
+ * instead of running the message again, because the first run may already
+ * have done things outside this Mac (sent something, published something).
+ *
+ * A bot works on up to two conversations at once, so the file holds one marker
+ * per running turn (`v: 2`). A `v: 1` file (a single marker, written before
+ * turns ran in parallel) is still read. Every write is a synchronous
+ * read-modify-rename, so turns in the same process cannot lose each other's
+ * markers.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const BOT_INFLIGHT_NAME = "inflight.json";
+export function botInflightPath(dir) {
+    return path.join(dir, BOT_INFLIGHT_NAME);
+}
+function isTurn(raw) {
+    const t = raw;
+    return t?.v === 1 && typeof t.messageId === "string" && Boolean(t.target);
+}
+/** Every turn that was in progress, oldest first. */
+export function readInflightTurns(dir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(botInflightPath(dir), "utf8"));
+        if (isTurn(raw))
+            return [raw];
+        const file = raw;
+        if (file?.v !== 2 || !Array.isArray(file.turns))
+            return [];
+        return file.turns.filter(isTurn);
+    }
+    catch {
+        return [];
+    }
+}
+/** The marker for one message, or null. */
+export function readInflight(dir, messageId) {
+    const turns = readInflightTurns(dir);
+    if (messageId === undefined)
+        return turns[0] ?? null;
+    return turns.find((t) => t.messageId === messageId) ?? null;
+}
+function writeTurns(dir, turns) {
+    if (turns.length === 0) {
+        fs.rmSync(botInflightPath(dir), { force: true });
+        return;
+    }
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = path.join(dir, `.inflight.tmp.${process.pid}.${Date.now()}`);
+    const file = { v: 2, turns };
+    fs.writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, botInflightPath(dir));
+}
+/** Add or replace the marker for `turn.messageId`; other turns' markers stay. */
+export function writeInflight(dir, turn) {
+    const others = readInflightTurns(dir).filter((t) => t.messageId !== turn.messageId);
+    writeTurns(dir, [...others, turn]);
+}
+export function patchInflight(dir, messageId, patch) {
+    const turns = readInflightTurns(dir);
+    const index = turns.findIndex((t) => t.messageId === messageId);
+    if (index < 0)
+        return;
+    turns[index] = { ...turns[index], ...patch };
+    writeTurns(dir, turns);
+}
+/** Remove one message's marker, or every marker when no id is given. */
+export function clearInflight(dir, messageId) {
+    if (messageId === undefined) {
+        writeTurns(dir, []);
+        return;
+    }
+    const turns = readInflightTurns(dir);
+    const rest = turns.filter((t) => t.messageId !== messageId);
+    if (rest.length !== turns.length)
+        writeTurns(dir, rest);
+}
+//# sourceMappingURL=inflight.js.map

package/dist/lib/bot/job-completions.d.ts

@@ -0,0 +1,89 @@
+/**
+ * job-completions.json — run completions the cloud has not accepted yet.
+ *
+ * Reporting a finished run is MANDATORY: nothing else clears the job's
+ * in-progress flag, and until it is cleared every later fire of that job is
+ * skipped as an overlap for up to an hour. So when the completion call fails
+ * (the network was down, the token was stale), the bot logs it loudly, still
+ * acks the inbox item — the work is done and must never run twice — and keeps
+ * the completion here to retry.
+ *
+ * A retry only re-sends a small report; it never re-runs the work.
+ *
+ * Retries are spaced by EXPONENTIAL BACKOFF and given up on by WALL-CLOCK AGE,
+ * not by a count of attempts. The inbox polls every 2 seconds, so a fixed
+ * ten-attempt budget was spent in about twenty seconds — an ordinary sixty-
+ * second network drop permanently lost the completion and wedged that job for
+ * the rest of the server's in-progress hour. Giving up is pegged to that same
+ * hour, after which the cloud releases the slot by itself anyway.
+ *
+ * ── After a reinstall: restore, adopt, repair (decision, 2026-09-16) ─────────
+ *
+ * This file lives in the bot's own folder (~/.hq/bots/<name>/), which is never
+ * synced. What `hq bot restore` / `hq bot adopt` do to it decides what happens
+ * to a completion owed by a run on the OLD machine:
+ *
+ * - REPAIR (the folder is still here; only the credentials are re-issued): the
+ *   file survives and its completions are still reported, with the new
+ *   credentials. That is correct — it is the same agent, and the complete route
+ *   authorizes by agent identity, not by machine.
+ * - ADOPT onto a fresh machine: there is no file, so nothing is reported from
+ *   here. That is not a lost report: the old machine ACKED the run before it
+ *   queued the completion (the work must never run twice), so the cloud will
+ *   not redeliver it, and the job's in-progress slot is released by the cloud
+ *   itself within the hour. Not duplicated, and not jammed for longer than the
+ *   outage already cost.
+ * - ADOPT into a folder that SURVIVED (bot.json gone, the rest left behind):
+ *   completions stamped with THIS bot's agentUid are reported as normal. A
+ *   completion stamped with a DIFFERENT agentUid — a same-named bot that was
+ *   deleted and re-created — is dropped, never sent: it belongs to another
+ *   identity, and reporting it against this one would be a cross-identity
+ *   write that can only fail or, worse, land on the wrong run.
+ *
+ * Per-job model SESSIONS (session-job-<jobId>.json) need no such care: a job
+ * that finds no session simply starts a fresh one, and a scheduled run carries
+ * everything it needs in its own prompt.
+ */
+import type { JobRunStatus } from "./api.js";
+/** First retry gap; each failure doubles it. */
+export declare const COMPLETION_RETRY_BASE_MS = 2000;
+/** Never wait longer than this between retries. */
+export declare const COMPLETION_RETRY_MAX_MS: number;
+/**
+ * Stop retrying a completion older than this. Matches the server's
+ * DEFAULT_JOBS_MAX_IN_PROGRESS_SECONDS: past it the cloud reclaims the job's
+ * in-progress slot on its own, so a later report changes nothing.
+ */
+export declare const MAX_COMPLETION_AGE_MS: number;
+export interface PendingJobCompletion {
+    v: 1;
+    /**
+     * The agent that owes this report. Checked before every retry so a folder
+     * that outlived its bot never reports under a different identity. Absent on
+     * entries written before it was recorded; those are treated as this bot's.
+     */
+    agentUid?: string;
+    jobId: string;
+    /** The inbox item id — the run id in the completion route. */
+    messageId: string;
+    status: JobRunStatus;
+    output?: string;
+    disposition?: string;
+    firstFailedAt: string;
+    attempts: number;
+    /** Epoch ms before which this must not be retried (exponential backoff). */
+    nextAttemptAt: number;
+}
+export declare function readPendingJobCompletions(dir: string): PendingJobCompletion[];
+/** The gap before attempt N (1-based), doubling and capped. */
+export declare function completionRetryDelayMs(attempts: number): number;
+/** True when this entry is due for another attempt. */
+export declare function isCompletionDue(entry: PendingJobCompletion, nowMs: number): boolean;
+/** True when this entry was owed by a different bot identity than `agentUid`. */
+export declare function isCompletionForOtherAgent(entry: PendingJobCompletion, agentUid: string): boolean;
+/** True when the cloud has already reclaimed the slot; retrying changes nothing. */
+export declare function isCompletionExpired(entry: PendingJobCompletion, nowMs: number): boolean;
+/** Record (or back off) a completion the cloud has not taken. */
+export declare function recordPendingJobCompletion(dir: string, entry: Omit<PendingJobCompletion, "v" | "firstFailedAt" | "attempts" | "nextAttemptAt">, now: Date): PendingJobCompletion;
+export declare function clearPendingJobCompletion(dir: string, messageId: string): void;
+//# sourceMappingURL=job-completions.d.ts.map