openmausbot 0.1.67 → 0.1.69

package/dist-server/server/routines.js

@@ -12,6 +12,9 @@ function routineRequestOwnerKey(owner) {
 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 LOCAL_DAY_MS = 24 * 60 * 60_000;
+const INTERVAL_RESTRICTION_SEARCH_MS = 9 * LOCAL_DAY_MS;
+const CLOCK_TIME = /^([01]\d|2[0-3]):([0-5]\d)$/;
 const MAX_RUNS = 2_000;
 const MAX_ATTACHMENTS = 50;
 const attachmentSchema = z.object({
@@ -86,7 +89,14 @@ 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: "interval",
+            everyMinutes: schedule.everyMinutes,
+            anchorAt: schedule.anchorAt,
+            ...(schedule.weekdays ? { weekdays: [...schedule.weekdays] } : {}),
+            ...(schedule.window ? { window: { ...schedule.window } } : {}),
+            ...(schedule.endsAt === undefined ? {} : { endsAt: schedule.endsAt }),
+        };
     }
     return { type: "daily", time: schedule.time, weekdays: [...schedule.weekdays] };
 }
@@ -164,6 +174,57 @@ function composeExecutionPrompt(prompt, attachments, carry) {
     }
     return parts.filter(Boolean).join("\n\n");
 }
+function cleanIntervalWeekdays(value) {
+    if (value == null)
+        return undefined;
+    if (!Array.isArray(value) || value.length === 0 || value.length > ALL_DAYS.length) {
+        throw new Error("Choose at least one valid interval day");
+    }
+    if (value.some((day) => typeof day !== "number" || !Number.isInteger(day) || day < 0 || day > 6)) {
+        throw new Error("Interval days must be whole numbers from 0 to 6");
+    }
+    if (new Set(value).size !== value.length)
+        throw new Error("Choose each interval day only once");
+    const weekdays = [...value].sort((a, b) => a - b);
+    return weekdays.length === ALL_DAYS.length ? undefined : weekdays;
+}
+function clockMinutes(value) {
+    const match = CLOCK_TIME.exec(value);
+    return match ? Number(match[1]) * 60 + Number(match[2]) : null;
+}
+function cleanIntervalWindow(value, everyMinutes) {
+    if (value == null)
+        return undefined;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Choose a valid interval time window");
+    }
+    const candidate = value;
+    const start = typeof candidate.start === "string" ? candidate.start : "";
+    const end = typeof candidate.end === "string" ? candidate.end : "";
+    const startMinutes = clockMinutes(start);
+    const endMinutes = clockMinutes(end);
+    if (startMinutes == null || endMinutes == null) {
+        throw new Error("Interval window times must use HH:MM");
+    }
+    if (startMinutes >= endMinutes) {
+        throw new Error("Interval window must start before it ends on the same day");
+    }
+    if (endMinutes - startMinutes < everyMinutes) {
+        throw new Error("Interval window must be at least as long as the interval");
+    }
+    return { start, end };
+}
+function cleanIntervalEndsAt(value, anchorAt) {
+    if (value == null)
+        return undefined;
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value < anchorAt ||
+        value > MAX_DATE_MS) {
+        throw new Error("Choose a valid interval end time after its start");
+    }
+    return value;
+}
 function finishedOrder(run) {
     return run.finishedAt ?? run.createdAt;
 }
@@ -191,7 +252,17 @@ function cleanSchedule(schedule) {
             anchorAt > MAX_DATE_MS) {
             throw new Error("Choose a valid interval start time");
         }
-        return { type: "interval", everyMinutes, anchorAt };
+        const weekdays = cleanIntervalWeekdays(schedule.weekdays);
+        const window = cleanIntervalWindow(schedule.window, everyMinutes);
+        const endsAt = cleanIntervalEndsAt(schedule.endsAt, anchorAt);
+        return {
+            type: "interval",
+            everyMinutes,
+            anchorAt,
+            ...(weekdays ? { weekdays } : {}),
+            ...(window ? { window } : {}),
+            ...(endsAt === undefined ? {} : { endsAt }),
+        };
     }
     throw new Error("Choose a supported schedule");
 }
@@ -203,17 +274,56 @@ function loadSchedule(value) {
         return null;
     }
 }
