@indigoai-us/hq-cli 5.135.0 → 5.137.0

package/dist/commands/bot-jobs.js

@@ -0,0 +1,445 @@
+/**
+ * `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 { BotApi, 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 api = deps.apiFor
+        ? deps.apiFor(dir)
+        : new BotApi({ token: deps.botTokenSupplier(dir) });
+    const ctx = { botName: name, kind };
+    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>");
+        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 });
+        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("If this computer is asleep or 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."));
+        return;
+    }
+    let jobs;
+    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

package/dist/commands/bot.js

@@ -18,6 +18,7 @@ import { hasPromotionHold, promotionHoldSummary } from "../lib/bot/promotion-hol
  *   hq bot daemon install|uninstall|status <name>
  *   hq bot rm <name> [--yes]
  *   hq bot intro <name>                   (re-send the introduction DM)
+ *   hq bot jobs <name> [--add "…" --every "…"] [--rm <jobId>] [--json]
  *
  * The bot's own identity (agt_) authenticates with 0600 machine creds under
  * ~/.hq/bots/<name>/; the OWNER's cached session is used only for create,
@@ -26,6 +27,7 @@ import { hasPromotionHold, promotionHoldSummary } from "../lib/bot/promotion-hol
 import { promoteLocalBot } from "../lib/bot/promote.js";
 import { addBotToCompanies, describeCompanyFailures, removeBotFromCompanies } from "./bot-companies.js";
 import { registerBotContinuityCommand } from "./bot-continuity.js";
+import { registerBotJobsCommand } from "./bot-jobs.js";
 import chalk from "chalk";
 import { execFileSync, spawn } from "node:child_process";
 import * as fs from "node:fs";
@@ -1543,6 +1545,7 @@ export function registerBotCommand(program) {
         .command("bot")
         .description("Personal local bots that run on this computer with your own model login");
     registerBotContinuityCommand(bot);
+    registerBotJobsCommand(bot, { requireBot, botTokenSupplier });
     bot.command("promote <name>")
         .description("Move this local bot to cloud compute, preserving its identity and private context")
         .requiredOption("--company <uid>", "Destination company identity")

package/dist/commands/channels.d.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { type ChannelSummary } from "./dm.js";
+import { type CallerIdentity, type ChannelMember, type ChannelSummary } from "./dm.js";
 /**
  * Human label for a channel row. Named channels (personal/company) show their
  * name + a `hq dm <slug>` hint; unnamed group DMs are identified by their
@@ -12,5 +12,13 @@ export declare function describeChannel(c: ChannelSummary): string;
  * fetched list) so the formatting is unit-testable without network/auth.
  */
 export declare function formatChannelsList(channels: ChannelSummary[]): string;
+/**
+ * Remove the caller from a channel roster before it is used for mentions.
+ * Machine principals identify themselves with the JWT uid; human sessions can
+ * also match the roster's email when the uid claim is absent.
+ */
+export declare function excludeCallerFromChannelMembers(members: ChannelMember[], caller: CallerIdentity): ChannelMember[];
+/** Render the roster as either dm-bind's tab-separated format or JSON. */
+export declare function formatChannelMembers(members: ChannelMember[], json: boolean): string;
 export declare function registerChannelsCommand(program: Command): void;
 //# sourceMappingURL=channels.d.ts.map

package/dist/commands/channels.js

