letagents 0.12.31 → 0.12.32

package/shared/ui/WakeRuleLine.vue

@@ -0,0 +1,51 @@
+<template>
+  <span v-if="summary" class="wake-rule-line" :title="details">
+    <WakeGlyph />
+    <span class="wake-rule-line-label">{{ summary.label }}</span>
+    <span v-if="summary.detail" class="wake-rule-line-detail">· {{ summary.detail }}</span>
+  </span>
+</template>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref } from "vue";
+import { formatWakeClock, summarizeWakeRuleParts, wakeRuleLabel, type WakeRule } from "../wake-rules.mjs";
+import WakeGlyph from "./WakeGlyph.vue";
+
+const props = defineProps<{ rules: readonly WakeRule[] }>();
+const now = ref(new Date());
+const summary = computed(() => summarizeWakeRuleParts(props.rules, now.value));
+const details = computed(() => props.rules
+  .map((rule) => wakeRuleLabel(rule, { formatTime: (iso) => formatWakeClock(iso, now.value) }))
+  .join("\n"));
+
+let tick: ReturnType<typeof setInterval> | undefined;
+onMounted(() => { tick = setInterval(() => { now.value = new Date(); }, 30_000); });
+onBeforeUnmount(() => clearInterval(tick));
+</script>
+
+<style>
+.wake-rule-line {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  min-width: 0;
+  max-width: 100%;
+  font-variant-numeric: tabular-nums slashed-zero;
+}
+.wake-rule-line > .wake-glyph {
+  width: 13px;
+  height: 13px;
+  opacity: 0.85;
+}
+.wake-rule-line-label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+/* How long, and how many more, stays visible when the label is shortened. */
+.wake-rule-line-detail {
+  flex-shrink: 0;
+  white-space: nowrap;
+}
+</style>

package/shared/ui/WakeRulesPanel.vue

