@indigoai-us/hq-cli 5.345.197 → 5.345.199

package/dist/lib/bot/jobs/meeting-rider.js

@@ -0,0 +1,284 @@
+/** The meeting-specific producer; extraction and event consumers remain source-independent. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import yaml from "js-yaml";
+import { ensureCognitoToken } from "../../../utils/cognito-session.js";
+import { getCompanyUid, vaultApiFetch } from "../../../utils/vault-api.js";
+import { assertSafeSegment } from "../../hot-channels/landing.js";
+import { meetingSignalSourceRef, cursorPath } from "../../signals/incremental.js";
+import { readAllLanes } from "../../lanes/store.js";
+import { runSignals } from "../../signals/engine.js";
+import { emitBotEvent, EVENT_PAYLOAD_BYTES } from "../events.js";
+import { executiveRiderEnabled } from "../executive-settings.js";
+export { isExecutiveBot } from "../executive-settings.js";
+import { readLocalJobsStrict, withJobsLock, writeLocalJobs } from "../local-jobs.js";
+import { readBuiltinJobsMarker, writeBuiltinJobsMarker } from "./hot-signal-sync.js";
+export const MEETING_RIDER_JOB_KIND = "meeting-rider";
+export const END_POLLS = 3;
+const MAX_LOCK_AGE = 6 * 60 * 60 * 1000;
+const TERMINAL = new Set(["completed", "done", "no_transcript", "failed", "fatal", "error", "cancelled", "canceled", "ended", "call_ended", "left", "processing"]);
+const terminal = (status) => TERMINAL.has(status.toLowerCase().replaceAll("-", "_"));
+function atomic(file, value) {
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== "ESRCH";
+    }
+}
+export function ensureMeetingRiderJob(dir) {
+    return withJobsLock(dir, () => {
+        const jobs = readLocalJobsStrict(dir);
+        const existing = jobs.find((job) => job.context?.jobKind === MEETING_RIDER_JOB_KIND);
+        const marker = readBuiltinJobsMarker(dir);
+        if (marker.registered[MEETING_RIDER_JOB_KIND])
+            return existing ?? null;
+        const job = existing ?? {
+            jobId: `job_${randomUUID().replaceAll("-", "").slice(0, 20)}`,
+            prompt: "Ride an attended live meeting and extract incremental signals in-process.",
+            trigger: { kind: "event", event: "meeting.detected" }, timezone: "UTC",
+            context: { jobKind: MEETING_RIDER_JOB_KIND }, createdAt: new Date().toISOString(),
+        };
+        if (!existing)
+            writeLocalJobs(dir, [...jobs, job]);
+        marker.registered[MEETING_RIDER_JOB_KIND] = new Date().toISOString();
+        writeBuiltinJobsMarker(dir, marker);
+        return job;
+    });
+}
+export function meetingRiderSettings(hqRoot, home = os.homedir()) {
+    const enabled = executiveRiderEnabled(home);
+    let interval = 20;
+    try {
+        const settings = yaml.load(fs.readFileSync(path.join(hqRoot, "core/settings/signals.yaml"), "utf8"));
+        const value = settings?.rider?.interval_seconds;
+        if (typeof value === "number" && Number.isFinite(value))
+            interval = Math.max(5, value);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    return { enabled, interval };
+}
+/** A crash after append but before removing the lock must not append the end event twice. */
+function emitEndedOnce(dir, meeting, record) {
+    let payload = { ...meeting, source_ref: meetingSignalSourceRef(meeting.meeting_id), signal_ids: record.signals_written };
+    if (Buffer.byteLength(JSON.stringify(payload), "utf8") >= EVENT_PAYLOAD_BYTES) {
+        // The summary is durable before emit. Keep the complete IDs there rather
+        // than silently truncating them or stranding completion on the event cap.
+        payload = { ...payload, signal_ids: [], signal_count: record.signals_written.length,
+            signal_ids_ref: { path: `workspace/executive/meetings/${meeting.company}/${meeting.meeting_id}.rider.json`, field: "signals_written" } };
+    }
+    emitBotEvent(dir, "meeting.ended", payload, new Date(), (event) => event.event === "meeting.ended" && event.payload.company === meeting.company && event.payload.meeting_id === meeting.meeting_id);
+}
+export function createMeetingRider(deps) {
+    const now = deps.now ?? (() => new Date());
+    const running = new Map();
+    const controller = new AbortController();
+    const root = path.join(deps.hqRoot, "workspace/executive/meetings");
+    const emit = deps.emit ?? ((meeting, record) => emitEndedOnce(deps.dir, meeting, record));
+    const paths = (meeting) => {
+        assertSafeSegment(meeting.company, "company");
+        assertSafeSegment(meeting.meeting_id, "meeting id");
+        const base = path.join(root, meeting.company, meeting.meeting_id);
+        return { lock: `${base}.rider.lock`, result: `${base}.rider.json` };
+    };
+    const persist = (state) => atomic(paths(state).lock, state);
+    const finish = (state) => {
+        const { lock, result } = paths(state);
+        const record = { started_at: state.started_at, ended_at: state.ended_at, passes: state.passes, signals_written: state.signals_written, lanes: state.lanes };
+        atomic(result, record);
+        emit({ company: state.company, meeting_id: state.meeting_id }, record);
+        fs.unlinkSync(lock);
+    };
+    const loop = async (state, resumed) => {
+        const file = paths(state).lock;
+        if (state.ended_at) {
+            finish(state);
+            return;
+        }
+        let first = !resumed || state.passes === 0;
+        while (!controller.signal.aborted) {
+            if (!deps.enabled()) {
+                deps.log("rider disabled");
+                fs.unlinkSync(file);
+                return;
+            }
+            const started = now().getTime();
+            const status = await deps.live({ meeting_id: state.meeting_id, company: state.company });
+            if (controller.signal.aborted)
+                return;
+            if (!status.attended) {
+                deps.log(`rider skipped ${state.meeting_id}: owner did not attend`);
+                fs.unlinkSync(file);
+                return;
+            }
+            state.end_polls = terminal(status.status) ? state.end_polls + 1 : 0;
+            // A detection delivered after the meeting ended needs just one final pass.
+            const ended = (first && terminal(status.status)) || state.end_polls >= END_POLLS;
+            first = false;
+            const pass = await deps.runIncremental({ meeting_id: state.meeting_id, company: state.company });
+            if (pass.skipped) {
+                deps.log(`rider ${state.meeting_id} waiting for the signals lock`);
+                // Keep a pending final pass pending even when the first read was terminal.
+                if (ended)
+                    state.end_polls = END_POLLS;
+                persist(state);
+            }
+            else {
+                state.passes++;
+                state.signals_written = [...new Set([...state.signals_written, ...pass.signal_ids])];
+                state.lanes = [...new Set([...state.lanes, ...(pass.lanes ?? [])])];
+                deps.log(`rider ${state.meeting_id} pass ${state.passes}`);
+                // Persist progress even on a stop; the next process resumes this cursor.
+                persist(state);
+                if (controller.signal.aborted)
+                    return;
+                if (ended) {
+                    if (!deps.enabled()) {
+                        deps.log("rider disabled");
+                        fs.unlinkSync(file);
+                        return;
+                    }
+                    state.ended_at = now().toISOString();
+                    persist(state);
+                    finish(state);
+                    return;
+                }
+            }
+            const seconds = deps.intervalSeconds?.() ?? 20;
+            const cadence = Number.isFinite(seconds) ? Math.max(5, seconds) * 1000 : 20_000;
+            await (deps.sleep ?? ((ms, signal) => delay(ms, undefined, { signal })))(Math.max(0, cadence - (now().getTime() - started)), controller.signal);
+        }
+    };
+    const launch = (state, resumed) => {
+        const key = paths(state).lock;
+        const task = loop(state, resumed).catch(() => {
+            if (!controller.signal.aborted)
+                deps.log(`rider ${state.meeting_id} interrupted; retained lock for restart`);
+        }).finally(() => running.delete(key));
+        running.set(key, task);
+    };
+    return {
+        /** Synchronously persists intent before the event handler may acknowledge delivery. */
+        start(payload) {
+            if (!deps.enabled()) {
+                deps.log("rider disabled");
+                return;
+            }
+            if (!payload || typeof payload !== "object")
+                throw new Error("Invalid meeting.detected payload");
+            const { company, meeting_id } = payload;
+            if (typeof company !== "string" || typeof meeting_id !== "string")
+                throw new Error("meeting.detected needs company and meeting_id");
+            const meeting = { company, meeting_id };
+            const { lock, result } = paths(meeting);
+            if (fs.existsSync(result) && !fs.existsSync(lock))
+                return;
+            fs.mkdirSync(path.dirname(lock), { recursive: true });
+            const state = { ...meeting, bot: deps.bot, pid: process.pid, started_at: now().toISOString(), passes: 0, end_polls: 0, signals_written: [], lanes: [] };
+            // Publish a complete intent atomically without replacing an existing lock.
+            const intent = `${lock}.${randomUUID()}.tmp`;
+            fs.writeFileSync(intent, JSON.stringify(state), { mode: 0o600 });
+            try {
+                fs.linkSync(intent, lock);
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+                deps.log(`rider already running: ${meeting_id}`);
+                return;
+            }
+            finally {
+                fs.unlinkSync(intent);
+            }
+            launch(state, false);
+        },
+        resume() {
+            if (!deps.enabled()) {
+                deps.log("rider disabled");
+                return;
+            }
+            if (!fs.existsSync(root))
+                return;
+            for (const company of fs.readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory())) {
+                for (const name of fs.readdirSync(path.join(root, company.name)).filter((name) => name.endsWith(".rider.lock"))) {
+                    const file = path.join(root, company.name, name);
+                    try {
+                        const state = JSON.parse(fs.readFileSync(file, "utf8"));
+                        if (state.bot !== deps.bot || paths(state).lock !== file || running.has(file))
+                            continue;
+                        if ((deps.isAlive ?? alive)(state.pid))
+                            continue;
+                        if (now().getTime() - fs.statSync(file).mtimeMs >= MAX_LOCK_AGE) {
+                            fs.unlinkSync(file);
+                            continue;
+                        }
+                        state.pid = process.pid;
+                        persist(state);
+                        launch(state, true);
+                    }
+                    catch {
+                        deps.log(`rider lock could not be resumed: ${name}`);
+                    }
+                }
+            }
+        },
+        async settled() { await Promise.all(running.values()); },
+        async stop() { controller.abort(); await Promise.all(running.values()); },
+    };
+}
+/** Production dependencies use the same attended endpoint as `meetings live`. */
+export function defaultMeetingRiderDeps(config, dir, log) {
+    return {
+        hqRoot: config.hqRoot, dir, bot: config.name, log,
+        enabled: () => meetingRiderSettings(config.hqRoot).enabled,
+        intervalSeconds: () => meetingRiderSettings(config.hqRoot).interval,
+        live: async ({ company, meeting_id }) => {
+            const token = await ensureCognitoToken();
+            const companyId = await getCompanyUid(token, company);
+            const response = await vaultApiFetch({ token, path: "/v1/meetings", query: { companyId, view: "live" } });
+            if (!response.ok)
+                throw new Error("Could not check attended meetings");
+            const data = await response.json();
+            if (!Array.isArray(data.bots))
+                throw new Error("Invalid attended meetings response");
+            const row = data.bots.find((bot) => bot && typeof bot === "object" &&
+                (bot.companyId === undefined || bot.companyId === companyId) &&
+                (bot.meetingId === meeting_id || bot.recallBotId === meeting_id || bot.botId === meeting_id));
+            if (row && typeof row.status !== "string")
+                throw new Error("Invalid attended meeting status");
+            return { attended: Boolean(row), status: typeof row?.status === "string" ? row.status : "unknown" };
+        },
+        runIncremental: async ({ company, meeting_id }) => {
+            const source = meetingSignalSourceRef(meeting_id);
+            const result = await runSignals({ hqRoot: config.hqRoot, company, source, incremental: true, trigger: "manual",
+                incrementalOptions: { onSignalWritten: async ({ event, ...payload }) => { emitBotEvent(dir, event, payload); } },
+            });
+            if (result.locked?.some((record) => record.company === company))
+                return { signal_ids: [], skipped: true };
+            if (!result.records.length || result.records.some((record) => record.status !== "complete"))
+                throw new Error("Incremental pass did not complete");
+            const file = path.join(config.hqRoot, cursorPath(company, source));
+            const cursor = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : { signal_ids: [] };
+            // US-003 adds signal metadata to lane records. Reading it is additive:
+            // older lanes have none and are not included in this source's summary.
+            const lanes = readAllLanes(config.hqRoot).filter((lane) => {
+                const signal = lane.signal;
+                return lane.company?.slug === company && signal?.source_ref === source;
+            }).map((lane) => lane.lane_id);
+            return { signal_ids: cursor.signal_ids, lanes };
+        },
+    };
+}
+//# sourceMappingURL=meeting-rider.js.map

