@indigoai-us/hq-cli 5.135.0 → 5.137.0

package/dist/lib/bot/api.js

@@ -101,6 +101,44 @@ export class BotApi {
     async ackInbox(agentUid, messageId) {
         await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/inbox/${encodeURIComponent(messageId)}/ack`, { method: "POST", body: {} });
     }
+    /**
+     * POST /v1/agents/{uid}/jobs/{jobId}/runs/{messageId}/complete — report one
+     * fired run as finished. MANDATORY: nothing else clears the job's
+     * in-progress flag, so a run that is never reported makes every later fire
+     * of that job `skipped-overlap` for up to an hour.
+     */
+    async completeJobRun(agentUid, jobId, messageId, completion) {
+        await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/jobs/${encodeURIComponent(jobId)}/runs/${encodeURIComponent(messageId)}/complete`, {
+            method: "POST",
+            body: {
+                status: completion.status,
+                ...(completion.output !== undefined ? { output: completion.output } : {}),
+                ...(completion.disposition !== undefined ? { disposition: completion.disposition } : {}),
+            },
+        }, [200, 201, 202, 204]);
+    }
+    /** GET /v1/agents/{uid}/jobs — the bot's own scheduled jobs (self-only). */
+    async listJobs(agentUid) {
+        const { body } = await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/jobs`);
+        return body.jobs ?? [];
+    }
+    /** POST /v1/agents/{uid}/jobs — schedule a new job for the bot itself. */
+    async createJob(agentUid, input) {
+        const { body } = await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/jobs`, {
+            method: "POST",
+            body: {
+                prompt: input.prompt,
+                ...(input.context ? { context: input.context } : {}),
+                ...(input.script ? { script: input.script } : {}),
+                schedule: input.schedule,
+            },
+        });
+        return body.job;
+    }
+    /** POST /v1/agents/{uid}/jobs/{jobId}/cancel — cancel and delete its schedule. */
+    async cancelJob(agentUid, jobId) {
+        await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/jobs/${encodeURIComponent(jobId)}/cancel`, { method: "POST", body: {} }, [200, 201, 202, 204]);
+    }
     /** POST /v1/notify/dm — send as the bot (agent identity). */
     async sendDm(input) {
         const payload = { toPersonUid: input.toPersonUid, body: input.body };

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

@@ -17,4 +17,7 @@ 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

@@ -17,4 +17,7 @@ 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

@@ -26,6 +26,48 @@ export interface InflightTurn {
         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;

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

@@ -0,0 +1,91 @@
+/**
+ * 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";
+export declare const BOT_JOB_COMPLETIONS_NAME = "job-completions.json";
+/** 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 botJobCompletionsPath(dir: string): string;
+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

package/dist/lib/bot/job-completions.js

@@ -0,0 +1,132 @@
+/**
+ * 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 * as fs from "node:fs";
+import * as path from "node:path";
+export const BOT_JOB_COMPLETIONS_NAME = "job-completions.json";
+/** First retry gap; each failure doubles it. */
+export const COMPLETION_RETRY_BASE_MS = 2_000;
+/** Never wait longer than this between retries. */
+export const COMPLETION_RETRY_MAX_MS = 5 * 60_000;
+/**
+ * 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 const MAX_COMPLETION_AGE_MS = 60 * 60_000;
+export function botJobCompletionsPath(dir) {
+    return path.join(dir, BOT_JOB_COMPLETIONS_NAME);
+}
+function isPending(raw) {
+    const c = raw;
+    return c?.v === 1 && typeof c.jobId === "string" && typeof c.messageId === "string" && typeof c.status === "string";
+}
+export function readPendingJobCompletions(dir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(botJobCompletionsPath(dir), "utf8"));
+        if (raw?.v !== 1 || !Array.isArray(raw.completions))
+            return [];
+        return raw.completions.filter(isPending);
+    }
+    catch {
+        return [];
+    }
+}
+/** The gap before attempt N (1-based), doubling and capped. */
+export function completionRetryDelayMs(attempts) {
+    const exponent = Math.max(0, attempts - 1);
+    // Bound the shift so a long-lived entry cannot overflow into Infinity.
+    const raw = COMPLETION_RETRY_BASE_MS * 2 ** Math.min(exponent, 20);
+    return Math.min(COMPLETION_RETRY_MAX_MS, raw);
+}
+/** True when this entry is due for another attempt. */
+export function isCompletionDue(entry, nowMs) {
+    return nowMs >= (entry.nextAttemptAt ?? 0);
+}
+/** True when this entry was owed by a different bot identity than `agentUid`. */
+export function isCompletionForOtherAgent(entry, agentUid) {
+    return typeof entry.agentUid === "string" && entry.agentUid !== "" && entry.agentUid !== agentUid;
+}
+/** True when the cloud has already reclaimed the slot; retrying changes nothing. */
+export function isCompletionExpired(entry, nowMs) {
+    const first = new Date(entry.firstFailedAt).getTime();
+    if (Number.isNaN(first))
+        return false;
+    return nowMs - first >= MAX_COMPLETION_AGE_MS;
+}
+function write(dir, completions) {
+    if (completions.length === 0) {
+        fs.rmSync(botJobCompletionsPath(dir), { force: true });
+        return;
+    }
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = path.join(dir, `.job-completions.tmp.${process.pid}.${Date.now()}`);
+    const file = { v: 1, completions };
+    fs.writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, botJobCompletionsPath(dir));
+}
+/** Record (or back off) a completion the cloud has not taken. */
+export function recordPendingJobCompletion(dir, entry, now) {
+    const rest = readPendingJobCompletions(dir);
+    const existing = rest.find((c) => c.messageId === entry.messageId);
+    const attempts = (existing?.attempts ?? 0) + 1;
+    const next = {
+        v: 1,
+        ...entry,
+        firstFailedAt: existing?.firstFailedAt ?? now.toISOString(),
+        attempts,
+        nextAttemptAt: now.getTime() + completionRetryDelayMs(attempts),
+    };
+    write(dir, [...rest.filter((c) => c.messageId !== entry.messageId), next]);
+    return next;
+}
+export function clearPendingJobCompletion(dir, messageId) {
+    const rest = readPendingJobCompletions(dir);
+    const kept = rest.filter((c) => c.messageId !== messageId);
+    if (kept.length !== rest.length)
+        write(dir, kept);
+}
+//# sourceMappingURL=job-completions.js.map

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

@@ -0,0 +1,109 @@
+/**
+ * Scheduled job runs: the third kind of inbox item a bot can be handed.
+ *
+ * The cloud does all the scheduling. hq-pro-agents fires a job on an
+ * EventBridge schedule and writes a DURABLE inbox item for the agent
+ * (`channel: "job"`) carrying the job's own prompt. Nothing is scheduled on
+ * this computer — there is no crontab, no launchd timer, no local clock.
+ *
+ * Two rules shape everything here (owner decisions, 2026-09-15):
+ *
+ * - CATCH-UP, never skip. A run whose `staleAfter` has passed is still run,
+ *   once, and the bot says in its report that it is a catch-up and names the
+ *   time the run was originally due. A Mac that was asleep overnight wakes up
+ *   and does the morning job late rather than silently dropping it.
+ * - ONE catch-up per job per wake. If several runs of the SAME job are pending
+ *   (a long sleep over many fires), only the newest runs; the older ones are
+ *   reported to the cloud as `skipped-precondition` with a plain disposition,
+ *   so the job's in-progress flag is released and the history is honest.
+ *
+ * Everything in this file is pure so the rules are unit-testable.
+ */
+import type { InboxItem } from "./api.js";
+/** The job fields an inbox item carries when `channel === "job"`. */
+export interface JobRunFields {
+    jobId: string;
+    prompt: string;
+    /** Opaque metadata from the job record (an object on the wire). */
+    context?: Record<string, unknown> | string;
+    script?: string;
+    /** When the schedule fired (ISO-8601) — the time the run was due. */
+    firedAt?: string;
+    /** Delivery deadline (ISO-8601); past it, this is a catch-up. */
+    staleAfter?: string;
+    requestId?: string;
+}
+export declare function isJobItem(item: Pick<InboxItem, "channel">): boolean;
+/**
+ * The job fields of an inbox item, or null when it is not a usable job run.
+ * A job item with no jobId or no prompt is nothing the bot can run; the caller
+ * acks it rather than looping on it forever.
+ */
+export declare function readJobRun(item: InboxItem): JobRunFields | null;
+/** The run's extra context as text for the turn, or null when there is none. */
+export declare function jobContextText(context: JobRunFields["context"]): string | null;
+/** The zone this computer is in — where the owner scheduled the job. */
+export declare function machineTimeZone(): string;
+/**
+ * A readable instant for a person: "2026-09-15 09:00 EDT".
+ *
+ * Rendered in the OWNER's zone, not UTC. Schedules are created in the machine's
+ * zone ("every weekday at 9am" means 9am where the owner lives), so reporting
+ * the same run as "due 13:00 UTC" reads as the wrong time to the only person
+ * who sees it. The format is fixed (en-CA + explicit parts) rather than
+ * locale-default, so the bot reads the same on every machine and the output is
+ * testable.
+ */
+export declare function formatJobTime(iso: string | undefined, timeZone?: string): string;
+/** True when the delivery deadline has passed: this run is late, not skipped. */
+export declare function isCatchUpRun(job: JobRunFields, now: Date): boolean;
+/**
+ * The user turn for a fired job. It says plainly that this is a scheduled run
+ * so the model does not answer as if a person had just spoken, and (for a late
+ * run) that it is a catch-up, naming the time the run was originally due.
+ */
+export declare function buildJobTurnPrompt(job: JobRunFields, opts: {
+    now: Date;
+    timeZone?: string;
+}): string;
+/**
+ * The line the bot's DM report starts with, so the owner sees at a glance that
+ * this is a scheduled run and not a reply to something they said.
+ */
+export declare function jobReportHeader(job: JobRunFields, catchUp: boolean, timeZone?: string): string;
+/**
+ * Sort key for "which pending run of this job is the newest".
+ *
+ * A run with NO timestamp must sort LOWEST, never highest. Falling back to the
+ * messageId was a real bug: an id like `jobrun-…` sorts above any ISO timestamp
+ * (letters beat digits), so a run missing `firedAt` would win as "newest" and
+ * supersede a genuinely newer run — the newer work would be skipped and the
+ * older one would run.
+ */
+export declare function jobRunOrderKey(item: InboxItem): string;
+/** The disposition reported for an older pending run of the same job. */
+export declare const SUPERSEDED_DISPOSITION = "a newer pending run of this job ran instead (the computer was asleep through several fires)";
+/**
+ * Decide which pending job runs to actually run. `handled` maps jobId to the
+ * newest run key this process has already picked up; it is UPDATED in place so
+ * a later poll cannot resurrect an older run of a job whose newer run already
+ * finished and was acked.
+ *
+ * Returns the message ids that must NOT be run — they are reported to the
+ * cloud as `skipped-precondition` instead.
+ */
+export declare function planJobRuns(items: InboxItem[], handled: Map<string, string>): {
+    superseded: Set<string>;
+};
+/**
+ * The most run output the cloud keeps (hq-pro-agents jobs/results.ts
+ * `MAX_JOB_RUN_OUTPUT_BYTES`). The server bounds it itself; the client sends up
+ * to the same bound rather than an arbitrary shorter cut, so a long report is
+ * recorded in full wherever the cloud can hold it.
+ */
+export declare const MAX_JOB_RUN_OUTPUT_BYTES: number;
+/** Cut `text` to at most `maxBytes` of UTF-8 without splitting a character. */
+export declare function jobRunOutput(text: string, maxBytes?: number): string;
+/** A saved report body with the run's header taken back off, for the cloud's record. */
+export declare function stripJobHeader(body: string, header: string | undefined): string;
+//# sourceMappingURL=job-run.d.ts.map