@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/bot/local-config.js

@@ -0,0 +1,145 @@
+/**
+ * `localConfig` — the non-secret shape of a bot's bot.json that the cloud
+ * stores alongside the agent record, so a reinstall (or a second Mac) can
+ * rebuild the same bot instead of re-creating it.
+ *
+ * The server treats it as opaque, caps it at 8 KB, and refuses any value that
+ * carries a key named secret/token/password/creds (case-insensitive). The CLI
+ * therefore builds it from an explicit allow-list of bot.json fields and
+ * checks the result before it leaves this machine: a bot's machine credentials
+ * live only in ~/.hq/bots/<name>/machine-creds.json and never travel here.
+ */
+import { botMemoryMode, effectiveBotCompanies, effectiveBotKind, isBotKind, isBotMemoryMode, isBotRuntimeId, } from "./config.js";
+/** Same limit the server enforces on the stored value. */
+const BOT_LOCAL_CONFIG_MAX_BYTES = 8 * 1024;
+/** Key names the server rejects outright (case-insensitive, substring). */
+const BOT_LOCAL_CONFIG_FORBIDDEN_KEY_RE = /secret|token|password|creds/i;
+/** Walks a value and throws when any key looks like it could carry a secret. */
+export function assertNoSecretKeys(value, path = "localConfig") {
+    if (Array.isArray(value)) {
+        value.forEach((item, i) => assertNoSecretKeys(item, `${path}[${i}]`));
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if (BOT_LOCAL_CONFIG_FORBIDDEN_KEY_RE.test(key)) {
+            throw Object.assign(new Error(`${path}.${key} looks like a credential; a bot's saved settings never carry one.`), {
+                expected: true,
+            });
+        }
+        assertNoSecretKeys(child, `${path}.${key}`);
+    }
+}
+/**
+ * The non-secret settings of a bot, for the cloud to keep. Absolute paths
+ * (hqRoot, memoryDir, workerDir) are deliberately left out: they belong to the
+ * machine the bot was created on, and a restore rebuilds them locally.
+ */
+export function buildBotLocalConfig(config) {
+    const kind = effectiveBotKind(config);
+    const companies = effectiveBotCompanies(config);
+    const local = {
+        v: 1,
+        runtime: config.runtime,
+        workerSource: config.workerSource ?? "scaffold",
+        ...(config.workerId ? { workerId: config.workerId } : {}),
+        ...(config.companySlug ? { companySlug: config.companySlug } : {}),
+        ...(config.model ? { model: config.model } : {}),
+        ...(config.effort ? { effort: config.effort } : {}),
+        kind,
+        ...(kind === "company" ? { companies } : {}),
+        ...(config.autoApprove === false ? { autoApprove: false } : {}),
+        memory: botMemoryMode(config),
+        ...(config.displayName ? { displayName: config.displayName } : {}),
+        ...(config.intro ? { intro: config.intro } : {}),
+        ...(config.kickoff ? { kickoff: config.kickoff } : {}),
+    };
+    assertNoSecretKeys(local);
+    if (Buffer.byteLength(JSON.stringify(local), "utf8") > BOT_LOCAL_CONFIG_MAX_BYTES) {
+        throw Object.assign(new Error("This bot's settings are too large to save in the cloud (over 8 KB)."), {
+            expected: true,
+        });
+    }
+    return local;
+}
+/**
+ * Tolerant read of whatever the server handed back: an older bot has no
+ * localConfig at all, and a field HQ no longer understands is dropped rather
+ * than losing the bot. Returns null when nothing usable was stored.
+ */
+export function parseBotLocalConfig(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const raw = value;
+    const str = (key) => {
+        const v = raw[key];
+        return typeof v === "string" && v.trim() ? v.trim() : undefined;
+    };
+    const out = { v: 1 };
+    const runtime = str("runtime");
+    if (isBotRuntimeId(runtime))
+        out.runtime = runtime;
+    const workerSource = str("workerSource");
+    if (workerSource === "worker" || workerSource === "scaffold")
+        out.workerSource = workerSource;
+    const workerId = str("workerId");
+    if (workerId)
+        out.workerId = workerId;
+    const companySlug = str("companySlug");
+    if (companySlug)
+        out.companySlug = companySlug;
+    const model = str("model");
+    if (model)
+        out.model = model;
+    const effort = str("effort");
+    if (effort)
+        out.effort = effort;
+    const kind = str("kind");
+    if (isBotKind(kind))
+        out.kind = kind;
+    if (Array.isArray(raw.companies)) {
+        const companies = raw.companies.filter((c) => typeof c === "string" && c.trim().length > 0).map((c) => c.trim());
+        if (companies.length > 0)
+            out.companies = [...new Set(companies)];
+    }
+    if (raw.autoApprove === false)
+        out.autoApprove = false;
+    const memory = str("memory");
+    if (isBotMemoryMode(memory))
+        out.memory = memory;
+    const displayName = str("displayName");
+    if (displayName)
+        out.displayName = displayName;
+    const intro = str("intro");
+    if (intro)
+        out.intro = intro;
+    const kickoff = str("kickoff");
+    if (kickoff)
+        out.kickoff = kickoff;
+    // A record with nothing recognisable in it is the same as none at all.
+    return Object.keys(out).length > 1 ? out : null;
+}
+/** What a restore falls back to for a bot created before localConfig existed. */
+export const BOT_RESTORE_DEFAULTS = {
+    runtime: "claude",
+    memory: "synced",
+    kind: "personal",
+};
+/** Human summary of the settings a restore is about to apply. */
+export function describeBotLocalConfig(local) {
+    if (!local) {
+        return `defaults (${BOT_RESTORE_DEFAULTS.runtime}, ${BOT_RESTORE_DEFAULTS.memory} memory, ${BOT_RESTORE_DEFAULTS.kind})`;
+    }
+    const bits = [
+        local.runtime ?? BOT_RESTORE_DEFAULTS.runtime,
+        `${local.memory ?? BOT_RESTORE_DEFAULTS.memory} memory`,
+        local.kind ?? BOT_RESTORE_DEFAULTS.kind,
+    ];
+    if (local.workerId)
+        bits.push(`worker ${local.workerId}`);
+    if (local.model)
+        bits.push(local.model);
+    return bits.join(", ");
+}
+//# sourceMappingURL=local-config.js.map