+function intervalHasRestrictions(schedule) {
+    return schedule.weekdays !== undefined || schedule.window !== undefined || schedule.endsAt !== undefined;
+}
+function intervalAllowsOccurrence(schedule, at) {
+    if (schedule.endsAt !== undefined && at > schedule.endsAt)
+        return false;
+    const date = new Date(at);
+    if (schedule.weekdays && !schedule.weekdays.includes(date.getDay()))
+        return false;
+    if (schedule.window) {
+        const minute = date.getHours() * 60 + date.getMinutes();
+        const start = clockMinutes(schedule.window.start);
+        const end = clockMinutes(schedule.window.end);
+        if (minute < start || minute >= end)
+            return false;
+    }
+    return true;
+}
+function isSameLocalDay(left, right) {
+    const a = new Date(left);
+    const b = new Date(right);
+    return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+}
+function nextAlignedInterval(schedule, after) {
+    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;
+}
 /** 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;
+        let candidate = nextAlignedInterval(schedule, after);
+        if (!intervalHasRestrictions(schedule))
+            return candidate;
+        const maxCandidates = Math.ceil(INTERVAL_RESTRICTION_SEARCH_MS / intervalMs) + 2;
+        for (let checked = 0; candidate !== null && checked < maxCandidates; checked++) {
+            if (schedule.endsAt !== undefined && candidate > schedule.endsAt)
+                return null;
+            if (intervalAllowsOccurrence(schedule, candidate))
+                return candidate;
+            const next = candidate + intervalMs;
+            candidate = Number.isSafeInteger(next) && next <= MAX_DATE_MS ? next : null;
+        }
+        return null;
     }
     const [hour, minute] = schedule.time.split(":").map(Number);
     const weekdays = new Set(cleanDays(schedule.weekdays));
@@ -227,10 +337,38 @@ export function nextOccurrence(schedule, after) {
     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;
+    const ceiling = Math.min(at, schedule.endsAt ?? at);
+    if (schedule.anchorAt > ceiling)
+        return null;
+    let candidate = schedule.anchorAt + Math.floor((ceiling - schedule.anchorAt) / intervalMs) * intervalMs;
+    if (!intervalHasRestrictions(schedule))
+        return candidate;
+    const maxCandidates = Math.ceil(INTERVAL_RESTRICTION_SEARCH_MS / intervalMs) + 2;
+    for (let checked = 0; checked < maxCandidates; checked++) {
+        if (intervalAllowsOccurrence(schedule, candidate))
+            return candidate;
+        const previous = candidate - intervalMs;
+        if (!Number.isSafeInteger(previous) || previous < schedule.anchorAt)
+            return null;
+        candidate = previous;
+    }
+    return null;
+}
+function mergeScheduleUpdate(current, incoming) {
+    if (current.type !== "interval" || incoming.type !== "interval")
+        return incoming;
+    const merged = { ...incoming };
+    if (!Object.hasOwn(incoming, "weekdays") && current.weekdays) {
+        merged.weekdays = [...current.weekdays];
+    }
+    if (!Object.hasOwn(incoming, "window") && current.window) {
+        merged.window = { ...current.window };
+    }
+    if (!Object.hasOwn(incoming, "endsAt") && current.endsAt !== undefined) {
+        merged.endsAt = current.endsAt;
+    }
+    return merged;
 }
 function sanitizeInput(input) {
     const name = String(input.name ?? "").trim().slice(0, 80);
@@ -449,6 +587,10 @@ export class RoutineManager {
     isActiveThread(threadId) {
         return this.runs.some((run) => run.threadId === threadId && ["running", "waiting"].includes(run.status));
     }
+    runForThread(threadId) {
+        const run = this.runs.find((candidate) => candidate.threadId === threadId);
+        return run ? cloneRun(run) : null;
+    }
     create(input, request) {
         if (request) {
             const receipt = this.matchingRoutineRequestReceipt(request);
@@ -463,13 +605,17 @@ export class RoutineManager {
         if (this.targetState(clean) === "missing")
             throw new Error(this.missingTargetMessage(clean.target));
         const at = this.now();
+        const nextRunAt = clean.enabled ? this.initialOccurrence(clean.schedule, at) : null;
+        if (clean.schedule.type === "interval" && clean.enabled && nextRunAt === null) {
+            throw new Error("This interval has no future runs. Choose a later end date or turn it off.");
+        }
         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,
+            nextRunAt,
             createdAt: at,
             updatedAt: at,
         };
@@ -501,7 +647,7 @@ export class RoutineManager {
             groupId: Object.hasOwn(patch, "groupId") ? patch.groupId : routine.groupId,
             runOn: patch.runOn ?? routine.runOn,
             enabled: patch.enabled ?? routine.enabled,
-            schedule: patch.schedule ?? routine.schedule,
+            schedule: patch.schedule ? mergeScheduleUpdate(routine.schedule, patch.schedule) : routine.schedule,
             durationMinutes: patch.durationMinutes ?? routine.durationMinutes,
             timeoutMinutes: Object.hasOwn(patch, "timeoutMinutes") ? patch.timeoutMinutes : routine.timeoutMinutes,
             attachments: patch.attachments ?? routine.attachments,
@@ -509,10 +655,19 @@ export class RoutineManager {
         });
         if (this.targetState(clean) === "missing")
             throw new Error(this.missingTargetMessage(clean.target));
+        const scheduleChanged = JSON.stringify(clean.schedule) !== JSON.stringify(routine.schedule);
+        const enabledChanged = clean.enabled !== routine.enabled;
+        // Definition-only edits retain due work and offline catch-up.
+        const nextRunAt = !clean.enabled ? null : scheduleChanged || enabledChanged
+            ? this.initialOccurrence(clean.schedule, now)
+            : routine.nextRunAt;
+        if (clean.schedule.type === "interval" && clean.enabled && nextRunAt === null) {
+            throw new Error("This interval has no future runs. Choose a later end date or turn it off.");
+        }
         const cancelledRuns = [];
         this.commitMutation(() => {
             Object.assign(routine, clean, {
-                nextRunAt: clean.enabled ? this.initialOccurrence(clean.schedule, now) : null,
+                nextRunAt,
                 // `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),
@@ -861,6 +1016,10 @@ export class RoutineManager {
                     routine.enabled = false;
                     routine.updatedAt = Math.max(now, routine.updatedAt + 1);
                 }
+                else if (routine.schedule.type === "interval" && routine.nextRunAt === null) {
+                    routine.enabled = false;
+                    routine.updatedAt = Math.max(now, routine.updatedAt + 1);
+                }
                 this.emitRoutine(routine);
                 changed = true;
             }
@@ -868,7 +1027,10 @@ export class RoutineManager {
                 this.save();
             for (const missed of missedRuns)
                 this.options.onRunFailed?.(missed);
-            for (const run of [...this.runs].reverse()) {
+            // Oldest queued requests have priority. New manual/webhook arrivals
+            // must not continually overtake work that has already waited. Snapshot
+            // the queue because each dispatch can asynchronously add/cancel work.
+            for (const run of this.runs.slice()) {
                 if (run.status !== "queued")
                     continue;
                 // A queued interval represents the latest useful check, not a backlog
@@ -887,6 +1049,15 @@ export class RoutineManager {
                         this.save();
                         this.emitRun(run);
                     }
+                    const requiresCurrentDayOccurrence = definition.schedule.weekdays !== undefined || definition.schedule.window !== undefined;
+                    const mayDispatch = intervalAllowsOccurrence(definition.schedule, now) &&
+                        (!requiresCurrentDayOccurrence || (latest !== null && isSameLocalDay(latest, now)));
+                    if (!mayDispatch) {
+                        if (nextOccurrence(definition.schedule, now) === null) {
+                            this.missQueuedRun(run, "The routine ended before this scheduled run could start");
+                        }
+                        continue;
+                    }
                 }
                 const state = this.targetState(run);
                 if (state === "busy")
@@ -949,9 +1120,19 @@ export class RoutineManager {
         // 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")))
+            (
+            // These outcomes ended the goal operation. Later room traffic is
+            // not a resume of that run; only the goal lifecycle can change its
+            // receipt. In-flight provider approvals have no goalStatus and
+            // continue to resolve normally below.
+            run.goalStatus === "needs-input" || run.goalStatus === "paused" ||
+                event.type === "turn.completed" || (event.type === "item.completed" && event.itemType === "assistant_text")))
             return null;
-        if (event.type === "request.opened") {
+        if (event.type === "turn.started") {
+            run.status = "running";
+            run.attention = undefined;
+        }
+        else if (event.type === "request.opened") {
             run.status = "waiting";
             run.attention = redactSecretsInText(event.summary).trim().slice(0, 500) || undefined;
         }
@@ -971,16 +1152,20 @@ export class RoutineManager {
             return null;
         }
         else if (event.type === "turn.completed") {
-            run.cost = event.cost;
-            run.denials = event.denials;
+            if (event.cost != null)
+                run.cost = (run.cost ?? 0) + event.cost;
+            if (event.denials?.length)
+                run.denials = [...new Set([...(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();
+            const pending = this.options.hasPendingDelegations?.(event.threadId) === true;
+            run.status = pending ? "waiting" : "completed";
+            run.attention = pending ? "Waiting for delegated work to finish" : undefined;
+            if (!pending)
+                run.finishedAt = this.now();
             run.error = undefined;
         }
         else {
@@ -1044,6 +1229,15 @@ export class RoutineManager {
         this.emitRun(run);
         this.options.onRunFailed?.(cloneRun(run));
     }
+    missQueuedRun(run, message) {
+        run.status = "missed";
+        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)

package/dist-server/server/service-cli.js

@@ -0,0 +1,63 @@
+// The `openmausbot service` command, kept separate from cli.ts so it can be
+// tested with explicit inputs: it renders the unit for this platform, writes
+// it next to the data, and prints the commands that install it.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { currentUser, launchdPlist, servicePlan, systemdUnit, unstableInstallWarning } from "./service-unit.js";
+/** The `serve` arguments the service repeats, from the options given to `service install`. */
+export function serviceServeArgs(input) {
+    const args = ["--port", String(input.port), "--data-dir", input.dataDir, "--no-pair"];
+    if (input.domain)
+        args.push("--domain", input.domain);
+    else if (input.tunnel)
+        args.push("--tunnel");
+    else if (input.tailscale)
+        args.push("--tailscale");
+    if (input.label)
+        args.push("--label", input.label);
+    return args;
+}
+export function runServiceCommand(input, io) {
+    const platform = input.platform ?? process.platform;
+    const home = input.home ?? homedir();
+    const plan = servicePlan(platform, input.dataDir, home);
+    if (!plan) {
+        io.error("services are written for Linux (systemd) and macOS (launchd); on Windows, use Task Scheduler to run `openmausbot serve` at startup");
+        return 1;
+    }
+    if (input.action === "uninstall") {
+        io.log(`to stop and remove the service:`);
+        for (const line of plan.deactivate)
+            io.log(`  ${line}`);
+        return 0;
+    }
+    const warning = unstableInstallWarning(input.script);
+    if (warning) {
+        io.error(warning);
+        return 1;
+    }
+    const spec = {
+        node: input.node,
+        script: input.script,
+        serveArgs: serviceServeArgs(input),
+        dataDir: input.dataDir,
+        user: input.user ?? currentUser(),
+        home,
+        bindsLowPorts: Boolean(input.domain),
+        ...(input.label ? { label: input.label } : {}),
+    };
+    const rendered = platform === "darwin" ? launchdPlist(spec) : systemdUnit(spec);
+    mkdirSync(input.dataDir, { recursive: true, mode: 0o700 });
+    writeFileSync(plan.file, rendered, { mode: 0o644 });
+    io.log(`wrote ${plan.file}`);
+    io.log("");
+    io.log(platform === "darwin" ? "to install and start it (runs at login):" : "to install and start it (runs at boot, restarts if it stops):");
+    for (const line of plan.activate)
+        io.log(`  ${line}`);
+    io.log("");
+    if (input.domain && platform === "linux")
+        io.log("the unit grants Caddy the capability for ports 80 and 443, so no setcap is needed under the service");
+    io.log(`logs: ${platform === "darwin" ? `${input.dataDir}/logs/service.log` : "journalctl -u openmausbot -f"}`);
+    io.log(`change options later by running \`openmausbot service install\` again with the new ones, then: ${platform === "darwin" ? plan.activate[1] : "sudo systemctl daemon-reload && sudo systemctl restart openmausbot"}`);
+    return 0;
+}

