openmausbot 0.1.55

package/dist-server/server/routines.js

@@ -0,0 +1,1111 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { DATA_DIR } from "./config.js";
+import { writeFileAtomic } from "./atomic.js";
+import { redactSecretsInText } from "./redact.js";
+const persistedSourceThreadId = z.string().trim().min(1).optional().catch(undefined);
+function routineRequestOwnerKey(owner) {
+    return JSON.stringify([owner.requestId, owner.messageId, owner.botId, owner.threadId]);
+}
+const ALL_DAYS = [0, 1, 2, 3, 4, 5, 6];
+const CATCH_UP_MS = 12 * 60 * 60_000;
+const MAX_DATE_MS = 8_640_000_000_000_000;
+const MAX_RUNS = 2_000;
+const MAX_ATTACHMENTS = 50;
+const attachmentSchema = z.object({
+    id: z.string().trim().min(1).max(200),
+    kind: z.enum(["file", "image"]),
+    name: z.string().trim().min(1).max(255),
+    path: z.string().trim().min(1).max(4_096),
+    size: z.number().finite().nonnegative(),
+});
+const ROUTINE_REQUEST_ACTIONS = new Set([
+    "create",
+    "update",
+    "pause",
+    "resume",
+    "run_now",
+    "delete",
+]);
+function isRoutineRequestAction(value) {
+    return typeof value === "string" && ROUTINE_REQUEST_ACTIONS.has(value);
+}
+function cleanDays(days) {
+    if (!Array.isArray(days))
+        return ALL_DAYS;
+    const out = [...new Set(days.filter((d) => Number.isInteger(d) && d >= 0 && d <= 6))].sort();
+    return out.length ? out : ALL_DAYS;
+}
+function cleanAttachments(value) {
+    if (value == null)
+        return [];
+    if (!Array.isArray(value) || value.length > MAX_ATTACHMENTS) {
+        throw new Error(`Add no more than ${MAX_ATTACHMENTS} attachments`);
+    }
+    const ids = new Set();
+    return value.map((candidate) => {
+        const parsed = attachmentSchema.safeParse(candidate);
+        if (!parsed.success || parsed.data.name.includes("\0") || parsed.data.path.includes("\0")) {
+            throw new Error("Choose a valid attachment");
+        }
+        if (ids.has(parsed.data.id))
+            throw new Error("Each attachment must be unique");
+        ids.add(parsed.data.id);
+        return { ...parsed.data };
+    });
+}
+function cleanTimeoutMinutes(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 5 || value > 240) {
+        throw new Error("Run limit must be a whole number from 5 to 240 minutes");
+    }
+    return value;
+}
+function loadTimeoutMinutes(value) {
+    try {
+        return cleanTimeoutMinutes(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A malformed legacy metadata field must not make the scheduler forget the
+ * otherwise valid routine or run that owns it. New writes still fail closed. */
+function loadAttachments(value) {
+    try {
+        return cleanAttachments(value);
+    }
+    catch {
+        return [];
+    }
+}
+function cloneSchedule(schedule) {
+    if (schedule.type === "once")
+        return { type: "once", at: schedule.at };
+    if (schedule.type === "interval") {
+        return { type: "interval", everyMinutes: schedule.everyMinutes, anchorAt: schedule.anchorAt };
+    }
+    return { type: "daily", time: schedule.time, weekdays: [...schedule.weekdays] };
+}
+function cloneAttachments(attachments) {
+    return attachments?.map((attachment) => ({ ...attachment })) ?? [];
+}
+function loadTarget(value) {
+    return value === "room-goal" ? "room-goal" : "bot";
+}
+const ROUTINE_GOAL_STATUSES = new Set([
+    "completed",
+    "needs-input",
+    "blocked",
+    "limit-reached",
+    "paused",
+    "stopped",
+    "failed",
+]);
+function loadGoalStatus(value, target) {
+    return target === "room-goal" && typeof value === "string" && ROUTINE_GOAL_STATUSES.has(value)
+        ? value
+        : undefined;
+}
+function loadGroupId(value, target) {
+    if (target !== "room-goal" || typeof value !== "string")
+        return undefined;
+    return value.trim() || undefined;
+}
+function cloneRoutine(routine) {
+    return {
+        ...routine,
+        schedule: cloneSchedule(routine.schedule),
+        attachments: cloneAttachments(routine.attachments),
+    };
+}
+function cloneRun(run) {
+    return {
+        ...run,
+        attachments: cloneAttachments(run.attachments),
+        denials: run.denials ? [...run.denials] : undefined,
+    };
+}
+/** Keep untrusted local paths inside the same quoted tag shape used by chat. */
+function escapeAttachmentPath(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll("\t", "&#9;")
+        .replaceAll("\r", "&#13;")
+        .replaceAll("\n", "&#10;");
+}
+function composeExecutionPrompt(prompt, attachments) {
+    const parts = [prompt];
+    for (const attachment of attachments ?? []) {
+        const tag = attachment.kind === "image" ? "attached-image" : "attached-file";
+        parts.push(`<${tag} path="${escapeAttachmentPath(attachment.path)}" name="${escapeAttachmentPath(attachment.name)}" />`);
+    }
+    return parts.filter(Boolean).join("\n\n");
+}
+function cleanSchedule(schedule) {
+    if (schedule?.type === "once") {
+        const at = Number(schedule.at);
+        if (!Number.isFinite(at))
+            throw new Error("Choose a valid date and time");
+        return { type: "once", at };
+    }
+    if (schedule?.type === "daily") {
+        const time = String(schedule.time ?? "");
+        if (!/^([01]\d|2[0-3]):[0-5]\d$/.test(time))
+            throw new Error("Time must use HH:MM");
+        return { type: "daily", time, weekdays: cleanDays(schedule.weekdays) };
+    }
+    if (schedule?.type === "interval") {
+        const { everyMinutes, anchorAt } = schedule;
+        if (typeof everyMinutes !== "number" || !Number.isInteger(everyMinutes) || everyMinutes < 5 || everyMinutes > 1_440) {
+            throw new Error("Interval must be a whole number from 5 to 1440 minutes");
+        }
+        if (typeof anchorAt !== "number" ||
+            !Number.isSafeInteger(anchorAt) ||
+            anchorAt < 0 ||
+            anchorAt > MAX_DATE_MS) {
+            throw new Error("Choose a valid interval start time");
+        }
+        return { type: "interval", everyMinutes, anchorAt };
+    }
+    throw new Error("Choose a supported schedule");
+}
+function loadSchedule(value) {
+    try {
+        return cleanSchedule(value);
+    }
+    catch {
+        return null;
+    }
+}
+/** Next wall-clock occurrence in this computer's timezone, strictly after `after`. */
+export function nextOccurrence(schedule, after) {
+    if (schedule.type === "once")
+        return schedule.at > after ? schedule.at : null;
+    if (schedule.type === "interval") {
+        if (schedule.anchorAt > after)
+            return schedule.anchorAt;
+        const intervalMs = schedule.everyMinutes * 60_000;
+        const intervalsElapsed = Math.floor((after - schedule.anchorAt) / intervalMs);
+        const candidate = schedule.anchorAt + (intervalsElapsed + 1) * intervalMs;
+        return Number.isSafeInteger(candidate) && candidate <= MAX_DATE_MS ? candidate : null;
+    }
+    const [hour, minute] = schedule.time.split(":").map(Number);
+    const weekdays = new Set(cleanDays(schedule.weekdays));
+    for (let offset = 0; offset <= 8; offset++) {
+        const d = new Date(after);
+        d.setDate(d.getDate() + offset);
+        d.setHours(hour, minute, 0, 0);
+        if (d.getTime() > after && weekdays.has(d.getDay()))
+            return d.getTime();
+    }
+    return null;
+}
+function latestIntervalOccurrence(schedule, at) {
+    if (schedule.anchorAt > at)
+        return null;
+    const intervalMs = schedule.everyMinutes * 60_000;
+    return schedule.anchorAt + Math.floor((at - schedule.anchorAt) / intervalMs) * intervalMs;
+}
+function sanitizeInput(input) {
+    const name = String(input.name ?? "").trim().slice(0, 80);
+    const prompt = String(input.prompt ?? "").trim().slice(0, 20_000);
+    const botId = String(input.botId ?? "").trim();
+    if (!name)
+        throw new Error("Give the routine a name");
+    if (!prompt)
+        throw new Error("Tell the bot what to do");
+    if (!botId)
+        throw new Error("Choose a bot");
+    const target = input.target ?? "bot";
+    if (target !== "bot" && target !== "room-goal")
+        throw new Error("Choose a valid routine target");
+    const groupId = typeof input.groupId === "string" ? input.groupId.trim() : "";
+    if (target === "room-goal" && !groupId)
+        throw new Error("Choose a room for this goal");
+    const runOn = input.runOn ?? "maus";
+    if (runOn !== "maus" && runOn !== "cloud")
+        throw new Error("Choose where this routine runs");
+    const attachments = cleanAttachments(input.attachments);
+    const timeoutMinutes = cleanTimeoutMinutes(input.timeoutMinutes);
+    if (target === "room-goal" && runOn === "cloud") {
+        throw new Error("Room goals can only run on this computer");
+    }
+    if (target === "room-goal" && attachments.length > 0) {
+        throw new Error("Room goals do not support attachments yet");
+    }
+    if (runOn === "cloud" && attachments.length > 0) {
+        throw new Error("Attachments can only run on this computer until cloud file staging is available");
+    }
+    return {
+        name,
+        prompt,
+        target,
+        botId,
+        groupId: target === "room-goal" ? groupId : undefined,
+        runOn,
+        enabled: input.enabled !== false,
+        schedule: cleanSchedule(input.schedule),
+        durationMinutes: Math.min(240, Math.max(5, Math.round(Number(input.durationMinutes) || 30))),
+        ...(timeoutMinutes === undefined ? {} : { timeoutMinutes }),
+        attachments,
+    };
+}
+export class RoutineManager {
+    file;
+    now;
+    options;
+    routines = [];
+    runs = [];
+    routineRequestReceipts = [];
+    timer = null;
+    ticking = false;
+    constructor(options) {
+        this.options = options;
+        this.file = options.file ?? join(DATA_DIR, "routines.json");
+        this.now = options.now ?? Date.now;
+        try {
+            const disk = JSON.parse(readFileSync(this.file, "utf8"));
+            this.routines = Array.isArray(disk.routines)
+                ? disk.routines.flatMap((routine) => {
+                    const schedule = loadSchedule(routine.schedule);
+                    if (!schedule)
+                        return [];
+                    const target = loadTarget(routine.target);
+                    const loaded = {
+                        ...routine,
+                        schedule,
+                        target,
+                        groupId: loadGroupId(routine.groupId, target),
+                        runOn: routine.runOn ?? "maus",
+                        timeoutMinutes: loadTimeoutMinutes(routine.timeoutMinutes),
+                        attachments: loadAttachments(routine.attachments),
+                        sourceThreadId: persistedSourceThreadId.parse(routine.sourceThreadId),
+                    };
+                    if (loaded.timeoutMinutes === undefined)
+                        delete loaded.timeoutMinutes;
+                    return [loaded];
+                })
+                : [];
+            this.runs = Array.isArray(disk.runs)
+                ? disk.runs.map((run) => {
+                    const target = loadTarget(run.target);
+                    const loaded = {
+                        ...run,
+                        target,
+                        goalStatus: loadGoalStatus(run.goalStatus, target),
+                        groupId: loadGroupId(run.groupId, target),
+                        runOn: run.runOn ?? "maus",
+                        timeoutMinutes: loadTimeoutMinutes(run.timeoutMinutes),
+                        attachments: loadAttachments(run.attachments),
+                        sourceThreadId: persistedSourceThreadId.parse(run.sourceThreadId),
+                    };
+                    if (loaded.timeoutMinutes === undefined)
+                        delete loaded.timeoutMinutes;
+                    return loaded;
+                })
+                : [];
+            this.routineRequestReceipts = Array.isArray(disk.routineRequestReceipts)
+                ? disk.routineRequestReceipts.filter((receipt) => typeof receipt?.requestId === "string" &&
+                    typeof receipt?.messageId === "string" &&
+                    typeof receipt?.botId === "string" &&
+                    typeof receipt?.threadId === "string" &&
+                    isRoutineRequestAction(receipt?.action) &&
+                    receipt?.fingerprintVersion === 1 &&
+                    typeof receipt?.fingerprint === "string" && /^[a-f0-9]{64}$/.test(receipt.fingerprint) &&
+                    typeof receipt?.resultId === "string" &&
+                    Number.isFinite(receipt?.appliedAt))
+                : [];
+        }
+        catch {
+            this.routines = [];
+            this.runs = [];
+            this.routineRequestReceipts = [];
+        }
+        // A local process cannot still own these turns after a full restart.
+        const recovered = [];
+        for (const run of this.runs) {
+            if (run.status === "running" || run.status === "waiting") {
+                run.status = "failed";
+                if (run.target === "room-goal")
+                    run.goalStatus = "failed";
+                run.error = "OpenMausBot restarted while this routine was running";
+                run.attention = undefined;
+                run.finishedAt = this.now();
+                recovered.push(cloneRun(run));
+            }
+        }
+        if (recovered.length > 0) {
+            this.save();
+            for (const run of recovered) {
+                this.notifyRunChanged(run);
+                this.options.onRunFailed?.(run);
+            }
+        }
+    }
+    listRoutines() {
+        return this.routines.map(cloneRoutine);
+    }
+    listRuns(from, to) {
+        return this.runs
+            .filter((r) => (from == null || r.scheduledFor >= from) && (to == null || r.scheduledFor <= to))
+            .sort((a, b) => b.scheduledFor - a.scheduledFor)
+            .map(cloneRun);
+    }
+    activeRunForBot(botId) {
+        const run = this.runs.find((candidate) => candidate.botId === botId && ["running", "waiting"].includes(candidate.status));
+        return run ? cloneRun(run) : null;
+    }
+    /** Active work that owns the bot's direct conversation. Room goals may use
+     * the same bot as their coordinator, but execute in a separate room task. */
+    activeBotRunForBot(botId) {
+        const run = this.runs.find((candidate) => candidate.target === "bot" &&
+            candidate.botId === botId &&
+            ["running", "waiting"].includes(candidate.status));
+        return run ? cloneRun(run) : null;
+    }
+    routineRequestReceipt(requestId) {
+        const receipt = this.routineRequestReceipts.find((candidate) => candidate.requestId === requestId);
+        return receipt ? { ...receipt } : null;
+    }
+    /** Small startup index used to locate only transcripts that may need
+     * cross-file commit recovery. Most launches have no receipts and therefore
+     * do not read or cache any transcript for this feature. */
+    routineRequestReceiptOwners() {
+        return this.routineRequestReceipts.map(({ requestId, messageId, botId, threadId }) => ({
+            requestId,
+            messageId,
+            botId,
+            threadId,
+        }));
+    }
+    /** Once the transcript card is durably settled, its scheduler receipt is
+     * redundant. Unsettled receipts are intentionally never count-evicted: an
+     * actionable card may survive indefinitely and must retain its exact-once
+     * recovery record for the same lifetime. */
+    forgetRoutineRequestReceipt(request) {
+        const receipt = this.matchingRoutineRequestReceipt(request);
+        if (!receipt)
+            return false;
+        const index = this.routineRequestReceipts.indexOf(receipt);
+        this.commitMutation(() => {
+            this.routineRequestReceipts.splice(index, 1);
+        });
+        return true;
+    }
+    forgetRoutineRequestReceiptsForThread(threadId) {
+        const kept = this.routineRequestReceipts.filter((receipt) => receipt.threadId !== threadId);
+        const removed = this.routineRequestReceipts.length - kept.length;
+        if (removed === 0)
+            return 0;
+        this.commitMutation(() => {
+            this.routineRequestReceipts = kept;
+        });
+        return removed;
+    }
+    /** Drop only receipts whose confirmation transcript no longer exists.
+     * Reachable open cards retain exact-once recovery for their full lifetime. */
+    reconcileRoutineRequestReceipts(reachable) {
+        const keys = new Set(reachable.map(routineRequestOwnerKey));
+        const kept = this.routineRequestReceipts.filter((receipt) => keys.has(routineRequestOwnerKey(receipt)));
+        const removed = this.routineRequestReceipts.length - kept.length;
+        if (removed === 0)
+            return 0;
+        this.commitMutation(() => {
+            this.routineRequestReceipts = kept;
+        });
+        return removed;
+    }
+    isActiveThread(threadId) {
+        return this.runs.some((run) => run.threadId === threadId && ["running", "waiting"].includes(run.status));
+    }
+    create(input, request) {
+        if (request) {
+            const receipt = this.matchingRoutineRequestReceipt(request);
+            if (receipt) {
+                const committed = this.routines.find((routine) => routine.id === receipt.resultId);
+                if (committed)
+                    return cloneRoutine(committed);
+                throw new Error("This routine request was already applied");
+            }
+        }
+        const clean = sanitizeInput(input);
+        if (this.targetState(clean) === "missing")
+            throw new Error(this.missingTargetMessage(clean.target));
+        const at = this.now();
+        const routine = {
+            id: randomUUID(),
+            ...clean,
+            // Only a confirmed chat card supplies `request`; the public calendar
+            // API cannot choose an arbitrary transcript as a reporting target.
+            sourceThreadId: request?.threadId,
+            nextRunAt: clean.enabled ? this.initialOccurrence(clean.schedule, at) : null,
+            createdAt: at,
+            updatedAt: at,
+        };
+        this.commitMutation(() => {
+            this.routines.unshift(routine);
+            if (request)
+                this.rememberRoutineRequest(request, routine.id, at);
+        });
+        this.emitRoutine(routine);
+        return cloneRoutine(routine);
+    }
+    update(id, patch, request) {
+        if (request) {
+            const receipt = this.matchingRoutineRequestReceipt(request);
+            if (receipt) {
+                const committed = this.routines.find((routine) => routine.id === receipt.resultId);
+                return committed ? cloneRoutine(committed) : null;
+            }
+        }
+        const routine = this.routines.find((r) => r.id === id);
+        if (!routine)
+            return null;
+        const now = this.now();
+        const clean = sanitizeInput({
+            name: patch.name ?? routine.name,
+            prompt: patch.prompt ?? routine.prompt,
+            target: patch.target ?? routine.target,
+            botId: patch.botId ?? routine.botId,
+            groupId: Object.hasOwn(patch, "groupId") ? patch.groupId : routine.groupId,
+            runOn: patch.runOn ?? routine.runOn,
+            enabled: patch.enabled ?? routine.enabled,
+            schedule: patch.schedule ?? routine.schedule,
+            durationMinutes: patch.durationMinutes ?? routine.durationMinutes,
+            timeoutMinutes: Object.hasOwn(patch, "timeoutMinutes") ? patch.timeoutMinutes : routine.timeoutMinutes,
+            attachments: patch.attachments ?? routine.attachments,
+        });
+        if (this.targetState(clean) === "missing")
+            throw new Error(this.missingTargetMessage(clean.target));
+        const cancelledRuns = [];
+        this.commitMutation(() => {
+            Object.assign(routine, clean, {
+                nextRunAt: clean.enabled ? this.initialOccurrence(clean.schedule, now) : null,
+                // `updatedAt` doubles as the optimistic revision on durable routine
+                // confirmation cards. Keep it monotonic even for two writes in one ms.
+                updatedAt: Math.max(now, routine.updatedAt + 1),
+            });
+            if (Object.hasOwn(patch, "timeoutMinutes") && patch.timeoutMinutes == null) {
+                delete routine.timeoutMinutes;
+            }
+            if (patch.enabled === false) {
+                for (const run of this.runs) {
+                    if (run.routineId !== routine.id || run.status !== "queued")
+                        continue;
+                    run.status = "cancelled";
+                    run.attention = undefined;
+                    run.finishedAt = this.now();
+                    run.error = "The routine was paused before this run started";
+                    cancelledRuns.push(run);
+                }
+            }
+            if (request)
+                this.rememberRoutineRequest(request, routine.id, now);
+        });
+        for (const run of cancelledRuns)
+            this.emitRun(run);
+        this.emitRoutine(routine);
+        return cloneRoutine(routine);
+    }
+    remove(id, request) {
+        if (request) {
+            const receipt = this.matchingRoutineRequestReceipt(request);
+            if (receipt) {
+                return true;
+            }
+        }
+        const at = this.routines.findIndex((r) => r.id === id);
+        if (at === -1)
+            return false;
+        const cancelledRuns = [];
+        this.commitMutation(() => {
+            this.routines.splice(at, 1);
+            for (const run of this.runs) {
+                if (run.routineId !== id || run.status !== "queued")
+                    continue;
+                run.status = "cancelled";
+                run.attention = undefined;
+                run.finishedAt = this.now();
+                cancelledRuns.push(run);
+            }
+            if (request)
+                this.rememberRoutineRequest(request, id, this.now());
+        });
+        for (const run of cancelledRuns)
+            this.emitRun(run);
+        this.options.emit?.({ kind: "routine.deleted", routineId: id });
+        return true;
+    }
+    disableForBot(botId) {
+        let changed = false;
+        for (const routine of this.routines) {
+            if (routine.botId !== botId || !routine.enabled)
+                continue;
+            routine.enabled = false;
+            routine.nextRunAt = null;
+            routine.updatedAt = Math.max(this.now(), routine.updatedAt + 1);
+            this.emitRoutine(routine);
+            changed = true;
+        }
+        for (const run of this.runs) {
+            if (run.botId !== botId || !["queued", "running", "waiting"].includes(run.status))
+                continue;
+            run.status = "cancelled";
+            if (run.target === "room-goal")
+                run.goalStatus = "stopped";
+            run.attention = undefined;
+            run.finishedAt = this.now();
+            run.error = "The assigned bot was deleted";
+            this.emitRun(run);
+            if (run.threadId) {
+                if (run.target === "room-goal" && run.groupId) {
+                    void this.options.interruptGoal?.(run.groupId, run.threadId).catch(() => { });
+                }
+                else {
+                    void this.options.interruptTurn?.(run.botId, run.threadId, run.runOn ?? "maus").catch(() => { });
+                }
+            }
+            changed = true;
+        }
+        if (changed)
+            this.save();
+    }
+    disableForGroup(groupId) {
+        let changed = false;
+        for (const routine of this.routines) {
+            if (routine.target !== "room-goal" || routine.groupId !== groupId || !routine.enabled)
+                continue;
+            routine.enabled = false;
+            routine.nextRunAt = null;
+            routine.updatedAt = Math.max(this.now(), routine.updatedAt + 1);
+            this.emitRoutine(routine);
+            changed = true;
+        }
+        for (const run of this.runs) {
+            if (run.target !== "room-goal" ||
+                run.groupId !== groupId ||
+                !["queued", "running", "waiting"].includes(run.status))
+                continue;
+            run.status = "cancelled";
+            run.goalStatus = "stopped";
+            run.attention = undefined;
+            run.finishedAt = this.now();
+            run.error = "The assigned room was deleted";
+            this.emitRun(run);
+            if (run.threadId) {
+                void this.options.interruptGoal?.(groupId, run.threadId).catch(() => { });
+            }
+            changed = true;
+        }
+        if (changed)
+            this.save();
+    }
+    runNow(id, request) {
+        if (request) {
+            const receipt = this.matchingRoutineRequestReceipt(request);
+            if (receipt) {
+                const committed = this.runs.find((run) => run.id === receipt.resultId);
+                return committed ? cloneRun(committed) : null;
+            }
+        }
+        const routine = this.routines.find((r) => r.id === id);
+        if (!routine)
+            return null;
+        let run;
+        this.commitMutation(() => {
+            run = this.newRun(routine, this.now(), true);
+            // A chat-confirmed "run now" reports back to the conversation that
+            // invoked this one run. It must not silently rebind future schedules.
+            if (request)
+                run.sourceThreadId = request.threadId;
+            if (request)
+                this.rememberRoutineRequest(request, run.id, this.now());
+        });
+        this.emitRun(run);
+        queueMicrotask(() => void this.tick());
+        return cloneRun(run);
+    }
+    /** Queue an event-driven job without inventing a calendar schedule. Webhook
+     * definitions live in their own store; the execution receipt deliberately
+     * reuses this manager so busy-bot ordering, task creation and VM routing stay
+     * identical for every unattended job. */
+    enqueueWebhook(input) {
+        if (this.options.botState(input.botId) === "missing") {
+            throw Object.assign(new Error("The assigned MAUS no longer exists"), { status: 410 });
+        }
+        const run = {
+            id: randomUUID(),
+            routineId: input.webhookId,
+            routineName: input.webhookName,
+            prompt: input.prompt,
+            target: "bot",
+            botId: input.botId,
+            runOn: input.runOn,
+            scheduledFor: input.receivedAt,
+            status: "queued",
+            manual: false,
+            triggerSource: "webhook",
+            webhookId: input.webhookId,
+            deliveryId: input.deliveryId,
+            attachments: [],
+            createdAt: this.now(),
+        };
+        this.runs.push(run);
+        this.save();
+        this.emitRun(run);
+        queueMicrotask(() => void this.tick());
+        return cloneRun(run);
+    }
+    activeWebhookRunCount(webhookId) {
+        return this.runs.filter((run) => run.webhookId === webhookId && ["queued", "running", "waiting"].includes(run.status)).length;
+    }
+    cancelQueuedWebhook(webhookId, message) {
+        let changed = false;
+        for (const run of this.runs) {
+            if (run.webhookId !== webhookId || run.status !== "queued")
+                continue;
+            run.status = "cancelled";
+            run.attention = undefined;
+            run.finishedAt = this.now();
+            run.error = message.slice(0, 500);
+            this.emitRun(run);
+            changed = true;
+        }
+        if (changed)
+            this.save();
+    }
+    async cancelRun(id) {
+        const run = this.runs.find((r) => r.id === id);
+        if (!run || !["queued", "running", "waiting"].includes(run.status))
+            return null;
+        run.status = "cancelled";
+        if (run.target === "room-goal")
+            run.goalStatus = "stopped";
+        run.attention = undefined;
+        run.finishedAt = this.now();
+        this.save();
+        this.emitRun(run);
+        if (run.threadId) {
+            if (run.target === "room-goal" && run.groupId) {
+                await this.options.interruptGoal?.(run.groupId, run.threadId).catch(() => { });
+            }
+            else {
+                await this.options.interruptTurn?.(run.botId, run.threadId, run.runOn ?? "maus").catch(() => { });
+            }
+        }
+        queueMicrotask(() => void this.tick());
+        return cloneRun(run);
+    }
+    markSeen(id) {
+        const run = this.runs.find((r) => r.id === id);
+        if (!run)
+            return null;
+        if (!run.seenAt) {
+            run.seenAt = this.now();
+            this.save();
+            this.emitRun(run);
+        }
+        return cloneRun(run);
+    }
+    start() {
+        if (this.timer)
+            return;
+        void this.tick();
+        this.timer = setInterval(() => void this.tick(), 10_000);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    async tick() {
+        if (this.ticking)
+            return;
+        this.ticking = true;
+        try {
+            const now = this.now();
+            for (const run of this.runs) {
+                if (!["running", "waiting"].includes(run.status) ||
+                    run.startedAt == null ||
+                    run.timeoutMinutes == null ||
+                    now - run.startedAt < run.timeoutMinutes * 60_000)
+                    continue;
+                const threadId = run.threadId;
+                const detail = `Stopped after reaching the ${run.timeoutMinutes}-minute run limit`;
+                if (run.target === "room-goal")
+                    run.goalStatus = "limit-reached";
+                this.failRun(run, detail);
+                if (!threadId)
+                    continue;
+                if (run.target === "room-goal" && run.groupId) {
+                    await this.options.interruptGoal?.(run.groupId, threadId, {
+                        status: "limit-reached",
+                        detail,
+                    }).catch(() => { });
+                }
+                else {
+                    await this.options.interruptTurn?.(run.botId, threadId, run.runOn ?? "maus").catch(() => { });
+                }
+            }
+            let changed = false;
+            const missedRuns = [];
+            for (const routine of this.routines) {
+                if (!routine.enabled || routine.nextRunAt == null || routine.nextRunAt > now)
+                    continue;
+                const pendingAt = routine.nextRunAt;
+                const late = now - pendingAt;
+                const scheduledFor = routine.schedule.type === "interval" && late <= CATCH_UP_MS
+                    ? latestIntervalOccurrence(routine.schedule, now) ?? pendingAt
+                    : pendingAt;
+                // One slow interval run must not build an unbounded queue of stale
+                // copies behind it. The series still advances on its original phase.
+                const overlapping = routine.schedule.type === "interval" && this.runs.some((run) => run.routineId === routine.id && ["queued", "running", "waiting"].includes(run.status));
+                if (!overlapping) {
+                    if (late > CATCH_UP_MS) {
+                        const missed = this.newRun(routine, scheduledFor, false);
+                        missed.status = "missed";
+                        missed.finishedAt = now;
+                        missed.error = "This computer was offline for more than 12 hours after the scheduled time";
+                        this.emitRun(missed);
+                        missedRuns.push(cloneRun(missed));
+                    }
+                    else {
+                        const run = this.newRun(routine, scheduledFor, false);
+                        this.emitRun(run);
+                    }
+                }
+                routine.nextRunAt =
+                    routine.schedule.type === "once" ? null : nextOccurrence(routine.schedule, Math.max(now, scheduledFor));
+                // `updatedAt` is the optimistic definition revision carried by
+                // routine confirmation cards. Moving the scheduler cursor is runtime
+                // progress, not a definition edit, so recurring ticks must not make a
+                // still-accurate pending confirmation stale. A one-time routine does
+                // mutate its definition by auto-disabling after its occurrence.
+                if (routine.schedule.type === "once") {
+                    routine.enabled = false;
+                    routine.updatedAt = Math.max(now, routine.updatedAt + 1);
+                }
+                this.emitRoutine(routine);
+                changed = true;
+            }
+            if (changed)
+                this.save();
+            for (const missed of missedRuns)
+                this.options.onRunFailed?.(missed);
+            for (const run of [...this.runs].reverse()) {
+                if (run.status !== "queued")
+                    continue;
+                // A queued interval represents the latest useful check, not a backlog
+                // item. If the bot stayed busy across later occurrences, align this
+                // scheduled receipt to the newest due point immediately before it can
+                // dispatch. Manual runs and webhook deliveries retain their exact
+                // requested/received timestamps.
+                const triggerSource = run.triggerSource ?? (run.manual ? "manual" : "schedule");
+                const definition = triggerSource === "schedule"
+                    ? this.routines.find((routine) => routine.id === run.routineId)
+                    : undefined;
+                if (definition?.schedule.type === "interval") {
+                    const latest = latestIntervalOccurrence(definition.schedule, now);
+                    if (latest !== null && latest > run.scheduledFor) {
+                        run.scheduledFor = latest;
+                        this.save();
+                        this.emitRun(run);
+                    }
+                }
+                const state = this.targetState(run);
+                if (state === "busy")
+                    continue;
+                if (state === "missing") {
+                    this.failRun(run, this.missingTargetMessage(run.target));
+                    continue;
+                }
+                // A webhook is an incoming message, so make its task the bot's live
+                // chat immediately. Scheduled work remains detached and unobtrusive.
+                const task = run.target === "room-goal"
+                    ? run.groupId
+                        ? this.options.createGoalTask?.(run.groupId, run.routineName) ?? null
+                        : null
+                    : this.options.createTask(run.botId, run.routineName, run.triggerSource === "webhook");
+                if (!task) {
+                    this.failRun(run, run.target === "room-goal"
+                        ? "Could not create a room task for this goal"
+                        : "Could not create a task for this run");
+                    continue;
+                }
+                run.threadId = task.threadId;
+                run.startedAt = this.now();
+                run.status = "running";
+                this.save();
+                this.emitRun(run);
+                try {
+                    const prompt = run.prompt ?? this.routines.find((r) => r.id === run.routineId)?.prompt;
+                    if (!prompt) {
+                        this.failThread(task.threadId, "The routine was deleted before it could start");
+                        continue;
+                    }
+                    const triggerSource = run.triggerSource ?? (run.manual ? "manual" : "schedule");
+                    if (run.target === "room-goal") {
+                        if (!run.groupId || !this.options.startGoal) {
+                            this.failThread(task.threadId, "Room goal routines are unavailable");
+                            continue;
+                        }
+                        await this.options.startGoal(run.groupId, task.threadId, prompt, run.botId, run.id, (message) => this.failThread(task.threadId, message));
+                    }
+                    else {
+                        await this.options.startTurn(run.botId, task.threadId, composeExecutionPrompt(prompt, run.attachments), run.runOn ?? "maus", triggerSource, (message) => this.failThread(task.threadId, message));
+                    }
+                }
+                catch (error) {
+                    this.failThread(task.threadId, error instanceof Error ? error.message : String(error));
+                }
+            }
+        }
+        finally {
+            this.ticking = false;
+        }
+    }
+    handleRuntimeEvent(event) {
+        const run = this.runs.find((r) => r.threadId === event.threadId && ["running", "waiting"].includes(r.status));
+        if (!run)
+            return null;
+        // A room goal contains several provider turns. Its orchestrator owns the
+        // terminal decision and reports it through finishGoalRun; one member's
+        // completion and private coordinator envelope are only intermediate
+        // protocol, never the routine receipt's result.
+        if (run.target === "room-goal" &&
+            (event.type === "turn.completed" || (event.type === "item.completed" && event.itemType === "assistant_text")))
+            return null;
+        if (event.type === "request.opened") {
+            run.status = "waiting";
+            run.attention = redactSecretsInText(event.summary).trim().slice(0, 500) || undefined;
+        }
+        else if (event.type === "request.resolved") {
+            run.status = "running";
+            run.attention = undefined;
+        }
+        else if (event.type === "item.completed" && event.itemType === "assistant_text") {
+            run.output = redactSecretsInText(event.text).trim().slice(0, 2_000);
+        }
+        else if (event.type === "runtime.error") {
+            run.error = redactSecretsInText(event.message).slice(0, 500);
+        }
+        else if (event.type === "turn.retrying") {
+            // the driver will relaunch this same run; a transient blip is not a
+            // receipt-worthy failure, so keep the run running and stay quiet
+            return null;
+        }
+        else if (event.type === "turn.completed") {
+            run.cost = event.cost;
+            run.denials = event.denials;
+            if (!event.ok) {
+                this.failRun(run, event.stopReason ?? run.error ?? "The bot did not complete this run");
+                queueMicrotask(() => void this.tick());
+                return cloneRun(run);
+            }
+            run.status = "completed";
+            run.attention = undefined;
+            run.finishedAt = this.now();
+            run.error = undefined;
+        }
+        else {
+            return null;
+        }
+        this.save();
+        this.emitRun(run);
+        if (event.type === "turn.completed")
+            queueMicrotask(() => void this.tick());
+        return cloneRun(run);
+    }
+    failThread(threadId, message) {
+        const run = this.runs.find((r) => r.threadId === threadId && ["running", "waiting"].includes(r.status));
+        if (!run)
+            return;
+        this.failRun(run, message);
+        queueMicrotask(() => void this.tick());
+    }
+    finishGoalRun(runId, status, detail) {
+        const run = this.runs.find((candidate) => candidate.id === runId &&
+            candidate.target === "room-goal" &&
+            ["running", "waiting"].includes(candidate.status));
+        if (!run || status === "working")
+            return null;
+        const safeDetail = redactSecretsInText(detail).trim();
+        run.goalStatus = status;
+        // Only a completed goal is a completed run. A team asking the human a
+        // question is still waiting on them, and a blocked or turn-capped goal
+        // did not finish — reporting either as "completed" would silence the
+        // one outcome that most needs a person's attention.
+        if (status === "failed" || status === "blocked" || status === "limit-reached") {
+            this.failRun(run, safeDetail ||
+                (status === "limit-reached" ? "The room goal reached its turn limit" : "The room goal is blocked"));
+        }
+        else if (status === "needs-input" || status === "paused") {
+            run.status = "waiting";
+            run.attention = safeDetail.slice(0, 500) || (status === "paused" ? "The room goal is paused" : "The team needs your input");
+            run.error = undefined;
+            this.save();
+            this.emitRun(run);
+        }
+        else {
+            run.status = status === "stopped" ? "cancelled" : "completed";
+            run.attention = undefined;
+            run.finishedAt = this.now();
+            run.error = undefined;
+            if (status !== "stopped")
+                run.output = safeDetail.slice(0, 2_000) || undefined;
+            this.save();
+            this.emitRun(run);
+        }
+        queueMicrotask(() => void this.tick());
+        return cloneRun(run);
+    }
+    failRun(run, message) {
+        run.status = "failed";
+        run.attention = undefined;
+        run.error = redactSecretsInText(message).slice(0, 500);
+        run.finishedAt = this.now();
+        this.save();
+        this.emitRun(run);
+        this.options.onRunFailed?.(cloneRun(run));
+    }
+    targetState(target) {
+        if (target.target === "room-goal") {
+            if (!target.groupId || !this.options.goalState)
+                return "missing";
+            return this.options.goalState(target.groupId, target.botId);
+        }
+        return this.options.botState(target.botId);
+    }
+    missingTargetMessage(target) {
+        return target === "room-goal"
+            ? "The assigned room or coordinator no longer exists"
+            : "The assigned bot no longer exists";
+    }
+    initialOccurrence(schedule, now) {
+        // Return the original time, not max(at, now): tick() already decides
+        // whether a stale "once" run fires or is recorded as "missed" based on
+        // how far past the scheduled time it is. Clamping to now here hides the
+        // original schedule from the run receipt (scheduledFor would read "now"
+        // instead of the time the user chose) and prevents the 12-hour missed
+        // threshold from ever triggering for a "once" routine created late.
+        if (schedule.type === "once")
+            return schedule.at;
+        return nextOccurrence(schedule, now);
+    }
+    newRun(routine, scheduledFor, manual) {
+        const run = {
+            id: randomUUID(),
+            routineId: routine.id,
+            routineName: routine.name,
+            prompt: routine.prompt,
+            durationMinutes: routine.durationMinutes,
+            ...(routine.timeoutMinutes === undefined ? {} : { timeoutMinutes: routine.timeoutMinutes }),
+            attachments: cloneAttachments(routine.attachments),
+            target: routine.target,
+            groupId: routine.groupId,
+            botId: routine.botId,
+            runOn: routine.runOn ?? "maus",
+            scheduledFor,
+            status: "queued",
+            manual,
+            triggerSource: manual ? "manual" : "schedule",
+            sourceThreadId: routine.sourceThreadId,
+            createdAt: this.now(),
+        };
+        this.runs.push(run);
+        return run;
+    }
+    emitRoutine(routine) {
+        this.options.emit?.({ kind: "routine", routine: cloneRoutine(routine) });
+    }
+    emitRun(run) {
+        this.options.emit?.({ kind: "routine.run", run: cloneRun(run) });
+        this.notifyRunChanged(run);
+    }
+    notifyRunChanged(run) {
+        try {
+            this.options.onRunChanged?.(cloneRun(run));
+        }
+        catch (error) {
+            // Reporting is secondary to scheduler truth. A transcript write must
+            // never strand the run in memory or prevent the next tick.
+            console.error("routine: source-thread lifecycle update failed", error);
+        }
+    }
+    matchingRoutineRequestReceipt(request) {
+        const receipt = this.routineRequestReceipts.find((candidate) => candidate.requestId === request.requestId);
+        if (!receipt)
+            return null;
+        if (receipt.action !== request.action ||
+            receipt.messageId !== request.messageId ||
+            receipt.botId !== request.botId ||
+            receipt.threadId !== request.threadId ||
+            receipt.fingerprintVersion !== request.fingerprintVersion ||
+            receipt.fingerprint !== request.fingerprint) {
+            throw new Error("Routine request receipt does not match this confirmation card");
+        }
+        return receipt;
+    }
+    rememberRoutineRequest(request, resultId, appliedAt) {
+        const existing = this.matchingRoutineRequestReceipt(request);
+        if (existing) {
+            if (existing.resultId !== resultId)
+                throw new Error("Routine request receipt has another result");
+            return;
+        }
+        this.routineRequestReceipts.unshift({ ...request, resultId, appliedAt });
+    }
+    /**
+     * A confirmation receipt is only true once the scheduler mutation and its
+     * receipt reached the same atomic file. Restore the complete in-memory
+     * state if writing or renaming that file fails so a retry cannot mistake an
+     * uncommitted action for a durable one.
+     */
+    commitMutation(mutate) {
+        const before = {
+            routines: this.routines.map(cloneRoutine),
+            runs: this.runs.map(cloneRun),
+            receipts: this.routineRequestReceipts.map((receipt) => ({ ...receipt })),
+        };
+        try {
+            mutate();
+            this.save();
+        }
+        catch (error) {
+            this.routines = before.routines;
+            this.runs = before.runs;
+            this.routineRequestReceipts = before.receipts;
+            throw error;
+        }
+    }
+    save() {
+        // Active receipts own cancellation, timeout, and provider-event routing;
+        // evicting one would strand live work. Treat MAX_RUNS as a soft history
+        // cap and reclaim only the oldest terminal receipts. An unusually large
+        // active queue may exceed it until work settles.
+        let excess = this.runs.length - MAX_RUNS;
+        for (let index = 0; index < this.runs.length && excess > 0;) {
+            if (["queued", "running", "waiting"].includes(this.runs[index].status)) {
+                index += 1;
+                continue;
+            }
+            this.runs.splice(index, 1);
+            excess -= 1;
+        }
+        mkdirSync(dirname(this.file), { recursive: true });
+        writeFileAtomic(this.file, JSON.stringify({
+            version: 1,
+            routines: this.routines,
+            runs: this.runs,
+            routineRequestReceipts: this.routineRequestReceipts,
+        }, null, 2), { mode: 0o600 });
+    }
+}