@@ -0,0 +1,201 @@
+<template>
+  <section v-if="rows.length || recent.length" ref="root" class="wake-rules" aria-label="Wake rules">
+    <TransitionGroup tag="ul" name="wake-rule" class="wake-rules-active">
+      <li
+        v-for="row in rows"
+        :key="row.rule.id"
+        class="wake-rule"
+        :data-rule-id="row.rule.id"
+        :data-state="row.cancelled ? 'cancelled' : 'active'"
+      >
+        <span class="wake-rule-mark"><WakeGlyph :state="row.cancelled ? 'ended' : 'waiting'" /></span>
+        <div class="wake-rule-copy">
+          <p class="wake-rule-kicker">{{ row.cancelled ? "Cancelled" : `Waiting ${describe(row.rule).preposition}` }}</p>
+          <strong>{{ describe(row.rule).object }}</strong>
+          <span v-if="row.rule.note" class="wake-rule-note">{{ row.rule.note }}</span>
+          <span class="wake-rule-meta">
+            <template v-if="row.rule.event === 'timer'">
+              Wakes in <time :datetime="row.rule.arguments.at" :title="fullTime(row.rule.arguments.at)">{{ until(row.rule.arguments.at!) }}</time>
+            </template>
+            <template v-else>
+              <time :datetime="row.rule.created_at" :title="`Since ${fullTime(row.rule.created_at)}`">{{ span(row.rule.created_at) }}</time> so far
+              · {{ row.rule.repeat ? "Repeats until" : "Expires" }}
+              <time :datetime="row.rule.expires_at" :title="fullTime(row.rule.expires_at)">{{ clock(row.rule.expires_at) }}</time>
+            </template>
+          </span>
+          <span v-if="row.error" class="wake-rule-error" role="status">{{ row.error }}</span>
+        </div>
+        <button
+          v-if="row.cancelled"
+          type="button"
+          class="wake-rule-action"
+          data-tone="undo"
+          :disabled="busy.has(row.rule.id)"
+          @click="undo(row.rule)"
+        >Undo</button>
+        <button
+          v-else-if="api"
+          type="button"
+          class="wake-rule-action"
+          :disabled="busy.has(row.rule.id)"
+          :aria-label="`Cancel wake rule: waiting ${describe(row.rule).preposition} ${describe(row.rule).object}`"
+          @click="cancel(row.rule)"
+        >Cancel</button>
+      </li>
+    </TransitionGroup>
+
+    <details v-if="recent.length" class="wake-rules-recent">
+      <summary>Recent wakes <span>{{ recent.length }}</span></summary>
+      <ul>
+        <li v-for="rule in recent" :key="rule.id" :data-status="rule.status">
+          <WakeGlyph :state="rule.status === 'fired' ? 'woke' : 'ended'" still />
+          <span class="wake-rules-recent-copy">
+            <strong>{{ outcomeLabel(rule) }}</strong>
+            <span>{{ describe(rule).preposition === "until" ? `until ${describe(rule).object}` : describe(rule).object }}</span>
+          </span>
+          <button
+            v-if="rule.wake_message_id"
+            type="button"
+            class="wake-rules-recent-time"
+            :title="`Show the wake message · ${fullTime(endedAt(rule))}`"
+            @click="emit('open-message', rule.wake_message_id)"
+          ><time :datetime="endedAt(rule)">{{ clock(endedAt(rule)) }}</time></button>
+          <time v-else class="wake-rules-recent-time" :datetime="endedAt(rule)" :title="fullTime(endedAt(rule))">{{ clock(endedAt(rule)) }}</time>
+        </li>
+      </ul>
+    </details>
+  </section>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, onMounted, reactive, ref, watch } from "vue";
+import {
+  describeWakeRule,
+  formatWakeClock,
+  formatWakeSpan,
+  type WakeRule,
+  type WakeRuleApi,
+} from "../wake-rules.mjs";
+import WakeGlyph from "./WakeGlyph.vue";
+
+const props = withDefaults(defineProps<{
+  roomId: string;
+  /** The agent's active rules, soonest first. */
+  rules: readonly WakeRule[];
+  recent?: readonly WakeRule[];
+  /** Without an API the panel is read-only. */
+  api?: Pick<WakeRuleApi, "cancel" | "restore"> | null;
+}>(), { recent: () => [], api: null });
+const emit = defineEmits<{ "open-message": [messageId: string] }>();
+
+/** How long a cancelled rule stays in place with Undo before it leaves. */
+const UNDO_WINDOW_MS = 8000;
+const now = ref(new Date());
+const busy = reactive(new Set<string>());
+const errors = reactive(new Map<string, string>());
+const cancelled = reactive(new Map<string, { rule: WakeRule; timer: ReturnType<typeof setTimeout> }>());
+/**
+ * Restored rules stay on screen until the room's lists catch up: back among
+ * the active rules, or among recent ones if anything that happened while it
+ * was cancelled woke the agent straight away.
+ */
+const restored = reactive(new Map<string, WakeRule>());
+watch(() => [props.rules, props.recent] as const, ([rules, recent]) => {
+  for (const rule of [...rules, ...recent]) {
+    if (rule.status !== "cancelled") restored.delete(rule.id);
+  }
+});
+
+// Undo happens where the action was: a cancelled rule keeps its row until
+// the window closes, even after the room's list no longer includes it.
+const rows = computed(() => {
+  const active = props.rules.filter((rule) => !cancelled.has(rule.id));
+  const held = [...cancelled.values()].map(({ rule }) => rule);
+  const revived = [...restored.values()].filter((rule) => !cancelled.has(rule.id) && !props.rules.some((candidate) => candidate.id === rule.id));
+  return [...active, ...held, ...revived]
+    .sort((left, right) => left.created_at.localeCompare(right.created_at) || left.id.localeCompare(right.id))
+    .map((rule) => ({ rule, cancelled: cancelled.has(rule.id), error: errors.get(rule.id) ?? null }));
+});
+
+const describe = (rule: Pick<WakeRule, "event" | "arguments">) =>
+  describeWakeRule(rule, { formatTime: (iso) => formatWakeClock(iso, now.value) });
+const clock = (iso: string) => formatWakeClock(iso, now.value);
+const span = (iso: string) => formatWakeSpan(now.value.getTime() - Date.parse(iso));
+const until = (iso: string) => formatWakeSpan(Date.parse(iso) - now.value.getTime());
+const fullTime = (iso: string | undefined) => iso
+  ? new Date(iso).toLocaleString(undefined, { dateStyle: "medium", timeStyle: "short" })
+  : "";
+const endedAt = (rule: WakeRule) => rule.last_fired_at ?? rule.updated_at;
+const root = ref<HTMLElement | null>(null);
+
+/**
+ * Cancel and Undo replace each other in the same place. When the pressed
+ * button was focused, focus moves to its replacement instead of the page.
+ */
+async function keepFocusOnRow(ruleId: string, hadFocus: boolean): Promise<void> {
+  if (!hadFocus) return;
+  await nextTick();
+  root.value?.querySelector<HTMLButtonElement>(`[data-rule-id="${CSS.escape(ruleId)}"] .wake-rule-action`)?.focus();
+}
+
+function rowHasFocus(ruleId: string): boolean {
+  const active = document.activeElement;
+  return Boolean(active && root.value?.querySelector(`[data-rule-id="${CSS.escape(ruleId)}"]`)?.contains(active));
+}
+
+function outcomeLabel(rule: WakeRule): string {
+  if (rule.status === "fired" || (rule.status === "active" && rule.fire_count > 0)) return "Woke";
+  if (rule.status === "expired") return "Stopped waiting";
+  return rule.cancelled_by ? `Cancelled by ${rule.cancelled_by.label}` : "Cancelled";
+}
+
+function release(ruleId: string): void {
+  const held = cancelled.get(ruleId);
+  if (held) clearTimeout(held.timer);
+  cancelled.delete(ruleId);
+}
+
+async function cancel(rule: WakeRule): Promise<void> {
+  if (!props.api || busy.has(rule.id)) return;
+  const hadFocus = rowHasFocus(rule.id);
+  busy.add(rule.id);
+  errors.delete(rule.id);
+  cancelled.set(rule.id, { rule, timer: setTimeout(() => release(rule.id), UNDO_WINDOW_MS) });
+  try {
+    await props.api.cancel(props.roomId, rule.id);
+  } catch (error) {
+    release(rule.id);
+    errors.set(rule.id, error instanceof Error ? error.message : "Couldn't cancel this wake rule. Try again.");
+  } finally {
+    busy.delete(rule.id);
+  }
+  // Undo (or Cancel again, if cancelling failed) is enabled only now.
+  await keepFocusOnRow(rule.id, hadFocus);
+}
+
+async function undo(rule: WakeRule): Promise<void> {
+  if (!props.api || busy.has(rule.id)) return;
+  const hadFocus = rowHasFocus(rule.id);
+  busy.add(rule.id);
+  try {
+    restored.set(rule.id, await props.api.restore(props.roomId, rule.id));
+    release(rule.id);
+  } catch (error) {
+    errors.set(rule.id, error instanceof Error ? error.message : "Couldn't restore this wake rule.");
+  } finally {
+    busy.delete(rule.id);
+  }
+  await keepFocusOnRow(rule.id, hadFocus);
+}
+
+let tick: ReturnType<typeof setInterval> | undefined;
+onMounted(() => {
+  tick = setInterval(() => { now.value = new Date(); }, 30_000);
+});
+onBeforeUnmount(() => {
+  clearInterval(tick);
+  for (const ruleId of [...cancelled.keys()]) release(ruleId);
+});
+</script>
+
+<style src="./wake-rules.css"></style>

