openmausbot 0.1.68 → 0.1.70

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);
@@ -311,6 +449,7 @@ export class RoutineManager {
                         timeoutMinutes: loadTimeoutMinutes(routine.timeoutMinutes),
                         attachments: loadAttachments(routine.attachments),
                         sourceThreadId: persistedSourceThreadId.parse(routine.sourceThreadId),
+                        resultsThreadId: persistedSourceThreadId.parse(routine.resultsThreadId),
                     };
                     if (loaded.timeoutMinutes === undefined)
                         delete loaded.timeoutMinutes;
@@ -329,6 +468,7 @@ export class RoutineManager {
                         timeoutMinutes: loadTimeoutMinutes(run.timeoutMinutes),
                         attachments: loadAttachments(run.attachments),
                         sourceThreadId: persistedSourceThreadId.parse(run.sourceThreadId),
+                        resultsThreadId: persistedSourceThreadId.parse(run.resultsThreadId),
                     };
                     if (loaded.timeoutMinutes === undefined)
                         delete loaded.timeoutMinutes;
@@ -467,21 +607,26 @@ 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,
         };
+        const discardResults = this.applyResultsInput(routine, input.resultsThreadId);
         this.commitMutation(() => {
             this.routines.unshift(routine);
             if (request)
                 this.rememberRoutineRequest(request, routine.id, at);
-        });
+        }, discardResults);
         this.emitRoutine(routine);
         return cloneRoutine(routine);
     }
@@ -505,7 +650,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,
@@ -513,16 +658,24 @@ export class RoutineManager {
         });
         if (this.targetState(clean) === "missing")
             throw new Error(this.missingTargetMessage(clean.target));
-        const cancelledRuns = [];
         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 destination = { ...routine, ...clean };
+        if (destination.botId !== routine.botId)
+            delete destination.resultsThreadId;
+        const discardResults = this.applyResultsInput(destination, patch.resultsThreadId);
+        const cancelledRuns = [];
         this.commitMutation(() => {
             Object.assign(routine, clean, {
-                // Renaming/editing instructions must not skip an occurrence that
-                // became due since the last tick (or erase an offline catch-up).
-                nextRunAt: !clean.enabled ? null : scheduleChanged || enabledChanged
-                    ? this.initialOccurrence(clean.schedule, now)
-                    : routine.nextRunAt,
+                resultsThreadId: destination.resultsThreadId,
+                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),
@@ -547,7 +700,7 @@ export class RoutineManager {
             }
             if (request)
                 this.rememberRoutineRequest(request, routine.id, now);
-        });
+        }, discardResults);
         for (const run of cancelledRuns)
             this.emitRun(run);
         this.emitRoutine(routine);
@@ -658,15 +811,19 @@ export class RoutineManager {
         if (!routine)
             return null;
         let run;
+        const allocations = [];
+        const previousDestination = routine.resultsThreadId;
         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.
+            run = this.newRun(routine, this.now(), true, allocations, request?.threadId ?? routine.sourceThreadId);
+            // Preserve the invoking chat as provenance/fallback for this run.
+            // An explicitly configured results destination continues to win.
             if (request)
                 run.sourceThreadId = request.threadId;
             if (request)
                 this.rememberRoutineRequest(request, run.id, this.now());
-        });
+        }, () => this.discardResultsThreads(allocations));
+        if (routine.resultsThreadId !== previousDestination)
+            this.emitRoutine(routine);
         this.emitRun(run);
         queueMicrotask(() => void this.tick());
         return cloneRun(run);
@@ -833,51 +990,57 @@ export class RoutineManager {
                     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);
+            const dueRoutines = this.routines.filter((routine) => routine.enabled && routine.nextRunAt != null && routine.nextRunAt <= now);
+            const scheduledRuns = [];
+            const allocations = [];
+            if (dueRoutines.length > 0) {
+                this.commitMutation(() => {
+                    for (const routine of dueRoutines) {
+                        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) {
+                            const run = this.newRun(routine, scheduledFor, false, allocations);
+                            if (late > CATCH_UP_MS) {
+                                run.status = "missed";
+                                run.finishedAt = now;
+                                run.error = "This computer was offline for more than 12 hours after the scheduled time";
+                            }
+                            scheduledRuns.push(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);
+                        }
+                        else if (routine.schedule.type === "interval" && routine.nextRunAt === null) {
+                            routine.enabled = false;
+                            routine.updatedAt = Math.max(now, routine.updatedAt + 1);
+                        }
                     }
-                }
-                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.discardResultsThreads(allocations));
+            }
+            // Reporting may persist transcript cards, so publish only after the
+            // scheduler batch (including each destination) is durable.
+            for (const routine of dueRoutines)
                 this.emitRoutine(routine);
-                changed = true;
+            for (const run of scheduledRuns)
+                this.emitRun(run);
+            for (const run of scheduledRuns) {
+                if (run.status === "missed")
+                    this.options.onRunFailed?.(cloneRun(run));
             }
-            if (changed)
-                this.save();
-            for (const missed of missedRuns)
-                this.options.onRunFailed?.(missed);
             // 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.
@@ -900,6 +1063,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")
@@ -1071,6 +1243,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)
@@ -1095,7 +1276,16 @@ export class RoutineManager {
             return schedule.at;
         return nextOccurrence(schedule, now);
     }
