@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

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

@@ -1,135 +0,0 @@
-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

@@ -1,18 +0,0 @@
-/**
- * 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

@@ -1,51 +0,0 @@
-/**
- * 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

@@ -1,23 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

@@ -1,119 +0,0 @@
-/**
- * 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

@@ -1,83 +0,0 @@
-/**
- * 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

@@ -1,89 +0,0 @@
-/**
- * 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