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

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

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