@indigoai-us/hq-cli 5.135.0 → 5.137.0

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

@@ -0,0 +1,246 @@
+/**
+ * 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.
+ */
+export function isJobItem(item) {
+    return item.channel === "job";
+}
+/**
+ * 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 function readJobRun(item) {
+    if (!isJobItem(item))
+        return null;
+    const jobId = typeof item.jobId === "string" ? item.jobId.trim() : "";
+    const prompt = typeof item.prompt === "string" ? item.prompt.trim() : "";
+    if (!jobId || !prompt)
+        return null;
+    return {
+        jobId,
+        prompt,
+        ...(item.context !== undefined && item.context !== null ? { context: item.context } : {}),
+        ...(typeof item.script === "string" && item.script.trim() ? { script: item.script } : {}),
+        ...(typeof item.firedAt === "string" && item.firedAt.trim() ? { firedAt: item.firedAt.trim() } : {}),
+        ...(typeof item.staleAfter === "string" && item.staleAfter.trim() ? { staleAfter: item.staleAfter.trim() } : {}),
+        ...(typeof item.requestId === "string" && item.requestId.trim() ? { requestId: item.requestId.trim() } : {}),
+    };
+}
+/** The run's extra context as text for the turn, or null when there is none. */
+export function jobContextText(context) {
+    if (context === undefined || context === null)
+        return null;
+    if (typeof context === "string")
+        return context.trim() || null;
+    try {
+        const keys = Object.keys(context);
+        if (keys.length === 0)
+            return null;
+        return JSON.stringify(context, null, 2);
+    }
+    catch {
+        return null;
+    }
+}
+/** The zone this computer is in — where the owner scheduled the job. */
+export function machineTimeZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    }
+    catch {
+        return "UTC";
+    }
+}
+/**
+ * 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 function formatJobTime(iso, timeZone = machineTimeZone()) {
+    if (!iso)
+        return "an unknown time";
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    try {
+        const parts = new Intl.DateTimeFormat("en-CA", {
+            timeZone,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            hour12: false,
+            timeZoneName: "short",
+        }).formatToParts(d);
+        const get = (type) => parts.find((p) => p.type === type)?.value ?? "";
+        const [year, month, day, hour, minute, zone] = [
+            get("year"),
+            get("month"),
+            get("day"),
+            get("hour"),
+            get("minute"),
+            get("timeZoneName"),
+        ];
+        if (!year || !month || !day || !hour || !minute)
+            throw new Error("incomplete");
+        // Intl renders midnight as "24" in some hourCycles; normalise to 00.
+        const h = hour === "24" ? "00" : hour;
+        return `${year}-${month}-${day} ${h}:${minute}${zone ? ` ${zone}` : ""}`;
+    }
+    catch {
+        return `${d.toISOString().slice(0, 16).replace("T", " ")} UTC`;
+    }
+}
+/** True when the delivery deadline has passed: this run is late, not skipped. */
+export function isCatchUpRun(job, now) {
+    if (!job.staleAfter)
+        return false;
+    const deadline = new Date(job.staleAfter);
+    if (Number.isNaN(deadline.getTime()))
+        return false;
+    return now.getTime() > deadline.getTime();
+}
+/**
+ * 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 function buildJobTurnPrompt(job, opts) {
+    const catchUp = isCatchUpRun(job, opts.now);
+    const due = formatJobTime(job.firedAt, opts.timeZone);
+    const lines = [];
+    // The due time is stated EXACTLY once: in the late sentence for a catch-up,
+    // in the opening sentence otherwise. Saying it twice reads as two times.
+    lines.push(`[Scheduled job · ${job.jobId}]`);
+    lines.push(`This is a scheduled run that fired on its own${catchUp ? "" : `, due at ${due}`}. Nobody just sent you a ` +
+        "message and nobody is waiting in a chat. Do the work described below, then finish with a short " +
+        "plain-language report of what you did and what you found — that report is what your owner reads.");
+    if (catchUp) {
+        lines.push(`This run is late: it was due at ${due} and is only running now because this computer was asleep ` +
+            "or switched off. Do it as a catch-up, skip anything that no longer makes sense at this hour, " +
+            "and say in your report that it ran late.");
+    }
+    const body = [lines.join("\n"), job.prompt];
+    const context = jobContextText(job.context);
+    if (context)
+        body.push(`Extra context for this run:\n${context}`);
+    return body.join("\n\n");
+}
+/**
+ * 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 function jobReportHeader(job, catchUp, timeZone) {
+    const base = `⏰ Scheduled job \`${job.jobId}\``;
+    return catchUp
+        ? `${base} — catch-up for the run due ${formatJobTime(job.firedAt, timeZone)}\n\n`
+        : `${base}\n\n`;
+}
+/**
+ * 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 function jobRunOrderKey(item) {
+    const fired = typeof item.firedAt === "string" ? item.firedAt.trim() : "";
+    if (fired)
+        return fired;
+    const received = typeof item.receivedAt === "string" ? item.receivedAt.trim() : "";
+    if (received)
+        return received;
+    return "";
+}
+/** The disposition reported for an older pending run of the same job. */
+export 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 function planJobRuns(items, handled) {
+    const superseded = new Set();
+    const byJob = new Map();
+    for (const item of items) {
+        const job = readJobRun(item);
+        if (!job)
+            continue;
+        const list = byJob.get(job.jobId);
+        if (list)
+            list.push(item);
+        else
+            byJob.set(job.jobId, [item]);
+    }
+    for (const [jobId, runs] of byJob) {
+        let newest = handled.get(jobId) ?? "";
+        for (const run of runs) {
+            const key = jobRunOrderKey(run);
+            if (key > newest)
+                newest = key;
+        }
+        handled.set(jobId, newest);
+        let keptNewest = false;
+        for (const run of runs) {
+            if (jobRunOrderKey(run) === newest && !keptNewest) {
+                keptNewest = true;
+                continue;
+            }
+            superseded.add(run.messageId);
+        }
+    }
+    return { superseded };
+}
+/**
+ * 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 const MAX_JOB_RUN_OUTPUT_BYTES = 64 * 1024;
+/** Cut `text` to at most `maxBytes` of UTF-8 without splitting a character. */
+export function jobRunOutput(text, maxBytes = MAX_JOB_RUN_OUTPUT_BYTES) {
+    const bytes = Buffer.from(text, "utf8");
+    if (bytes.byteLength <= maxBytes)
+        return text;
+    let end = maxBytes;
+    // Step back over UTF-8 continuation bytes (10xxxxxx) to a character boundary.
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end -= 1;
+    return bytes.subarray(0, end).toString("utf8");
+}
+/** A saved report body with the run's header taken back off, for the cloud's record. */
+export function stripJobHeader(body, header) {
+    return header && body.startsWith(header) ? body.slice(header.length) : body;
+}
+//# sourceMappingURL=job-run.js.map

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

