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

package/dist/commands/bot-jobs.js

@@ -1,454 +0,0 @@
-/**
- * `hq bot jobs` — a local bot's recurring scheduled work.
- *
- *   hq bot jobs <botName>                                  list
- *   hq bot jobs <botName> --add "<what to do>" --every "<plain english>"
- *   hq bot jobs <botName> --add "<what to do>" --cron "0 9 * * 1-5"
- *   hq bot jobs <botName> --rm <jobId>
- *
- * The schedule lives in the cloud, never on this computer: hq-pro-agents holds
- * the job and fires it on an EventBridge schedule, and the bot's inbox loop
- * runs the fired run (see lib/bot/job-run.ts). Nothing here writes a crontab,
- * a launchd plist, or a systemd unit — by rule.
- *
- * The routes are self-only per agent, so every call uses the BOT's own machine
- * identity — the same credential path its turns use — not the owner's session.
- */
-import chalk from "chalk";
-import { execFileSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { localJobsClient } from "../lib/bot/local-jobs.js";
-import { BotApiError } from "../lib/bot/api.js";
-import { effectiveBotKind } from "../lib/bot/config.js";
-// ─── Schedule translation ────────────────────────────────────────────────────
-/** Mirrors hq-pro-agents `MIN_RECURRING_INTERVAL_SECONDS`. */
-export const MIN_RECURRING_INTERVAL_SECONDS = 5 * 60;
-/** Mirrors hq-pro-agents `DEFAULT_MAX_ACTIVE_JOBS_PER_AGENT`. */
-export const MAX_ACTIVE_JOBS_PER_AGENT = 25;
-/** Mirrors hq-pro-agents `MAX_PROMPT_BYTES`. */
-export const MAX_PROMPT_BYTES = 16 * 1024;
-export class BotJobsError extends Error {
-    expected = true;
-}
-function refuse(message) {
-    throw new BotJobsError(message);
-}
-/** The machine's own IANA zone, so "9am" means 9am where the owner lives. */
-export function machineTimezone() {
-    try {
-        return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
-    }
-    catch {
-        return "UTC";
-    }
-}
-/**
- * Standard 5-field cron → the EventBridge form the cloud stores.
- *
- * EventBridge cron has SIX fields (a trailing year), numbers its days of week
- * 1–7 with SUNDAY = 1 (standard cron uses 0–6 with SUNDAY = 0), and refuses
- * `*` in BOTH the day-of-month and day-of-week fields — exactly one must be
- * `?`. An expression that is already `cron(...)` or `rate(...)` is passed
- * through untouched.
- */
-export function toEventBridgeCron(expr) {
-    const trimmed = expr.trim();
-    // An explicit cron(...) / rate(...) is the caller saying "this is already the
-    // cloud's own syntax" — passed through untranslated, on purpose.
-    if (/^(cron|rate)\s*\(/i.test(trimmed))
-        return trimmed;
-    const fields = trimmed.split(/\s+/).filter(Boolean);
-    if (fields.length === 6) {
-        // Six BARE fields are ambiguous: EventBridge's sixth field is a trailing
-        // year, Quartz's first is leading seconds. Guessing wrong silently moves
-        // every run. Make the caller say which they mean.
-        refuse(`"${trimmed}" has six fields, and I can't tell whether that is an EventBridge expression ` +
-            `(minute hour day-of-month month day-of-week year) or a Quartz one (leading seconds) — ` +
-            `reading it the wrong way would schedule the job at the wrong time. Pass five fields ` +
-            `("0 9 * * 1-5"), or wrap it yourself as cron(...) if it is already an EventBridge expression.`);
-    }
-    if (fields.length !== 5) {
-        refuse(`"${trimmed}" is not a cron expression. A cron expression has five fields: ` +
-            `minute hour day-of-month month day-of-week (for example "0 9 * * 1-5").`);
-    }
-    const [minute, hour, month] = [fields[0], fields[1], fields[3]];
-    let dayOfMonth = fields[2];
-    let dayOfWeek = fields[4];
-    if (dayOfWeek === "*" || dayOfWeek === "?") {
-        dayOfWeek = "?";
-        if (dayOfMonth === "?")
-            dayOfMonth = "*";
-    }
-    else {
-        dayOfWeek = shiftDayOfWeek(dayOfWeek);
-        if (dayOfMonth === "*")
-            dayOfMonth = "?";
-    }
-    return `cron(${minute} ${hour} ${dayOfMonth} ${month} ${dayOfWeek} *)`;
-}
-/**
- * Standard 0–6 (SUN=0, and 7 also SUN) → EventBridge 1–7 (SUN=1).
- *
- * Mapped per TERM, not per digit. Shifting digits individually turned a range
- * that wraps past Sunday — "6-0" (Sat–Sun), "5-1" (Fri–Mon) — into "7-1" /
- * "6-2": reversed or plain wrong, and silently so. Such a range is refused with
- * the list form that does work.
- */
-function shiftDayOfWeek(field) {
-    return field
-        .split(",")
-        .map((term) => shiftDayOfWeekTerm(term.trim()))
-        .join(",");
-}
-function shiftDay(n) {
-    return (n % 7) + 1;
-}
-function shiftDayOfWeekTerm(term) {
-    const step = term.match(/^(.+)\/(\d+)$/);
-    if (step)
-        return `${shiftDayOfWeekTerm(step[1])}/${step[2]}`;
-    const range = term.match(/^(\d+)-(\d+)$/);
-    if (range) {
-        const from = shiftDay(Number(range[1]));
-        const to = shiftDay(Number(range[2]));
-        if (from > to) {
-            const days = [];
-            for (let d = Number(range[1]);; d = (d + 1) % 7) {
-                days.push(d);
-                if (d === Number(range[2]) % 7)
-                    break;
-                if (days.length > 7)
-                    break;
-            }
-            refuse(`"${term}" is a day-of-week range that wraps past Sunday, which the schedule cannot express. ` +
-                `List the days instead, for example "${days.join(",")}".`);
-        }
-        return `${from}-${to}`;
-    }
-    if (/^\d+$/.test(term))
-        return String(shiftDay(Number(term)));
-    // Day NAMES (MON, MON-FRI) mean the same thing in both syntaxes.
-    return term;
-}
-/**
- * The smallest gap a recurring expression can produce, in seconds, or null
- * when it is not a recognised rate()/cron() form. Mirrors hq-pro-agents
- * `recurringIntervalSeconds` so the CLI can refuse a sub-floor schedule with
- * the server's own reason instead of a round-trip and a raw 400.
- */
-export function recurringIntervalSeconds(expr) {
-    const rate = expr.trim().match(/^rate\(\s*(\d+)\s+(minute|minutes|hour|hours|day|days)\s*\)$/i);
-    if (rate) {
-        const n = Number(rate[1]);
-        if (!Number.isFinite(n) || n <= 0)
-            return null;
-        const unit = rate[2].toLowerCase();
-        if (unit.startsWith("minute"))
-            return n * 60;
-        if (unit.startsWith("hour"))
-            return n * 3600;
-        return n * 86400;
-    }
-    const cron = expr.trim().match(/^cron\(\s*(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s*\)$/i);
-    if (!cron)
-        return null;
-    const minute = cron[1];
-    if (minute === "*" || minute === "?")
-        return 60;
-    // EventBridge also writes a step as "start/every" ("0/10" = every 10 minutes
-    // from :00), which the rate()-style regex alone rejected as unparseable.
-    const step = minute.match(/^(?:\*|\d+|\d+-\d+)\/(\d+)$/);
-    if (step) {
-        const n = Number(step[1]);
-        return Number.isFinite(n) && n > 0 ? n * 60 : null;
-    }
-    if (/^\d+-\d+$/.test(minute))
-        return 60;
-    if (/^\d+(,\d+)*$/.test(minute)) {
-        const values = minute.split(",").map(Number).sort((a, b) => a - b);
-        if (values.some((v) => !Number.isFinite(v) || v < 0 || v > 59))
-            return null;
-        if (values.length === 1)
-            return 3600;
-        let smallest = 60 - values[values.length - 1] + values[0]; // wrap to the next hour
-        for (let i = 1; i < values.length; i += 1)
-            smallest = Math.min(smallest, values[i] - values[i - 1]);
-        return smallest * 60;
-    }
-    return null;
-}
-/** Refuse a schedule the cloud would refuse, with the cloud's own reason. */
-export function assertScheduleWithinFloor(expr) {
-    const interval = recurringIntervalSeconds(expr);
-    if (interval === null) {
-        refuse("schedule.cron must be a valid rate(...) or cron(...) expression");
-    }
-    if (interval < MIN_RECURRING_INTERVAL_SECONDS) {
-        refuse(`recurring jobs may not fire more often than every ${MIN_RECURRING_INTERVAL_SECONDS / 60} minutes`);
-    }
-}
-export function scheduleHelperPath(hqRoot) {
-    return path.join(hqRoot, "core", "scripts", "jobs-schedule-parse.sh");
-}
-/**
- * Plain English → cron, using HQ's OWN helper (`core/scripts/jobs-schedule-parse.sh`)
- * so `hq bot jobs --every` and the `/schedule` command agree on what "every
- * weekday morning" means. When the helper is not in this HQ root, the caller is
- * told to pass `--cron` instead rather than getting a second, divergent parser.
- */
-export function parseScheduleText(text, opts) {
-    const helper = scheduleHelperPath(opts.hqRoot);
-    const exists = opts.exists ?? ((p) => fs.existsSync(p));
-    if (!exists(helper)) {
-        refuse(`I can't turn "${text}" into a schedule: HQ's schedule helper is not in this HQ folder ` +
-            `(${helper}). Pass the schedule directly instead, for example --cron "0 9 * * 1-5".`);
-    }
-    const exec = opts.exec ?? execFileSync;
-    let raw;
-    try {
-        raw = String(exec("bash", [helper, "--tz", opts.timezone, text], { encoding: "utf8" })).trim();
-    }
-    catch (err) {
-        const out = err.stdout;
-        raw = typeof out === "string" ? out.trim() : "";
-        if (!raw) {
-            refuse(`I couldn't work out a schedule from "${text}". Pass --cron "<expression>" instead.`);
-        }
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        refuse(`I couldn't work out a schedule from "${text}". Pass --cron "<expression>" instead.`);
-    }
-    if (!parsed.ok || !parsed.cron) {
-        refuse(`I couldn't work out a schedule from "${text}"${parsed.error ? ` (${parsed.error})` : ""}. Pass --cron "<expression>" instead.`);
-    }
-    return {
-        cron: parsed.cron,
-        timezone: parsed.timezone?.trim() || opts.timezone,
-        ...(parsed.human?.trim() ? { human: parsed.human.trim() } : {}),
-    };
-}
-/** The create body the cloud expects, with the client-side limits enforced first. */
-export function buildCreateJobBody(input) {
-    const prompt = input.prompt.trim();
-    if (!prompt)
-        refuse("Say what the job should do: --add \"<what to do>\".");
-    if (Buffer.byteLength(prompt, "utf-8") > MAX_PROMPT_BYTES) {
-        refuse(`That instruction is too long (${Buffer.byteLength(prompt, "utf-8")} bytes; the limit is ${MAX_PROMPT_BYTES}). ` +
-            `Shorten it, or put the detail in a file the bot reads when the job runs.`);
-    }
-    const cron = toEventBridgeCron(input.cron);
-    assertScheduleWithinFloor(cron);
-    return {
-        prompt,
-        ...(input.context ? { context: input.context } : {}),
-        schedule: { kind: "recurring", cron, timezone: input.timezone },
-    };
-}
-// ─── Reading jobs back ───────────────────────────────────────────────────────
-/** A schedule in plain words, falling back to the raw expression. */
-export function describeSchedule(job) {
-    const schedule = job.schedule;
-    if (!schedule)
-        return "on a schedule";
-    if (schedule.kind === "once")
-        return `once, at ${schedule.at ?? "an unknown time"}${schedule.timezone ? ` (${schedule.timezone})` : ""}`;
-    const expr = schedule.cron ?? "";
-    const zone = schedule.timezone ? ` (${schedule.timezone})` : "";
-    const words = cronInWords(expr);
-    return words ? `${words}${zone}` : `${expr}${zone}`;
-}
-const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
-/** A small humaniser for the shapes `--every` actually produces. */
-export function cronInWords(expr) {
-    const rate = expr.trim().match(/^rate\(\s*(\d+)\s+(minute|minutes|hour|hours|day|days)\s*\)$/i);
-    if (rate)
-        return `every ${rate[1]} ${rate[2].toLowerCase()}`;
-    const cron = expr.trim().match(/^cron\(\s*(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+\S+\s*\)$/i);
-    if (!cron)
-        return null;
-    const [minute, hour, dayOfMonth, month, dayOfWeek] = [cron[1], cron[2], cron[3], cron[4], cron[5]];
-    const step = minute.match(/^(?:\*|\d+)\/(\d+)$/);
-    if (step && hour === "*")
-        return `every ${step[1]} minutes`;
-    const hourStep = hour.match(/^(?:\*|\d+)\/(\d+)$/);
-    if (/^\d+$/.test(minute) && hourStep)
-        return `every ${hourStep[1]} hours`;
-    if (!/^\d+$/.test(minute) || !/^\d+$/.test(hour))
-        return null;
-    const at = `${String(Number(hour)).padStart(2, "0")}:${String(Number(minute)).padStart(2, "0")}`;
-    if (month !== "*")
-        return null;
-    if (dayOfWeek === "?" || dayOfWeek === "*") {
-        if (dayOfMonth === "*" || dayOfMonth === "?")
-            return `every day at ${at}`;
-        if (/^\d+$/.test(dayOfMonth))
-            return `on day ${dayOfMonth} of each month at ${at}`;
-        return null;
-    }
-    // EventBridge days of week: SUNDAY = 1.
-    if (dayOfWeek === "2-6")
-        return `every weekday at ${at}`;
-    if (/^\d$/.test(dayOfWeek))
-        return `every ${DAY_NAMES[(Number(dayOfWeek) + 6) % 7]} at ${at}`;
-    if (/^\d(,\d)+$/.test(dayOfWeek)) {
-        const days = dayOfWeek.split(",").map((d) => DAY_NAMES[(Number(d) + 6) % 7]);
-        return `every ${days.join(", ")} at ${at}`;
-    }
-    return null;
-}
-/** "never run yet" / "succeeded 2026-09-15 09:00 UTC". */
-export function describeLastRun(job) {
-    if (!job.lastStatus && !job.lastRunAt)
-        return "not run yet";
-    const when = job.lastRunAt ? ` ${job.lastRunAt.slice(0, 16).replace("T", " ")} UTC` : "";
-    return `${job.lastStatus ?? "ran"}${when}`;
-}
-export function formatJobsList(botName, jobs) {
-    if (jobs.length === 0) {
-        return `${botName} has no scheduled jobs. Add one with: hq bot jobs ${botName} --add "<what to do>" --every "<when>"`;
-    }
-    const lines = [`${botName} has ${jobs.length} scheduled job${jobs.length === 1 ? "" : "s"}:`];
-    for (const job of jobs) {
-        lines.push("");
-        lines.push(`  ${chalk.bold(job.jobId)}${job.status && job.status !== "active" ? chalk.yellow(` (${job.status})`) : ""}`);
-        lines.push(`    ${job.prompt.replace(/\s+/g, " ").slice(0, 120)}`);
-        lines.push(`    runs ${describeSchedule(job)}`);
-        lines.push(`    next run: ${job.nextRunAt ? `${job.nextRunAt.slice(0, 16).replace("T", " ")} UTC` : "not scheduled yet"}`);
-        lines.push(`    last run: ${describeLastRun(job)}`);
-    }
-    return lines.join("\n");
-}
-// ─── Errors a person can act on ──────────────────────────────────────────────
-/**
- * Turn a jobs-route failure into one plain line.
- *
- * Personal bots are refused by the cloud today: their JWT carries the owner's
- * `per_…` company claim and the jobs routes require a `cmp_…`, so the fail-closed
- * guard answers 403 `CROSS_AGENT_JOB` (hq-pro-agents jobs/errors.ts
- * `CrossAgentJobError`). That server fix is a separate change; until it lands the
- * refusal must read as "not available yet for this kind of bot", not as a raw 403.
- * Once the server accepts personal bots the refusal simply stops happening — no
- * client change needed.
- *
- * ONLY that exact code is rewritten. Every other 403, and every 404, keeps its
- * real message: masking them would hide a genuinely missing job or a different
- * permission problem behind copy about the wrong thing.
- */
-export function jobsErrorMessage(err, ctx) {
-    if (!(err instanceof BotApiError))
-        return err instanceof Error ? err.message : String(err);
-    if (ctx.kind === "personal" && err.status === 403 && err.code === "CROSS_AGENT_JOB") {
-        return (`Scheduled jobs aren't available for personal bots yet — the cloud only accepts them from ` +
-            `company bots. Create ${ctx.botName} as a company bot (hq bot create ${ctx.botName} --kind company ` +
-            `--company <slug>) to schedule work, or wait for personal-bot support.`);
-    }
-    if (err.status === 401)
-        return "Not authenticated — the bot's credentials were refused. Try: hq bot restart " + ctx.botName;
-    if (err.code === "JOB_QUOTA_EXCEEDED" || err.status === 409) {
-        return (`${ctx.botName} already has the maximum of ${MAX_ACTIVE_JOBS_PER_AGENT} scheduled jobs. ` +
-            `Remove one first: hq bot jobs ${ctx.botName} --rm <jobId>`);
-    }
-    if (err.status === 404 && err.code === "JOB_NOT_FOUND")
-        return `${ctx.botName} has no job with that id.`;
-    if (err.code === "INVALID_SCHEDULE" || err.code === "JOB_VALIDATION") {
-        return err.message.replace(/^HQ API [^:]+: /, "");
-    }
-    return err.message;
-}
-export async function runBotJobs(nameArg, opts, deps) {
-    const { name, dir, config } = deps.requireBot(nameArg);
-    const kind = effectiveBotKind(config);
-    const out = deps.out ?? ((line) => console.log(line));
-    const ctx = { botName: name, kind };
-    // The schedule lives with the bot: this bot runs on this computer, so its
-    // jobs live in its folder and it fires them itself.
-    let client;
-    const jobsApi = async () => {
-        if (client)
-            return client;
-        client = deps.apiFor ? deps.apiFor(dir) : localJobsClient(dir);
-        return client;
-    };
-    if (opts.add !== undefined && opts.rm !== undefined) {
-        refuse("Add a job or remove one, not both in the same command.");
-    }
-    if (opts.rm !== undefined) {
-        const jobId = opts.rm.trim();
-        if (!jobId)
-            refuse("Say which job to remove: --rm <jobId>");
-        const api = await jobsApi();
-        try {
-            await api.cancelJob(config.agentUid, jobId);
-        }
-        catch (err) {
-            refuse(jobsErrorMessage(err, ctx));
-        }
-        out(opts.json ? JSON.stringify({ ok: true, removed: jobId }, null, 2) : chalk.green(`Removed ${jobId}. ${name} will not run it again.`));
-        return;
-    }
-    if (opts.add !== undefined) {
-        if (!opts.every && !opts.cron) {
-            refuse(`Say how often it should run: --every "every weekday at 9am", or --cron "0 9 * * 1-5".`);
-        }
-        if (opts.every && opts.cron)
-            refuse("Use --every or --cron, not both.");
-        const timezone = opts.tz?.trim() || (deps.timezone ?? machineTimezone)();
-        const parse = deps.parseSchedule ?? parseScheduleText;
-        const schedule = opts.every
-            ? parse(opts.every, { hqRoot: config.hqRoot, timezone })
-            : { cron: opts.cron, timezone };
-        const body = buildCreateJobBody({ prompt: opts.add, cron: schedule.cron, timezone: schedule.timezone });
-        const api = await jobsApi();
-        let created;
-        try {
-            created = await api.createJob(config.agentUid, body);
-        }
-        catch (err) {
-            refuse(jobsErrorMessage(err, ctx));
-        }
-        if (opts.json) {
-            out(JSON.stringify({ ok: true, job: created }, null, 2));
-            return;
-        }
-        const words = ("human" in schedule && schedule.human) || describeSchedule(created);
-        out(chalk.green(`Scheduled ${created.jobId}: ${name} will ${body.prompt.replace(/\s+/g, " ").slice(0, 120)} — ${words}.`));
-        out(chalk.gray(`It runs on this computer while ${name} is running. If a run is due while the computer is asleep or ` +
-            `${name} is stopped, it runs once, as a catch-up, the next time ${name} is running.`));
-        return;
-    }
-    let jobs;
-    const api = await jobsApi();
-    try {
-        jobs = await api.listJobs(config.agentUid);
-    }
-    catch (err) {
-        refuse(jobsErrorMessage(err, ctx));
-    }
-    out(opts.json ? JSON.stringify(jobs, null, 2) : formatJobsList(name, jobs));
-}
-export function registerBotJobsCommand(bot, deps) {
-    bot
-        .command("jobs <name>")
-        .description("Show, schedule, or remove a bot's recurring jobs (the schedule runs in the cloud, not on this computer)")
-        .option("--add <what>", "Schedule new work, in plain language")
-        .option("--every <when>", 'How often, in plain language (e.g. "every weekday at 9am")')
-        .option("--cron <expr>", 'How often, as a cron expression (e.g. "0 9 * * 1-5")')
-        .option("--tz <zone>", "IANA timezone for the schedule (default: this computer's)")
-        .option("--rm <jobId>", "Remove a scheduled job")
-        .option("--json", "Print machine-readable JSON")
-        .action(async (name, opts) => {
-        try {
-            await runBotJobs(name, opts, deps);
-        }
-        catch (err) {
-            console.error(chalk.red(err instanceof Error ? err.message : String(err)));
-            process.exit(1);
-        }
-    });
-}
-//# sourceMappingURL=bot-jobs.js.map