package/shared/ui/wake-rules.css

@@ -0,0 +1,273 @@
+/*
+ * Wake rules read as a quiet state, not an alert: neutral colour, one glyph,
+ * and motion only when a person changes something.
+ */
+.wake-rules {
+  display: grid;
+  gap: 8px;
+}
+.wake-rules ul {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.wake-rules time,
+.wake-rule-copy strong {
+  font-variant-numeric: tabular-nums slashed-zero;
+}
+
+.wake-rules-active {
+  position: relative;
+  display: grid;
+  gap: 8px;
+}
+.wake-rule {
+  display: grid;
+  grid-template-columns: 30px minmax(0, 1fr) auto;
+  gap: 11px;
+  align-items: start;
+  padding: 14px;
+  border: 1px solid color-mix(in srgb, var(--text) 7.5%, transparent);
+  border-radius: 16px;
+  background: color-mix(in srgb, var(--text) 2.6%, transparent);
+}
+.wake-rule-mark {
+  display: grid;
+  place-items: center;
+  width: 30px;
+  height: 30px;
+  border-radius: 10px;
+  background: color-mix(in srgb, var(--text-secondary) 12%, transparent);
+  color: var(--text-secondary);
+}
+.wake-rule-copy {
+  min-width: 0;
+}
+.wake-rule-kicker {
+  margin: 0;
+  color: var(--text-secondary);
+  font-size: 0.64rem;
+  font-weight: 760;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+.wake-rule-copy strong {
+  display: block;
+  margin-top: 4px;
+  color: var(--text);
+  font-size: 0.84rem;
+  font-weight: 640;
+  line-height: 1.45;
+  overflow-wrap: anywhere;
+}
+.wake-rule-note {
+  display: block;
+  margin-top: 3px;
+  color: var(--text-secondary);
+  font-size: 0.75rem;
+  line-height: 1.45;
+  overflow-wrap: anywhere;
+}
+.wake-rule-meta {
+  display: block;
+  margin-top: 6px;
+  color: var(--text-tertiary);
+  font-size: 0.69rem;
+  line-height: 1.4;
+}
+.wake-rule-error {
+  display: block;
+  margin-top: 6px;
+  color: var(--red-text);
+  font-size: 0.71rem;
+  line-height: 1.4;
+}
+.wake-rule[data-state="cancelled"] {
+  border-style: dashed;
+  background: transparent;
+}
+.wake-rule[data-state="cancelled"] .wake-rule-copy strong {
+  color: var(--text-secondary);
+  text-decoration: line-through;
+  text-decoration-color: color-mix(in srgb, var(--text-secondary) 45%, transparent);
+}
+
+.wake-rule-action {
+  align-self: center;
+  min-height: 32px;
+  padding: 0 11px;
+  border: 1px solid color-mix(in srgb, var(--text) 12%, transparent);
+  border-radius: 9px;
+  background: transparent;
+  color: var(--text-secondary);
+  font: inherit;
+  font-size: 0.72rem;
+  font-weight: 650;
+  cursor: pointer;
+  transition:
+    transform 120ms var(--ease-out),
+    background-color 140ms ease,
+    border-color 140ms ease,
+    color 140ms ease;
+}
+.wake-rule-action[data-tone="undo"] {
+  border-color: color-mix(in srgb, var(--blue) 38%, transparent);
+  color: var(--blue);
+}
+@media (hover: hover) and (pointer: fine) {
+  .wake-rule-action:hover:not(:disabled) {
+    background: color-mix(in srgb, var(--text) 6%, transparent);
+    color: var(--text);
+  }
+  .wake-rule-action[data-tone="undo"]:hover:not(:disabled) {
+    background: color-mix(in srgb, var(--blue) 10%, transparent);
+    color: var(--blue);
+  }
+}
+.wake-rule-action:active:not(:disabled) {
+  transform: scale(0.97);
+}
+.wake-rule-action:focus-visible,
+.wake-rules-recent summary:focus-visible,
+.wake-rules-recent-time:focus-visible {
+  outline: 2px solid var(--blue);
+  outline-offset: 2px;
+}
+.wake-rule-action:disabled {
+  cursor: default;
+  opacity: 0.5;
+}
+
+/* A person's cancel or undo is the only change that moves a row. */
+.wake-rule-enter-active {
+  transition: opacity 220ms var(--ease-out), transform 220ms var(--ease-out);
+}
+.wake-rule-enter-from {
+  opacity: 0;
+  transform: translateY(4px) scale(0.98);
+}
+.wake-rule-leave-active {
+  position: absolute;
+  inset-inline: 0;
+  pointer-events: none;
+  transition: opacity 150ms ease-in, transform 150ms ease-in;
+}
+.wake-rule-leave-to {
+  opacity: 0;
+  transform: scale(0.99);
+}
+.wake-rule-move {
+  transition: transform 220ms var(--ease-out);
+}
+
+.wake-rules-recent summary {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  width: fit-content;
+  padding: 4px 2px;
+  border-radius: 6px;
+  color: var(--text-secondary);
+  font-size: 0.64rem;
+  font-weight: 760;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  list-style: none;
+  cursor: pointer;
+}
+.wake-rules-recent summary::-webkit-details-marker {
+  display: none;
+}
+.wake-rules-recent summary::before {
+  content: "";
+  width: 5px;
+  height: 5px;
+  border-right: 1.5px solid currentColor;
+  border-bottom: 1.5px solid currentColor;
+  rotate: -45deg;
+  transition: rotate 160ms var(--ease-out);
+}
+.wake-rules-recent[open] summary::before {
+  rotate: 45deg;
+}
+.wake-rules-recent summary span {
+  color: var(--text-tertiary);
+  letter-spacing: 0;
+}
+.wake-rules-recent li {
+  display: grid;
+  grid-template-columns: 16px minmax(0, 1fr) auto;
+  gap: 9px;
+  align-items: center;
+  padding: 7px 2px;
+  color: var(--text-tertiary);
+  font-size: 0.73rem;
+  line-height: 1.4;
+}
+.wake-rules-recent li[data-status="fired"] > .wake-glyph {
+  color: var(--text-secondary);
+}
+.wake-rules-recent-copy {
+  display: flex;
+  gap: 6px;
+  min-width: 0;
+}
+.wake-rules-recent-copy strong {
+  flex-shrink: 0;
+  color: var(--text-secondary);
+  font-weight: 650;
+}
+.wake-rules-recent-copy span {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.wake-rules-recent-time {
+  min-height: 0;
+  padding: 2px 4px;
+  border: 0;
+  border-radius: 5px;
+  background: transparent;
+  color: var(--text-tertiary);
+  font: inherit;
+  font-size: 0.69rem;
+  line-height: 1.4;
+}
+/* An inline link: compact row, generous target. Hosts may size buttons for touch. */
+.wake-rules button.wake-rules-recent-time {
+  position: relative;
+  min-height: 0;
+  cursor: pointer;
+}
+.wake-rules button.wake-rules-recent-time::after {
+  content: "";
+  position: absolute;
+  inset: -8px -6px;
+}
+@media (hover: hover) and (pointer: fine) {
+  button.wake-rules-recent-time:hover {
+    color: var(--text);
+    text-decoration: underline;
+    text-underline-offset: 2px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .wake-rule-enter-active,
+  .wake-rule-leave-active,
+  .wake-rule-move {
+    transition: opacity 150ms ease;
+  }
+  .wake-rule-enter-from,
+  .wake-rule-leave-to {
+    transform: none;
+  }
+  .wake-rules-recent summary::before {
+    transition: none;
+  }
+}
+@media (prefers-contrast: more) {
+  .wake-rule {
+    border-color: color-mix(in srgb, var(--text) 28%, transparent);
+  }
+}

package/shared/wake-rules.d.mts

@@ -0,0 +1,145 @@
+export type WakeRuleEvent =
+  | "timer"
+  | "task.status_changed"
+  | "github.check_completed"
+  | "github.review_submitted"
+  | "github.pr_closed";
+export type WakeRuleStatus = "active" | "fired" | "expired" | "cancelled";
+export type WakeTaskStatus =
+  | "proposed" | "accepted" | "assigned" | "in_progress" | "blocked" | "in_review" | "merged" | "done" | "cancelled";
+export type WakeCheckConclusion =
+  | "success" | "failure" | "neutral" | "cancelled" | "skipped" | "timed_out" | "action_required" | "stale";
+export type WakeReviewState = "approved" | "changes_requested" | "commented";
+
+export interface WakeRuleArguments {
+  at?: string;
+  task_id?: string;
+  to?: WakeTaskStatus[];
+  branch?: string;
+  pr?: number;
+  mine?: true;
+  conclusions?: WakeCheckConclusion[];
+  states?: WakeReviewState[];
+  merged_only?: true;
+}
+
+export interface WakeRuleInput {
+  event: WakeRuleEvent;
+  arguments?: Record<string, unknown>;
+  repeat?: boolean;
+  expires_at?: string;
+  note?: string | null;
+}
+
+export interface ParsedWakeRuleInput {
+  event: WakeRuleEvent;
+  arguments: WakeRuleArguments;
+  repeat: boolean;
+  expires_at: string;
+  note: string | null;
+}
+
+export interface WakeRuleActor { kind: "agent" | "human"; id: string; label: string }
+
+/** A rule as the API returns it to agents, people and apps. */
+export interface WakeRule extends ParsedWakeRuleInput {
+  id: string;
+  room_id: string;
+  agent_key: string;
+  agent_name: string;
+  status: WakeRuleStatus;
+  created_at: string;
+  updated_at: string;
+  fire_count: number;
+  last_fired_at: string | null;
+  /** The room message that last woke the agent, when it fired or expired. */
+  wake_message_id: string | null;
+  cancelled_by: WakeRuleActor | null;
+}
+
+export interface WakeRulePage {
+  room_id: string;
+  active: WakeRule[];
+  /** Rules that fired, expired or were cancelled in the last 7 days, newest first. */
+  recent: WakeRule[];
+}
+
+/** Supplied by each app to the shared wake-rule components. */
+export interface WakeRuleApi {
+  list(roomId: string): Promise<WakeRulePage>;
+  cancel(roomId: string, ruleId: string): Promise<WakeRule>;
+  restore(roomId: string, ruleId: string): Promise<WakeRule>;
+}
+
+export type WakeNoticeOutcome = "fired" | "expired";
+
+export interface WakeCheckFact { name: string; conclusion: string; url: string | null }
+export interface WakeCheckPushFact { head_ref: string | null; checks: WakeCheckFact[] }
+export interface WakeOccurrenceFacts {
+  task_id?: string;
+  status?: string;
+  previous_status?: string;
+  pr?: number | null;
+  /** CI: every settled push that mattered, each with the latest result of its checks. */
+  pushes?: WakeCheckPushFact[];
+  reviewer?: string | null;
+  state?: string;
+  merged?: boolean;
+  url?: string | null;
+  /** The newest event considered, so a repeating rule only looks after it. */
+  cursor_at?: string;
+}
+
+export const WAKE_RULE_EVENTS: readonly WakeRuleEvent[];
+export const WAKE_RULE_STATUSES: readonly WakeRuleStatus[];
+export const WAKE_NOTICE_SOURCE: "wake_rule";
+export const WAKE_RULE_LIMITS: Readonly<{
+  activePerAgent: number;
+  defaultTtlMs: number;
+  maxTtlMs: number;
+  minLeadMs: number;
+  noteMaxLength: number;
+  branchMaxLength: number;
+  repeatDebounceMs: number;
+  checkSettleMs: number;
+  timerGraceMs: number;
+}>;
+export const WAKE_TASK_STATUSES: readonly WakeTaskStatus[];
+export const WAKE_CHECK_CONCLUSIONS: readonly WakeCheckConclusion[];
+export const WAKE_REVIEW_STATES: readonly WakeReviewState[];
+
+export class WakeRuleError extends Error { status: number; constructor(message: string, status?: number) }
+
+export function parseWakeRuleInput(value: unknown, now?: Date): ParsedWakeRuleInput;
+export function wakeRuleIdentityKey(event: WakeRuleEvent, args: WakeRuleArguments): string;
+export function isFailedCheckConclusion(conclusion: string): boolean;
+
+type Describable = Pick<WakeRule, "event" | "arguments">;
+export interface WakeRuleDescribeOptions { formatTime?: (iso: string) => string }
+export function describeWakeRule(rule: Describable, options?: WakeRuleDescribeOptions): { preposition: "for" | "until"; object: string };
+export function wakeRuleLabel(rule: Describable, options?: WakeRuleDescribeOptions): string;
+export function describeWakeOccurrence(rule: Describable, facts: WakeOccurrenceFacts): string;
+export function formatWakeNotice(input: {
+  rule: Pick<WakeRule, "id" | "event" | "arguments" | "note" | "repeat" | "expires_at"> & { fire_count?: number };
+  outcome: WakeNoticeOutcome;
+  facts: WakeOccurrenceFacts;
+  agentName: string | null | undefined;
+}): { text: string; display_text: string };
+
+export function formatWakeClock(iso: string, now?: Date, locale?: string): string;
+export function formatWakeSpan(ms: number): string;
+export function wakeRuleTiming(
+  rule: Pick<WakeRule, "event" | "arguments" | "created_at">,
+  now?: Date,
+  locale?: string,
+): { text: string; datetime: string };
+export function summarizeWakeRuleParts(
+  rules: readonly Pick<WakeRule, "event" | "arguments" | "created_at">[] | null | undefined,
+  now?: Date,
+  locale?: string,
+): { label: string; detail: string } | null;
+export function summarizeWakeRules(
+  rules: readonly Pick<WakeRule, "event" | "arguments" | "created_at">[] | null | undefined,
+  now?: Date,
+  locale?: string,
+): string | null;