@@ -11,6 +11,8 @@
  *     session.json        model-CLI session id for the owner DM
  *     session-dm-<hexPeerUid>.json  one session per other DM correspondent
  *     session-room-<channelId>.json  one session per room the bot answers in
+ *     session-job-<jobId>.json       one session per scheduled job the bot runs
+ *     job-completions.json  run completions the cloud has not accepted yet
  *     pid                 single-file pid lock
  *     logs/bot.log        rotated at 5MB
  *
@@ -39,10 +41,16 @@ export declare function botInboxStatePath(dir: string): string;
  * Model conversations are scoped to a DM correspondent or room. The owner's
  * legacy "dm" scope remains stable; other senders use "dm:<peerUid>".
  */
-export type BotSessionScope = "dm" | `dm:${string}` | `room:${string}`;
+export type BotSessionScope = "dm" | `dm:${string}` | `room:${string}` | `job:${string}`;
 /** Preserve the owner session; keep every other correspondent separate. */
 export declare function dmSessionScope(peerUid: string, ownerUid: string): BotSessionScope;
 export declare function roomSessionScope(channelId: string): BotSessionScope;
+/**
+ * One session per scheduled job. A job turn must never resume the owner's DM
+ * conversation (a scheduled run is not a reply), and two different jobs must
+ * not share a session either — each recurring routine keeps its own history.
+ */
+export declare function jobSessionScope(jobId: string): BotSessionScope;
 export declare function botSessionPath(dir: string, scope?: BotSessionScope): string;
 export declare function botTokenStateDir(dir: string): string;
 /**

package/dist/lib/bot/paths.js

@@ -11,6 +11,8 @@
  *     session.json        model-CLI session id for the owner DM
  *     session-dm-<hexPeerUid>.json  one session per other DM correspondent
  *     session-room-<channelId>.json  one session per room the bot answers in
+ *     session-job-<jobId>.json       one session per scheduled job the bot runs
+ *     job-completions.json  run completions the cloud has not accepted yet
  *     pid                 single-file pid lock
  *     logs/bot.log        rotated at 5MB
  *
@@ -69,11 +71,23 @@ export function dmSessionScope(peerUid, ownerUid) {
 export function roomSessionScope(channelId) {
     return `room:${channelId}`;
 }
+/**
+ * One session per scheduled job. A job turn must never resume the owner's DM
+ * conversation (a scheduled run is not a reply), and two different jobs must
+ * not share a session either — each recurring routine keeps its own history.
+ */
+export function jobSessionScope(jobId) {
+    return `job:${jobId}`;
+}
 export function botSessionPath(dir, scope = "dm") {
     if (scope === "dm")
         return path.join(dir, BOT_SESSION_NAME);
     if (scope.startsWith("dm:"))
         return path.join(dir, `session-dm-${Buffer.from(scope.slice(3)).toString("hex")}.json`);
+    if (scope.startsWith("job:")) {
+        const jobId = scope.slice("job:".length).replace(/[^A-Za-z0-9_-]/g, "_");
+        return path.join(dir, `session-job-${jobId}.json`);
+    }
     const channelId = scope.slice("room:".length).replace(/[^A-Za-z0-9_-]/g, "_");
     return path.join(dir, `session-room-${channelId}.json`);
 }

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