package/dist/lib/bot/jobs/signal-to-lane.d.ts

@@ -0,0 +1,32 @@
+import { type BotConfig } from "../config.js";
+import { type LocalJob } from "../local-jobs.js";
+import type { JobRunCompletion } from "../api.js";
+export declare const SIGNAL_TO_LANE_JOB_KIND = "signal-to-lane";
+export declare function signalLaneCompanies(config: BotConfig): string[];
+export declare function ensureSignalToLaneJobs(dir: string, config: BotConfig, companies?: string[], home?: string): LocalJob[];
+/** Only new locally extracted signals reach here; cloud upload/garden is separate. */
+export declare function emitExecutiveSignalWritten(hqRoot: string, company: string, payload: Record<string, string>, root?: string, home?: string): boolean;
+/** Persist intent before publishing a new signal file; ordinary redo creates none. */
+export declare function prepareSignalPublication(hqRoot: string, company: string, payload: Record<string, string>): void;
+/** A pre-append crash retries; a post-append crash uses the event journal's dedupe. */
+export declare function flushSignalPublications(hqRoot: string, company: string, emit?: typeof emitExecutiveSignalWritten): void;
+type Create = (input: {
+    hqRoot: string;
+    company: string;
+    signal_id: string;
+}) => Promise<{
+    lane_id: string;
+    existing: boolean;
+}>;
+export declare function runSignalToLane(input: {
+    dir: string;
+    config: BotConfig;
+    payload: unknown;
+    company: unknown;
+    log: (message: string) => void;
+    create?: Create;
+    companies?: string[];
+    home?: string;
+}): Promise<JobRunCompletion>;
+export {};
+//# sourceMappingURL=signal-to-lane.d.ts.map