@@ -1,7 +1,7 @@
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
-import { channelSlug } from "./dm.js";
+import { callerFromToken, channelSlug, fetchChannelMembers, fetchChannels, matchChannelsByName, } from "./dm.js";
 /**
  * Human label for a channel row. Named channels (personal/company) show their
  * name + a `hq dm <slug>` hint; unnamed group DMs are identified by their
@@ -42,6 +42,31 @@ export function formatChannelsList(channels) {
     }
     return lines.join("\n");
 }
+/**
+ * Remove the caller from a channel roster before it is used for mentions.
+ * Machine principals identify themselves with the JWT uid; human sessions can
+ * also match the roster's email when the uid claim is absent.
+ */
+export function excludeCallerFromChannelMembers(members, caller) {
+    return members.filter((member) => {
+        if (caller.personUid && member.personUid === caller.personUid)
+            return false;
+        if (caller.email &&
+            member.email &&
+            member.email.trim().toLowerCase() === caller.email) {
+            return false;
+        }
+        return true;
+    });
+}
+/** Render the roster as either dm-bind's tab-separated format or JSON. */
+export function formatChannelMembers(members, json) {
+    if (json)
+        return JSON.stringify(members);
+    return members
+        .map((member) => `${member.displayName ?? ""}\t${member.personUid}`)
+        .join("\n");
+}
 async function runChannelsList() {
     try {
         const token = await ensureCognitoToken();
@@ -64,6 +89,29 @@ async function runChannelsList() {
         process.exit(1);
     }
 }
+async function runChannelsMembers(channelName, opts) {
+    try {
+        const token = await ensureCognitoToken();
+        const channels = await fetchChannels(token);
+        const matches = matchChannelsByName(channels, channelName);
+        if (matches.length === 0) {
+            console.error(chalk.red(`No channel named '${channelName}' — run \`hq channels\` to see your channels.`));
+            process.exit(1);
+        }
+        if (matches.length > 1) {
+            const scopes = matches.map((match) => match.scope ?? "?").join(", ");
+            console.error(chalk.red(`'${channelName}' matches ${matches.length} channels (${scopes}) — this is ambiguous.`));
+            process.exit(1);
+        }
+        const members = await fetchChannelMembers(token, matches[0].channelId);
+        const visibleMembers = excludeCallerFromChannelMembers(members, callerFromToken(token));
+        console.log(formatChannelMembers(visibleMembers, opts.json === true));
+    }
+    catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
 export function registerChannelsCommand(program) {
     const channels = program
         .command("channels")
@@ -74,5 +122,12 @@ export function registerChannelsCommand(program) {
         .action(async () => {
         await runChannelsList();
     });
+    channels
+        .command("members <channel>")
+        .description("Print the members of one of your DM channels.")
+        .option("--json", "Output the member array as JSON.")
+        .action(async (channelName, opts) => {
+        await runChannelsMembers(channelName, opts);
+    });
 }
 //# sourceMappingURL=channels.js.map

package/dist/commands/dm.d.ts

@@ -192,6 +192,12 @@ export declare function buildConnectionActionBody(identifier: string, matched: C
 };
 /** Fetch the caller's channels (GET /v1/notify/channels). */
 export declare function fetchChannels(token: string): Promise<ChannelSummary[]>;
+/**
+ * Fetch a channel's roster (GET /v1/notify/channels/{id}/members). Any member
+ * who can read the channel may read its members, so this is the same gate the
+ * post itself passes. Used to resolve `@name` mentions into participant uids.
+ */
+export declare function fetchChannelMembers(token: string, channelId: string): Promise<ChannelMember[]>;
 /** One incoming DM as returned by GET /v1/notify/inbox. */
 export interface DmInboxEvent {
     eventId: string;

package/dist/commands/dm.js

@@ -503,7 +503,7 @@ export async function fetchChannels(token) {
  * who can read the channel may read its members, so this is the same gate the
  * post itself passes. Used to resolve `@name` mentions into participant uids.
  */
-async function fetchChannelMembers(token, channelId) {
+export async function fetchChannelMembers(token, channelId) {
     const res = await vaultApiFetch({
         token,
         path: `/v1/notify/channels/${encodeURIComponent(channelId)}/members`,

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

@@ -29,6 +29,59 @@ export interface InboxItem {
     mentionedMe?: boolean;
     memberCount?: number;
     senderTrust?: "member";
+    /**
+     * Scheduled-job run items only (channel === "job"). The cloud fires the job
+     * on its own schedule and writes this durable item; the run carries its own
+     * prompt instead of `text` (server: hq-pro-agents jobs/run-record.ts
+     * `JobRunInboxItem`).
+     */
+    jobId?: string;
+    prompt?: string;
+    context?: Record<string, unknown> | string;
+    script?: string;
+    firedAt?: string;
+    staleAfter?: string;
+    requestId?: string;
+}
+/** The terminal outcome a box reports for one fired run. */
+export type JobRunStatus = "succeeded" | "failed" | "skipped-precondition";
+export interface JobRunCompletion {
+    status: JobRunStatus;
+    output?: string;
+    disposition?: string;
+}
+/** A job record as the cloud returns it (hq-pro-agents jobs/schema.ts `JobRecord`). */
+export interface BotJobRecord {
+    jobId: string;
+    prompt: string;
+    status?: string;
+    schedule?: {
+        kind?: string;
+        cron?: string;
+        at?: string;
+        timezone?: string;
+    };
+    context?: Record<string, unknown>;
+    script?: string;
+    createdAt?: string;
+    nextRunAt?: string;
+    lastRunAt?: string;
+    lastStatus?: string;
+    runCount?: number;
+}
+export interface CreateJobInput {
+    prompt: string;
+    context?: Record<string, unknown>;
+    script?: string;
+    schedule: {
+        kind: "once";
+        at: string;
+        timezone: string;
+    } | {
+        kind: "recurring";
+        cron: string;
+        timezone: string;
+    };
 }
 /** @deprecated use InboxItem */
 export type DmInboxItem = InboxItem;
@@ -132,6 +185,19 @@ export declare class BotApi {
     pullInbox(agentUid: string): Promise<InboxItem[]>;
     /** POST /v1/agents/{uid}/inbox/{messageId}/ack */
     ackInbox(agentUid: string, messageId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    completeJobRun(agentUid: string, jobId: string, messageId: string, completion: JobRunCompletion): Promise<void>;
+    /** GET /v1/agents/{uid}/jobs — the bot's own scheduled jobs (self-only). */
+    listJobs(agentUid: string): Promise<BotJobRecord[]>;
+    /** POST /v1/agents/{uid}/jobs — schedule a new job for the bot itself. */
+    createJob(agentUid: string, input: CreateJobInput): Promise<BotJobRecord>;
+    /** POST /v1/agents/{uid}/jobs/{jobId}/cancel — cancel and delete its schedule. */
+    cancelJob(agentUid: string, jobId: string): Promise<void>;
     /** POST /v1/notify/dm — send as the bot (agent identity). */
     sendDm(input: {
         toPersonUid: string;