@@ -105,6 +105,18 @@ export declare function botKindParagraph(input: Pick<BuildSystemPromptInput, "ag
  * preamble (grok).
  */
 export declare function buildSystemPrompt(input: BuildSystemPromptInput): string;
+/**
+ * What the bot knows about putting its own work on a schedule. The schedule
+ * lives in the cloud; the bot never writes a crontab or a launchd timer.
+ *
+ * The catch-up wording is deliberately precise. The cloud only dead-letters a
+ * stale run on the job's NEXT fire, and the staleness window is an hour, so a
+ * missed run is picked up on wake only if the wake happens within about an
+ * hour; a longer outage means that run is gone and the job simply resumes at
+ * its next scheduled time. Promising an unconditional catch-up would be the bot
+ * telling its owner something untrue about work they are relying on.
+ */
+export declare function scheduledJobsParagraph(botName: string): string;
 /**
  * The one-time introduction the bot DMs its owner when it first comes online.
  * A bot created with `--intro` sends that text verbatim instead.

package/dist/lib/bot/prompt.js

@@ -289,6 +289,12 @@ export function buildSystemPrompt(input) {
         `comes from a room with other people in it (a "Recent messages:" block may follow for context; the last part is the message you are answering). ` +
         `Answer for the room: reply to the person who asked, keep it short, and never repeat your private memory, your owner's files, ` +
         `or anything from your DMs to other people.`);
+    // Only company bots: the cloud's jobs routes refuse a personal bot's per_
+    // company claim today, so telling a personal bot it can schedule work makes
+    // it promise its owner something that then fails. Drop this condition when
+    // the server accepts personal bots — the paragraph itself needs no change.
+    if (kind === "company")
+        parts.push(scheduledJobsParagraph(input.botName));
     if (workerMode && worker) {
         const yamlPath = path.join(input.workerDir, "worker.yaml");
         if (worker.instructions) {
@@ -333,6 +339,31 @@ export function buildSystemPrompt(input) {
     }
     return `${parts.join("\n\n")}\n`;
 }
+/**
+ * What the bot knows about putting its own work on a schedule. The schedule
+ * lives in the cloud; the bot never writes a crontab or a launchd timer.
+ *
+ * The catch-up wording is deliberately precise. The cloud only dead-letters a
+ * stale run on the job's NEXT fire, and the staleness window is an hour, so a
+ * missed run is picked up on wake only if the wake happens within about an
+ * hour; a longer outage means that run is gone and the job simply resumes at
+ * its next scheduled time. Promising an unconditional catch-up would be the bot
+ * telling its owner something untrue about work they are relying on.
+ */
+export function scheduledJobsParagraph(botName) {
+    return (`## Scheduled jobs\n\n` +
+        `You can put your own work on a recurring schedule. When your owner asks for something regular ` +
+        `("check X every weekday morning", "send me a summary every Friday"), run ` +
+        `\`hq bot jobs ${botName} --add "<what to do>" --every "<plain English, e.g. every weekday at 9am>"\`. ` +
+        `See what you have scheduled with \`hq bot jobs ${botName}\`, and remove one with ` +
+        `\`hq bot jobs ${botName} --rm <jobId>\`.\n` +
+        `After you schedule something, say back in plain words what you set up and when it will run. Also say what ` +
+        `happens if this computer is asleep or switched off when a run is due: it is picked up as a catch-up when the ` +
+        `computer wakes, as long as it wakes within about an hour; after a longer outage that run is skipped and the ` +
+        `job carries on at its next scheduled time. A schedule cannot fire more often than every 5 minutes.\n` +
+        `When one of these fires you get a turn that starts with "[Scheduled job · …]". Nobody is waiting in a chat: ` +
+        `do the work and finish with a short report — that report is what your owner reads.`);
+}
 /**
  * The one-time introduction the bot DMs its owner when it first comes online.
  * A bot created with `--intro` sends that text verbatim instead.

package/dist/lib/bot/room-policy.d.ts

@@ -1,5 +1,10 @@
-/** Reply to any correspondent or delivered room message, except our own posts. */
+/** Reply to any correspondent or delivered room message, except our own posts.
+ * Jobs (channel "job") are scheduled runs the cloud fired: not addressed to
+ * anyone, they resolve to their own lane and model session, and report in the
+ * owner's DM.
+ */
 import type { InboxItem } from "./api.js";
+import { type JobRunFields } from "./job-run.js";
 import { type BotSessionScope } from "./paths.js";
 export type ReplyTarget = {
     kind: "dm";
@@ -12,6 +17,18 @@ export type ReplyTarget = {
     sessionScope: BotSessionScope;
     /** True when this bot was @mentioned: answer without claiming. */
     mentioned: boolean;
+} | {
+    /**
+     * A scheduled job the cloud fired for this bot. Nobody sent it: the work
+     * is the job's own prompt, and the result is reported in the owner's DM,
+     * clearly marked as a scheduled run rather than a reply.
+     */
+    kind: "job";
+    jobId: string;
+    /** Where the report goes: the bot's DM with its owner. */
+    peerUid: string;
+    sessionScope: BotSessionScope;
+    job: JobRunFields;
 };
 export interface ReplyPolicyConfig {
     ownerUid: string;

package/dist/lib/bot/room-policy.js

@@ -1,5 +1,10 @@
-/** Reply to any correspondent or delivered room message, except our own posts. */
-import { roomSessionScope } from "./paths.js";
+/** Reply to any correspondent or delivered room message, except our own posts.
+ * Jobs (channel "job") are scheduled runs the cloud fired: not addressed to
+ * anyone, they resolve to their own lane and model session, and report in the
+ * owner's DM.
+ */
+import { readJobRun } from "./job-run.js";
+import { jobSessionScope, roomSessionScope } from "./paths.js";
 function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -13,6 +18,19 @@ export function isDmItem(item) {
 }
 export function resolveReplyTarget(item, config) {
     const sender = item.fromPersonUid ?? "";
+    if (item.channel === "job") {
+        const job = readJobRun(item);
+        // A job item with no jobId or no prompt is nothing the bot can run.
+        if (!job)
+            return null;
+        return {
+            kind: "job",
+            jobId: job.jobId,
+            peerUid: config.ownerUid,
+            sessionScope: jobSessionScope(job.jobId),
+            job,
+        };
+    }
     if (isDmItem(item)) {
         return sender && sender !== config.agentUid ? { kind: "dm", peerUid: sender } : null;
     }

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

@@ -13,6 +13,14 @@
  * - 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,
@@ -82,6 +90,18 @@ export declare const MAX_PARALLEL_TURNS = 2;
 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) => Promise<void>;
 export interface BotRunDeps {
     dir: string;
@@ -163,7 +183,9 @@ export interface BotHandle {
 /**
  * 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. An unsupported item gets a lane of its own.
+ * 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;