package/dist-server/server/service-unit.js

@@ -0,0 +1,129 @@
+// `openmausbot service install`: keep the server running across reboots.
+// Renders a systemd unit (Linux) or a launchd agent (macOS) that runs the
+// same `openmausbot serve …` the operator just used, and either installs it
+// (when allowed to) or writes it next to the data and prints the two
+// commands that install it. Pure rendering lives here so it is testable;
+// the CLI decides where the file goes.
+import { homedir, userInfo } from "node:os";
+import { posix } from "node:path";
+// Unit files describe a Linux or macOS machine, so their paths are POSIX
+// whatever host renders them (the Windows CI runner included).
+const { basename, dirname, join } = posix;
+export const SYSTEMD_UNIT_NAME = "openmausbot.service";
+export const LAUNCHD_LABEL = "com.openmausbot.serve";
+function quoteSystemd(value) {
+    // systemd's ExecStart splits on whitespace and understands double quotes.
+    return /[\s"\\]/.test(value) ? `"${value.replace(/[\\"]/g, "\\$&")}"` : value;
+}
+function needsStripTypes(script) {
+    return script.endsWith(".ts");
+}
+export function serviceCommand(spec) {
+    return [spec.node, ...(needsStripTypes(spec.script) ? ["--experimental-strip-types"] : []), spec.script, "serve", ...spec.serveArgs];
+}
+export function systemdUnit(spec) {
+    const lines = [
+        "# Written by `openmausbot service install`. Re-run it to change the options.",
+        "[Unit]",
+        `Description=OpenMausBot${spec.label ? ` (${spec.label})` : ""}`,
+        "After=network-online.target",
+        "Wants=network-online.target",
+        "",
+        "[Service]",
+        "Type=simple",
+        `User=${spec.user}`,
+        `WorkingDirectory=${spec.home}`,
+        `Environment=HOME=${spec.home}`,
+        `Environment=OMB_DATA_DIR=${spec.dataDir}`,
+        `ExecStart=${serviceCommand(spec).map(quoteSystemd).join(" ")}`,
+        "Restart=always",
+        "RestartSec=3",
+        "KillMode=mixed",
+        "TimeoutStopSec=30",
+    ];
+    if (spec.bindsLowPorts) {
+        lines.push("# serve --domain: Caddy binds ports 80 and 443 without running as root.");
+        lines.push("AmbientCapabilities=CAP_NET_BIND_SERVICE");
+        lines.push("CapabilityBoundingSet=CAP_NET_BIND_SERVICE");
+    }
+    lines.push("", "[Install]", "WantedBy=multi-user.target", "");
+    return lines.join("\n");
+}
+function xml(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+export function launchdPlist(spec) {
+    const args = serviceCommand(spec).map((arg) => `\t\t<string>${xml(arg)}</string>`).join("\n");
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        "<dict>",
+        "\t<key>Label</key>",
+        `\t<string>${LAUNCHD_LABEL}</string>`,
+        "\t<key>ProgramArguments</key>",
+        "\t<array>",
+        args,
+        "\t</array>",
+        "\t<key>EnvironmentVariables</key>",
+        "\t<dict>",
+        "\t\t<key>HOME</key>",
+        `\t\t<string>${xml(spec.home)}</string>`,
+        "\t\t<key>OMB_DATA_DIR</key>",
+        `\t\t<string>${xml(spec.dataDir)}</string>`,
+        "\t\t<key>PATH</key>",
+        "\t\t<string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>",
+        "\t</dict>",
+        "\t<key>WorkingDirectory</key>",
+        `\t<string>${xml(spec.home)}</string>`,
+        "\t<key>RunAtLoad</key>",
+        "\t<true/>",
+        "\t<key>KeepAlive</key>",
+        "\t<true/>",
+        "\t<key>StandardOutPath</key>",
+        `\t<string>${xml(join(spec.dataDir, "logs", "service.log"))}</string>`,
+        "\t<key>StandardErrorPath</key>",
+        `\t<string>${xml(join(spec.dataDir, "logs", "service.log"))}</string>`,
+        "</dict>",
+        "</plist>",
+        "",
+    ].join("\n");
+}
+/** An `npx` cache path is pruned without notice; a service must not point at it. */
+export function unstableInstallWarning(script) {
+    const normalized = script.replace(/\\/g, "/");
+    if (/\/_npx\//.test(normalized) || /\/\.npm\/_npx\//.test(normalized)) {
+        return `this command runs from an npx cache (${dirname(script)}), which npm may delete at any time. Install it permanently first (npm install -g openmausbot) and run \`openmausbot service install\` from that install.`;
+    }
+    return null;
+}
+/** Where the rendered file goes and how to activate it, per platform. */
+export function servicePlan(platform, dataDir, home = homedir()) {
+    if (platform === "linux") {
+        const installed = `/etc/systemd/system/${SYSTEMD_UNIT_NAME}`;
+        return {
+            file: join(dataDir, SYSTEMD_UNIT_NAME),
+            installed,
+            activate: [`sudo install -m 644 ${join(dataDir, SYSTEMD_UNIT_NAME)} ${installed}`, "sudo systemctl daemon-reload", `sudo systemctl enable --now ${basename(SYSTEMD_UNIT_NAME, ".service")}`],
+            deactivate: [`sudo systemctl disable --now ${basename(SYSTEMD_UNIT_NAME, ".service")}`, `sudo rm ${installed}`, "sudo systemctl daemon-reload"],
+        };
+    }
+    if (platform === "darwin") {
+        const installed = join(home, "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
+        return {
+            file: join(dataDir, `${LAUNCHD_LABEL}.plist`),
+            installed,
+            activate: [`mkdir -p ${dirname(installed)} && cp ${join(dataDir, `${LAUNCHD_LABEL}.plist`)} ${installed}`, `launchctl bootstrap gui/$(id -u) ${installed}`],
+            deactivate: [`launchctl bootout gui/$(id -u)/${LAUNCHD_LABEL}`, `rm ${installed}`],
+        };
+    }
+    return null;
+}
+export function currentUser() {
+    try {
+        return userInfo().username;
+    }
+    catch {
+        return process.env.USER || process.env.USERNAME || "openmausbot";
+    }
+}

package/dist-server/server/steer-queue.js

@@ -18,6 +18,30 @@
 // the feature.
 import { newId } from "./contracts.js";
 const queues = new Map(); // threadId → waiting sends
+const listeners = new Set();
+const changed = () => {
+    for (const listener of listeners) {
+        try {
+            listener();
+        }
+        catch {
+            console.warn("steer-queue: change listener failed");
+        }
+    }
+};
+/** Public pending chips only: never expose provider prompts or reply context. */
+export function queuedSteerSnapshot(ownsThread) {
+    return Object.fromEntries([...queues]
+        .filter(([threadId, entry]) => ownsThread(entry.botId, threadId))
+        .map(([threadId, entry]) => [threadId, entry.items.map((item) => ({
+            queueId: item.messageId, text: item.text, ...(item.reason ? { reason: item.reason } : {}),
+        }))]));
+}
+/** Publish changes synchronously so every client can restore/cancel the queue. */
+export function onSteeredQueueChange(listener) {
+    listeners.add(listener);
+    return () => { listeners.delete(listener); };
+}
 /** Hold a mid-turn send off the transcript until drain. */
 export function queueSteeredMessage(botId, threadId, text, options = {}) {
     const id = newId();
@@ -32,8 +56,10 @@ export function queueSteeredMessage(botId, threadId, text, options = {}) {
         prompt: options.prompt ?? text,
         replyToId: options.replyToId,
         sendId: options.sendId,
+        reason: options.reason,
     });
     queues.set(threadId, entry);
+    changed();
     return { id };
 }
 /** Drain every queue whose task is idle: append the held lines (leaf is now
@@ -52,6 +78,7 @@ export function drainSteeredMessages(store, run, isBlocked) {
         if (!bot) {
             // the bot or task was deleted while messages waited
             queues.delete(threadId);
+            changed();
             continue;
         }
         if (bot.busy || isBlocked?.(entry.botId, threadId))
@@ -59,6 +86,7 @@ export function drainSteeredMessages(store, run, isBlocked) {
         // committed to draining: the entry leaves the map before anything runs,
         // so a settle racing another settle can never fire the same queue twice
         queues.delete(threadId);
+        changed();
         const appended = [];
         for (const item of entry.items) {
             // queueId is the pending-chip identity from the 202; append still
@@ -89,7 +117,7 @@ export function queuedSteeredMessage(botId, threadId, sendId) {
     if (!entry || entry.botId !== botId)
         return null;
     const item = entry.items.find((candidate) => candidate.sendId === sendId);
-    return item ? { id: item.messageId, text: item.text, replyToId: item.replyToId } : null;
+    return item ? { id: item.messageId, text: item.text, replyToId: item.replyToId, ...(item.reason ? { reason: item.reason } : {}) } : null;
 }
 /** Drop one waiting send owned by this bot so it never drains. The queue id
  * is stable even if the bot switches away from the task while the request is
@@ -106,6 +134,7 @@ export function cancelSteeredMessage(botId, messageId, expectedThreadId) {
             queues.delete(threadId);
         else
             queues.set(threadId, { botId: entry.botId, items });
+        changed();
         return true;
     }
     return false;