@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

@@ -0,0 +1,219 @@
+/**
+ * The resident bot process: `hq bot run <name>` (local-bots US-003/US-004).
+ *
+ * - pid lock in ~/.hq/bots/<name>/pid; status.json is the observable state
+ * - refuses to start unless the creds file names this bot's agt_ AND the
+ *   server-side record is owned by the configured owner
+ * - heartbeat every 30s (POST /v1/agents/{uid}/heartbeat, agent JWT)
+ * - inbox poll every 2s: DMs go to ONE headless model turn (resumed by
+ *   session id); the reply is sent as the bot; the message is acked only after
+ *   the reply is sent; processed ids persist so a crash between reply and ack
+ *   never answers twice
+ * - any correspondent can message the bot; each sender has a separate session
+ * - first start only: the intro DM, then (when bot.json has `kickoff`) ONE
+ *   model turn on that prompt as if the owner sent it, answered in the DM, so
+ *   a guided bot starts working without waiting for the owner to type
+ * - job items (channel "job"): a run the cloud fired on an EventBridge
+ *   schedule. Nothing is scheduled on this computer. The run is one model turn
+ *   in its own session (one per jobId), reported in the owner's DM with a
+ *   "scheduled job" header through the same split/recovery path as every other
+ *   reply, and reported back to the cloud EXACTLY ONCE — nothing else clears
+ *   the job's in-progress flag. A run whose staleAfter has passed still runs,
+ *   once, labelled a catch-up; older pending runs of the same job are reported
+ *   skipped-precondition instead of piling up.
+ * - delivered room items (channels / group chats) are eligible for replies; claimed
+ *   first (first-claim-wins), one session per room, reply posted in the room
+ * - conversations run side by side: up to MAX_PARALLEL_TURNS turns at once,
+ *   one lane per model session (one DM correspondent, or one room). Messages
+ *   in the same lane run in order, so a session is never resumed by two turns
+ *   at once and a thread's answers never arrive out of sequence.
+ * - while a turn runs, each finished assistant message is posted as its own
+ *   message (progress.ts); turns have no time limit
+ * - every received message gets a reply: a turn that fails after the model
+ *   started (error, crash, owner stop, restart) posts one "did not finish"
+ *   message and is NOT run again — it may already have done outward things.
+ *   inflight.json marks the turn in progress so a restart can say so.
+ * - a turn that fails because the coding tool's sign-in no longer works
+ *   (runtime-sign-in.ts) is not a failure of the message: the bot says once
+ *   per conversation that it needs a sign-in, keeps the message un-acked,
+ *   holds new turns, and tries again every SIGN_IN_RETRY_MS (and at once
+ *   after a restart). A turn that works clears it.
+ * - failures before the model starts (missing binary) retry with backoff;
+ *   5 model failures in 10 minutes → state `failed` and a clean exit (launchd
+ *   does not respawn a clean exit). Owner stops never count.
+ *
+ * Everything with a side effect is injectable so the loop is unit-testable.
+ */
+import { type OwnerContext } from "./owner-context.js";
+import { type BotApi, type InboxItem } from "./api.js";
+import type { BotConfig, BotKind } from "./config.js";
+import { containsNoReplySentinel, type ProgressPosterOptions } from "./progress.js";
+import { type BotLogger } from "./log.js";
+import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult } from "./runtime/index.js";
+import type { VaultObjectDownloader } from "../agent-kit/attachment-download.js";
+import { type HeartbeatAgentUidSource, type HeartbeatCredsSource, type HeartbeatIdentityMismatchReporter } from "../heartbeat-identity.js";
+import { type BotState, type BotStatusFile } from "./status.js";
+import { type CliUpdate, type CliUpdateWatch } from "./cli-update.js";
+export declare const INBOX_POLL_INTERVAL_MS = 2000;
+export declare const HEARTBEAT_INTERVAL_MS = 30000;
+/** First 429/5xx wait when Retry-After is absent (inbox polls at 2s). */
+export declare const API_BACKOFF_BASE_MS = 4000;
+/** Ceiling for exponential poll/heartbeat backoff. */
+export declare const API_BACKOFF_CAP_MS: number;
+/** Honor Retry-After up to this; a bogus 30-day header must not park the bot. */
+export declare const API_RETRY_AFTER_CAP_MS: number;
+export declare const API_RETRY_AFTER_FLOOR_MS = 1000;
+/**
+ * How long to wait after a failed inbox poll or heartbeat.
+ * 429/5xx (and transport errors) back off exponentially, honouring Retry-After
+ * when present. Other 4xx keep the normal interval so a 401 is not stretched.
+ */
+export declare function apiPollDelayMs(opts: {
+    err: unknown;
+    attempt: number;
+    intervalMs: number;
+    random?: () => number;
+}): number;
+export declare const FAILURE_WINDOW_MS: number;
+export declare const FAILURE_LIMIT = 5;
+export declare const MAX_ATTEMPTS_PER_MESSAGE = 3;
+export declare const THINKING_EMOJI = "\uD83D\uDC40";
+export declare const ROOM_THINKING_STATUS = "is thinking\u2026";
+export declare const RECENT_MESSAGES_LIMIT = 15;
+export declare const RECENT_MESSAGE_MAX_CHARS = 400;
+/** Model turns a bot runs at once (each on a different conversation). */
+export declare const MAX_PARALLEL_TURNS = 2;
+/**
+ * Failed attempts to deliver ONE saved message before the bot stops trying.
+ * A body the server refuses (too long, malformed) is refused identically every
+ * time, so retrying it on every 2s poll only hammers the API and leaves the
+ * person with no answer and no explanation.
+ */
+export declare const RECOVERY_ATTEMPT_LIMIT = 5;
+/** What the person sees when a reply could not be delivered at all. */
+export declare const UNDELIVERABLE_REPLY_TEXT = "I wrote a reply but couldn't deliver it. Ask me again and I'll keep it shorter.";
+/**
+ * The same, for a scheduled run. Nobody asked, so "ask me again" is wrong: the
+ * run DID finish, and its outcome is still recorded with the job in HQ.
+ */
+export declare const UNDELIVERABLE_JOB_REPORT_TEXT = "This scheduled run finished, but I couldn't deliver its report here. Its result is saved with the job's run history.";
+/**
+ * Scheduled work must never crowd out the people the bot talks to. A job turn
+ * can run for a long time, so at most ONE runs at a time, and a job never takes
+ * the last free slot: a DM or a room message can always start immediately
+ * instead of waiting, with no explanation, behind two long jobs.
+ */
+export declare const MAX_PARALLEL_JOB_TURNS = 1;
+export type SleepFn = (ms: number, signal?: AbortSignal) => Promise<void>;
+export interface BotRunDeps {
+    dir: string;
+    config: BotConfig;
+    api: BotApi;
+    runtime: BotRuntime;
+    runTurn?: (runtime: BotRuntime, input: RuntimeTurnInput) => Promise<RuntimeTurnResult>;
+    now?: () => Date;
+    sleep?: SleepFn;
+    random?: () => number;
+    log?: BotLogger;
+    pid?: number;
+    isProcessAlive?: (pid: number) => boolean;
+    inboxIntervalMs?: number;
+    /** Cached, default-off reader for the local inbox polling gate. */
+    inboxPollBackoffEnabled?: () => Promise<boolean>;
+    /** Default-off gate for the per-job quiet-success option. */
+    jobQuietOptionEnabled?: () => boolean | Promise<boolean>;
+    heartbeatIntervalMs?: number;
+    /** Override the rendered system prompt (tests). */
+    systemPromptOverride?: string;
+    /** Signal source; defaults to `process`. */
+    processEvents?: {
+        once(event: "SIGTERM" | "SIGINT" | "SIGUSR2", cb: () => void): unknown;
+    };
+    /** Called when the loop ends; defaults to process.exit. */
+    exit?: (code: number) => void;
+    /** Skip the pid lock (tests that run several bots in one process). */
+    skipPidLock?: boolean;
+    /** Progress-post timing overrides (tests). */
+    progress?: Pick<ProgressPosterOptions, "coalesceMs" | "minGapMs" | "workingNoticeMs" | "setTimer" | "clearTimer" | "now">;
+    /**
+     * The owner's verified company context, prepended to every owner DM turn
+     * of a PERSONAL bot (never room turns, never a company bot's turns) so the
+     * model never mistakes the bot's own (empty) memberships for its owner's.
+     * Omitted in tests that do not exercise it.
+     */
+    ownerContext?: () => Promise<OwnerContext>;
+    /** Turns run at once across conversations (default MAX_PARALLEL_TURNS). */
+    maxParallelTurns?: number;
+    /** Wait between retries while the coding tool needs a sign-in (default SIGN_IN_RETRY_MS). */
+    signInRetryMs?: number;
+    /**
+     * Downloads a chat attachment's bytes with the bot's own machine identity
+     * (vault presign). Unset = attachments are listed with a "cannot download"
+     * reason instead of a path.
+     */
+    downloadAttachment?: VaultObjectDownloader;
+    agentUidSource?: HeartbeatAgentUidSource;
+    credsSource?: HeartbeatCredsSource;
+    reportIdentityMismatch?: HeartbeatIdentityMismatchReporter;
+    /**
+     * Watches the hq-cli install this process was started from (cli-update.ts).
+     * When it reports an update, the bot stops taking inbox items, lets running
+     * turns finish, and exits CLI_UPDATE_RESTART_EXIT_CODE. Unset = no watch.
+     */
+    cliUpdate?: CliUpdateWatch;
+    /**
+     * Called after the pid lock is released and just before the update-restart
+     * exit: the place to start a replacement when no supervisor will.
+     */
+    onCliUpdateRestart?: (update: CliUpdate, log: BotLogger) => void;
+}
+export declare const KICKOFF_MESSAGE_ID = "kickoff";
+/**
+ * The environment a model turn's `hq` commands run in.
+ *
+ * The bot process carries its own machine identity in HQ_MACHINE_CREDS_FILE /
+ * HQ_MACHINE_TOKEN_STATE_DIR so its inbox, heartbeat and posts are the bot's.
+ * What a turn inherits depends on the bot's kind:
+ * - A PERSONAL bot acts as its owner on every turn (DMs, the kickoff, rooms):
+ *   everything the owner asks for — a company, a bot, an invite, a share —
+ *   belongs to the owner's account, and the cloud rightly refuses a bot that
+ *   tries to own it ("No person entity found"). Stripping the marker makes
+ *   every `hq` command in the turn use the owner's sign-in, the same one the
+ *   desktop app shares, so no command needs a special case. The bot's id
+ *   (never a credential) rides along in HQ_BOT_AGENT_UID so what the owner
+ *   creates in the turn — a company — can add the bot as a member afterwards.
+ * - A COMPANY bot acts as itself on every turn, like a cloud agent: the
+ *   machine identity stays, and the cloud evaluates it through its own
+ *   company memberships. It never acts as the owner, in DMs or in rooms.
+ * Pure so the rule is unit-testable.
+ */
+export declare function turnEnv(base: NodeJS.ProcessEnv, kind: BotKind, agentUid?: string, companySlug?: string): NodeJS.ProcessEnv;
+/** The core worker HQ's setup bot runs. */
+export declare const SETUP_WORKER_ID = "setup";
+/** The one message a person gets when a turn on their message did not finish. */
+export declare function didNotFinishText(reason: string, progressPosted: boolean): string;
+export { containsNoReplySentinel };
+/** Grok emits is_error with this message when the model produces only reasoning tokens. */
+export declare function isReasoningOnlyError(excerpt: string): boolean;
+/** Owner stop, `hq bot stop` or `hq bot restart`: all arrive as the same signal. */
+export declare const STOPPED_BY_OWNER_REASON = "I was stopped before I was done";
+export declare const RESTARTED_REASON = "I was restarted while I was working on it";
+export interface BotHandle {
+    stop(mode?: "abort" | "drain"): Promise<void>;
+    /** Resolves when both loops have ended (state stopped or failed). */
+    done: Promise<BotState>;
+    status(): BotStatusFile | null;
+    /** True when no inbox message is queued or being worked on. */
+    idle(): boolean;
+}
+/**
+ * The lane an inbox item runs in: the model session its turn resumes. Owner
+ * DMs retain the legacy DM session; other senders and rooms each have their
+ * own, and so does each scheduled job (two different jobs must never share a
+ * model session, and a job must never pollute the owner's DM conversation).
+ * An item that never reaches a model turn gets a lane of its own.
+ */
+export declare function inboxLaneKey(item: InboxItem, config: Pick<BotConfig, "ownerUid" | "agentUid" | "name">): string;
+export declare function preflightCreds(dir: string, config: BotConfig): string | null;
+export declare function runBot(deps: BotRunDeps): Promise<BotHandle>;
+//# sourceMappingURL=run.d.ts.map