feat(quick): stop or snooze a ringing alarm by saying so

CHANGELOG.md

@@ -6,6 +6,12 @@ and versions follow [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 
 ### Added
+- **Say "stop" or "snooze" to a ringing alarm.** While a Sentient alarm rings, typing or saying "stop", "stop the
+  alarm", "turn it off", "snooze" or "snooze for 5 minutes" in a chat, by voice or in Telegram, Discord or WhatsApp
+  stops or snoozes it at once, with no model ("Alarm stopped.", "Snoozed until 7:39 AM."). A snooze is 9 minutes
+  unless you say how long or change "Snooze length" in Settings. The banner has a Snooze button too, and after a
+  snooze it shows until when, with Turn off. When no alarm is ringing, these words go to the assistant as before, so
+  "turn off the alarm" can still mean your house alarm (#390).
 - **Sentient in group chats, safely.** You can now pair a Telegram group or a Discord server channel with the same
   `/pair` code. Sentient answers only you there, when you mention it, reply to it or send a command. What other people
   write is treated like an email from a stranger: Sentient can read it, but never takes orders from it, and after

desktop/src/components/shell/AlarmBanner.tsx

@@ -1,18 +1,24 @@
-/** #359 A ringing alarm: a banner with Stop while the chime plays (stores/alarm.ts). */
-import { IconAlarm, IconVolume, IconVolumeOff } from '@tabler/icons-react'
+/** #359 A ringing alarm: a banner with Stop and Snooze while the chime plays (stores/alarm.ts). #390: after a snooze,
+ *  from here or by saying "snooze" anywhere, it says until when, with Turn off. */
+import { IconAlarm, IconAlarmSnooze, IconVolume, IconVolumeOff, IconX } from '@tabler/icons-react'
 import { AnimatePresence, motion } from 'motion/react'
-import { Button } from '@/components/ui'
+import { Button, IconButton } from '@/components/ui'
+import { formatTime } from '@/lib/utils'
 import { useAlarm } from '@/stores/alarm'
 
 export function AlarmBanner() {
   const ringing = useAlarm((s) => s.ringing)
+  const snoozed = useAlarm((s) => s.snoozed)
   const playing = useAlarm((s) => s.playing)
   const stop = useAlarm((s) => s.stop)
+  const snooze = useAlarm((s) => s.snooze)
+  const turnOff = useAlarm((s) => s.turnOff)
 
   return (
     <AnimatePresence initial={false}>
       {ringing && (
         <motion.div
+          key="ringing"
           initial={{ height: 0, opacity: 0 }}
           animate={{ height: 'auto', opacity: 1 }}
           exit={{ height: 0, opacity: 0 }}
@@ -35,12 +41,46 @@ export function AlarmBanner() {
               {playing ? <IconVolume size={14} /> : <IconVolumeOff size={14} />}
               {playing ? 'Ringing' : "Can't play sound"}
             </span>
+            {ringing.reminderId && (
+              <Button size="sm" variant="secondary" onClick={snooze}>
+                Snooze
+              </Button>
+            )}
             <Button size="sm" variant="primary" onClick={stop} autoFocus>
               Stop
             </Button>
           </div>
         </motion.div>
       )}
+      {!ringing && snoozed && (
+        <motion.div
+          key="snoozed"
+          initial={{ height: 0, opacity: 0 }}
+          animate={{ height: 'auto', opacity: 1 }}
+          exit={{ height: 0, opacity: 0 }}
+          className="shrink-0 overflow-hidden border-b border-border bg-elevated"
+          role="status"
+        >
+          <div className="flex items-center gap-3 px-4 py-2 text-sm text-fg">
+            <span className="flex text-fg-muted">
+              <IconAlarmSnooze size={20} />
+            </span>
+            <span className="min-w-0 flex-1">
+              <span className="font-medium">{snoozed.title}</span>{' '}
+              <span className="text-fg-muted">Snoozed until {formatTime(snoozed.until)}</span>
+            </span>
+            <Button size="sm" variant="secondary" onClick={turnOff}>
+              Turn off
+            </Button>
+            <IconButton
+              size="sm"
+              icon={<IconX size={14} />}
+              label="Hide"
+              onClick={() => useAlarm.setState({ snoozed: null })}
+            />
+          </div>
+        </motion.div>
+      )}
     </AnimatePresence>
   )
 }

desktop/src/features/settings/SchemaForm.tsx

@@ -33,6 +33,11 @@ export const LABELS: Record<string, FieldLabel> = {
     description:
       'Simple requests like "set a timer for 10 minutes", "remind me at 6 pm to call Ravi", "wake me at 7" or "what\'s next on my calendar" happen at once, without the model. English for now.'
   },
+  'chat.alarm_snooze_minutes': {
+    label: 'Snooze length',
+    unit: 'min',
+    description: 'How long "snooze" puts off a ringing alarm, unless you say how long ("snooze for 5 minutes").'
+  },
   // channels (#359)
   'channels.deliver_reminders': {
     label: 'Reminders and alarms on your phone too',

desktop/src/lib/api.ts

@@ -122,6 +122,7 @@ import type {
   RoleName,
   Reminder,
   ReminderStatus,
+  SnoozedAlarm,
   RuleProposal,
   SecretStatus,
   SentientConfig,
@@ -902,7 +903,11 @@ export const api = {
   // §23 timers and reminders (#150) -------------------------------------------------------------
   reminders: {
     list: (status: ReminderStatus | 'all' = 'scheduled') => http.get<{ reminders: Reminder[] }>('/api/reminders', { query: { status } }),
-    cancel: (id: string) => http.post<Reminder>(`/api/reminders/${enc(id)}/cancel`)
+    cancel: (id: string) => http.post<Reminder>(`/api/reminders/${enc(id)}/cancel`),
+    /** Stop a ringing alarm (#390). */
+    stop: (id: string) => http.post<Reminder>(`/api/reminders/${enc(id)}/stop`),
+    /** Snooze a ringing alarm (#390); minutes default to the snooze setting. */
+    snooze: (id: string, minutes?: number) => http.post<SnoozedAlarm>(`/api/reminders/${enc(id)}/snooze`, minutes ? { minutes } : {})
   },
 
   // §16 webhooks --------------------------------------------------------------------------

desktop/src/lib/events.ts

@@ -183,6 +183,8 @@ export function installDomainEvents(qc: QueryClient): () => void {
       if (e.data?.id === 'webhook') void qc.invalidateQueries({ queryKey: qk.hooks })
     })
   )
+  // #390: a ringing alarm stopped or snoozed anywhere (a chat, voice, a messaging app) updates the banner
+  offs.push(live.onDomain('reminder.updated', (e) => useAlarm.getState().updated(e.data)))
   offs.push(live.onDomain('memory.updated', () => void qc.invalidateQueries({ queryKey: qk.memories.all })))
   offs.push(live.onDomain('skill.updated', () => void qc.invalidateQueries({ queryKey: qk.skills.all })))
   offs.push(live.onDomain('mcp.review', () => void qc.invalidateQueries({ queryKey: qk.integrations.mcp })))

desktop/src/lib/types.ts

@@ -2991,4 +2991,13 @@ export interface Reminder {
   fired_at: ISODate | null
   cancelled_at: ISODate | null
   notification_id: string | null
+  /** An alarm: when it was stopped or snoozed while ringing (#390). */
+  stopped_at?: ISODate | null
+  /** An alarm made by a snooze: the id of the alarm that was ringing (#390). */
+  snoozed_from?: string | null
+}
+
+export interface SnoozedAlarm {
+  stopped: Reminder
+  reminder: Reminder
 }

desktop/src/stores/alarm.ts

@@ -1,26 +1,48 @@
 /**
  * A ringing alarm (#359). An alarm's `reminder` notification (`payload.event = "alarm"`) starts a chime made with
- * Web Audio, so no sound file ships with the app. It rings until Stop, or for `MAX_RING_MS` at most.
+ * Web Audio, so no sound file ships with the app. It rings until Stop or Snooze, or for `MAX_RING_MS` at most.
+ *
+ * The engine knows which alarm rings too (#390): Stop and Snooze here tell it, and saying "stop" or "snooze" in a chat,
+ * by voice or in a messaging app stops or snoozes it there. Its `reminder.updated` events then update the banner:
+ * a snooze turns it into "Snoozed until 7:39 AM", a stop hides it.
  */
 import { create } from 'zustand'
-import type { Notification } from '@/lib/types'
+import { api } from '@/lib/api'
+import type { Notification, Reminder } from '@/lib/types'
 
-const MAX_RING_MS = 3 * 60_000
+const MAX_RING_MS = 3 * 60_000 // the engine's RING_S
 const PATTERN_MS = 1400
 
 export interface RingingAlarm {
   id: string
+  /** The alarm in the engine (`payload.reminder_id`), when the notification has one. */
+  reminderId?: string
   title: string
   message: string
   startedAt: number
 }
 
+export interface Snoozed {
+  /** The new alarm the snooze set. */
+  reminderId: string
+  title: string
+  until: string
+}
+
 interface AlarmState {
   ringing: RingingAlarm | null
+  snoozed: Snoozed | null
   /** True while the sound is really playing (the audio output started). */
   playing: boolean
   ring: (n: Notification) => void
+  /** Stop button: silence it here and tell the engine. */
   stop: () => void
+  /** Snooze button: silence it here and ask the engine for a snooze. */
+  snooze: () => void
+  /** Turn off a snoozed alarm (cancels the alarm the snooze set). */
+  turnOff: () => void
+  /** A `reminder.updated` event: a stop or snooze from anywhere (#390). */
+  updated: (r: Reminder) => void
 }
 
 let ctx: AudioContext | null = null
@@ -57,12 +79,22 @@ export function isAlarm(n: Notification): boolean {
   return n.kind === 'reminder' && n.payload?.event === 'alarm'
 }
 
+function reminderOf(n: Notification): string | undefined {
+  const id = n.payload?.reminder_id
+  return typeof id === 'string' && id ? id : undefined
+}
+
 export const useAlarm = create<AlarmState>((set, get) => ({
   ringing: null,
+  snoozed: null,
   playing: false,
   ring: (n) => {
     silence()
-    set({ ringing: { id: n.id, title: n.title || 'Alarm', message: n.message, startedAt: Date.now() }, playing: false })
+    set({
+      ringing: { id: n.id, reminderId: reminderOf(n), title: n.title || 'Alarm', message: n.message, startedAt: Date.now() },
+      snoozed: null,
+      playing: false
+    })
     try {
       const audio = new AudioContext()
       ctx = audio
@@ -80,11 +112,45 @@ export const useAlarm = create<AlarmState>((set, get) => ({
       set({ playing: false }) // no audio output: the card and the notification still show
     }
     limit = window.setTimeout(() => {
-      if (get().ringing?.id === n.id) get().stop()
+      if (get().ringing?.id === n.id) {
+        silence() // the engine stops counting it as ringing at the same time
+        set({ ringing: null, playing: false })
+      }
     }, MAX_RING_MS)
   },
   stop: () => {
+    const id = get().ringing?.reminderId
     silence()
     set({ ringing: null, playing: false })
+    if (id) void api.reminders.stop(id).catch(() => undefined) // already stopped elsewhere: nothing to do
+  },
+  snooze: () => {
+    const ringing = get().ringing
+    if (!ringing?.reminderId) return get().stop()
+    silence()
+    set({ ringing: null, playing: false })
+    void api.reminders.snooze(ringing.reminderId).then(
+      ({ reminder }) => {
+        if (!get().ringing) set({ snoozed: { reminderId: reminder.id, title: ringing.title, until: reminder.fire_at } })
+      },
+      () => undefined // it had stopped already
+    )
+  },
+  turnOff: () => {
+    const snoozed = get().snoozed
+    set({ snoozed: null })
+    if (snoozed) void api.reminders.cancel(snoozed.reminderId).catch(() => undefined)
+  },
+  updated: (r) => {
+    const { ringing, snoozed } = get()
+    if (ringing?.reminderId && r.snoozed_from === ringing.reminderId && r.status === 'scheduled') {
+      silence()
+      set({ ringing: null, playing: false, snoozed: { reminderId: r.id, title: ringing.title, until: r.fire_at } })
+    } else if (ringing?.reminderId === r.id && r.stopped_at) {
+      silence()
+      set({ ringing: null, playing: false })
+    } else if (snoozed?.reminderId === r.id && r.status !== 'scheduled') {
+      set({ snoozed: null }) // it was turned off, or it is ringing again
+    }
   }
 }))

docs/API.md

@@ -104,7 +104,7 @@ Envelope: `{"type": "task.updated", "data": {...}, "ts": "..."}`
 | `import.updated` | **MemoryImportJob** (section 19): an import from ChatGPT, Claude or OpenClaw started, read a batch or finished |
 | `backup.updated` | `{what: "backup"\|"snapshot"\|"restore_staged"\|"restore_cancelled"\|"restore_dismissed", name?, source?}` (section 20): refetch `GET /api/backups` |
 | `folders.updated` | `{id, removed?: true, progress?: {done, total}}` (section 22): a folder was added, removed or queued, or a look through it started, moved on (at most once a second) or ended; refetch `GET /api/folders` |
-| `reminder.updated` | **Reminder** (section 23): a timer or reminder was set, cancelled or went off |
+| `reminder.updated` | **Reminder** (section 23): a timer or reminder was set, cancelled or went off, or a ringing alarm was stopped or snoozed |
 
 ---
 
@@ -3346,6 +3346,7 @@ language under `sentient/agent/fastpath/`, tried for `assistant.language` and th
 | cancel | "cancel the timer", "stop the pasta timer", "cancel the 10 minute timer", "cancel my reminder to stretch", "cancel all timers", "turn off the gym alarm" | two or more match and "all" was not said; nothing matches the words given; a plural without "all" |
 | home (#175) | "turn off the living room lights", "turn on the bedroom lamp", "living room lights off", "turn the lights in the kitchen off", "switch off all the lights", "dim the living room lights to 30%", "turn on the coffee maker" | Home Assistant not connected or not reachable; the words name no room or device exactly (one light named that, the lights of the room named that, or the lights whose names hold every word); "the bedroom light" when the bedroom has two; "the lights" without a room or "all"; a device left out by the entity picker; locks, alarms, doors, garage doors and gates, and switches that sound like one (never quick); a question ("is the porch light on") |
 | alarm (#359) | "wake me at 7", "wake me up at 6:30 am", "set an alarm for 6:30", "set an alarm for 6:30 tomorrow", "set a 6:30 alarm", "set an alarm for 7 called gym", "wake me up in 20 minutes" | a repeating wish, a day name, "today" at a time that has passed, "tomorrow morning" |
+| stop or snooze a ringing alarm (#390) | only while a Sentient alarm rings: "stop", "stop the alarm", "turn it off", "turn off the gym alarm", "I'm up" (`stop_alarm`, "Alarm stopped."); "snooze", "snooze for 5 minutes", "snooze 10", "5 more minutes" (`snooze_alarm`, "Snoozed until 7:39 AM.") | nothing ringing ("stop the alarm" may mean a house alarm, #175: the usual commands and then the model have it); the words name another alarm ("stop the pasta alarm"); a snooze that is unclear ("snooze for a bit") or over 3 hours |
 | calendar (#359) | "what's next on my calendar", "what's my next meeting", "when is my next meeting", "what do I have next" | no calendar connected; anything more ("... and email it to Ravi"), another day ("what's on my calendar tomorrow"), a bare "what's next" |
 
 An alarm is the one place a clock time without AM or PM is fine, as on a phone: "set an alarm for 6:30" rings at the
@@ -3372,16 +3373,25 @@ off with `chat.quick_commands`.
 **Timers, reminders and alarms** (`sentient/reminders/`, table `reminders`). **Reminder**
 `{id, kind: "timer"|"reminder"|"alarm", message, connector: ""|"to"|"about"|"that", label, duration_s, fire_at, status:
 "scheduled"|"fired"|"cancelled", session_id, channel, language, source: "quick"|"chat"|"api", created_at, fired_at,
-cancelled_at, notification_id}`. `fire_at` is UTC; a clock time is read in the user's timezone
+cancelled_at, notification_id, stopped_at, snoozed_from}`. `fire_at` is UTC; a clock time is read in the user's timezone
 (`assistant.timezone`). `duration_s` is a timer's length or a reminder's "in 20 minutes". `session_id` is the chat it
 was set in (null in an incognito chat). A timer runs 1 second to 24 hours; a reminder or alarm can be up to a year
-ahead. An alarm has no `message`; its `label` names it ("gym").
+ahead. An alarm has no `message`; its `label` names it ("gym"). `stopped_at` is when a ringing alarm was stopped or
+snoozed; `snoozed_from` is set on an alarm made by a snooze, to the id of the alarm that was ringing (#390).
+
+**A ringing alarm (#390).** An alarm counts as ringing for 3 minutes after it goes off (as long as the window's chime
+plays), until it is stopped or snoozed: from the banner's **Stop** or **Snooze**, over REST, or by saying "stop" or
+"snooze" in any chat, by voice or in a messaging app (a quick command, above). A snooze stops it and sets a new alarm
+with the same `label`, `channel` and chat, `chat.alarm_snooze_minutes` from now (9 by default, 1 to 60), or the minutes
+said (1 minute to 3 hours). The engine publishes `reminder.updated` for the new alarm first and then for the one that
+stopped (`stopped_at` set), so the window turns the ringing banner into "Snoozed until 7:39 AM" (with **Turn off**,
+which cancels the snoozed alarm) or hides it when it stopped.
 
 When one comes due, the engine sends a `reminder` notification (`notification.new`): title "Timer done" (message "Your
 10 minute timer is done."), "Reminder" (message: what to remind about) or "Alarm" / "Alarm: gym" (message "It's
 7:00 AM.", or when late "Your 7:00 AM alarm went off while Sentient wasn't running."), payload `{event:
 "timer"|"reminder"|"alarm", reminder_id, fire_at, late, channel, session_id?}`. The window rings for an alarm: a
-banner with **Stop** and a chime (Web Audio, no sound file) that plays until Stop, for 3 minutes at most. One that came due while Sentient was not running goes off when it
+banner with **Stop** and **Snooze** and a chime (Web Audio, no sound file) that plays until Stop, for 3 minutes at most. One that came due while Sentient was not running goes off when it
 starts, and says when it was due (`late: true`). A reminder set in a Telegram, Discord or WhatsApp chat is also sent
 to that chat (the delivery is listed on the Activity timeline as "A timer, reminder or alarm you set"); one set
 anywhere else stays on the desktop, unless `channels.deliver_reminders` is on (#359, off by default; "Reminders and
@@ -3399,6 +3409,10 @@ ones are forgotten after 30 days.
 - `list_reminders(kind = "any")` (risk `read`; `kind` "timer", "reminder", "alarm" or "any") → `{status, reminders}`,
   soonest first.
 - `cancel_reminder(reminder_id)` (risk `write`) → `{status, reminder}`.
+- `stop_alarm()` (risk `write`, #390) → `{status, stopped: [Reminder]}`: stops every ringing alarm. `{error: "No Sentient
+  alarm is ringing right now."}` when none is (the model may then think of a house alarm, #175).
+- `snooze_alarm(minutes = 0)` (risk `write`, #390) → `{status, stopped, reminder}`: the alarm that rang and the new one.
+  `minutes` 0 is `chat.alarm_snooze_minutes`. With several ringing, the newest is snoozed and the others stop.
 
 Each `reminder` in a result also has `fire_at_local` and `seconds_left`.
 
@@ -3408,4 +3422,9 @@ Each `reminder` in a result also has `fire_at_local` and `seconds_left`.
 - `POST /api/reminders` `{kind: "timer"|"reminder"|"alarm", minutes?, at?, message?, label?}` → Reminder (`source: "api"`).
   400 with a plain `detail` when it can't be set.
 - `POST /api/reminders/{id}/cancel` → Reminder. 404 when unknown, 409 when it already went off or was cancelled.
+- `POST /api/reminders/{id}/stop` → Reminder (#390): stop that ringing alarm. 404 when unknown, 409 when it isn't
+  ringing.
+- `POST /api/reminders/{id}/snooze` `{minutes?}` → `{stopped: Reminder, reminder: Reminder}` (#390): snooze that ringing
+  alarm (`minutes` defaults to `chat.alarm_snooze_minutes`; the new alarm has `source: "api"`). 400 for a length
+  outside 1 minute to 3 hours, 404 when unknown, 409 when it isn't ringing.
 - Event `reminder.updated` (section 1). The Activity timeline (section 21) lists them under `reminders`.