-    newRun(routine, scheduledFor, manual) {
+    newRun(routine, scheduledFor, manual, allocations, sourceThreadId = routine.sourceThreadId) {
+        if (routine.target === "bot" && this.options.resolveResultsThread) {
+            const destination = this.options.resolveResultsThread({ ...routine, sourceThreadId }, false);
+            if (destination !== routine.resultsThreadId) {
+                if (destination)
+                    allocations.push({ botId: routine.botId, threadId: destination });
+                routine.resultsThreadId = destination;
+                routine.updatedAt = Math.max(this.now(), routine.updatedAt + 1);
+            }
+        }
         const run = {
             id: randomUUID(),
             routineId: routine.id,
@@ -1112,12 +1302,44 @@ export class RoutineManager {
             status: "queued",
             manual,
             triggerSource: manual ? "manual" : "schedule",
-            sourceThreadId: routine.sourceThreadId,
+            sourceThreadId,
+            resultsThreadId: routine.resultsThreadId,
             createdAt: this.now(),
         };
         this.runs.push(run);
         return run;
     }
+    discardResultsThreads(allocations) {
+        for (const { botId, threadId } of allocations) {
+            try {
+                this.options.discardResultsThread?.(botId, threadId);
+            }
+            catch (error) {
+                console.error("routine: could not discard uncommitted results thread", error);
+            }
+        }
+    }
+    applyResultsInput(routine, value) {
+        if (routine.target !== "bot") {
+            if (value != null)
+                throw Object.assign(new Error("Results threads are only available for bot routines"), { status: 400 });
+            delete routine.resultsThreadId;
+            return;
+        }
+        if (value === undefined)
+            return;
+        if (value === null) {
+            const destination = this.options.resolveResultsThread?.(routine, true);
+            if (!destination)
+                throw new Error("Could not create a results thread for this routine");
+            routine.resultsThreadId = destination;
+            return () => this.options.discardResultsThread?.(routine.botId, destination);
+        }
+        if (typeof value !== "string" || !value.trim() || !this.options.isResultsThread?.(routine.botId, value.trim())) {
+            throw Object.assign(new Error("Choose a visible results thread belonging to this bot"), { status: 400 });
+        }
+        routine.resultsThreadId = value.trim();
+    }
     emitRoutine(routine) {
         this.options.emit?.({ kind: "routine", routine: cloneRoutine(routine) });
     }
@@ -1164,7 +1386,7 @@ export class RoutineManager {
      * state if writing or renaming that file fails so a retry cannot mistake an
      * uncommitted action for a durable one.
      */
-    commitMutation(mutate) {
+    commitMutation(mutate, rollback) {
         const before = {
             routines: this.routines.map(cloneRoutine),
             runs: this.runs.map(cloneRun),
@@ -1178,6 +1400,12 @@ export class RoutineManager {
             this.routines = before.routines;
             this.runs = before.runs;
             this.routineRequestReceipts = before.receipts;
+            try {
+                rollback?.();
+            }
+            catch (cleanupError) {
+                console.error("routine: could not discard uncommitted results thread", cleanupError);
+            }
             throw error;
         }
     }

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();
@@ -33,10 +57,27 @@ export function queueSteeredMessage(botId, threadId, text, options = {}) {
         replyToId: options.replyToId,
         sendId: options.sendId,
         reason: options.reason,
+        unattended: options.unattended,
     });
     queues.set(threadId, entry);
+    changed();
     return { id };
 }
+/** Where a thread stands among this bot's threads waiting for a free slot:
+ * 1 for the next to start. The drain visits queues in insertion order, so
+ * insertion order is the line. Null when nothing of this bot's is waiting
+ * on that thread. */
+export function queuedThreadPosition(botId, threadId) {
+    let position = 0;
+    for (const [candidate, entry] of queues) {
+        if (entry.botId !== botId || !entry.items.some((item) => item.reason === "capacity"))
+            continue;
+        position += 1;
+        if (candidate === threadId)
+            return position;
+    }
+    return null;
+}
 /** Drain every queue whose task is idle: append the held lines (leaf is now
  * the finished turn's last item), then one run per thread whose prompt is
  * the texts separated by a blank line. `userMessage` is the last appended line
@@ -53,6 +94,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))
@@ -60,6 +102,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
@@ -81,7 +124,10 @@ export function drainSteeredMessages(store, run, isBlocked) {
         // message into one HTML block, which makes that attachment stop being a
         // native image when the combined follow-up is dispatched.
         const prompt = entry.items.map((item) => item.prompt).join("\n\n");
-        void run(entry.botId, threadId, prompt, last, appended.map((message) => message.id));
+        void run(entry.botId, threadId, prompt, last, appended.map((message) => message.id), 
+        // one unattended line makes the whole drained turn unattended: a
+        // person's words in the same queue cannot re-attend a bot's own
+        entry.items.some((item) => item.unattended === true));
     }
 }
 /** Find the receipt for a retry whose message is still waiting to drain. */
@@ -107,6 +153,7 @@ export function cancelSteeredMessage(botId, messageId, expectedThreadId) {
             queues.delete(threadId);
         else
             queues.set(threadId, { botId: entry.botId, items });
+        changed();
         return true;
     }
     return false;