@chatpanel/events 0.15.0 → 0.17.0

package/index.js

@@ -30,7 +30,7 @@ export { defineToolGroup, createToolGroupRegistry, ToolGroupError } from './tool
 export { toolNeedFor } from './tool-need.js';
 export { parseFlowchart, layoutFlowchart, renderFlowchartSvg } from './flowchart.js';
 export { validateView, validateViewInvocation, viewResult } from './view.js';
-export { validateWidget, validateWidgetMessage, effectiveGrants, WIDGET_SURFACES } from './widget.js';
+export { validateWidget, validateWidgetMessage, effectiveGrants, widgetIcon, WIDGET_SURFACES } from './widget.js';
 export { fuseRRF, planQueries, multiSearch } from './rrf.js';
 export {
   ACCESS_LOG_VERSION, ACCESS_LOG_MAX, redactAccessArgs, makeAccessEvent,
@@ -45,7 +45,22 @@ export { defineModel, defineMiddleware, defineRouteStrategy, createModelRouter,
 export { makeSourceStore, manifestText, shortUrl, readSource, sourceId } from './sources-retrieval.js';
 export { classifySource, extractUrls, hostMatches, meetReach, sourcePolicyFor, DEFAULT_INTERNAL_PATTERNS, INTERNAL_PATTERN_CATALOG } from './sources.js';
 export { defineRule, createRuleEngine, SUPPRESSED, RuleError } from './rules.js';
+export {
+  SCHEDULE_KINDS, TRIGGER_KINDS, JOB_ACTIONS, MISSED_POLICIES, ScheduleError,
+  validateSchedule, nextFireAt, occurrencesBetween, nextWakeAt,
+  defineTrigger, createTriggerRegistry, BUILTIN_TRIGGERS,
+  timerTrigger, meetingStartedTrigger, meetingEndedTrigger, personJoinedTrigger,
+  phraseTrigger, topicTrigger, questionTrigger, voiceCommandTrigger,
+  defineJob, dueJobs, jobsForEvent, occurrenceKey,
+} from './schedule.js';
 export { defineMeetingAnalyzer, createAnalyzerRegistry, CADENCES, AnalyzerError } from './meeting-analyzers.js';
+export {
+  DEFAULT_WAKE, MAX_COMMANDS_PER_DELTA, DAYPART_HOUR, VoiceIntentError,
+  compileWake, findWakeCommand, parseCommand, commandsFromSegments,
+  parseDuration, parseClock, parseWhen, parseNumberWords, normalizeSpeech, tokenize, editDistance,
+  defineVoiceIntent, createVoiceIntentRegistry, defaultVoiceIntents, BUILTIN_VOICE_INTENTS,
+  timerIntent, reminderIntent, scheduleIntent, noteIntent, monitorIntent,
+} from './voice-intents.js';
 export { explainMcpError, packageFromArgs } from './mcp-errors.js';
 export { createManifest, ManifestError, SOURCES } from './manifest.js';
 export { createKernel, meetDecisions, KernelError, REQUIRED_PLUGINS, ALLOW_ALL } from './kernel.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "The canonical ChatPanel event-log and capability contracts \u2014 typed durable facts, clock-free deterministic linearization, schema upcasting, and the invariants the replay harness asserts. Pure, dependency-free ESM shared by the ChatPanel extension, gateway and bridge.",
   "type": "module",
   "main": "index.js",
@@ -25,6 +25,7 @@
     "./route-graph.js": "./route-graph.js",
     "./router.js": "./router.js",
     "./rules.js": "./rules.js",
+    "./schedule.js": "./schedule.js",
     "./scopes.js": "./scopes.js",
     "./search-engines.js": "./search-engines.js",
     "./skill-manifest.js": "./skill-manifest.js",
@@ -39,6 +40,7 @@
     "./tool-need.js": "./tool-need.js",
     "./trajectory.js": "./trajectory.js",
     "./upcast.js": "./upcast.js",
+    "./voice-intents.js": "./voice-intents.js",
     "./observability.js": "./observability.js",
     "./flowchart.js": "./flowchart.js",
     "./rrf.js": "./rrf.js",
@@ -71,6 +73,7 @@
     "router.js",
     "rrf.js",
     "rules.js",
+    "schedule.js",
     "scopes.js",
     "search-engines.js",
     "skill-manifest.js",
@@ -85,6 +88,7 @@
     "tool-need.js",
     "trajectory.js",
     "upcast.js",
+    "voice-intents.js",
     "view.js",
     "widget.js"
   ],

package/schedule.js

@@ -0,0 +1,374 @@
+// Jobs — the thing that runs when nobody asked it to.
+//
+// Every turn ChatPanel has ever run began with a person pressing send. A job does not, and
+// that single difference is what this contract is mostly about: consent, cost, dedup and a
+// findable result all have to be settled BEFORE the run, because there is nobody sitting
+// there to judge the outcome.
+//
+// Three layers, and the split is the whole point (see docs/feature-f5-scheduler.md):
+//
+//   • schedule maths — "when does this next fire", "what did we miss while the laptop was
+//     asleep". Pure input → output, and wrong in a subtly different way in every
+//     reimplementation, so it is written once, here.
+//   • the job model, admission and dedup — policy, also here.
+//   • WAKING UP — `chrome.alarms`, `WorkManager`, `BGTaskScheduler`. The only platform-bound
+//     part, injected by the client, never imported.
+//
+// A trigger says WHEN. It never says what, and it cannot widen what a job may do: a phrase
+// spoken in a meeting can start a job the user already created and approved, and can do
+// nothing else. That is deliberate — the transcript is written by everyone in the room.
+//
+// WALL CLOCK, NOT INTERVALS. "Every day at 8am" is stored as an hour and a minute, not as
+// 86_400_000 milliseconds, because the second one drifts by an hour twice a year and nobody
+// can explain why the brief started arriving at 7. `now` is injected for the same reason it
+// is everywhere else in this package: so a Wednesday can be tested on a Tuesday.
+
+export class ScheduleError extends Error {
+  constructor(code, message) { super(message); this.name = 'ScheduleError'; this.code = code; }
+}
+
+export const SCHEDULE_KINDS = Object.freeze(['once', 'interval', 'daily', 'weekly']);
+export const TRIGGER_KINDS = Object.freeze(['timer', 'meeting', 'voice', 'data']);
+/** What a job does when it fires. `skill` is the headline: the instruction IS a skill. */
+export const JOB_ACTIONS = Object.freeze(['skill', 'prompt', 'monitor', 'notify']);
+/** What to do about occurrences that passed while nothing was running. */
+export const MISSED_POLICIES = Object.freeze(['skip', 'runOnce', 'runAll']);
+
+const MAX_CATCH_UP = 20;   // a fortnight asleep must not queue a hundred model calls
+
+// ---------------------------------------------------------------------------
+// Schedule maths
+// ---------------------------------------------------------------------------
+
+function atLocal(base, { days = 0, hour, minute = 0 }) {
+  const d = new Date(base);
+  d.setDate(d.getDate() + days);
+  d.setHours(hour, minute, 0, 0);
+  return d.getTime();
+}
+
+const isWeekend = (ts) => { const d = new Date(ts).getDay(); return d === 0 || d === 6; };
+
+export function validateSchedule(s) {
+  if (!s || typeof s !== 'object') throw new ScheduleError('BAD_SCHEDULE', 'schedule must be an object');
+  if (!SCHEDULE_KINDS.includes(s.kind)) throw new ScheduleError('BAD_SCHEDULE', `unknown schedule kind '${s.kind}'`);
+  if (s.kind === 'once' && !(s.at > 0)) throw new ScheduleError('BAD_SCHEDULE', 'once needs `at`');
+  if (s.kind === 'interval' && !(s.everyMs >= 60_000)) {
+    // A minute is the floor every platform's scheduler shares (chrome.alarms refuses less).
+    // Accepting 5s here would produce a job that silently fires on somebody else's cadence.
+    throw new ScheduleError('BAD_SCHEDULE', 'interval needs everyMs >= 60000');
+  }
+  if (s.kind === 'daily' || s.kind === 'weekly') {
+    if (!Number.isInteger(s.hour) || s.hour < 0 || s.hour > 23) throw new ScheduleError('BAD_SCHEDULE', 'hour must be 0-23');
+    const m = s.minute ?? 0;
+    if (!Number.isInteger(m) || m < 0 || m > 59) throw new ScheduleError('BAD_SCHEDULE', 'minute must be 0-59');
+  }
+  if (s.kind === 'weekly' && (!Number.isInteger(s.weekday) || s.weekday < 0 || s.weekday > 6)) {
+    throw new ScheduleError('BAD_SCHEDULE', 'weekly needs weekday 0-6 (Sunday = 0)');
+  }
+  return s;
+}
+
+/**
+ * The first firing STRICTLY after `from`. Null when a one-shot is already spent.
+ *
+ * Strictly after, so feeding a fire time back in advances instead of returning the same
+ * occurrence forever — the loop that ran a job and then asked "what's next?" would otherwise
+ * never stop.
+ */
+export function nextFireAt(schedule, from) {
+  const s = validateSchedule(schedule);
+  const minute = s.minute ?? 0;
+  switch (s.kind) {
+    case 'once':
+      return s.at > from ? s.at : null;
+    case 'interval': {
+      // Anchored so a job restored from storage keeps its original phase instead of drifting
+      // a little later every time the extension restarts.
+      const anchor = s.anchor ?? from;
+      if (anchor > from) return anchor;
+      const steps = Math.floor((from - anchor) / s.everyMs) + 1;
+      return anchor + steps * s.everyMs;
+    }
+    case 'daily': {
+      let at = atLocal(from, { hour: s.hour, minute });
+      if (at <= from) at = atLocal(from, { days: 1, hour: s.hour, minute });
+      if (s.weekdaysOnly) for (let i = 0; i < 7 && isWeekend(at); i++) at = atLocal(at, { days: 1, hour: s.hour, minute });
+      return at;
+    }
+    case 'weekly': {
+      const day = new Date(from).getDay();
+      let delta = (s.weekday - day + 7) % 7;
+      if (delta === 0 && atLocal(from, { hour: s.hour, minute }) <= from) delta = 7;
+      return atLocal(from, { days: delta, hour: s.hour, minute });
+    }
+    default:
+      return null;
+  }
+}
+
+/** Every firing in (from, to], oldest first. Capped: a long sleep is not a queue of work. */
+export function occurrencesBetween(schedule, from, to, max = MAX_CATCH_UP) {
+  const out = [];
+  let cursor = from;
+  while (out.length < max) {
+    const at = nextFireAt(schedule, cursor);
+    if (at === null || at > to) break;
+    out.push(at);
+    cursor = at;
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Triggers — declarations. A trigger says WHEN, never what.
+// ---------------------------------------------------------------------------
+
+/**
+ * @param matches (event, params, ctx) => match | null. Pure and synchronous, like rules.js:
+ *        "did this match" must be answerable without side effects or a network.
+ * @param watches the event types it can possibly match, so a busy bus is cheap.
+ */
+export function defineTrigger({
+  id, label, kind, watches = [], description = '', classUsed = 'R', matches = null, params = {},
+}) {
+  if (!id) throw new ScheduleError('BAD_TRIGGER', 'trigger.id required');
+  if (!TRIGGER_KINDS.includes(kind)) throw new ScheduleError('BAD_TRIGGER', `trigger '${id}': unknown kind '${kind}'`);
+  if (kind !== 'timer' && typeof matches !== 'function') {
+    throw new ScheduleError('BAD_TRIGGER', `trigger '${id}': an event trigger needs matches()`);
+  }
+  return Object.freeze({ id, label: label || id, kind, watches: Object.freeze([...watches]), description, classUsed, matches, params: Object.freeze({ ...params }) });
+}
+
+export function createTriggerRegistry(triggers = []) {
+  const list = [...triggers];
+  return {
+    add(t) { list.push(t); return () => { const i = list.indexOf(t); if (i >= 0) list.splice(i, 1); }; },
+    list: () => [...list],
+    get: (id) => list.find((t) => t.id === id) || null,
+  };
+}
+
+const words = (s) => String(s || '').toLowerCase().match(/[\p{L}\p{N}']+/gu) || [];
+const norm = (s) => String(s || '').trim().toLowerCase();
+
+// Whose speech a meeting trigger cares about. The default is 'anyone' because a phrase
+// trigger is usually watching for what OTHERS say — unlike a spoken command, which is only
+// ever the owner's (see voice-intents.js).
+function speakerAllowed(want, speaker, ctx) {
+  if (want === 'me') return !!ctx?.isSelf?.(speaker);
+  if (want === 'others') return !ctx?.isSelf?.(speaker);
+  return true;
+}
+
+export const timerTrigger = defineTrigger({
+  id: 'timer:schedule',
+  label: 'On a schedule',
+  kind: 'timer',
+  description: 'Once, on an interval, daily, or on a weekday — "every weekday at 8am".',
+});
+
+export const meetingStartedTrigger = defineTrigger({
+  id: 'meeting:started',
+  label: 'When a meeting starts',
+  kind: 'meeting',
+  watches: ['meeting.started'],
+  matches: (event, params = {}) => {
+    if (params.platform && norm(event.platform) !== norm(params.platform)) return null;
+    if (params.titleIncludes && !norm(event.title).includes(norm(params.titleIncludes))) return null;
+    return { why: `meeting started: ${event.title || event.meetingId}` };
+  },
+});
+
+export const meetingEndedTrigger = defineTrigger({
+  id: 'meeting:ended',
+  label: 'When a meeting ends',
+  kind: 'meeting',
+  watches: ['meeting.ended'],
+  matches: (event) => ({ why: `meeting ended: ${event.title || event.meetingId}` }),
+});
+
+export const personJoinedTrigger = defineTrigger({
+  id: 'meeting:person-joined',
+  label: 'When someone joins',
+  kind: 'meeting',
+  watches: ['meeting.person-joined'],
+  // No names means anyone — "tell me when the call fills up" is as valid as "tell me when
+  // Alex joins", and an empty list that matched nothing would look like a broken job.
+  matches: (event, params = {}) => {
+    const want = (params.names || []).map(norm).filter(Boolean);
+    const joined = (event.people || []).filter((p) => !want.length || want.some((n) => norm(p) === n || norm(p).startsWith(`${n} `)));
+    return joined.length ? { why: `joined: ${joined.join(', ')}`, people: joined } : null;
+  },
+});
+
+export const phraseTrigger = defineTrigger({
+  id: 'meeting:phrase',
+  label: 'When a phrase is said',
+  kind: 'meeting',
+  watches: ['meeting.transcript.delta'],
+  matches: (event, params = {}, ctx = {}) => {
+    const any = (params.any || []).map(norm).filter(Boolean);
+    if (!any.length) return null; // a phrase trigger with no phrase would fire on every word
+    for (const seg of event.segments || []) {
+      if (!speakerAllowed(params.speaker, seg.speaker, ctx)) continue;
+      const text = norm(seg.text);
+      const hit = any.find((p) => text.includes(p));
+      if (hit) return { why: `“${hit}” said by ${seg.speaker || 'someone'}`, segment: seg, phrase: hit };
+    }
+    return null;
+  },
+});
+
+export const topicTrigger = defineTrigger({
+  id: 'meeting:topic',
+  label: 'When someone talks about something',
+  kind: 'meeting',
+  watches: ['meeting.transcript.delta'],
+  // Looser than a phrase on purpose: "says something about pricing" should not require the
+  // word "pricing" in the exact shape the job author typed. Term overlap over the window is
+  // deterministic, explainable, and free — a model would be all three of the opposite.
+  matches: (event, params = {}, ctx = {}) => {
+    const terms = (params.terms || []).map(norm).filter(Boolean);
+    if (!terms.length) return null;
+    const need = Math.max(1, Math.min(params.minHits || 1, terms.length));
+    const window = (event.segments || []).filter((s) => speakerAllowed(params.speaker, s.speaker, ctx));
+    const bag = new Set(window.flatMap((s) => words(s.text)));
+    const hits = terms.filter((t) => t.split(/\s+/).every((w) => bag.has(w)));
+    return hits.length >= need ? { why: `talking about ${hits.join(', ')}`, terms: hits } : null;
+  },
+});
+
+// A question mark is the cheap half; the interrogative openers are what catch speech-to-text
+// output, which frequently drops the punctuation entirely.
+const QUESTION = /^(who|what|when|where|why|how|which|whose|can|could|would|should|shall|do|does|did|is|are|was|were|will|have|has|any(one|body)|is there|are there)\b/i;
+
+export const questionTrigger = defineTrigger({
+  id: 'meeting:question',
+  label: 'When a question is asked',
+  kind: 'meeting',
+  watches: ['meeting.transcript.delta'],
+  matches: (event, params = {}, ctx = {}) => {
+    for (const seg of event.segments || []) {
+      if (!speakerAllowed(params.speaker || 'others', seg.speaker, ctx)) continue;
+      const text = String(seg.text || '').trim();
+      if (text.length < 8) continue; // "what?" is not a question worth waking a model for
+      if (text.includes('?') || QUESTION.test(text)) return { why: `question from ${seg.speaker || 'someone'}`, segment: seg };
+    }
+    return null;
+  },
+});
+
+export const voiceCommandTrigger = defineTrigger({
+  id: 'voice:command',
+  label: 'When you say the wake word',
+  kind: 'voice',
+  watches: ['voice.command'],
+  matches: (event, params = {}) => {
+    const want = params.intents || [];
+    if (!event.command?.allowed) return null; // authority is settled upstream; never widened here
+    if (want.length && !want.includes(event.command.intent)) return null;
+    return { why: `you said “${event.command.command}”`, command: event.command };
+  },
+});
+
+export const BUILTIN_TRIGGERS = Object.freeze([
+  timerTrigger, meetingStartedTrigger, meetingEndedTrigger, personJoinedTrigger,
+  phraseTrigger, topicTrigger, questionTrigger, voiceCommandTrigger,
+]);
+
+// ---------------------------------------------------------------------------
+// Jobs
+// ---------------------------------------------------------------------------
+
+/**
+ * @param action  { kind: 'skill', skillId } — the headline case: the instruction IS a skill,
+ *                so "every morning, do my daily brief" is a job whose action names the skill
+ *                the user already wrote. Also 'prompt' (raw text), 'monitor', 'notify'.
+ * @param limits  { maxPerDay } — a job that fails must back off, not retry in a tight loop.
+ * @param onMissed what to do about occurrences that passed while nothing was awake. Stated,
+ *                because silently running eleven catch-up briefs is as wrong as silently
+ *                running none, and the difference is money.
+ */
+export function defineJob({
+  id, name, trigger, schedule = null, params = {}, action,
+  enabled = true, onMissed = 'runOnce', limits = {}, approval = null, createdAt = 0,
+}) {
+  if (!id) throw new ScheduleError('BAD_JOB', 'job.id required');
+  if (!name) throw new ScheduleError('BAD_JOB', `job '${id}': name required`);
+  if (!trigger) throw new ScheduleError('BAD_JOB', `job '${id}': trigger required`);
+  if (!action || !JOB_ACTIONS.includes(action.kind)) {
+    throw new ScheduleError('BAD_JOB', `job '${id}': action.kind must be one of ${JOB_ACTIONS}`);
+  }
+  if (action.kind === 'skill' && !action.skillId) throw new ScheduleError('BAD_JOB', `job '${id}': skill action needs skillId`);
+  if (!MISSED_POLICIES.includes(onMissed)) throw new ScheduleError('BAD_JOB', `job '${id}': unknown onMissed '${onMissed}'`);
+  if (trigger === timerTrigger.id || schedule) validateSchedule(schedule);
+  return {
+    id, name, trigger, schedule, params: { ...params }, action: { ...action },
+    enabled: !!enabled, onMissed, limits: { ...limits }, approval, createdAt: createdAt || 0,
+  };
+}
+
+/**
+ * Dedup is on the SCHEDULED time, never the fired time — a wake-up at 09:04 for the 09:00
+ * slot is the 09:00 run, and a second wake-up for that slot is a no-op. Alarms are
+ * approximate and devices sleep; without this, "approximately 9" means "twice".
+ */
+export function occurrenceKey(jobId, at) { return `${jobId}@${at}`; }
+
+/**
+ * Which timer jobs are due, and which of those are catch-up rather than on-time.
+ *
+ * @param lastRun { [jobId]: ts } — the last OCCURRENCE run, not the last wake-up.
+ */
+export function dueJobs(jobs, { now, lastRun = {}, admit = null, max = MAX_CATCH_UP } = {}) {
+  const out = [];
+  for (const job of jobs || []) {
+    if (!job.enabled) continue;
+    if (job.trigger !== timerTrigger.id || !job.schedule) continue;
+    if (admit && !admit(job)) continue;
+    const since = lastRun[job.id] || job.createdAt || 0;
+    if (!since) continue; // a job with no anchor cannot know what it missed
+    const missed = occurrencesBetween(job.schedule, since, now, max);
+    if (!missed.length) continue;
+    const runs = job.onMissed === 'runAll' ? missed
+      : job.onMissed === 'runOnce' ? [missed[missed.length - 1]]
+        : [];
+    for (const at of runs) out.push({ job, at, key: occurrenceKey(job.id, at), late: now - at > 60_000, missedCount: missed.length });
+    // 'skip' still reports so the caller can advance its watermark without running anything.
+    if (!runs.length) out.push({ job, at: missed[missed.length - 1], key: occurrenceKey(job.id, missed[missed.length - 1]), skipped: true, missedCount: missed.length });
+  }
+  return out;
+}
+
+/** The soonest any timer job wants to be woken, so a client arms ONE platform alarm. */
+export function nextWakeAt(jobs, { now, lastRun = {} } = {}) {
+  let soonest = null;
+  for (const job of jobs || []) {
+    if (!job.enabled || job.trigger !== timerTrigger.id || !job.schedule) continue;
+    const at = nextFireAt(job.schedule, Math.max(now, lastRun[job.id] || 0));
+    if (at !== null && (soonest === null || at < soonest)) soonest = at;
+  }
+  return soonest;
+}
+
+/**
+ * Which jobs an event fires. Returns matches; running them is the host's business, because
+ * only the host knows what a skill costs and whether the user approved it.
+ */
+export function jobsForEvent(jobs, event, { registry, ctx = {}, admit = null } = {}) {
+  const out = [];
+  for (const job of jobs || []) {
+    if (!job.enabled) continue;
+    if (admit && !admit(job)) continue;
+    const trigger = registry?.get(job.trigger);
+    if (!trigger || trigger.kind === 'timer') continue;
+    if (trigger.watches.length && !trigger.watches.includes(event?.type)) continue;
+    let match = null;
+    try { match = trigger.matches(event, job.params, ctx); } catch { match = null; }
+    // A condition that threw did not match. Firing on an unanswered question is how
+    // automation does something nobody asked for.
+    if (match) out.push({ job, trigger, match, key: occurrenceKey(job.id, event.at || event.t || 0) });
+  }
+  return out;
+}

package/voice-intents.js

@@ -0,0 +1,664 @@
+// Spoken commands — "<wake word>, set a timer for ten minutes".
+//
+// A meeting transcript already streams into ChatPanel every few seconds, speaker-attributed.
+// That makes it an INPUT DEVICE, not just a record: a person can address the product in the
+// middle of a call and expect something to happen. The obvious way to build that is to ask a
+// model, every tick, whether anything was said to us. That is the wrong shape — it pays a
+// model call per tick to answer "no" almost every time, and the answer arrives a minute
+// after the sentence ended.
+//
+// So the model is used ONCE, to parse a command that a free matcher already found, and
+// never to watch. Everything here is class R: pure string work, microseconds, no network,
+// no tokens. The parse either recognises the command or reports `needsModel`, which is the
+// seam a small model fills for the phrasings a grammar will never cover.
+//
+// THREE THINGS THIS MODULE REFUSES TO DO, each because it would break a rule that matters:
+//
+//   1. It does not act. `parseCommand` returns a description of what was asked for; the
+//      host decides whether that is allowed and carries it out. A parser that could start a
+//      timer could also be talked into starting anything, by anyone in the room.
+//   2. It does not know who is allowed to speak to it. The host passes `self`, because only
+//      the host knows which speaker label is the device's owner — and gating on that is the
+//      whole security story (see commandsFromSegments).
+//   3. It does not read a clock. `now` is injected, exactly like loop.js and event.js, so a
+//      command parses identically on replay and a test does not have to wait for Wednesday.
+//
+// Local time is deliberate: "9am" means 9am where the person is standing, so the resolved
+// timestamps come from the host's own timezone via Date. That is the only environmental
+// input, and it is the one users would be astonished to see normalised away.
+
+export class VoiceIntentError extends Error {
+  constructor(code, message) { super(message); this.name = 'VoiceIntentError'; this.code = code; }
+}
+
+/** What a wake word defaults to when the user has not chosen one. Configurable per install. */
+export const DEFAULT_WAKE = Object.freeze(['chatpanel']);
+
+// Speech-to-text mangles a brand name it has never seen: "chatpanel" comes back as "chat
+// panel", "chat pal", "chad panel". A gate that only accepts the exact spelling is a gate
+// that never opens on a real transcript. Tolerance scales with length because one edit in a
+// four-letter word is a different word, and two edits in a nine-letter one is still clearly
+// the same attempt.
+function slack(len) { return len <= 4 ? 0 : len <= 6 ? 1 : 2; }
+
+// The widest span of spoken tokens that may add up to one wake phrase ("chat" "pan" "ell").
+const MAX_WAKE_TOKENS = 3;
+
+// Bounded Levenshtein — returns early once the distance cannot come in under `max`, so a
+// wake scan over a long transcript stays linear in practice.
+export function editDistance(a, b, max = Infinity) {
+  if (a === b) return 0;
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    let best = i;
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(
+        prev[j] + 1,
+        cur[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+      if (cur[j] < best) best = cur[j];
+    }
+    if (best > max) return max + 1;
+    prev = cur;
+  }
+  return prev[b.length];
+}
+
+// Lowercase and blank out punctuation WITHOUT changing length, so every offset computed
+// against the normalised copy still points at the same character of the original. The
+// command text handed back to the user keeps its capitals and its apostrophes; matching
+// never has to care about either.
+export function normalizeSpeech(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[‘’]/g, "'")
+    .replace(/[^\p{L}\p{N}':.\s]/gu, ' ');
+}
+
+/** Tokens with offsets into the ORIGINAL string. */
+export function tokenize(text) {
+  const norm = normalizeSpeech(text);
+  const out = [];
+  const re = /[\p{L}\p{N}'.:]+/gu;
+  let m;
+  while ((m = re.exec(norm))) {
+    // Keep dots INSIDE a token ("a.m.", "9:30") and drop them at the edges — a trailing
+    // full stop turned "ten minutes." into an unknown unit, the kind of bug that only
+    // shows up on the one transcript that punctuates.
+    const w = m[0].replace(/^[.:]+|[.:]+$/g, '');
+    if (w) out.push({ w, start: m.index, end: m.index + m[0].length });
+  }
+  return out;
+}
+
+/**
+ * Compile the user's chosen wake word(s) into a matcher. Accepts a string or a list; each is
+ * squashed to letters so "chat panel", "ChatPanel" and "chat-panel" are one phrase.
+ */
+export function compileWake(words = DEFAULT_WAKE) {
+  const list = (Array.isArray(words) ? words : [words])
+    .map((w) => String(w || '').toLowerCase().replace(/[^\p{L}\p{N}]/gu, ''))
+    .filter((w) => w.length >= 3); // shorter than this and ordinary speech trips it constantly
+  if (!list.length) throw new VoiceIntentError('BAD_WAKE', 'wake word must have at least 3 letters');
+  return Object.freeze({ phrases: Object.freeze(list) });
+}
+
+/**
+ * Find "<wake>, <command>" in one utterance.
+ *
+ * Returns the command with its ORIGINAL casing, plus which wake phrase matched and where —
+ * the host logs the span so a user can see why something fired.
+ */
+export function findWakeCommand(text, wake = compileWake()) {
+  const raw = String(text || '');
+  const tokens = tokenize(raw);
+  if (!tokens.length) return null;
+  for (let i = 0; i < tokens.length; i++) {
+    let squashed = '';
+    for (let n = 0; n < MAX_WAKE_TOKENS && i + n < tokens.length; n++) {
+      squashed += tokens[i + n].w.replace(/[^\p{L}\p{N}]/gu, '');
+      for (const phrase of wake.phrases) {
+        // A window far from the phrase's length cannot match; skip the distance work.
+        if (Math.abs(squashed.length - phrase.length) > slack(phrase.length)) continue;
+        if (editDistance(squashed, phrase, slack(phrase.length)) <= slack(phrase.length)) {
+          const end = tokens[i + n].end;
+          const command = stripLeadIn(raw.slice(end));
+          return { command, wake: phrase, heard: raw.slice(tokens[i].start, end), at: tokens[i].start };
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// "chatpanel, could you please set a timer" — politeness is not part of the command, and
+// leaving it in makes every intent pattern carry an optional-courtesy prefix.
+function stripLeadIn(text) {
+  return String(text)
+    .replace(/^[\s,.:;!?-]+/, '')
+    .replace(/^(?:(?:hey|hi|ok|okay|yo)\b[\s,]*)+/i, '')
+    .replace(/^(?:(?:can|could|would|will)\s+you\s+(?:please\s+)?|please\s+)/i, '')
+    .trim();
+}
+
+// ---------------------------------------------------------------------------
+// Numbers, durations and clock times as people actually say them
+// ---------------------------------------------------------------------------
+
+const SMALL = {
+  zero: 0, one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9,
+  ten: 10, eleven: 11, twelve: 12, thirteen: 13, fourteen: 14, fifteen: 15, sixteen: 16,
+  seventeen: 17, eighteen: 18, nineteen: 19,
+};
+const TENS = { twenty: 20, thirty: 30, forty: 40, fourty: 40, fifty: 50, sixty: 60, seventy: 70, eighty: 80, ninety: 90 };
+const FRACTION = { half: 0.5, quarter: 0.25 };
+
+/** "twenty five" → 25, "a" → 1, "half" → 0.5. Returns null when the words are not a number. */
+export function parseNumberWords(words) {
+  if (!words.length) return null;
+  let total = null;
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i];
+    if (w === 'and' || w === 'of') continue; // "two AND a half", "a quarter OF an hour"
+    // "an hour" is one hour. "A quarter of an hour" is a quarter, and "two and A half" is
+    // 2.5 — in both of those the article belongs to the fraction, not to the count.
+    if (w === 'a' || w === 'an') {
+      if (total === null && !(words[i + 1] in FRACTION)) total = 1;
+      continue;
+    }
+    if (w in FRACTION) { total = (total ?? 0) + FRACTION[w]; continue; }
+    if (w in SMALL) { total = (total ?? 0) + SMALL[w]; continue; }
+    if (w in TENS) { total = (total ?? 0) + TENS[w]; continue; }
+    if (/^\d+(?:\.\d+)?$/.test(w)) { total = (total ?? 0) + Number(w); continue; }
+    return null;
+  }
+  return total;
+}
+
+const UNIT_MS = {
+  second: 1000, seconds: 1000, sec: 1000, secs: 1000, s: 1000,
+  minute: 60_000, minutes: 60_000, min: 60_000, mins: 60_000, m: 60_000,
+  hour: 3_600_000, hours: 3_600_000, hr: 3_600_000, hrs: 3_600_000, h: 3_600_000,
+  day: 86_400_000, days: 86_400_000,
+};
+
+// "10", "10m", "90s" — a number welded to its unit, which is how people type and how STT
+// sometimes renders speech.
+const GLUED = /^(\d+(?:\.\d+)?)(s|m|h|secs?|mins?|hrs?|seconds?|minutes?|hours?|days?)$/;
+
+/**
+ * Total duration named anywhere in `text`: "10 minutes", "an hour and a half",
+ * "1 hour 30 minutes", "90s", "half an hour", "two and a half hours".
+ *
+ * Summing every (quantity, unit) pair rather than taking the first is what makes
+ * "1 hour 30 minutes" 90 minutes instead of an hour.
+ */
+export function parseDuration(text) {
+  const tokens = tokenize(text);
+  let ms = 0;
+  let start = -1;
+  let end = -1;
+  let matched = false;
+  let qty = [];        // words that could still add up to a quantity
+  let qtyStart = -1;
+
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    const take = (n, unit, from, to) => {
+      ms += n * unit;
+      if (start < 0) start = from;
+      end = to;
+      matched = true;
+    };
+    const glued = GLUED.exec(t.w);
+    const unit = glued ? UNIT_MS[glued[2]] : UNIT_MS[t.w];
+    if (!unit) {
+      // Not a unit: extend the pending quantity while it still parses as a number, else
+      // start over from this word. An unrelated clause before the number cannot poison it.
+      const next = [...qty, t.w];
+      if (parseNumberWords(next) !== null) { if (qtyStart < 0) qtyStart = t.start; qty = next; }
+      else if (parseNumberWords([t.w]) !== null) { qty = [t.w]; qtyStart = t.start; }
+      else { qty = []; qtyStart = -1; }
+      continue;
+    }
+    if (glued) take(Number(glued[1]), unit, t.start, t.end);
+    else {
+      const n = qty.length ? parseNumberWords(qty) : null;
+      if (n !== null) take(n, unit, qtyStart >= 0 ? qtyStart : t.start, t.end);
+    }
+    qty = []; qtyStart = -1;
+    // "an hour and a half" — the fraction trails its unit, so here is the only place it
+    // can be attributed to the right one.
+    const j = consumeTrailingFraction(tokens, i);
+    if (j > i) { ms += FRACTION[tokens[j].w] * unit; end = tokens[j].end; i = j; }
+  }
+  if (!matched || ms <= 0) return null;
+  return { ms: Math.round(ms), start, end };
+}
+
+// Index of the last token of a trailing "…and a half" / "…and a quarter", or `i` when what
+// follows is something else.
+function consumeTrailingFraction(tokens, i) {
+  let j = i + 1;
+  if (tokens[j]?.w !== 'and') return i;
+  j++;
+  if (tokens[j]?.w === 'a' || tokens[j]?.w === 'an') j++;
+  return FRACTION[tokens[j]?.w] === undefined ? i : j;
+}
+
+const WEEKDAYS = {
+  sunday: 0, sun: 0, monday: 1, mon: 1, tuesday: 2, tue: 2, tues: 2, wednesday: 3, wed: 3,
+  weds: 3, thursday: 4, thu: 4, thur: 4, thurs: 4, friday: 5, fri: 5, saturday: 6, sat: 6,
+};
+
+// When someone names a part of the day instead of a time. Chosen to be unsurprising rather
+// than clever: a reminder that fires at a time nobody expected is worse than one that fires
+// at a boring one.
+export const DAYPART_HOUR = Object.freeze({ morning: 9, afternoon: 14, evening: 19, night: 20, tonight: 19, noon: 12, midnight: 0 });
+
+function atLocal(base, { days = 0, hour, minute = 0 }) {
+  const d = new Date(base);
+  d.setDate(d.getDate() + days);
+  d.setHours(hour, minute, 0, 0);
+  return d.getTime();
+}
+
+/**
+ * When a command says to do something: "in 20 minutes", "at 9am", "tomorrow at 3",
+ * "on Wednesday at 9am", "every weekday morning".
+ *
+ * Returns `{ at, recurrence }`. `recurrence` is null for one-shots and otherwise the shape
+ * the scheduler consumes — daily/weekly plus a local wall-clock time, NOT an interval in
+ * milliseconds, because "every day at 8am" survives a daylight-saving change and
+ * "every 86400000ms" does not.
+ */
+export function parseWhen(text, { now = Date.now() } = {}) {
+  const raw = String(text || '');
+  const norm = normalizeSpeech(raw);
+
+  // WHERE the time was said matters as much as what it was: a reminder's body is the
+  // command minus the time phrase, and a phrase at the START of the sentence ("remind me
+  // every weekday morning to check the queue") used to take the whole reminder with it.
+  let from = Infinity;
+  let to = -1;
+  const span = (a, b) => { if (a < from) from = a; if (b > to) to = b; };
+
+  // "in 20 minutes" — relative, and unambiguous enough to answer before anything else.
+  const rel = /\bin\s+(.+)$/i.exec(norm);
+  if (rel) {
+    const d = parseDuration(rel[1]);
+    if (d) {
+      const base = rel.index + rel[0].length - rel[1].length;
+      return { at: now + d.ms, recurrence: null, kind: 'relative', ...widen(norm, rel.index, base + d.end) };
+    }
+  }
+
+  const every = /\bevery\s+(day|morning|afternoon|evening|night|week|weekday|[a-z]+day|mon|tue|tues|wed|weds|thu|thur|thurs|fri|sat|sun)\b/i.exec(norm)
+    || /\b(daily|nightly|weekly)\b/i.exec(norm);
+  const clock = parseClock(norm);
+  const dayWord = /\b(today|tonight|tomorrow)\b/i.exec(norm);
+  const weekdayMatch = /\b(next\s+)?(sunday|sun|monday|mon|tuesday|tues|tue|wednesday|weds|wed|thursday|thurs|thur|thu|friday|fri|saturday|sat)\b/i.exec(norm);
+  const daypart = /\b(morning|afternoon|evening|tonight|night|noon|midnight)\b/i.exec(norm);
+
+  if (every) span(every.index, every.index + every[0].length);
+  if (clock) span(clock.start, clock.end);
+  if (dayWord) span(dayWord.index, dayWord.index + dayWord[0].length);
+  if (weekdayMatch) span(weekdayMatch.index, weekdayMatch.index + weekdayMatch[0].length);
+  if (daypart) span(daypart.index, daypart.index + daypart[0].length);
+
+  let hour = clock ? clock.hour : daypart ? DAYPART_HOUR[daypart[1]] : null;
+  const minute = clock ? clock.minute : 0;
+  // "tonight at 8" is 8 in the EVENING. A bare hour with no meridiem, said alongside a part
+  // of the day that is plainly not the morning, means the afternoon reading.
+  if (clock && !clock.meridiem && hour < 12 && daypart && DAYPART_HOUR[daypart[1]] >= 12) hour += 12;
+
+  if (every) {
+    const word = (every[1] || '').toLowerCase();
+    const h = hour ?? DAYPART_HOUR[word] ?? DAYPART_HOUR[word.replace(/ly$/, '')] ?? 9; // "nightly" is night
+    const at = word in WEEKDAYS
+      ? nextWeekday(now, WEEKDAYS[word], h, minute)
+      : word === 'week' || word === 'weekly'
+        ? atLocal(now, { days: 7, hour: h, minute })
+        : nextDailyAt(now, h, minute, word === 'weekday');
+    const recurrence = word in WEEKDAYS
+      ? { kind: 'weekly', weekday: WEEKDAYS[word], hour: h, minute }
+      : word === 'week' || word === 'weekly'
+        ? { kind: 'weekly', weekday: new Date(now).getDay(), hour: h, minute }
+        : { kind: 'daily', hour: h, minute, weekdaysOnly: word === 'weekday' };
+    return { at, recurrence, kind: 'recurring', ...widen(norm, from, to) };
+  }
+
+  if (hour === null && !dayWord && !weekdayMatch) return null;
+
+  if (weekdayMatch) {
+    const wd = WEEKDAYS[weekdayMatch[2]];
+    const h = hour ?? 9;
+    // "next Wednesday" is never today, even when today is Wednesday and the hour is ahead.
+    const at = nextWeekday(now, wd, h, minute, !!weekdayMatch[1]);
+    return { at, recurrence: null, kind: 'weekday', ...widen(norm, from, to) };
+  }
+
+  const h = hour ?? DAYPART_HOUR[daypart?.[1] || 'morning'];
+  if (dayWord) {
+    const w = dayWord[1].toLowerCase();
+    return { at: atLocal(now, { days: w === 'tomorrow' ? 1 : 0, hour: h, minute }), recurrence: null, kind: w, ...widen(norm, from, to) };
+  }
+  // A bare clock time: today if it is still ahead, otherwise the same time tomorrow. Firing
+  // immediately for a time that has already passed is never what was meant.
+  let at = atLocal(now, { hour: h, minute });
+  if (at <= now) at = atLocal(now, { days: 1, hour: h, minute });
+  return { at, recurrence: null, kind: 'clock', ...widen(norm, from, to) };
+}
+
+// Grow a time span backwards over the preposition that introduced it, so cutting it out of
+// "take the kids to school AT 9am" does not leave a dangling "at".
+function widen(norm, from, to) {
+  if (!(from >= 0) || !(to > from)) return { start: -1, end: -1 };
+  const lead = /\b(?:at|on|by|in|this|starting|from)\s+$/i.exec(norm.slice(0, from));
+  return { start: lead ? from - lead[0].length : from, end: to };
+}
+
+function nextDailyAt(now, hour, minute, weekdaysOnly = false) {
+  let at = atLocal(now, { hour, minute });
+  if (at <= now) at = atLocal(now, { days: 1, hour, minute });
+  if (weekdaysOnly) {
+    for (let i = 0; i < 7; i++) {
+      const day = new Date(at).getDay();
+      if (day !== 0 && day !== 6) break;
+      at = atLocal(at, { days: 1, hour, minute });
+    }
+  }
+  return at;
+}
+
+function nextWeekday(now, weekday, hour, minute, skipToday = false) {
+  const d = new Date(now);
+  let delta = (weekday - d.getDay() + 7) % 7;
+  if (delta === 0 && (skipToday || atLocal(now, { hour, minute }) <= now)) delta = 7;
+  return atLocal(now, { days: delta, hour, minute });
+}
+
+/** "9am", "9:30 pm", "at nine", "21:15", "9 o'clock". Returns 24h {hour, minute}. */
+export function parseClock(text) {
+  const norm = normalizeSpeech(text);
+  // A NUMBER IS ONLY A TIME WHEN SOMETHING SAYS SO. "set a timer for 10 minutes" contains
+  // the digits of a perfectly good clock time, and reading it as 10 o'clock is how a timer
+  // becomes tomorrow morning. The cue must be attached to THIS number — a meridiem, a
+  // minutes part, "o'clock", or an immediately preceding "at" — not merely present
+  // somewhere in the sentence.
+  const re = /(\d{1,2})(?:[:.](\d{2}))?\s*(a\.?m\.?|p\.?m\.?|o'?clock)?/gi;
+  let m;
+  while ((m = re.exec(norm))) {
+    const attachedAt = /\bat\s+$/.test(norm.slice(0, m.index));
+    if (!m[2] && !m[3] && !attachedAt) continue;
+    let hour = Number(m[1]);
+    const minute = m[2] ? Number(m[2]) : 0;
+    if (hour > 23 || minute > 59) continue;
+    const mer = (m[3] || '').replace(/[.\s]/g, '').toLowerCase();
+    if (mer === 'pm' && hour < 12) hour += 12;
+    if (mer === 'am' && hour === 12) hour = 0;
+    return { hour, minute, meridiem: mer === 'am' || mer === 'pm', start: m.index, end: m.index + m[0].length };
+  }
+  // Spelled out: "at nine am". "at half past" is deliberately unsupported — rare in STT
+  // output and ambiguous enough to deserve a model rather than a guess.
+  const words = /\bat\s+([a-z]+)(?:\s+(a\.?m\.?|p\.?m\.?))?/i.exec(norm);
+  if (words) {
+    const n = parseNumberWords([words[1]]);
+    if (n !== null && Number.isInteger(n) && n >= 0 && n <= 23) {
+      let hour = n;
+      const mer = (words[2] || '').replace(/[.\s]/g, '').toLowerCase();
+      if (mer === 'pm' && hour < 12) hour += 12;
+      if (mer === 'am' && hour === 12) hour = 0;
+      return { hour, minute: 0, meridiem: mer === 'am' || mer === 'pm', start: words.index, end: words.index + words[0].length };
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Intents — declarations, so a client adds one without touching the parser
+// ---------------------------------------------------------------------------
+
+/**
+ * @param match (command, ctx) => args | null. Pure and synchronous, for the same reason
+ *        rules.js insists on it: "did this match" must be answerable without side effects.
+ * @param classUsed what carrying it out costs — R for a local timer, C when it will start a
+ *        model turn. Declared, never inferred, so the honest answer to "did that spend
+ *        anything" is readable in the declaration.
+ * @param effects  'idempotent' | 'non-replayable' — the host uses it to decide whether a
+ *        redelivered command may be re-run.
+ */
+export function defineVoiceIntent({
+  id, label, description = '', examples = [], classUsed = 'R',
+  effects = 'idempotent', requiresApproval = false, match,
+}) {
+  if (!id) throw new VoiceIntentError('BAD_INTENT', 'intent.id required');
+  if (typeof match !== 'function') throw new VoiceIntentError('BAD_INTENT', `intent '${id}': match required`);
+  return Object.freeze({ id, label: label || id, description, examples: Object.freeze([...examples]), classUsed, effects, requiresApproval, match });
+}
+
+export function createVoiceIntentRegistry(intents = []) {
+  const list = [...intents];
+  return {
+    add(intent) {
+      list.push(intent);
+      return () => { const i = list.indexOf(intent); if (i >= 0) list.splice(i, 1); };
+    },
+    list: () => [...list],
+    get: (id) => list.find((i) => i.id === id) || null,
+
+    /**
+     * First intent whose pattern matches wins; declaration order is precedence. A command
+     * nothing recognises comes back with `needsModel`, which is a different answer from "not
+     * a command" — the host may pay for a small model to read it, and MUST NOT guess.
+     */
+    parse(command, ctx = {}) {
+      const text = String(command || '').trim();
+      if (!text) return null;
+      for (const intent of list) {
+        let args = null;
+        try { args = intent.match(text, ctx); } catch { args = null; }
+        if (args) return { intent: intent.id, label: intent.label, classUsed: intent.classUsed, effects: intent.effects, requiresApproval: intent.requiresApproval, args, command: text, needsModel: false };
+      }
+      return { intent: null, args: null, command: text, needsModel: true };
+    },
+  };
+}
+
+// ── the built-ins ──────────────────────────────────────────────────────────
+// Deliberately the four that are local, revertible and need no new permission. Anything
+// that sends, spends or clicks is not a good first thing to trigger by talking near a
+// laptop, and belongs behind the per-action confirm gate the host already has.
+
+export const timerIntent = defineVoiceIntent({
+  id: 'voice:timer',
+  label: 'Set a timer',
+  description: 'Starts a countdown and alerts when it finishes.',
+  examples: ['set a timer for 10 minutes', 'start a 90 second timer', 'timer for an hour and a half'],
+  match: (command, { now = Date.now() } = {}) => {
+    if (!/\btimers?\b/i.test(command)) return null;
+    const d = parseDuration(command);
+    if (!d) return null;
+    // "timer for the standup" — whatever is left once the duration and the plumbing words
+    // are removed is what the timer is FOR, and a labelled timer is the difference between
+    // three anonymous countdowns and three useful ones.
+    const label = (command.slice(0, d.start) + ' ' + command.slice(d.end))
+      .replace(/\b(set|start|make|create|a|an|the|for|please|timer|timers|to|of|and|half|quarter)\b/gi, ' ');
+    return { ms: d.ms, at: now + d.ms, label: tidy(label) };
+  },
+});
+
+export const reminderIntent = defineVoiceIntent({
+  id: 'voice:reminder',
+  label: 'Set a reminder',
+  description: 'Remembers something and raises it at the time you said.',
+  examples: ['remind me to send the deck at 4pm', 'remember to take the kids to school at 9am on Wednesday', 'remind me every weekday morning to check the queue'],
+  match: (command, { now = Date.now() } = {}) => {
+    const m = /\b(?:remind\s+(?:me|us)|reminder|remember)\b/i.exec(command);
+    if (!m) return null;
+    const when = parseWhen(command, { now });
+    // Cut out exactly the span parseWhen matched — a notification that already says when it
+    // is should not also read "…at 9am on wednesday" in its title, and the phrase can sit at
+    // either end of the sentence ("remind me every weekday morning to check the queue").
+    let text = when && when.end > when.start
+      ? command.slice(0, when.start) + ' ' + command.slice(when.end)
+      : command;
+    text = text.slice(text.toLowerCase().indexOf(m[0].toLowerCase()) + m[0].length);
+    text = tidy(text.replace(/^(?:\s*(?:to|that|about|i\s+need\s+to|we\s+need\s+to))\b/i, ''));
+    if (!text) return null; // "remind me" with nothing to remember is not a reminder
+    return { text, at: when?.at ?? null, recurrence: when?.recurrence ?? null, when: when?.kind ?? null };
+  },
+});
+
+export const noteIntent = defineVoiceIntent({
+  id: 'voice:note',
+  label: 'Take a note',
+  description: 'Appends a line to the meeting notes.',
+  examples: ['note that we agreed to ship on Friday', 'take a note: budget is approved'],
+  match: (command) => {
+    const m = /^(?:take\s+a\s+note|make\s+a\s+note|note)\b[\s:,-]*(?:that\s+)?(.+)$/i.exec(command.trim());
+    const text = m && tidy(m[1]);
+    return text ? { text } : null;
+  },
+});
+
+export const monitorIntent = defineVoiceIntent({
+  id: 'voice:monitor',
+  label: 'Watch for something',
+  description: 'Starts a live monitor that answers as the meeting continues.',
+  examples: ['watch for whether we agree a date', 'keep an eye on the pricing question', 'track who owns the migration'],
+  classUsed: 'C', // it starts model turns for the rest of the meeting — say so
+  match: (command) => {
+    const m = /^(?:watch\s+(?:out\s+)?for|watch|keep\s+an\s+eye\s+on|track|monitor)\b[\s:,-]*(?:whether\s+|if\s+|for\s+)?(.+)$/i.exec(command.trim());
+    const prompt = m && tidy(m[1]);
+    return prompt && prompt.length > 2 ? { prompt } : null;
+  },
+});
+
+// "Every weekday at 8am run my daily brief." The recurrence parser already existed for
+// reminders; what makes this different is that the thing being scheduled is WORK — a skill
+// the user already wrote — so the job says only when, and the skill stays the single
+// definition of what. Declared class C because it will start a model turn every time.
+export const scheduleIntent = defineVoiceIntent({
+  id: 'voice:schedule',
+  label: 'Schedule something',
+  description: 'Runs one of your skills (or a plain instruction) on a schedule.',
+  examples: ['every weekday at 8am run my daily brief', 'run the standup summary every morning', 'tomorrow at 9 do the release checklist'],
+  classUsed: 'C',
+  match: (command, { now = Date.now() } = {}) => {
+    const verb = /\b(run|do|start|kick\s+off|execute)\b/i.exec(command);
+    if (!verb) return null;
+    const when = parseWhen(command, { now });
+    // No time is not a schedule — it is a request to do something now, which is a chat
+    // message, not a job. Refusing here is what keeps "run the checklist" out of the
+    // scheduler.
+    if (!when) return null;
+    let target = when.end > when.start
+      ? command.slice(0, when.start) + ' ' + command.slice(when.end)
+      : command;
+    const v = /\b(run|do|start|kick\s+off|execute)\b/i.exec(target);
+    target = tidy((v ? target.slice(v.index + v[0].length) : target)
+      .replace(/^\s*(?:my|the|our)\b/i, '')
+      .replace(/\b(skill|job|task)\b\s*$/i, ''));
+    if (!target) return null;
+    return { target, at: when.at, recurrence: when.recurrence, when: when.kind };
+  },
+});
+
+export const BUILTIN_VOICE_INTENTS = Object.freeze([timerIntent, reminderIntent, scheduleIntent, noteIntent, monitorIntent]);
+
+function tidy(s) {
+  return String(s || '').replace(/\s+/g, ' ').replace(/^[\s,.:;-]+|[\s,.:;-]+$/g, '').trim();
+}
+
+/** A registry preloaded with the built-ins — the common case, one call. */
+export function defaultVoiceIntents() {
+  return createVoiceIntentRegistry(BUILTIN_VOICE_INTENTS);
+}
+
+/**
+ * Parse one utterance end to end: wake word, then intent.
+ *
+ * Returns null when the utterance was not addressed to us — which is almost every utterance
+ * in a meeting, and must therefore be the cheapest path through this module.
+ */
+export function parseCommand(text, { wake = compileWake(), intents = defaultVoiceIntents(), now = Date.now() } = {}) {
+  const found = findWakeCommand(text, wake);
+  if (!found) return null;
+  const parsed = intents.parse(found.command, { now });
+  if (!parsed) return null;
+  return { ...parsed, wake: found.wake, heard: found.heard, at: found.at };
+}
+
+// ---------------------------------------------------------------------------
+// Transcript → commands
+// ---------------------------------------------------------------------------
+
+/** How many commands one transcript delta may produce. */
+export const MAX_COMMANDS_PER_DELTA = 3;
+
+/**
+ * Scan new transcript segments for commands addressed to us.
+ *
+ * WHO IS ALLOWED TO SPEAK TO IT is the whole security question here. A meeting transcript
+ * carries everyone in the room, so an ungated version of this lets any participant put
+ * reminders on someone else's device by saying the wake word — and lets a compromised page
+ * do it by writing captions. `self` is therefore matched by the HOST, which is the only
+ * layer that knows which label is the device owner; segments from anyone else come back
+ * with `allowed: false` rather than being dropped silently, so "why didn't it fire" has an
+ * answer.
+ *
+ * @param segments [{ t, speaker, text }] — the delta, not the whole meeting.
+ * @param isSelf   (speaker) => boolean. Omit ONLY when the host has decided anyone may
+ *                 command this install; the default refuses, because failing closed on a
+ *                 question about authority is the only safe default.
+ */
+export function commandsFromSegments(segments, {
+  wake = compileWake(), intents = defaultVoiceIntents(), isSelf = null,
+  sinceTs = 0, now = Date.now(), meetingId = '', max = MAX_COMMANDS_PER_DELTA,
+} = {}) {
+  const out = [];
+  for (const seg of segments || []) {
+    if (!seg || !seg.text) continue;
+    if (seg.t && seg.t <= sinceTs) continue;
+    const parsed = parseCommand(seg.text, { wake, intents, now });
+    if (!parsed) continue;
+    // NO INTENT, NO ACTION. parseCommand returns a shape for anything that carries the wake
+    // word and a time-ish phrase, intent included or not — so "we should talk about the chat
+    // panel roadmap next week" came back as a command with intent:null and the caller acted
+    // on it anyway. In a live meeting that means ordinary conversation quietly sets timers,
+    // which is what happened: a caption grows, keeps matching, and fires again.
+    //
+    // An automation that runs when it did not understand the request is worse than one that
+    // does nothing, so an unrecognised utterance stops here.
+    if (!parsed.intent) continue;
+    const allowed = isSelf ? !!isSelf(seg.speaker) : false;
+    out.push({
+      ...parsed,
+      allowed,
+      speaker: seg.speaker || '',
+      t: seg.t || now,
+      meetingId,
+      // Stable across redeliveries of the same segment, so the dedupe actually dedupes.
+      //
+      // `parsed.at` used to be in this key, and it is an ABSOLUTE time computed as now + the
+      // spoken duration — so it changed on every scan. A live caption is rescanned as the
+      // sentence grows (deliberately: a half-heard command must get a second chance), which
+      // meant one "set a timer for 10 seconds" produced a brand-new key, and a brand-new
+      // timer, on every caption update — indefinitely, and faster than the user could delete
+      // them. The key now carries only what the same utterance keeps: where it was said, and
+      // what it asked for.
+      // IDENTITY, NOT FRESHNESS. `seg.t` is bumped every time a live caption's text grows —
+      // that is what keeps the line flowing through the delta filter — so keying on it made
+      // one spoken request look like a new request on every update, and a single "set a timer
+      // for 30 seconds" became a screenful of timers. `sid` is assigned once per utterance and
+      // never moves, so the same sentence keeps one key however many times it is rescanned.
+      key: `voice:${meetingId}:${seg.sid || seg.t || 0}:${parsed.intent || 'unknown'}:${parsed.ms ?? parsed.when ?? ''}`,
+    });
+    if (out.length >= max) break; // a pathological transcript cannot fire fifty actions
+  }
+  return out;
+}

package/widget.js

@@ -42,6 +42,11 @@ export function validateWidget(w) {
   if (!str(w.name)) throw new EventError('SHAPE', 'widget.name required');
   if (!str(w.html)) throw new EventError('SHAPE', 'widget.html required');
   if (w.html.length > MAX_HTML) throw new EventError('SHAPE', `widget.html exceeds ${MAX_HTML} bytes`);
+  // An icon NAME (the client maps it to its own icon set), so a pinned widget is
+  // recognisable at a glance rather than being one of five identical marks.
+  if (w.icon != null && !(str(w.icon) && /^[a-z][a-z0-9-]{0,31}$/.test(w.icon))) {
+    throw new EventError('SHAPE', 'widget.icon must be an icon name like "timer"');
+  }
   if (w.surface != null && !WIDGET_SURFACES.includes(w.surface)) {
     throw new EventError('SHAPE', `widget.surface must be one of ${WIDGET_SURFACES}`);
   }
@@ -108,3 +113,41 @@ export function effectiveGrants(widget, approved = []) {
   const asked = new Set(widget?.requests || []);
   return (approved || []).filter((id) => asked.has(id));
 }
+
+// Pick an icon for a widget from what it is called. A pinned widget sits in a narrow strip
+// next to the others, so five identical marks are worse than no icon at all — the point of
+// pinning is to find the thing without reading.
+//
+// Returns an icon NAME, not a glyph: the client owns how it is drawn (the extension resolves
+// these through its vendored set, a mobile client through its own), and a name survives that
+// mapping in a way an emoji does not. Every name here exists in the extension's icon set.
+const ICON_WORDS = [
+  [/\b(timers?|pomodoro|stopwatch|countdowns?|intervals?)\b/i, 'timer'],
+  [/\b(calc|calculators?|math|arithmetic|tip)\b/i, 'hash'],
+  [/\b(notes?|sticky|scratch|memos?|journals?)\b/i, 'notebook-pen'],
+  [/\b(todos?|tasks?|checklists?|habits?|trackers?)\b/i, 'list-checks'],
+  [/\b(charts?|graphs?|stats?|metrics?|dashboards?)\b/i, 'bar-chart-3'],
+  [/\b(convert|converters?|units?|currency|exchange|weights?)\b/i, 'scale'],
+  [/\b(calendars?|schedules?|agendas?|dates?)\b/i, 'calendar'],
+  [/\b(clocks?|time|timezones?|zones?)\b/i, 'clock'],
+  [/\b(goals?|targets?|focus|okrs?)\b/i, 'target'],
+  [/\b(ideas?|brainstorm|prompts?)\b/i, 'lightbulb'],
+  [/\b(dice|random|rolls?|roller|coins?|shuffle)\b/i, 'zap'],
+  [/\b(search|find|lookup)\b/i, 'search'],
+  [/\b(web|urls?|links?|browser)\b/i, 'globe'],
+  [/\b(mood|mind|memory|brain)\b/i, 'brain'],
+  [/\b(password|secrets?|vault|lock)\b/i, 'lock'],
+  [/\b(quotes?|sayings?)\b/i, 'quote'],
+  [/\b(meetings?|standups?|people|team)\b/i, 'users'],
+  [/\b(music|player|sound|audio)\b/i, 'play'],
+  [/\b(photos?|images?|gallery)\b/i, 'image'],
+  [/\b(files?|documents?|docs?)\b/i, 'file-text'],
+];
+
+/** The widget's own icon if it declared one, else one derived from its name. */
+export function widgetIcon(widget) {
+  if (widget?.icon) return widget.icon;
+  const name = String(widget?.name || '');
+  for (const [re, iconName] of ICON_WORDS) if (re.test(name)) return iconName;
+  return 'app-window'; // generic, but never the mark the shelf itself uses
+}