@oar-sh/oar 0.9.15 → 0.9.17

package/shared/relay-events.mjs

@@ -11,6 +11,8 @@
 // SDK-free and side-effect free: imported by the server, the remote_relay
 // contract and the browser (which renders the event rows).
 
+import { RELAY_SCHEDULE_MESSAGE_KIND } from './relay-schedules.mjs';
+
 export const RELAY_EVENT_VERSION = 1;
 
 // `messages.kind` of the message the relay writes into the watcher's
@@ -20,6 +22,10 @@ export const RELAY_EVENT_MESSAGE_KIND = 'relay-event';
 
 export const RELAY_EVENT_TYPES = Object.freeze([
   'question_asked',
+  // The owner answered or dismissed a question that does not block (remote_relay
+  // `ask`). The asking session is always told, without a subscription; a
+  // subscription that takes question_asked takes it too.
+  'question_answered',
   'error',
   'turn_end',
   'task_started',
@@ -51,12 +57,16 @@ const ALL_EVENT_TYPES = Object.freeze([...RELAY_EVENT_TYPES, RELAY_EVENT_HEARTBE
 // whole context; a failed one is still a task_failed.
 export const RELAY_EVENT_SUBAGENT_FINISHED_TYPE = 'subagent_finished';
 
+// Not named in `events`: question_asked takes it (relayEventTypesTake).
+export const RELAY_EVENT_QUESTION_ANSWERED_TYPE = 'question_answered';
+const NAMED_EVENT_TYPES = RELAY_EVENT_TYPES.filter((type) => type !== RELAY_EVENT_QUESTION_ANSWERED_TYPE);
+
 // What `events` may name: the event types, the narrower subagent_finished
 // and the relay's own relay_restarted.
 export const RELAY_EVENT_SUBSCRIBABLE_TYPES = Object.freeze([
-  ...RELAY_EVENT_TYPES.slice(0, RELAY_EVENT_TYPES.indexOf('task_finished') + 1),
+  ...NAMED_EVENT_TYPES.slice(0, NAMED_EVENT_TYPES.indexOf('task_finished') + 1),
   RELAY_EVENT_SUBAGENT_FINISHED_TYPE,
-  ...RELAY_EVENT_TYPES.slice(RELAY_EVENT_TYPES.indexOf('task_finished') + 1),
+  ...NAMED_EVENT_TYPES.slice(NAMED_EVENT_TYPES.indexOf('task_finished') + 1),
   ...RELAY_EVENT_RELAY_LEVEL_TYPES,
 ]);
 
@@ -74,9 +84,18 @@ export function isRelayLevelOnly(types) {
   return list.length > 0 && list.every((type) => RELAY_EVENT_RELAY_LEVEL_TYPES.includes(type));
 }
 
-// The default before subagent_finished: every type but task_started. A
-// subscription made without events stored exactly this list.
-export const RELAY_EVENT_LEGACY_DEFAULT_TYPES = Object.freeze(RELAY_EVENT_TYPES.filter((type) => type !== 'task_started'));
+// The default before subagent_finished: every type of then but task_started.
+// A subscription made without events stored exactly this list. Written out:
+// a type added since (question_answered) is not part of it.
+export const RELAY_EVENT_LEGACY_DEFAULT_TYPES = Object.freeze([
+  'question_asked',
+  'error',
+  'turn_end',
+  'task_finished',
+  'task_failed',
+  'stalled',
+  'all_idle',
+]);
 
 /**
  * The events a stored subscription takes. A list that is exactly the old
@@ -98,21 +117,25 @@ export function isLegacyDefaultRelayEventTypes(types) {
 }
 
 /**
- * Whether a subscription's `events` take this event: its type named, or a
- * task_finished of anything but a shell command under subagent_finished.
+ * Whether a subscription's `events` take this event: its type named, a
+ * question_answered under question_asked (the answer to a question it was
+ * told of), or a task_finished of anything but a shell command under
+ * subagent_finished.
  */
 export function relayEventTypesTake(types, event) {
   const list = Array.isArray(types) ? types : [];
   const type = toText(event?.type);
   if (list.includes(type)) return true;
+  if (type === RELAY_EVENT_QUESTION_ANSWERED_TYPE) return list.includes('question_asked');
   return type === 'task_finished'
     && list.includes(RELAY_EVENT_SUBAGENT_FINISHED_TYPE)
     && toText(event?.detail?.kind) !== 'shell';
 }
 
 // Never held back: not by the 30 s coalescing, not by the digest past the
-// hourly cap (they still count toward it).
-export const RELAY_EVENT_URGENT_TYPES = Object.freeze(['question_asked', 'error']);
+// hourly cap (they still count toward it). An answer is a decision the
+// asking session may be waiting for.
+export const RELAY_EVENT_URGENT_TYPES = Object.freeze(['question_asked', 'question_answered', 'error']);
 
 export const RELAY_EVENT_SCOPES = Object.freeze(['sessions', 'all']);
 
@@ -125,11 +148,17 @@ export const RELAY_EVENT_LIMITS = Object.freeze({
   stalledMinutesMax: 24 * 60,
   heartbeatMinutesMin: 1,
   heartbeatMinutesMax: 24 * 60,
+  // Per subscription: a digest of its non-urgent events every N minutes,
+  // and the session ids an "all" subscription leaves out.
+  digestMinutesMin: 1,
+  digestMinutesMax: 24 * 60,
+  excludeMax: 50,
   matchMaxChars: 200,
   sessionsMax: 50,
   activeSubscriptionsPerWatcher: 20,
   previewChars: 300,
   questionChars: 500,
+  answerChars: 2000,
   optionsMax: 8,
   linesPerMessage: 40,
   // Across paired relays. The watching relay asks the watched one for new
@@ -183,6 +212,20 @@ export function isRelayEventDelivery(pending) {
   return toText(pending?.messageKind) === RELAY_EVENT_MESSAGE_KIND;
 }
 
+// The relay's own automated messages that reach a worker as a turn: event
+// messages and scheduled prompts (shared/relay-schedules.mjs). The dequeue
+// payload names their kind, and the workers push them without the steer note.
+export const RELAY_AUTOMATED_MESSAGE_KINDS = Object.freeze([RELAY_EVENT_MESSAGE_KIND, RELAY_SCHEDULE_MESSAGE_KIND]);
+
+export function isRelayAutomatedMessageKind(kind) {
+  return RELAY_AUTOMATED_MESSAGE_KINDS.includes(toText(kind));
+}
+
+/** Whether a delivered queue message is one of the relay's automated messages (isRelayEventDelivery's wider sibling). */
+export function isRelayAutomatedDelivery(pending) {
+  return isRelayAutomatedMessageKind(pending?.messageKind);
+}
+
 /** Any type an event message can carry, the heartbeat included. */
 export function isRelayEventType(type) {
   return ALL_EVENT_TYPES.includes(toText(type));
@@ -210,6 +253,149 @@ export function compileRelayEventMatch(pattern) {
   }
 }
 
+// ─── Quiet hours ─────────────────────────────────────────────────────────────
+//
+// A subscription's `quiet_hours` is `{ from: "23:00", to: "06:00", tz }`: a
+// window of local wall-clock time in an IANA time zone, which may cross
+// midnight. Non-urgent events that fall in it are held until it ends.
+
+const CLOCK_PATTERN = /^([01]?\d|2[0-3]):([0-5]\d)$/;
+
+/** Minutes after midnight of "HH:MM" (or "H:MM"), or null. */
+export function relayEventClockMinutes(value) {
+  const match = CLOCK_PATTERN.exec(toText(value));
+  return match ? Number(match[1]) * 60 + Number(match[2]) : null;
+}
+
+function clockText(minutes) {
+  return `${String(Math.floor(minutes / 60)).padStart(2, '0')}:${String(minutes % 60).padStart(2, '0')}`;
+}
+
+/** The canonical name of an IANA time zone this runtime knows, or ''. */
+export function canonicalRelayEventTimeZone(value) {
+  const tz = toText(value);
+  if (!tz || tz.length > 64) return '';
+  try {
+    return new Intl.DateTimeFormat('en-US', { timeZone: tz }).resolvedOptions().timeZone || '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * A `quiet_hours` value checked: `{ ok: true, value }` with `{ from, to, tz }`
+ * as "HH:MM" and the zone's canonical name, `{ ok: true, value: null }` when
+ * there is none, `{ ok: false, error }` otherwise. Takes the object or its
+ * JSON text.
+ */
+export function normalizeRelayEventQuietHours(input) {
+  if (input === undefined || input === null || input === false || (typeof input === 'string' && !input.trim())) return { ok: true, value: null };
+  let value = input;
+  if (typeof value === 'string') {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return { ok: false, error: 'quiet_hours must be an object: {"from":"23:00","to":"06:00","tz":"Europe/Berlin"}' };
+    }
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return { ok: false, error: 'quiet_hours must be an object: {"from":"23:00","to":"06:00","tz":"Europe/Berlin"}' };
+  }
+  // Some providers send every property of the schema, an unused one empty.
+  if (['from', 'to', 'tz'].every((key) => !toText(value[key]))) return { ok: true, value: null };
+  const from = relayEventClockMinutes(value.from);
+  const to = relayEventClockMinutes(value.to);
+  if (from === null || to === null) return { ok: false, error: 'quiet_hours from and to must be times of day as "HH:MM" (00:00 to 23:59)' };
+  if (from === to) return { ok: false, error: 'quiet_hours from and to must differ' };
+  if (!toText(value.tz)) return { ok: false, error: 'quiet_hours needs tz, an IANA time zone such as "Europe/Berlin"' };
+  const tz = canonicalRelayEventTimeZone(value.tz);
+  if (!tz) return { ok: false, error: `quiet_hours tz "${oneLine(value.tz, 64)}" is not an IANA time zone (for example "Europe/Berlin", "America/New_York", "UTC")` };
+  return { ok: true, value: { from: clockText(from), to: clockText(to), tz } };
+}
+
+/** "23:00–06:00 Europe/Berlin" */
+export function relayEventQuietHoursText(quiet) {
+  return `${oneLine(quiet?.from, 5)}–${oneLine(quiet?.to, 5)} ${oneLine(quiet?.tz, 64)}`.trim();
+}
+
+const DAY_MS = 24 * 60 * 60_000;
+
+function minuteFloor(ms) {
+  return Math.floor(ms / 60_000) * 60_000;
+}
+
+const zoneFormatters = new Map();
+
+function zoneFormatter(tz) {
+  let formatter = zoneFormatters.get(tz);
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat('en-US', {
+      timeZone: tz,
+      hourCycle: 'h23',
+      year: 'numeric',
+      month: 'numeric',
+      day: 'numeric',
+      hour: 'numeric',
+      minute: 'numeric',
+    });
+    zoneFormatters.set(tz, formatter);
+  }
+  return formatter;
+}
+
+/** The wall clock in `tz` at instant `ms`, as the UTC timestamp of the same digits. */
+function wallClock(ms, tz) {
+  const parts = {};
+  for (const part of zoneFormatter(tz).formatToParts(new Date(ms))) parts[part.type] = Number(part.value);
+  return Date.UTC(parts.year, parts.month - 1, parts.day, (parts.hour || 0) % 24, parts.minute || 0);
+}
+
+function insideWindow(minute, from, to) {
+  return from < to ? minute >= from && minute < to : minute >= from || minute < to;
+}
+
+function wallMinute(wall) {
+  const date = new Date(wall);
+  return date.getUTCHours() * 60 + date.getUTCMinutes();
+}
+
+/**
+ * When the quiet window that instant `ms` falls in ends (epoch ms), or null
+ * when `ms` is outside it (or the value is not a valid window). The clock
+ * changes: where the clocks go back and `to` comes twice, the window ends
+ * the first time and is not entered again in the repeated hour; where `to`
+ * falls in the hour the clocks skip, it ends the moment they jump. A known
+ * limit: a `from` inside the repeated hour starts the window on the first
+ * pass, and on the second pass the minutes before `from` read as outside.
+ */
+export function relayEventQuietWindowEnd(quiet, ms) {
+  const from = relayEventClockMinutes(quiet?.from);
+  const to = relayEventClockMinutes(quiet?.to);
+  const tz = canonicalRelayEventTimeZone(quiet?.tz);
+  if (from === null || to === null || from === to || !tz || !Number.isFinite(ms)) return null;
+  const wall = wallClock(ms, tz);
+  const minute = wallMinute(wall);
+  if (!insideWindow(minute, from, to)) return null;
+  const day = Date.UTC(new Date(wall).getUTCFullYear(), new Date(wall).getUTCMonth(), new Date(wall).getUTCDate());
+  // Past midnight's side of a window that crosses it ends today, else tomorrow.
+  const target = day + (from > to && minute >= from ? DAY_MS : 0) + to * 60_000;
+  // The instants whose local time reads `target`, under the offsets in force
+  // around it; the earliest is the end. Already past it, `ms` is in the
+  // repeated hour after the window ended: outside.
+  const offsets = new Set([-DAY_MS, 0, DAY_MS].map((shift) => wallClock(target + shift, tz) - minuteFloor(target + shift)));
+  const ends = [...offsets]
+    .map((offset) => target - offset)
+    .filter((instant) => wallClock(instant, tz) === target)
+    .sort((a, b) => a - b);
+  if (ends.length) return ends[0] > ms ? ends[0] : null;
+  // `to` does not exist that day (the clocks skip it): the first minute
+  // outside the window.
+  for (let instant = minuteFloor(ms) + 60_000; instant <= ms + 2 * DAY_MS; instant += 60_000) {
+    if (!insideWindow(wallMinute(wallClock(instant, tz)), from, to)) return instant;
+  }
+  return null;
+}
+
 /** The text a `match` is tried on, or null when the event has none. */
 export function relayEventMatchText(event) {
   const detail = event?.detail || {};
@@ -349,6 +535,24 @@ export function formatRelayEventLine(event) {
       if (options.length) parts.push(`options: ${options.map((option) => `[${option}]`).join(' ')}`);
       if (detail.approvalCard) parts.push('(an approval card: only the user can answer it)');
       else if (oneLine(detail.questionId, 80)) parts.push(`(question_id ${oneLine(detail.questionId, 80)})`);
+      if (detail.kind === 'ask') parts.push('(asked with ask: it does not block that session)');
+      return parts.join(' ');
+    }
+    case 'question_answered': {
+      const id = oneLine(detail.questionId, 80);
+      const parts = [`${head}${id ? ` (question_id ${id})` : ''} ${quote(detail.prompt, RELAY_EVENT_LIMITS.questionChars)}`];
+      if (detail.dismissed === true) {
+        parts.push('→ the user dismissed it without an answer; decide yourself or ask again later');
+      } else {
+        const choice = oneLine(detail.choice, 120);
+        const answer = oneLine(detail.answer, RELAY_EVENT_LIMITS.answerChars);
+        parts.push(`→ the user answered ${quote(answer || choice, RELAY_EVENT_LIMITS.answerChars)}`);
+        if (choice && choice !== answer) parts.push(`(option [${choice}])`);
+      }
+      // The relay whose UI it came from: the one the ask is kept on, or a
+      // paired relay's Inbox.
+      const via = oneLine(detail.via, 60);
+      if (via) parts.push(`(via relay ${quote(via, 60)})`);
       return parts.join(' ');
     }
     case 'error': {
@@ -377,7 +581,7 @@ export function formatRelayEventLine(event) {
   }
 }
 
-const URGENT_ORDER = ['question_asked', 'error'];
+const URGENT_ORDER = ['question_asked', 'question_answered', 'error'];
 
 function replayOrder(a, b) {
   const rank = (event) => {
@@ -393,6 +597,48 @@ function pushCapped(lines, events) {
   if (events.length > shown.length) lines.push(`${RELAY_EVENT_LINE_PREFIX} … and ${events.length - shown.length} more`);
 }
 
+function distinct(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+/**
+ * The lines in front of the events: one "Digest of" line for the hourly
+ * cap's digest (`digest`) and a subscription's digest together, and one for
+ * events quiet hours held. An event's `held` is `{ reason: 'quiet', from,
+ * to, tz }` or `{ reason: 'digest', minutes, subscriptionId }`, set when it
+ * is delivered. A subscription's digest of a single event reads as that
+ * event, without a line of its own.
+ */
+function headerLines(events, { digest = false, all = events } = {}) {
+  const lines = [];
+  // The cap's digest is of this relay's events and live ones; what the
+  // options held, replayed events included, is counted from all.
+  const capped = digest && events.length > 0;
+  const gathered = all.filter((event) => event?.held?.reason === 'digest');
+  const parts = [];
+  if (capped) {
+    parts.push(`the limit of ${RELAY_EVENT_LIMITS.wakesPerHour} wake-ups an hour is reached; until it frees up, events come every ${Math.round(RELAY_EVENT_LIMITS.digestIntervalMs / 60_000)} min`);
+  }
+  if (gathered.length > 1 || (capped && gathered.length)) {
+    parts.push(distinct(gathered.map((event) => {
+      const minutes = Number(event.held.minutes) || 0;
+      const id = oneLine(event.held.subscriptionId, 80);
+      return `${id ? `subscription ${id}` : 'a subscription'} every ${minutes} min`;
+    })).join(', '));
+    parts.push('questions and errors come at once');
+  }
+  if (parts.length) {
+    const count = capped ? events.length : gathered.length;
+    lines.push(`Digest of ${count} event${count === 1 ? '' : 's'} (${parts.join('; ')}):`);
+  }
+  const quiet = all.filter((event) => event?.held?.reason === 'quiet');
+  if (quiet.length) {
+    const windows = distinct(quiet.map((event) => relayEventQuietHoursText(event.held)));
+    lines.push(`Held during quiet hours (${windows.join(', ')}): ${quiet.length} event${quiet.length === 1 ? '' : 's'}, delivered now that the window has ended; questions and errors came at once.`);
+  }
+  return lines;
+}
+
 /**
  * The whole message for one wake-up: the lead line, then one line per event
  * (at most `linesPerMessage`, then a count of the rest). `digest` says the
@@ -417,10 +663,7 @@ export function buildRelayEventMessageText(events, { digest = false, ended = []
     if (!replays.has(relayId)) replays.set(relayId, []);
     replays.get(relayId).push(event);
   }
-  const lines = [RELAY_EVENT_LEAD];
-  if (digest && plain.length) {
-    lines.push(`Digest of ${plain.length} event${plain.length === 1 ? '' : 's'} (the limit of ${RELAY_EVENT_LIMITS.wakesPerHour} wake-ups an hour is reached; until it frees up, events come every ${Math.round(RELAY_EVENT_LIMITS.digestIntervalMs / 60_000)} min):`);
-  }
+  const lines = [RELAY_EVENT_LEAD, ...headerLines(plain, { digest, all: list })];
   pushCapped(lines, plain);
   for (const group of replays.values()) {
     const lost = group.filter((event) => event.type === RELAY_EVENT_LINK_LOST_TYPE);
@@ -431,7 +674,12 @@ export function buildRelayEventMessageText(events, { digest = false, ended = []
       lines.push(`Replayed: ${kept.length} event${kept.length === 1 ? '' : 's'} relay ${quote(relayDisplayName(group[0]), 60)} kept while the link was down, questions and errors first:`);
       pushCapped(lines, kept);
     }
-    for (const event of restored) lines.push(formatRelayEventLine(event));
+    for (const event of restored) {
+      // Kept events a subscription's digest or quiet hours hold come later.
+      const held = (Number(event?.detail?.kept) || 0) - kept.length;
+      lines.push(formatRelayEventLine(event)
+        + (held > 0 ? `; ${held} of them ${held === 1 ? 'is' : 'are'} held by your subscription's digest or quiet hours and come${held === 1 ? 's' : ''} later` : ''));
+    }
   }
   const endedIds = (Array.isArray(ended) ? ended : []).map((id) => oneLine(id, 80)).filter(Boolean);
   if (endedIds.length) {
@@ -443,6 +691,7 @@ export function buildRelayEventMessageText(events, { digest = false, ended = []
 // An event line: the prefix, a paired relay's name, the session, the type.
 export const RELAY_EVENT_LINE_PATTERN = /^\[relay event\] (?:[^"·\n]{1,60} · )?(?:session "(?:[^"]*)" \([^)]*\)(?: on relay "[^"]*")?: )?([a-z_]+)/;
 const DIGEST_LINE_PATTERN = /^Digest of \d+ events?/;
+const QUIET_LINE_PATTERN = /^Held during quiet hours/;
 const REPLAYED_LINE_PATTERN = /^Replayed: \d+ events?/;
 
 /**
@@ -454,9 +703,10 @@ const REPLAYED_LINE_PATTERN = /^Replayed: \d+ events?/;
 export function parseRelayEventMessageText(text) {
   const rows = String(text ?? '').split(/\r?\n/).map((line) => line.trimEnd()).filter((line) => line.trim());
   const body = rows[0] === RELAY_EVENT_LEAD ? rows.slice(1) : rows;
-  const digest = DIGEST_LINE_PATTERN.test(body[0] || '');
+  const digest = body.some((line) => DIGEST_LINE_PATTERN.test(line));
+  const quiet = body.some((line) => QUIET_LINE_PATTERN.test(line));
   const replayed = body.some((line) => REPLAYED_LINE_PATTERN.test(line));
-  const lines = body.filter((line) => !DIGEST_LINE_PATTERN.test(line) && !REPLAYED_LINE_PATTERN.test(line));
+  const lines = body.filter((line) => !DIGEST_LINE_PATTERN.test(line) && !QUIET_LINE_PATTERN.test(line) && !REPLAYED_LINE_PATTERN.test(line));
   const types = [];
   let count = 0;
   for (const line of lines) {
@@ -470,5 +720,5 @@ export function parseRelayEventMessageText(text) {
     const more = /^\[relay event\] … and (\d+) more$/.exec(line);
     if (more) count += Number(more[1]) || 0;
   }
-  return { lines, types, count: count || lines.length, digest, replayed };
+  return { lines, types, count: count || lines.length, digest, quiet, replayed };
 }

package/shared/relay-schedules.mjs

@@ -0,0 +1,128 @@
+// Relay schedules: a prompt the relay queues into a session at a set time,
+// once or every N minutes. An agent sets one with remote_relay's `schedule`
+// (its own conversation by default, or another session of this relay); the
+// relay keeps it in its database, so it outlives a restart that the agent's
+// own timers would not.
+//
+// What the relay writes is an ordinary queued message of its own (`messages.kind
+// = 'relay-schedule'`) whose first line says what it is: automated, never the
+// user's, and it approves nothing.
+//
+// SDK-free and side-effect free: imported by the server and the remote_relay
+// contract (the browser keeps its own copy of what it needs:
+// server/public/app/relay-schedule-view.mjs).
+
+// `messages.kind` of the message a schedule queues.
+export const RELAY_SCHEDULE_MESSAGE_KIND = 'relay-schedule';
+
+// Socket event with the whole active list, sent on every change.
+export const RELAY_SCHEDULE_SOCKET_EVENT = 'relay_schedules';
+
+export const RELAY_SCHEDULE_LIMITS = Object.freeze({
+  everyMinutesMin: 5,
+  everyMinutesMax: 10080,
+  // Active schedules that fire into one conversation, and active schedules
+  // one conversation set (for itself or for others).
+  perConversation: 20,
+  titleMax: 100,
+  textMax: 20000,
+  // How far ahead `at` may lie.
+  aheadMaxDays: 366,
+  // An `at` this little in the past is taken as "now" (a clock between the
+  // worker's check and the relay's).
+  pastGraceMs: 60_000,
+});
+
+const MINUTE_MS = 60_000;
+const DAY_MS = 24 * 60 * MINUTE_MS;
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+function oneLine(value, max) {
+  const text = toText(value).replace(/[\r\n\t]+/g, ' ').replace(/\s+/g, ' ');
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/** A schedule title as stored and shown: one line, capped. */
+export function normalizeRelayScheduleTitle(value) {
+  return oneLine(value, RELAY_SCHEDULE_LIMITS.titleMax);
+}
+
+/**
+ * `at` as an agent may write it: an ISO time with a zone (or a Z). Returns
+ * `{ ok:true, value }` with the canonical ISO string, or `{ ok:false, error }`.
+ * A time without a zone is refused: the relay and the agent may not share one.
+ */
+export function normalizeRelayScheduleAt(value, { now = Date.now() } = {}) {
+  const text = toText(value);
+  if (!text) return { ok: true, value: null };
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:?\d{2})$/i.test(text)) {
+    return { ok: false, error: 'at must be an ISO time with a zone, e.g. 2026-11-02T06:30:00Z or 2026-11-02T07:30:00+01:00' };
+  }
+  const ms = Date.parse(text);
+  if (!Number.isFinite(ms)) return { ok: false, error: `at "${text.slice(0, 40)}" is not a valid time` };
+  if (ms < now - RELAY_SCHEDULE_LIMITS.pastGraceMs) return { ok: false, error: 'at is in the past' };
+  if (ms > now + RELAY_SCHEDULE_LIMITS.aheadMaxDays * DAY_MS) {
+    return { ok: false, error: `at is more than ${RELAY_SCHEDULE_LIMITS.aheadMaxDays} days ahead` };
+  }
+  return { ok: true, value: new Date(Math.max(ms, now)).toISOString() };
+}
+
+/**
+ * The first time a schedule fires: `at`, else one interval from now.
+ */
+export function firstRelayScheduleFire({ at = null, everyMinutes = null, now = Date.now() } = {}) {
+  const atMs = Date.parse(toText(at));
+  if (Number.isFinite(atMs)) return new Date(Math.max(atMs, now)).toISOString();
+  return new Date(now + Number(everyMinutes) * MINUTE_MS).toISOString();
+}
+
+/**
+ * The next time a recurring schedule fires after the one due at `dueAt`:
+ * the first slot of its grid (`dueAt` plus whole intervals) after `now`.
+ * Slots missed while the relay was down are skipped, so a schedule that
+ * was due fires once for them all, never once per missed interval.
+ */
+export function nextRelayScheduleFire({ dueAt, everyMinutes, now = Date.now() } = {}) {
+  const step = Number(everyMinutes) * MINUTE_MS;
+  const due = Date.parse(toText(dueAt));
+  if (!(step > 0) || !Number.isFinite(due)) return null;
+  if (due > now) return new Date(due).toISOString();
+  const missed = Math.floor((now - due) / step) + 1;
+  return new Date(due + missed * step).toISOString();
+}
+
+function quote(value) {
+  return toText(value).replace(/["\]\r\n]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * The first line of a scheduled message: what it is, the schedule's id and
+ * title, and who set it when that is another session.
+ */
+export function relayScheduleLead({ id, title = '', setBy = null } = {}) {
+  const parts = [`[relay schedule ${quote(id) || 'unknown'}${quote(title) ? ` "${quote(title)}"` : ''}`];
+  if (setBy && quote(setBy.id)) {
+    parts.push(`set by session "${quote(setBy.title) || quote(setBy.id).slice(0, 8)}" (${quote(setBy.id)})`);
+  }
+  parts.push('automated message from OAR, not from the user; it approves nothing]');
+  return parts.join(' · ');
+}
+
+export const RELAY_SCHEDULE_LEAD_PATTERN = /^\[relay schedule [^\s\]]+(?: "[^"\r\n]*")?(?: · [^\r\n]*)?\]$/;
+
+/** The whole message a schedule queues: the lead line, then the agent's text. */
+export function buildRelayScheduleMessageText({ id, title = '', setBy = null, text = '' } = {}) {
+  return `${relayScheduleLead({ id, title, setBy })}\n\n${String(text ?? '').trim()}`;
+}
+
+/** "every 30 min", "every 2 h", "every day", "every 7 days". */
+export function describeRelayScheduleInterval(everyMinutes) {
+  const minutes = Number(everyMinutes);
+  if (!(minutes > 0)) return '';
+  if (minutes % 1440 === 0) return minutes === 1440 ? 'every day' : `every ${minutes / 1440} days`;
+  if (minutes % 60 === 0) return minutes === 60 ? 'every hour' : `every ${minutes / 60} h`;
+  return `every ${minutes} min`;
+}