@oar-sh/oar 0.9.14 → 0.9.16

package/shared/relay-asks.mjs

@@ -0,0 +1,145 @@
+// Questions that don't block: remote_relay's `ask` puts a question for the
+// owner into a session (a card there and in the Inbox) and returns at once;
+// the asking session keeps working and is told the answer later, as a relay
+// event (question_answered).
+//
+// One ask is `{ id, kind: 'ask', session, question, options, recommendation,
+// detail, urgency, status, answer, choice, createdBy, creator, ... }`. Its
+// `status` is pending until the owner answers or dismisses it, or the agent
+// that asked withdraws it.
+//
+// Every text of an ask is written by an agent, possibly on another relay:
+// whoever shows it shows it as plain text.
+//
+// SDK-free and side-effect free: imported by the server, the remote_relay
+// contract and the browser.
+
+// The kind a question card carries in /api/relay-questions and the Inbox:
+// `ask` (this feature), `approval` (a relay's Allow / Deny card on its own
+// agent's call, context.source 'remote_relay'), `ask_user` (every other card a
+// turn waits on).
+export const RELAY_QUESTION_KINDS = Object.freeze(['ask', 'ask_user', 'approval']);
+export const RELAY_ASK_KIND = 'ask';
+
+export const RELAY_ASK_URGENCIES = Object.freeze(['normal', 'now']);
+export const RELAY_ASK_STATUSES = Object.freeze(['pending', 'answered', 'dismissed', 'withdrawn', 'cancelled']);
+// What the Inbox lists under its divider (for answeredKeepMs).
+export const RELAY_ASK_CLOSED_STATUSES = Object.freeze(['answered', 'dismissed']);
+
+// Socket event the relay sends on every change of an ask (`{ ask }`) and
+// of the Inbox's count (`{ pending }`).
+export const RELAY_ASK_SOCKET_EVENT = 'relay_ask_updated';
+
+export const RELAY_ASK_LIMITS = Object.freeze({
+  questionMax: 500,
+  optionsMax: 8,
+  optionMax: 120,
+  recommendationMax: 300,
+  detailMax: 2000,
+  // Pending asks one conversation may have asked (for itself and others), and
+  // pending asks one session may have open.
+  pendingPerConversation: 20,
+  // How long an answered or dismissed ask stays in the Inbox, under its divider.
+  answeredKeepMs: 24 * 60 * 60_000,
+  // Closed asks are kept this long, then pruned.
+  closedKeepMs: 7 * 24 * 60 * 60_000,
+  // The asking relay looks for answers to its asks on a paired relay this often.
+  remotePollMs: 5_000,
+  remotePollFailingMs: 30_000,
+  listMax: 200,
+});
+
+// Ask ids carry this prefix: the question routes tell them from cards by it.
+export const RELAY_ASK_ID_PREFIX = 'ask_';
+
+export function isRelayAskId(value) {
+  return /^ask_[a-z0-9]{6,40}$/.test(String(value ?? '').trim());
+}
+
+function toText(value) {
+  return String(value ?? '').trim();
+}
+
+// Control characters of agent text go; line breaks stay in the detail only.
+const CONTROLS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u2028\u2029]+/g;
+
+function oneLine(value) {
+  return String(value ?? '').replace(CONTROLS, ' ').replace(/[\r\n\t]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+function multiLine(value) {
+  return String(value ?? '').replace(/\r\n?/g, '\n').replace(CONTROLS, ' ').replace(/[ \t]+\n/g, '\n').trim();
+}
+
+function invalid(error) {
+  return { ok: false, error };
+}
+
+/**
+ * An ask as an agent writes it, checked: `{ ok, value: { question, options,
+ * recommendation, detail, urgency } }` or `{ ok:false, error }`. Too long is
+ * refused, never cut: the owner decides on the words the agent chose. The
+ * recommendation may name an option (matched case-insensitively, then given
+ * the option's spelling) or be free text.
+ */
+export function normalizeRelayAskInput(input = {}) {
+  const source = input && typeof input === 'object' ? input : {};
+  const question = oneLine(source.question);
+  if (!question) return invalid('ask needs question (the question for the owner, at most 500 characters)');
+  if (question.length > RELAY_ASK_LIMITS.questionMax) {
+    return invalid(`question is longer than ${RELAY_ASK_LIMITS.questionMax} characters; put the background in detail`);
+  }
+  let rawOptions = source.options;
+  if (rawOptions === undefined || rawOptions === null || rawOptions === '') rawOptions = [];
+  if (typeof rawOptions === 'string') rawOptions = rawOptions.split(/\r?\n/);
+  if (!Array.isArray(rawOptions)) return invalid('options must be a list of short labels');
+  const options = [];
+  for (const raw of rawOptions) {
+    if (typeof raw !== 'string' && typeof raw !== 'number') return invalid('options must be a list of short labels');
+    const label = oneLine(raw);
+    if (!label) continue;
+    if (label.length > RELAY_ASK_LIMITS.optionMax) return invalid(`an option is longer than ${RELAY_ASK_LIMITS.optionMax} characters: "${label.slice(0, 40)}…"`);
+    if (options.some((option) => option.toLowerCase() === label.toLowerCase())) continue;
+    options.push(label);
+  }
+  if (options.length > RELAY_ASK_LIMITS.optionsMax) return invalid(`options takes at most ${RELAY_ASK_LIMITS.optionsMax} labels`);
+  let recommendation = oneLine(source.recommendation);
+  if (recommendation.length > RELAY_ASK_LIMITS.recommendationMax) {
+    return invalid(`recommendation is longer than ${RELAY_ASK_LIMITS.recommendationMax} characters`);
+  }
+  const named = options.find((option) => option.toLowerCase() === recommendation.toLowerCase());
+  if (named) recommendation = named;
+  const detail = multiLine(source.detail);
+  if (detail.length > RELAY_ASK_LIMITS.detailMax) return invalid(`detail is longer than ${RELAY_ASK_LIMITS.detailMax} characters`);
+  const urgency = toText(source.urgency).toLowerCase() || 'normal';
+  if (!RELAY_ASK_URGENCIES.includes(urgency)) return invalid(`urgency must be one of: ${RELAY_ASK_URGENCIES.join(', ')}`);
+  return { ok: true, value: { question, options, recommendation, detail, urgency } };
+}
+
+/**
+ * The owner's answer to an ask: `{ ok, value: { answer, choice } }` or
+ * `{ ok:false, error }`. `choice` is the option picked (its own spelling),
+ * `answer` the text the asker reads: the typed text, else the choice.
+ */
+export function normalizeRelayAskAnswer(ask, { answer = '', choice = '' } = {}) {
+  const options = Array.isArray(ask?.options) ? ask.options : [];
+  const wanted = oneLine(choice);
+  let picked = '';
+  if (wanted) {
+    picked = options.find((option) => option.toLowerCase() === wanted.toLowerCase()) || '';
+    if (!picked) return invalid(`"${wanted.slice(0, 80)}" is not an option of this question`);
+  }
+  const text = multiLine(answer).slice(0, RELAY_ASK_LIMITS.detailMax);
+  if (!picked && !text) return invalid('An answer needs a choice or some text');
+  // A typed text that is an option counts as that choice.
+  if (!picked) picked = options.find((option) => option.toLowerCase() === oneLine(text).toLowerCase()) || '';
+  return { ok: true, value: { answer: text || picked, choice: picked } };
+}
+
+/** The kind of a formatted question card (a row of /api/relay-questions). */
+export function relayQuestionKind(question) {
+  const kind = toText(question?.kind);
+  if (RELAY_QUESTION_KINDS.includes(kind)) return kind;
+  const context = question && typeof question.context === 'object' && question.context ? question.context : {};
+  return toText(context.source) === 'remote_relay' ? 'approval' : 'ask_user';
+}

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 };
 }