package/dist/lib/bot/local-jobs.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Scheduled jobs for a bot that runs on this computer.
+ *
+ * The schedule lives with the bot. A local bot keeps its jobs in `jobs.json`
+ * in its own folder and fires them itself, from the same loop that checks its
+ * inbox. A due job becomes an ordinary `channel: "job"` inbox item, so it runs
+ * through exactly the path a cloud-fired job does (own session, "scheduled
+ * job" header in the owner's DM, catch-up label when late). Only the three
+ * calls that talk to the cloud about a run are answered here instead:
+ * pulling due runs, acking them, and recording how they finished.
+ *
+ * Rules:
+ * - Jobs fire only while the bot is running. After a sleep or an outage, a job
+ *   runs ONCE for its newest missed time, labelled a catch-up; older missed
+ *   times are not replayed.
+ * - A job never overlaps itself. A new fire waits until the previous run of
+ *   the same job has finished (or has been silent for an hour).
+ * - A fire is recorded before it is handed over, so a crash never runs the
+ *   same due time twice.
+ */
+import { type BotApi, type InboxItem } from "./api.js";
+export interface LocalJob {
+    jobId: string;
+    prompt: string;
+    /** Standard 5-field cron, evaluated in `timezone`. */
+    cron: string;
+    timezone: string;
+    context?: Record<string, unknown>;
+    createdAt: string;
+    /** The newest due time already handed to the bot. */
+    lastFiredAt?: string;
+    /** The run in progress, if any. */
+    inFlight?: {
+        messageId: string;
+        since: string;
+    };
+    lastRunAt?: string;
+    lastStatus?: string;
+    runCount?: number;
+}
+export declare function readLocalJobs(dir: string): LocalJob[];
+/**
+ * Run a read-change-write of `jobs.json` under an exclusive lock. The running
+ * bot (firing, finishing) and `hq bot jobs` (add, remove) are separate
+ * processes; without the lock one can write back a stale copy and silently
+ * undo the other's change.
+ */
+export declare function withJobsLock<T>(dir: string, fn: () => T): T;
+export interface CronMatcher {
+    minutes: Set<number>;
+    hours: Set<number>;
+    days: Set<number>;
+    months: Set<number>;
+    weekdays: Set<number>;
+    dayRestricted: boolean;
+    weekdayRestricted: boolean;
+}
+/**
+ * The job's schedule as a standard 5-field cron. Jobs are stored in the same
+ * form the cloud uses (`cron(m h dom mon dow year)`, Sunday = 1, `?` for the
+ * unused day field), so the same `hq bot jobs` input works for either home.
+ */
+export declare function toStandardCron(expr: string): string | null;
+/** Parse a standard 5-field cron, or null when it is not one. */
+export declare function parseCron(expr: string): CronMatcher | null;
+export declare function latestDueFire(job: LocalJob, now: Date): Date | null;
+/** The next time this job is due after `now`, within a week; null otherwise. */
+export declare function nextDueFire(job: LocalJob, now: Date): Date | null;
+export declare function addLocalJob(dir: string, input: {
+    prompt: string;
+    cron: string;
+    timezone: string;
+    context?: Record<string, unknown>;
+}, now?: Date): LocalJob;
+/** Forget the once-per-minute check (tests, and a bot restarted in-process). */
+export declare function resetLocalJobChecks(): void;
+export declare function takeDueLocalJobRuns(dir: string, now?: Date): InboxItem[];
+/**
+ * The bot's cloud client, with its scheduled runs answered on this computer:
+ * due local jobs join the inbox, and their ack and completion are recorded
+ * locally instead of being sent to the cloud.
+ */
+export declare function withLocalJobs(api: BotApi, dir: string, clock?: () => Date): BotApi;
+/**
+ * `hq bot jobs` against the bot's own folder: the same three calls the cloud
+ * client offers, answered from `jobs.json`.
+ */
+export declare function localJobsClient(dir: string, clock?: () => Date): Pick<BotApi, "listJobs" | "createJob" | "cancelJob">;
+//# sourceMappingURL=local-jobs.d.ts.map

package/dist/lib/bot/local-jobs.js

@@ -0,0 +1,459 @@
+/**
+ * Scheduled jobs for a bot that runs on this computer.
+ *
+ * The schedule lives with the bot. A local bot keeps its jobs in `jobs.json`
+ * in its own folder and fires them itself, from the same loop that checks its
+ * inbox. A due job becomes an ordinary `channel: "job"` inbox item, so it runs
+ * through exactly the path a cloud-fired job does (own session, "scheduled
+ * job" header in the owner's DM, catch-up label when late). Only the three
+ * calls that talk to the cloud about a run are answered here instead:
+ * pulling due runs, acking them, and recording how they finished.
+ *
+ * Rules:
+ * - Jobs fire only while the bot is running. After a sleep or an outage, a job
+ *   runs ONCE for its newest missed time, labelled a catch-up; older missed
+ *   times are not replayed.
+ * - A job never overlaps itself. A new fire waits until the previous run of
+ *   the same job has finished (or has been silent for an hour).
+ * - A fire is recorded before it is handed over, so a crash never runs the
+ *   same due time twice.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { BotApiError } from "./api.js";
+const LOCAL_JOBS_FILE = "jobs.json";
+const LOCAL_JOB_MESSAGE_PREFIX = "localjob-";
+/** How far back a missed fire is still looked for (one week). */
+const LOOKBACK_MINUTES = 7 * 24 * 60;
+/** A run that never reported back releases its job after this long. */
+const IN_FLIGHT_RELEASE_MS = 60 * 60 * 1000;
+/** A fire is "late" (a catch-up) once this long past its due time. */
+const STALE_AFTER_MS = 10 * 60 * 1000;
+function localJobsPath(dir) {
+    return path.join(dir, LOCAL_JOBS_FILE);
+}
+export function readLocalJobs(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(localJobsPath(dir), "utf8"));
+        return Array.isArray(parsed.jobs) ? parsed.jobs.filter((job) => !!job && typeof job.jobId === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+function writeLocalJobs(dir, jobs) {
+    const file = localJobsPath(dir);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ v: 1, jobs }, null, 2));
+    fs.renameSync(tmp, file);
+}
+// ─── Lock ────────────────────────────────────────────────────────────────────
+/** A lock older than this belongs to a process that died holding it. */
+const LOCK_STALE_MS = 30_000;
+const LOCK_WAIT_MS = 5_000;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Run a read-change-write of `jobs.json` under an exclusive lock. The running
+ * bot (firing, finishing) and `hq bot jobs` (add, remove) are separate
+ * processes; without the lock one can write back a stale copy and silently
+ * undo the other's change.
+ */
+export function withJobsLock(dir, fn) {
+    const lock = `${localJobsPath(dir)}.lock`;
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            fs.writeFileSync(lock, String(process.pid), { flag: "wx" });
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            try {
+                if (Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS) {
+                    fs.rmSync(lock, { force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new Error(`The bot's job list is busy (${lock}). Try again in a moment.`);
+            sleepSync(25);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        fs.rmSync(lock, { force: true });
+    }
+}
+// ─── Cron ────────────────────────────────────────────────────────────────────
+const FIELD_RANGES = [
+    [0, 59], // minute
+    [0, 23], // hour
+    [1, 31], // day of month
+    [1, 12], // month
+    [0, 7], // day of week (0 and 7 are Sunday)
+];
+function parseField(field, [min, max]) {
+    const out = new Set();
+    for (const part of field.split(",")) {
+        const [rangePart, stepPart] = part.split("/");
+        const step = stepPart === undefined ? 1 : Number(stepPart);
+        if (!Number.isInteger(step) || step < 1)
+            return null;
+        let lo;
+        let hi;
+        if (rangePart === "*") {
+            lo = min;
+            hi = max;
+        }
+        else if (/^\d+-\d+$/.test(rangePart ?? "")) {
+            [lo, hi] = rangePart.split("-").map(Number);
+        }
+        else if (/^\d+$/.test(rangePart ?? "")) {
+            lo = Number(rangePart);
+            hi = stepPart === undefined ? lo : max;
+        }
+        else {
+            return null;
+        }
+        if (lo < min || hi > max || lo > hi)
+            return null;
+        for (let v = lo; v <= hi; v += step)
+            out.add(v);
+    }
+    return out;
+}
+const DAY_NAMES = { SUN: 0, MON: 1, TUE: 2, WED: 3, THU: 4, FRI: 5, SAT: 6 };
+const MONTH_NAMES = {
+    JAN: 1, FEB: 2, MAR: 3, APR: 4, MAY: 5, JUN: 6, JUL: 7, AUG: 8, SEP: 9, OCT: 10, NOV: 11, DEC: 12,
+};
+function replaceNames(field, names) {
+    return field.replace(/[A-Za-z]{3}/g, (name) => {
+        const value = names[name.toUpperCase()];
+        return value === undefined ? name : String(value);
+    });
+}
+/**
+ * The job's schedule as a standard 5-field cron. Jobs are stored in the same
+ * form the cloud uses (`cron(m h dom mon dow year)`, Sunday = 1, `?` for the
+ * unused day field), so the same `hq bot jobs` input works for either home.
+ */
+export function toStandardCron(expr) {
+    const trimmed = expr.trim();
+    const wrapped = /^cron\((.*)\)$/.exec(trimmed);
+    if (!wrapped)
+        return trimmed.split(/\s+/).length === 5 ? trimmed : null;
+    const fields = wrapped[1].trim().split(/\s+/);
+    if (fields.length !== 6)
+        return null;
+    const [minute, hour, dom, month, dow] = fields;
+    const standardDow = dow === "?" || dow === "*"
+        ? "*"
+        : replaceNames(dow, { SUN: 1, MON: 2, TUE: 3, WED: 4, THU: 5, FRI: 6, SAT: 7 }).replace(/\d+/g, (n) => String(Number(n) - 1));
+    return [minute, hour, dom === "?" ? "*" : dom, month, standardDow].join(" ");
+}
+/** Parse a standard 5-field cron, or null when it is not one. */
+export function parseCron(expr) {
+    const standard = toStandardCron(expr);
+    if (!standard)
+        return null;
+    const fields = standard.split(/\s+/).map((field, i) => i === 3 ? replaceNames(field, MONTH_NAMES) : i === 4 ? replaceNames(field, DAY_NAMES) : field);
+    if (fields.length !== 5)
+        return null;
+    const sets = fields.map((field, i) => parseField(field, FIELD_RANGES[i]));
+    if (sets.some((set) => set === null))
+        return null;
+    const [minutes, hours, days, months, weekdays] = sets;
+    if (weekdays.has(7))
+        weekdays.add(0);
+    return {
+        minutes: minutes,
+        hours: hours,
+        days: days,
+        months: months,
+        weekdays: weekdays,
+        dayRestricted: fields[2] !== "*",
+        weekdayRestricted: fields[4] !== "*",
+    };
+}
+const WEEKDAY = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+const formatters = new Map();
+function zonedParts(date, timeZone) {
+    let format = formatters.get(timeZone);
+    if (!format) {
+        format = new Intl.DateTimeFormat("en-US", {
+            timeZone,
+            hour12: false,
+            minute: "numeric",
+            hour: "numeric",
+            day: "numeric",
+            month: "numeric",
+            weekday: "short",
+        });
+        formatters.set(timeZone, format);
+    }
+    const parts = format.formatToParts(date);
+    const get = (type) => parts.find((p) => p.type === type)?.value ?? "";
+    return {
+        minute: Number(get("minute")),
+        hour: Number(get("hour")) % 24,
+        day: Number(get("day")),
+        month: Number(get("month")),
+        weekday: WEEKDAY[get("weekday")] ?? -1,
+    };
+}
+function cronMatches(cron, date, timeZone) {
+    const t = zonedParts(date, timeZone);
+    if (!cron.minutes.has(t.minute) || !cron.hours.has(t.hour) || !cron.months.has(t.month))
+        return false;
+    const dayOk = cron.days.has(t.day);
+    const weekdayOk = cron.weekdays.has(t.weekday);
+    // Standard cron: when both day fields are restricted, either may match.
+    if (cron.dayRestricted && cron.weekdayRestricted)
+        return dayOk || weekdayOk;
+    return dayOk && weekdayOk;
+}
+/**
+ * The newest time this job was due, at or before `now` and after the last one
+ * already fired. Null when nothing new is due.
+ */
+/** `rate(5 minutes)` / `rate(1 hour)` / `rate(2 days)` as milliseconds. */
+function rateIntervalMs(expr) {
+    const match = /^rate\((\d+)\s+(minute|minutes|hour|hours|day|days)\)$/.exec(expr.trim());
+    if (!match)
+        return null;
+    const n = Number(match[1]);
+    const unit = match[2].startsWith("minute") ? 60_000 : match[2].startsWith("hour") ? 3_600_000 : 86_400_000;
+    return n > 0 ? n * unit : null;
+}
+function isRunnableSchedule(expr) {
+    return rateIntervalMs(expr) !== null || parseCron(expr) !== null;
+}
+export function latestDueFire(job, now) {
+    const interval = rateIntervalMs(job.cron);
+    if (interval) {
+        const origin = Date.parse(job.createdAt);
+        const steps = Math.floor((now.getTime() - origin) / interval);
+        if (steps < 1)
+            return null;
+        const due = origin + steps * interval;
+        return job.lastFiredAt && Date.parse(job.lastFiredAt) >= due ? null : new Date(due);
+    }
+    const cron = parseCron(job.cron);
+    if (!cron)
+        return null;
+    const start = new Date(now);
+    start.setUTCSeconds(0, 0);
+    const floor = Math.max(job.lastFiredAt ? Date.parse(job.lastFiredAt) : Date.parse(job.createdAt), start.getTime() - LOOKBACK_MINUTES * 60_000);
+    for (let t = start.getTime(); t > floor; t -= 60_000) {
+        const at = new Date(t);
+        if (cronMatches(cron, at, job.timezone))
+            return at;
+    }
+    return null;
+}
+/** The next time this job is due after `now`, within a week; null otherwise. */
+export function nextDueFire(job, now) {
+    const interval = rateIntervalMs(job.cron);
+    if (interval) {
+        const origin = Date.parse(job.createdAt);
+        const steps = Math.max(0, Math.floor((now.getTime() - origin) / interval)) + 1;
+        return new Date(origin + steps * interval);
+    }
+    const cron = parseCron(job.cron);
+    if (!cron)
+        return null;
+    const start = new Date(now);
+    start.setUTCSeconds(0, 0);
+    for (let i = 1; i <= LOOKBACK_MINUTES; i += 1) {
+        const at = new Date(start.getTime() + i * 60_000);
+        if (cronMatches(cron, at, job.timezone))
+            return at;
+    }
+    return null;
+}
+// ─── The job list (what `hq bot jobs` reads and writes) ──────────────────────
+function toJobRecord(job, now = new Date()) {
+    const next = nextDueFire(job, now);
+    return {
+        jobId: job.jobId,
+        prompt: job.prompt,
+        status: "active",
+        schedule: { kind: "recurring", cron: job.cron, timezone: job.timezone },
+        ...(job.context ? { context: job.context } : {}),
+        createdAt: job.createdAt,
+        ...(next ? { nextRunAt: next.toISOString() } : {}),
+        ...(job.lastRunAt ? { lastRunAt: job.lastRunAt } : {}),
+        ...(job.lastStatus ? { lastStatus: job.lastStatus } : {}),
+        ...(job.runCount ? { runCount: job.runCount } : {}),
+    };
+}
+export function addLocalJob(dir, input, now = new Date()) {
+    if (!isRunnableSchedule(input.cron))
+        throw new Error(`"${input.cron}" is not a schedule this bot can run.`);
+    const job = {
+        jobId: `job_${randomUUID().replace(/-/g, "").slice(0, 20)}`,
+        prompt: input.prompt,
+        cron: input.cron,
+        timezone: input.timezone,
+        ...(input.context ? { context: input.context } : {}),
+        createdAt: now.toISOString(),
+    };
+    withJobsLock(dir, () => writeLocalJobs(dir, [...readLocalJobs(dir), job]));
+    return job;
+}
+/** Remove a job. Returns false when the bot has no job with that id. */
+function removeLocalJob(dir, jobId) {
+    return withJobsLock(dir, () => {
+        const jobs = readLocalJobs(dir);
+        const next = jobs.filter((job) => job.jobId !== jobId);
+        if (next.length === jobs.length)
+            return false;
+        writeLocalJobs(dir, next);
+        return true;
+    });
+}
+// ─── Firing ──────────────────────────────────────────────────────────────────
+/**
+ * Hand over every job that is due now. Each fire is recorded (lastFiredAt and
+ * inFlight) before its inbox item is returned.
+ */
+const lastCheckedMinute = new Map();
+/** Forget the once-per-minute check (tests, and a bot restarted in-process). */
+export function resetLocalJobChecks() {
+    lastCheckedMinute.clear();
+}
+export function takeDueLocalJobRuns(dir, now = new Date()) {
+    // Schedules have minute resolution and the inbox is polled every few
+    // seconds: look at the jobs once per minute.
+    const minute = Math.floor(now.getTime() / 60_000);
+    if (lastCheckedMinute.get(dir) === minute)
+        return [];
+    lastCheckedMinute.set(dir, minute);
+    return withJobsLock(dir, () => {
+        const jobs = readLocalJobs(dir);
+        if (jobs.length === 0)
+            return [];
+        const items = [];
+        let changed = false;
+        const next = jobs.map((job) => {
+            if (job.inFlight && now.getTime() - Date.parse(job.inFlight.since) < IN_FLIGHT_RELEASE_MS)
+                return job;
+            const due = latestDueFire(job, now);
+            if (!due) {
+                if (job.inFlight) {
+                    changed = true;
+                    return { ...job, inFlight: undefined };
+                }
+                return job;
+            }
+            const firedAt = due.toISOString();
+            const messageId = `${LOCAL_JOB_MESSAGE_PREFIX}${job.jobId}-${due.getTime()}`;
+            items.push({
+                messageId,
+                channel: "job",
+                jobId: job.jobId,
+                prompt: job.prompt,
+                ...(job.context ? { context: job.context } : {}),
+                firedAt,
+                staleAfter: new Date(due.getTime() + STALE_AFTER_MS).toISOString(),
+                receivedAt: now.toISOString(),
+            });
+            changed = true;
+            return { ...job, lastFiredAt: firedAt, inFlight: { messageId, since: now.toISOString() } };
+        });
+        if (changed)
+            writeLocalJobs(dir, next);
+        return items;
+    });
+}
+function isLocalJobMessage(messageId) {
+    return messageId.startsWith(LOCAL_JOB_MESSAGE_PREFIX);
+}
+/** Record how a local run finished and release the job for its next fire. */
+function finishLocalJobRun(dir, jobId, messageId, completion, now = new Date()) {
+    withJobsLock(dir, () => {
+        const jobs = readLocalJobs(dir);
+        let changed = false;
+        const next = jobs.map((job) => {
+            if (job.jobId !== jobId)
+                return job;
+            changed = true;
+            const releases = !job.inFlight || job.inFlight.messageId === messageId;
+            return {
+                ...job,
+                ...(releases ? { inFlight: undefined } : {}),
+                lastRunAt: now.toISOString(),
+                lastStatus: completion.status,
+                runCount: (job.runCount ?? 0) + (completion.status === "succeeded" || completion.status === "failed" ? 1 : 0),
+            };
+        });
+        if (changed)
+            writeLocalJobs(dir, next);
+    });
+}
+/**
+ * The bot's cloud client, with its scheduled runs answered on this computer:
+ * due local jobs join the inbox, and their ack and completion are recorded
+ * locally instead of being sent to the cloud.
+ */
+export function withLocalJobs(api, dir, clock = () => new Date()) {
+    const local = Object.create(api);
+    local.pullInbox = async (agentUid) => {
+        // Cloud first: if that call fails, nothing local has been taken yet, so
+        // no due run is recorded as fired and then dropped.
+        const cloud = await api.pullInbox(agentUid);
+        return [...cloud, ...takeDueLocalJobRuns(dir, clock())];
+    };
+    local.ackInbox = async (agentUid, messageId) => {
+        if (isLocalJobMessage(messageId))
+            return;
+        await api.ackInbox(agentUid, messageId);
+    };
+    local.completeJobRun = async (agentUid, jobId, messageId, completion) => {
+        if (isLocalJobMessage(messageId)) {
+            finishLocalJobRun(dir, jobId, messageId, completion, clock());
+            return;
+        }
+        await api.completeJobRun(agentUid, jobId, messageId, completion);
+    };
+    return local;
+}
+/** The most jobs one bot may hold (the same cap the cloud uses). */
+const MAX_LOCAL_JOBS = 25;
+/**
+ * `hq bot jobs` against the bot's own folder: the same three calls the cloud
+ * client offers, answered from `jobs.json`.
+ */
+export function localJobsClient(dir, clock = () => new Date()) {
+    return {
+        async listJobs() {
+            const now = clock();
+            return readLocalJobs(dir).map((job) => toJobRecord(job, now));
+        },
+        async createJob(_agentUid, input) {
+            if (input.schedule.kind !== "recurring") {
+                throw new BotApiError(400, "local jobs", "JOB_VALIDATION", "A local bot runs recurring jobs only.");
+            }
+            if (readLocalJobs(dir).length >= MAX_LOCAL_JOBS) {
+                throw new BotApiError(409, "local jobs", "JOB_QUOTA_EXCEEDED", `at most ${MAX_LOCAL_JOBS} jobs`);
+            }
+            const job = addLocalJob(dir, { prompt: input.prompt, cron: input.schedule.cron, timezone: input.schedule.timezone, ...(input.context ? { context: input.context } : {}) }, clock());
+            return toJobRecord(job, clock());
+        },
+        async cancelJob(_agentUid, jobId) {
+            if (!removeLocalJob(dir, jobId)) {
+                throw new BotApiError(404, "local jobs", "JOB_NOT_FOUND", `Job '${jobId}' not found`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=local-jobs.js.map