package/dist/lib/bot/jobs/signal-to-lane.js

@@ -0,0 +1,169 @@
+/** Source-independent action-item consumer for the personal Executive. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { readBotConfig } from "../config.js";
+import { botsRoot } from "../paths.js";
+import { fleetProfileOwnerCompanies } from "../fleet-local.js";
+import { fleetHotSignalSyncCompanies } from "../fleet-cron.js";
+import { readActiveCompanySlug, readBuiltinJobsMarker, writeBuiltinJobsMarker } from "./hot-signal-sync.js";
+import { isExecutiveBot } from "./meeting-rider.js";
+import { readLocalJobsStrict, writeLocalJobs, withJobsLock } from "../local-jobs.js";
+import { emitBotEvent } from "../events.js";
+import { isLanesError } from "../../lanes/errors.js";
+import { lookupSignal } from "../../lanes/signal-lane.js";
+export const SIGNAL_TO_LANE_JOB_KIND = "signal-to-lane";
+export function signalLaneCompanies(config) {
+    return fleetHotSignalSyncCompanies(config, readActiveCompanySlug(config.hqRoot) ?? null, fleetProfileOwnerCompanies(config.agentUid));
+}
+export function ensureSignalToLaneJobs(dir, config, companies = signalLaneCompanies(config), home) {
+    if (!isExecutiveBot(config, home))
+        return [];
+    return withJobsLock(dir, () => {
+        const jobs = readLocalJobsStrict(dir);
+        const marker = readBuiltinJobsMarker(dir);
+        for (const company of new Set(companies)) {
+            if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(company) || company === "personal")
+                continue;
+            const key = `${SIGNAL_TO_LANE_JOB_KIND}:${company}`;
+            if (marker.registered[key])
+                continue;
+            if (!jobs.some(job => job.context?.jobKind === SIGNAL_TO_LANE_JOB_KIND && job.context.company === company)) {
+                jobs.push({ jobId: `job_${randomUUID().replaceAll("-", "").slice(0, 20)}`,
+                    prompt: "Open a conductor lane from an action item in-process.", timezone: "UTC",
+                    trigger: { kind: "event", event: "signal.written", filter: { type: "action_item", company } },
+                    context: { jobKind: SIGNAL_TO_LANE_JOB_KIND, company }, createdAt: new Date().toISOString() });
+            }
+            marker.registered[key] = new Date().toISOString();
+        }
+        writeLocalJobs(dir, jobs);
+        writeBuiltinJobsMarker(dir, marker);
+        return jobs.filter(job => job.context?.jobKind === SIGNAL_TO_LANE_JOB_KIND);
+    });
+}
+/** Only new locally extracted signals reach here; cloud upload/garden is separate. */
+export function emitExecutiveSignalWritten(hqRoot, company, payload, root = botsRoot(), home) {
+    if (!fs.existsSync(root))
+        return false;
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(root, entry.name);
+        const config = readBotConfig(dir);
+        if (!config || typeof config.hqRoot !== "string" || path.resolve(config.hqRoot) !== path.resolve(hqRoot) || !isExecutiveBot(config, home))
+            continue;
+        if (!signalLaneCompanies(config).includes(company))
+            continue;
+        emitBotEvent(dir, "signal.written", { ...payload, company }, new Date(), prior => prior.event === "signal.written" && prior.payload.company === company && prior.payload.signal_id === payload.signal_id);
+        return true;
+    }
+    return false;
+}
+function publicationDir(hqRoot, company) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(company))
+        throw new Error("Invalid signal publication company");
+    return path.join(hqRoot, "workspace", "signal-publications", company);
+}
+/** Persist intent before publishing a new signal file; ordinary redo creates none. */
+export function prepareSignalPublication(hqRoot, company, payload) {
+    const dir = publicationDir(hqRoot, company);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = path.join(dir, createHash("sha256").update(payload.signal_id).digest("hex") + ".json");
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(payload), { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+/** A pre-append crash retries; a post-append crash uses the event journal's dedupe. */
+export function flushSignalPublications(hqRoot, company, emit = emitExecutiveSignalWritten) {
+    const dir = publicationDir(hqRoot, company);
+    if (!fs.existsSync(dir))
+        return;
+    for (const name of fs.readdirSync(dir).filter(name => /^[a-f0-9]{64}\.json$/.test(name))) {
+        const file = path.join(dir, name);
+        let payload;
+        try {
+            payload = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        if (!payload || typeof payload !== "object" || Array.isArray(payload) ||
+            ["signal_id", "type", "source_ref", "audience_key", "origin"].some(key => typeof payload[key] !== "string")) {
+            throw new Error("Invalid signal publication intent");
+        }
+        try {
+            lookupSignal(hqRoot, company, payload.signal_id);
+        }
+        catch (error) {
+            if (isLanesError(error) && error.error === "signal_not_found")
+                continue;
+            throw error;
+        }
+        if (emit(hqRoot, company, payload)) {
+            try {
+                fs.unlinkSync(file);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+    }
+}
+const createDefault = async (input) => {
+    // Load the CLI admission graph only when a signal actually needs a lane.
+    const { createLaneFromSignal } = await import("../../../commands/lanes.js");
+    return createLaneFromSignal(input);
+};
+export async function runSignalToLane(input) {
+    if (!isExecutiveBot(input.config, input.home))
+        return { status: "skipped-precondition", output: "Not the Executive" };
+    const payload = input.payload;
+    const company = input.company;
+    if (!payload || payload.type !== "action_item" || typeof payload.signal_id !== "string" || !payload.signal_id.trim() ||
+        typeof company !== "string" || payload.company !== company || !(input.companies ?? signalLaneCompanies(input.config)).includes(company)) {
+        return { status: "skipped-precondition", output: "Signal outside the served company or action-item scope" };
+    }
+    // Persist deferred IDs before acknowledging; the next matching event retries.
+    const file = path.join(input.dir, "signal-to-lane-pending.json");
+    const read = () => {
+        try {
+            const value = JSON.parse(fs.readFileSync(file, "utf8"));
+            if (!value || typeof value !== "object" || Array.isArray(value) ||
+                Object.values(value).some(ids => !Array.isArray(ids) || ids.some(id => typeof id !== "string"))) {
+                throw new Error("Invalid pending signal lane state");
+            }
+            return Object.assign(Object.create(null), value);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return Object.create(null);
+            throw err;
+        }
+    };
+    const update = (change) => withJobsLock(input.dir, () => {
+        const pending = read();
+        change(pending);
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(pending), { mode: 0o600 });
+        fs.renameSync(tmp, file);
+        return pending;
+    });
+    const pending = update(p => { p[company] = [...new Set([...(p[company] ?? []), payload.signal_id])]; });
+    for (const signal_id of pending[company] ?? []) {
+        try {
+            const result = await (input.create ?? createDefault)({ hqRoot: input.config.hqRoot, company, signal_id });
+            input.log(JSON.stringify(result));
+            update(p => { p[company] = (p[company] ?? []).filter(id => id !== signal_id); });
+        }
+        catch (err) {
+            if (!isLanesError(err) || err.error !== "no_conductor_link")
+                throw err;
+            input.log(JSON.stringify({ error: "no_conductor_link", company, signal_id }));
+        }
+    }
+    return { status: "succeeded", output: "Signal lane processing finished; deferred signals retry on the next matching event" };
+}
+//# sourceMappingURL=signal-to-lane.js.map

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

@@ -23,7 +23,12 @@ export interface LocalJob {
     jobId: string;
     prompt: string;
     /** Standard 5-field cron, evaluated in `timezone`. */
-    cron: string;
+    cron?: string;
+    trigger?: {
+        kind: "event";
+        event: string;
+        filter?: Record<string, string>;
+    };
     timezone: string;
     context?: Record<string, unknown>;
     createdAt: string;
@@ -45,6 +50,12 @@ export interface LocalJob {
     runCount?: number;
 }
 export declare function readLocalJobs(dir: string): LocalJob[];
+/**
+ * `jobs.json` for a write that adds a job: a missing file is an empty list,
+ * but a file that exists and cannot be read or parsed throws, so adding a job
+ * never writes back a list that drops every other job.
+ */
+export declare function readLocalJobsStrict(dir: string): LocalJob[];
 export declare function writeLocalJobs(dir: string, jobs: LocalJob[]): void;
 /**
  * Run a read-change-write of `jobs.json` under an exclusive lock. The running
@@ -74,9 +85,11 @@ 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 toJobRecord(job: LocalJob, now?: Date): BotJobRecord;
 export declare function addLocalJob(dir: string, input: {
     prompt: string;
-    cron: string;
+    cron?: string;
+    trigger?: LocalJob["trigger"];
     timezone: string;
     context?: Record<string, unknown>;
 }, now?: Date): LocalJob;

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

@@ -22,6 +22,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
 import { BotApiError } from "./api.js";
+import { ackBotEvent } from "./events.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). */
@@ -47,7 +48,7 @@ export function readLocalJobs(dir) {
  * but a file that exists and cannot be read or parsed throws, so adding a job
  * never writes back a list that drops every other job.
  */
-function readLocalJobsForAdd(dir) {
+export function readLocalJobsStrict(dir) {
     let text;
     try {
         text = fs.readFileSync(localJobsPath(dir), "utf8");
@@ -270,6 +271,8 @@ function scheduleOrigin(job) {
     return Date.parse(job.scheduledFrom ?? job.createdAt);
 }
 export function latestDueFire(job, now) {
+    if (job.trigger || !job.cron)
+        return null;
     const interval = rateIntervalMs(job.cron);
     if (interval) {
         const origin = scheduleOrigin(job);
@@ -294,6 +297,8 @@ export function latestDueFire(job, now) {
 }
 /** The next time this job is due after `now`, within a week; null otherwise. */
 export function nextDueFire(job, now) {
+    if (job.trigger || !job.cron)
+        return null;
     const interval = rateIntervalMs(job.cron);
     if (interval) {
         const origin = scheduleOrigin(job);
@@ -313,13 +318,13 @@ export function nextDueFire(job, now) {
     return null;
 }
 // ─── The job list (what `hq bot jobs` reads and writes) ──────────────────────
-function toJobRecord(job, now = new Date()) {
+export 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.trigger ? { trigger: job.trigger } : { schedule: { kind: "recurring", cron: job.cron, timezone: job.timezone } }),
         ...(job.context ? { context: job.context } : {}),
         createdAt: job.createdAt,
         ...(next ? { nextRunAt: next.toISOString() } : {}),
@@ -329,17 +334,24 @@ function toJobRecord(job, now = new Date()) {
     };
 }
 export function addLocalJob(dir, input, now = new Date()) {
-    if (!isRunnableSchedule(input.cron))
+    if (input.trigger && (!input.trigger.event.trim() || input.trigger.kind !== "event" || input.cron))
+        throw new Error("An event job needs an event and no cron schedule.");
+    if (!input.trigger && (!input.cron || !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,
+        ...(input.trigger ? { trigger: input.trigger } : { cron: input.cron }),
         timezone: input.timezone,
         ...(input.context ? { context: input.context } : {}),
         createdAt: now.toISOString(),
     };
-    withJobsLock(dir, () => writeLocalJobs(dir, [...readLocalJobsForAdd(dir), job]));
+    withJobsLock(dir, () => {
+        const jobs = readLocalJobsStrict(dir);
+        if (jobs.length >= MAX_LOCAL_JOBS)
+            throw new BotApiError(409, "local jobs", "JOB_QUOTA_EXCEEDED", `at most ${MAX_LOCAL_JOBS} jobs`);
+        writeLocalJobs(dir, [...jobs, job]);
+    });
     return job;
 }
 /**
@@ -350,7 +362,7 @@ export function ensureLocalJob(dir, matches, input, now = new Date()) {
     if (!isRunnableSchedule(input.cron))
         throw new Error(`"${input.cron}" is not a schedule this bot can run.`);
     return withJobsLock(dir, () => {
-        const jobs = readLocalJobsForAdd(dir);
+        const jobs = readLocalJobsStrict(dir);
         const existing = jobs.find(matches);
         if (existing)
             return { job: existing, created: false };
@@ -386,6 +398,7 @@ schedule, now = new Date()) {
             timezone: schedule.timezone ?? jobs[index].timezone,
             scheduledFrom: now.toISOString(),
         };
+        delete updated.trigger;
         jobs[index] = updated;
         writeLocalJobs(dir, jobs);
         return updated;
@@ -517,6 +530,10 @@ export function withLocalJobs(api, dir, clock = () => new Date()) {
         return [...cloud, ...takeDueLocalJobRuns(dir, clock())];
     };
     local.ackInbox = async (agentUid, messageId) => {
+        if (messageId.startsWith("localjob-event-")) {
+            ackBotEvent(dir, messageId);
+            return;
+        }
         if (isLocalJobMessage(messageId))
             return;
         await api.ackInbox(agentUid, messageId);