@chatpanel/events 0.23.1 → 0.27.0

package/voice-intents.js

@@ -27,6 +27,14 @@
 // 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.
 
+import {
+  defineSchema, describeSchema, responseFormat, coerce, createStructuredStream,
+} from './structured.js';
+// The same list meeting triggers read. "Has this person finished the thought?" must have ONE
+// answer in this package — a second copy here would drift, and two features would disagree
+// about the same caption on the same screen.
+import { DANGLING_TAILS } from './schedule.js';
+
 export class VoiceIntentError extends Error {
   constructor(code, message) { super(message); this.name = 'VoiceIntentError'; this.code = code; }
 }
@@ -41,8 +49,12 @@ export const DEFAULT_WAKE = Object.freeze(['chatpanel']);
 // 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").
+// The widest span of spoken tokens that may add up to a ONE-WORD wake phrase ("chat" "pan"
+// "ell"). A longer phrase widens its own window — see compileWake.
 const MAX_WAKE_TOKENS = 3;
+// …but never without limit: the scan is O(tokens x window x phrases) over every utterance,
+// and a wake phrase longer than this is a sentence, not a wake phrase.
+const WAKE_TOKEN_CEILING = 8;
 
 // Bounded Levenshtein — returns early once the distance cannot come in under `max`, so a
 // wake scan over a long transcript stays linear in practice.
@@ -99,39 +111,433 @@ export function tokenize(text) {
  * 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
+  // SEVERAL PHRASES, however they arrive. People do not say one fixed thing: "ok chatpanel",
+  // "okay chat panel" and "hey chatpanel" are one intent with three spellings, and asking
+  // someone to pick exactly one is asking them to remember which one they picked.
+  //
+  // A COMMA SEPARATES THEM — "chatpanel, siri, google" is what anyone would write, and any
+  // other separator is a rule to learn. The apparent conflict ("okay, chat panel" is also how
+  // you would write ONE phrase) is not a real one: matching strips punctuation from the
+  // TRANSCRIPT, so a comma is never needed inside a configured phrase to hear one spoken.
+  // Type "okay chat panel" and "okay, chat panel" is heard. `|`, `;` and newlines work too.
+  const raw = (Array.isArray(words) ? words : String(words ?? '').split(/[,|;\n]/))
+    .map((w) => String(w ?? '').trim())
+    .filter(Boolean);
+  const list = [];
+  // The phrases AS TYPED, kept alongside the squashed forms and in the same order. The
+  // squashed form is an implementation detail — "okchatpanel" is neither what the user wrote
+  // nor what they would say — so any UI that echoes the setting back must have the original
+  // to show. Deduped on the squashed form, keeping the first spelling of each.
+  const labels = [];
+  let widest = 1;
+  for (const phrase of raw) {
+    // Punctuation and spacing are stripped, so "ok chat panel", "ok, chat panel" and
+    // "okchatpanel" compile to one and the same thing — which is what makes the setting
+    // forgiving of how it was typed AND of how the transcriber spaced it.
+    const squashed = phrase.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '');
+    if (squashed.length < 3) continue; // shorter than this and ordinary speech trips it constantly
+    if (list.includes(squashed)) continue;
+    list.push(squashed);
+    labels.push(phrase);
+    // The scan joins adjacent spoken tokens looking for the phrase, so its window has to be
+    // at least as wide as the longest phrase is in WORDS — otherwise a three-word wake phrase
+    // could never be found, however it was typed. +1 for a transcriber that splits one of
+    // them ("chat" "pan" "ell").
+    widest = Math.max(widest, phrase.split(/\s+/).filter(Boolean).length + 1);
+  }
   if (!list.length) throw new VoiceIntentError('BAD_WAKE', 'wake word must have at least 3 letters');
-  return Object.freeze({ phrases: Object.freeze(list) });
+  return Object.freeze({
+    phrases: Object.freeze(list),
+    labels: Object.freeze(labels),
+    maxTokens: Math.min(Math.max(widest, MAX_WAKE_TOKENS), WAKE_TOKEN_CEILING),
+  });
 }
 
 /**
- * Find "<wake>, <command>" in one utterance.
+ * How much of what follows the wake word is the command.
  *
- * 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.
+ * THE 720-HOUR TIMER. One caption held six wake words and 420 characters, and the command was
+ * "everything after the first one to the end of the line". So "Okay, chat panel. Set a timer
+ * for 1 minute" swallowed four later sentences including "…research on the weather for the
+ * next 30 days" — and the duration parser, scanning the whole span, found 30 days. The user
+ * got a 720-hour timer from a request for one minute.
+ *
+ * A spoken command is a sentence, occasionally two ("Set a timer for 30 seconds. Make it
+ * two."). Never a paragraph. Bounded here, and bounded again by the next wake word: a second
+ * address is by definition the end of the first command.
  */
-export function findWakeCommand(text, wake = compileWake()) {
-  const raw = String(text || '');
-  const tokens = tokenize(raw);
-  if (!tokens.length) return null;
+export const MAX_COMMAND_SENTENCES = 2;
+
+/** Where every wake phrase sits in this text, in order. Shared by the singular and plural. */
+function wakeHits(raw, tokens, wake) {
+  const hits = [];
+  const window = wake.maxTokens || MAX_WAKE_TOKENS; // an older compiled wake has no maxTokens
   for (let i = 0; i < tokens.length; i++) {
     let squashed = '';
-    for (let n = 0; n < MAX_WAKE_TOKENS && i + n < tokens.length; n++) {
+    let matched = false;
+    for (let n = 0; n < window && i + n < tokens.length && !matched; 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 };
+          hits.push({
+            phrase,
+            start: tokens[i].start,
+            end: tokens[i + n].end,
+            addressed: isAddressed(raw, tokens, i, n),
+          });
+          // Skip past the phrase so "chat panel" is one hit, not two overlapping ones.
+          i += n;
+          matched = true;
+          break;
         }
       }
     }
   }
-  return null;
+  return hits;
+}
+
+/**
+ * The first `max` sentences of `text`, or all of it when it has fewer.
+ *
+ * A boundary is terminal punctuation followed by WHITESPACE or the end — not any full stop.
+ * "Go to google.com and search" is one sentence; splitting on the dot in a domain cut a
+ * command down to "Go to google." and sent that. Decimals ("2.5 minutes") and initials break
+ * the same way.
+ */
+function firstSentences(text, max) {
+  const t = String(text || '');
+  if (!t) return t;
+  const re = /[.!?…]+["'\u2019\u201d)\]]*(?=\s|$)/g;
+  let taken = 0;
+  let m;
+  while (taken < max && (m = re.exec(t))) {
+    taken += 1;
+    if (taken === max) return t.slice(0, m.index + m[0].length);
+  }
+  // Fewer sentences than asked for — all of it. A trailing fragment with no terminal
+  // punctuation is still what they said, and must not be silently emptied.
+  return t;
+}
+
+/**
+ * EVERY "<wake>, <command>" in one utterance, in order.
+ *
+ * A live caption often carries a whole minute of speech, and a person addressing an assistant
+ * addresses it more than once in a minute. Returning only the first match meant the other
+ * five requests in the same caption were invisible — and made the first command swallow them.
+ */
+export function findWakeCommands(text, wake = compileWake(), { maxSentences = MAX_COMMAND_SENTENCES } = {}) {
+  const raw = String(text || '');
+  const tokens = tokenize(raw);
+  if (!tokens.length) return [];
+  const hits = wakeHits(raw, tokens, wake);
+  return hits.map((hit, idx) => {
+    // Bounded by the NEXT address, then by sentence count. A second wake word is the end of
+    // the first command however the sentences fall.
+    const stop = idx + 1 < hits.length ? hits[idx + 1].start : raw.length;
+    const span = raw.slice(hit.end, stop);
+    const command = trimTrailingLeadIn(stripLeadIn(firstSentences(span, maxSentences)).trim());
+    return {
+      command,
+      wake: hit.phrase,
+      heard: raw.slice(hit.start, hit.end),
+      at: hit.start,
+      addressed: hit.addressed,
+      // What was said after the command's own sentences, up to the next address. Not part of
+      // the command — kept so a caller refining with a model has the surrounding words.
+      rest: raw.slice(hit.end + span.indexOf(command) + command.length, stop).trim(),
+    };
+  });
+}
+
+/**
+ * Find "<wake>, <command>" in one utterance — the first one.
+ *
+ * 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(), opts = {}) {
+  return findWakeCommands(text, wake, opts)[0] || null;
+}
+
+/**
+ * The REQUEST inside a spoken utterance — not everything that followed the wake word.
+ *
+ * People do not stop talking when they finish asking. A real capture:
+ *
+ *   "Okay, chat panel. Whenever I do anything or ask any question just to do a research for
+ *    me and get me the answer, okay? All right, so. I want to know how is the weather in
+ *    Fairview today? All right, so we will see. It does anything. Does it get added to?"
+ *
+ * Everything after the wake word became the job's name AND its prompt, so the job was a
+ * paragraph of thinking-aloud with a weather question buried in the middle — which is what
+ * "it didn't separate" means, and why the answer was useless even on the runs that happened.
+ *
+ * What this does, and deliberately no more: split into sentences, drop the ones that are pure
+ * filler, and prefer a QUESTION when one was asked (the LAST one — people circle back, and
+ * the restatement is the version they meant). Everything here is free, deterministic and
+ * reversible. Turning rambling into a good PROMPT is a model's job, and the parser already
+ * says so by returning `needsModel`; this is the FLOOR under that, for when no model is
+ * configured and for the instant before one answers. It is a heuristic over speech and it
+ * will sometimes pick the wrong sentence — that is precisely why the contract asks the host
+ * to pay for a model rather than pretending this is the answer.
+ */
+
+// Sentences carrying no request — verbal punctuation, thinking aloud, or narrating the very
+// experiment being run. Matched WHOLE, so "so we will see" goes and "see if the build passed"
+// stays.
+const FILLER_SENTENCE = new RegExp('^(?:'
+  + "ok(?:ay)?|all ?right|right|so|well|um+|uh+|hmm+|yeah|yep|hey|and|but|then|now"
+  + "|let(?:'s| us) see|we(?:'ll| will) see|so we(?:'ll| will) see"
+  + "|i think it is doing something|it does anything|does it (?:do )?anything"
+  + "|hold on(?: a second)?|one second|let me see|i think|i guess|here we go|there we go"
+  + "|test(?:ing)?"
+  + ')[\\s,.!?]*$', 'i');
+
+const SENTENCE_SPLIT = /(?<=[.!?])\s+/;
+
+/**
+ * True when a sentence is only filler — verbal punctuation rather than a request.
+ *
+ * Checked CLAUSE BY CLAUSE, because people string filler together with commas: "All right,
+ * so we will see." is two fillers in one sentence and matches neither whole. Every clause
+ * must be filler for the sentence to be, so "right after the demo, remind me" survives on the
+ * strength of its first clause even though the second would pass alone.
+ */
+export function isFillerSentence(text) {
+  const t = String(text || '').trim().replace(/^[\s,.:;!?-]+/, '');
+  if (!t) return true;
+  if (FILLER_SENTENCE.test(t)) return true;
+  const clauses = t.split(',').map((c) => c.trim()).filter(Boolean);
+  return clauses.length > 1 && clauses.every((c) => FILLER_SENTENCE.test(c));
+}
+
+/**
+ * @returns { request, name, ambiguous } — the text to act on, a short label for it, and
+ *          whether more than one question was asked (in which case `request` is everything
+ *          meaningful and a model should be asked to pick). Both strings fall back to the
+ *          cleaned original rather than to nothing: a command we could not parse is still a
+ *          command the user gave, and dropping it silently is the worse failure.
+ */
+export function refineSpokenCommand(text, { maxName = 48 } = {}) {
+  const raw = stripLeadIn(String(text || '')).trim();
+  if (!raw) return { request: '', name: '' };
+  const sentences = raw.split(SENTENCE_SPLIT).map((t) => t.trim()).filter(Boolean);
+  const meaningful = sentences.filter((t) => !isFillerSentence(t));
+  // ONE question is the request. SEVERAL is a guess, and this function refuses to make it.
+  //
+  // A real capture contained three: a standing preamble ("whenever I ask anything, research
+  // it for me, okay?"), the actual request ("how is the weather in Fairview today?") and a
+  // meta-question about the tool ("does it get added to?"). Last-wins picks the third,
+  // longest-wins picks the first, and every other rule that fits this sample is a rule fitted
+  // to this sample. Choosing between them needs to understand them — which is a model's job,
+  // and exactly what `needsModel` exists to ask for. So: an unambiguous question is used, and
+  // an ambiguous one is handed on WHOLE with `ambiguous` set, for the caller to refine.
+  const questions = meaningful.filter((t) => /\?\s*$/.test(t));
+  const ambiguous = questions.length > 1;
+  const picked = questions.length === 1
+    ? questions[0]
+    : (meaningful.length ? meaningful.join(' ') : raw);
+  const request = stripLeadIn(picked).trim() || raw;
+  // The name is a label in a list, not the instruction. One line, clipped on a word boundary.
+  const flat = request.replace(/\s+/g, ' ').trim();
+  const name = flat.length > maxName
+    ? `${flat.slice(0, maxName - 1).replace(/\s+\S*$/, '')}…`
+    : flat;
+  return { request, name: name || flat, ambiguous };
+}
+
+/**
+ * Ask a model what was actually being asked — the other half of `needsModel`.
+ *
+ * The parser has always returned `needsModel: true` for a command it did not recognise, with
+ * a comment saying the host "may pay for a small model to read it, and MUST NOT guess". No
+ * host ever did, so an unrecognised spoken request became a job whose name and prompt were
+ * both the entire utterance. refineSpokenCommand() is the free floor under this; when several
+ * questions were asked it declines to choose, and THIS is what chooses.
+ *
+ * Deliberately a tiny, single-shot classification with a strict output shape: it runs on a
+ * fast model while a meeting is happening, so it must cost about as much as one sentence.
+ */
+/**
+ * The shape of the answer, declared ONCE.
+ *
+ * It used to be typed twice — as prose inside the prompt string and again as a list of enum
+ * values thirty lines below in the parser — with nothing making the two agree. Adding a kind
+ * to one and not the other is a silent, permanent bug: the model answers correctly and the
+ * parser maps it to "question" forever. Now the prompt is rendered from this and the parser
+ * coerces onto it, so there is only one place a field exists.
+ */
+export const REFINEMENT_SCHEMA = defineSchema({
+  name: 'voice_refinement',
+  fields: {
+    request: {
+      type: 'string', required: true, max: 400,
+      describe: 'the one thing they actually want done, in their own words, one sentence',
+    },
+    name: { type: 'string', max: 48, describe: 'a label of at most 6 words' },
+    kind: {
+      type: 'enum',
+      values: ['question', 'monitor', 'note', 'skill', 'none'],
+      // An unknown kind becomes a QUESTION — the least surprising thing to do with something
+      // someone asked for, and the only kind that is undone by ignoring the answer. Guessing
+      // "monitor" instead would leave a card watching the meeting that nobody asked for.
+      default: 'question',
+      describe: 'the SMALLEST kind that does what they asked',
+    },
+    skill: { type: 'string', max: 80, describe: 'the skill name, only when kind is skill' },
+  },
+  // "none" is a real answer and the most important one to honour: it is how the model says
+  // "they were just talking", which is the case that produced junk jobs. It arrives two ways —
+  // as the whole reply, and as the value of `request` — and both are this.
+  nothing: { request: '', name: '', kind: 'none', skill: '' },
+});
+
+export function refinementPrompt(utterance) {
+  return [
+    'A person spoke to their assistant during a meeting. Below is everything they said after',
+    'the wake word, transcribed live — so it contains false starts, thinking aloud, and',
+    'sometimes several questions where only one is the request.',
+    '',
+    describeSchema(REFINEMENT_SCHEMA),
+    '',
+    'Pick the SMALLEST kind that does what they asked:',
+    '  question — answer it once, now. The DEFAULT for anything they want to know.',
+    '  monitor  — only if they asked to be told as the meeting CONTINUES ("let me know if",',
+    '             "keep an eye on"). A one-off question is NOT a monitor.',
+    '  note     — they asked for notes written down ("take notes on", "write that up").',
+    '  skill    — they named a saved skill ("use the summarize skill"); put its name in `skill`.',
+    '  none     — not asking for anything: thinking aloud, or talking ABOUT the assistant.',
+    'Never invent a request that is not there — return "none". Keep `request` close to their',
+    'words; do not answer it.',
+    '',
+    'WHAT THEY SAID:',
+    String(utterance || ''),
+  ].join('\n');
+}
+
+/**
+ * The body fragment that makes a capable endpoint enforce the shape server-side.
+ * Null for an agent CLI, which has no such control — the prompt and the repair pass carry it.
+ */
+export function refinementFormat(mode = 'schema') { return responseFormat(REFINEMENT_SCHEMA, { mode }); }
+
+/**
+ * Read the model's answer back, defensively.
+ *
+ * Everything generic — code fences, a prose preamble, single quotes, a trailing comma, the
+ * word "none" in place of an object, a key spelled `Request` — is handled by the shared
+ * coercer, which means every OTHER structured call in the product gets those repairs too.
+ * What stays here is only what is true of THIS answer and no other.
+ *
+ * Returns null for anything unusable, so the caller falls back to the deterministic pass
+ * rather than acting on a hallucinated request.
+ */
+export function parseRefinement(text) {
+  const got = coerce(text, REFINEMENT_SCHEMA);
+  if (!got) return null;
+  return settleRefinement(got.value);
+}
+
+/**
+ * The two rules that are about voice commands rather than about JSON.
+ *
+ * Shared with the streaming reader below, because a rule applied on the final answer and not
+ * on the partial one is a rule the user watches the UI break. Exported because a caller that
+ * fetches the answer through the generic structured-call capability gets the raw coerced
+ * object and still needs these — the rules must not live only inside one of two paths.
+ */
+export function settleRefinement(v) {
+  if (!v) return null;
+  const request = String(v.request || '').trim();
+  if (v.kind === 'none' || !request) return { request: '', name: '', kind: 'none', skill: '' };
+  // A "skill" with no name is a question — there is nothing to run.
+  const kind = v.kind === 'skill' && !v.skill ? 'question' : v.kind;
+  return { request, name: String(v.name || '').trim() || request, kind, skill: v.skill || '' };
+}
+
+/**
+ * The same answer, AS IT ARRIVES.
+ *
+ * A refinement is asked for mid-meeting while someone is waiting to see whether they were
+ * heard, and the standing rule is that every model output streams with visible progress. The
+ * `settled` set is what makes that safe: `request` can be shown growing, and `kind` — which
+ * decides whether a monitor gets created — is only acted on once the model has closed it.
+ *
+ *     const s = refinementStream({ onChange: (v, settled) => paint(v, settled) });
+ *     await stream({ …, onDelta: (d) => s.push(d) });
+ *     const final = s.end().value;   // already settled, or null
+ */
+export function refinementStream({ onChange = null } = {}) {
+  const inner = createStructuredStream(REFINEMENT_SCHEMA, {
+    onChange: onChange ? (v, settled) => onChange(settleRefinement(v), settled) : null,
+  });
+  const wrap = (snap) => ({ ...snap, value: settleRefinement(snap.value) });
+  return {
+    push: (chunk) => wrap(inner.push(chunk)),
+    end: () => wrap(inner.end()),
+    snapshot: () => wrap(inner.snapshot()),
+    reset: () => inner.reset(),
+    get text() { return inner.text; },
+  };
+}
+
+/**
+ * Was the assistant SPOKEN TO, or merely spoken about?
+ *
+ * "we should talk about the chat panel roadmap next week" contains the wake word and is not a
+ * command — acting on it is how ordinary conversation quietly set timers. But "Okay, chat
+ * panel. Anytime I ask a question…" is unmistakably addressed, and dropping it is why a
+ * clearly-spoken request did nothing at all.
+ *
+ * The signal that separates them is grammatical and cheap: a wake word used as a NOUN is
+ * introduced by a determiner or preposition ("the chat panel", "about ChatPanel", "our chat
+ * panel"). A wake word used as a VOCATIVE is at the start of what is being said, or follows
+ * an address word ("okay", "hey", "hi"), or follows the end of the previous sentence.
+ *
+ * Wrong sometimes, in both directions — which is exactly why it decides whether to ASK
+ * (needsModel, a visible and reversible monitor) rather than whether to act.
+ */
+const NOUN_MARKERS = /^(?:the|a|an|our|your|their|my|this|that|these|those|about|on|in|of|with|via|using|called|named|to)$/i;
+
+function isAddressed(raw, tokens, i, n = 0) {
+  // The fuzzy match is generous enough to SWALLOW a leading article: "a chat panel" squashes
+  // to "achatpanel", one edit from "chatpanel", so the determiner ends up inside the matched
+  // span instead of before it. Check the first matched token too, or "a chat panel would be
+  // useful here" reads as an address purely because the "a" was absorbed.
+  if (n > 0 && NOUN_MARKERS.test(String(tokens[i].w || '').replace(/[^\p{L}\p{N}]/gu, ''))) return false;
+  if (i === 0) return true; // nothing before it — it opens the utterance
+  const prev = tokens[i - 1];
+  const word = String(prev.w || '').replace(/[^\p{L}\p{N}]/gu, '');
+  if (NOUN_MARKERS.test(word)) return false; // "the chat panel" — a thing, not a listener
+  // Punctuation before it is the vocative comma or a sentence break — "…here. Okay, chat
+  // panel", "so I was thinking. ChatPanel, what did we decide?" — and both mean a fresh
+  // address rather than a continuing noun phrase. Measured from the previous token's START,
+  // because the tokenizer keeps trailing punctuation ON the token ("thinking."), so the gap
+  // between tokens is only the space and the full stop would be missed.
+  if (/[.!?,;:]["')\]]?\s*$/.test(raw.slice(prev.start, tokens[i].start))) return true;
+  // "hey chatpanel", "ok chatpanel" — an address word is the other way people open one.
+  return /^(?:ok|okay|hey|hi|yo|hello|so|um|uh)$/i.test(word);
+}
+
+/**
+ * Drop the NEXT address's run-up from the end of this command.
+ *
+ * A command is bounded by where the next wake phrase starts — but people open an address with
+ * a word or two before the name ("…Okay, chat panel."), and those land on the end of the
+ * previous command. Harmless to read, ruinous to identity: as the caption grows, "start
+ * monitoring the pricing question." becomes "…pricing question. Okay", which is different
+ * words, a different key, and therefore the same request acted on twice.
+ *
+ * Only the address words are trimmed, and only from the end — the same short list that marks
+ * an opening in isAddressed().
+ */
+function trimTrailingLeadIn(text) {
+  return String(text)
+    .replace(/(?:[\s,.:;!?-]*\b(?:ok|okay|hey|hi|yo|hello|so|um+|uh+|and|then|now)\b)+[\s,.:;!?-]*$/i, '')
+    .trim();
 }
 
 // "chatpanel, could you please set a timer" — politeness is not part of the command, and
@@ -590,13 +996,94 @@ export function parseCommand(text, { wake = compileWake(), intents = defaultVoic
   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 };
+  return { ...parsed, wake: found.wake, heard: found.heard, at: found.at, addressed: found.addressed !== false };
 }
 
 // ---------------------------------------------------------------------------
 // Transcript → commands
 // ---------------------------------------------------------------------------
 
+/**
+ * Has the speaker finished the thought? — and PUNCTUATION IS NOT THE EVIDENCE.
+ *
+ * This used to be `endsSentence`: a full stop at the end of the caption meant the speaker had
+ * stopped. Live caption engines punctuate as they go, and they punctuate FRAGMENTS. One
+ * capture of this feature in use produced, in order: "Take.", "Take the question and ask
+ * the.", "set a timer for.", "let's summar." — four full stops nobody uttered, and four
+ * half-sentences sent to a model as requests while the speaker was still saying the rest.
+ *
+ * So the full stop is thrown away and the LAST WORD is read instead. A command ending on a
+ * preposition, an article, a conjunction or an auxiliary ("…ask the", "…a timer for") is
+ * someone mid-thought, however the transcriber punctuated it.
+ *
+ * A HINT, NOT A VERDICT. "Tell me what that is" is a real request that ends on 'is', so a
+ * dangling tail must never DISCARD a command — it only makes the gate below wait longer for
+ * the rest to arrive. A command that is never acted on is the worse failure of the two.
+ */
+// Words that can end a sentence grammatically but in speech mean the qualifier is still being
+// chosen — "summarize the last 30 seconds, like, maybe…".
+const TRAILING_HEDGES = new Set(['maybe', 'perhaps', 'probably', 'basically', 'roughly', 'kinda', 'sorta']);
+
+export function commandLooksFinished(text) {
+  const t = String(text || '').trim().replace(/[\s.,;:!?…'"’”)\]-]+$/u, '');
+  if (!t) return false;
+  const tokens = t.toLowerCase().match(/[\p{L}\p{N}']+/gu) || [];
+  const last = tokens[tokens.length - 1];
+  if (!last) return false;
+  return !DANGLING_TAILS.has(last) && !TRAILING_HEDGES.has(last);
+}
+
+// Terminal punctuation. Worth almost nothing on its own — see above — but it is the only
+// signal a caller with no gate has, so the ungated path keeps asking for it ON TOP of the
+// tail test rather than getting looser than it was.
+const endsSentence = (text) => /[.!?…]["'’”)\]]*\s*$/.test(String(text || '').trim());
+
+/**
+ * The SHORTEST span that parses wins.
+ *
+ * "Set a timer for 30 seconds. And then that should actually set a timer for 30 seconds."
+ * is one request said twice, and the duration parser sums what it finds across the span —
+ * so a two-sentence window turned 30 seconds into 60 and produced a one-minute timer nobody
+ * asked for. Worse, it moved: as the caption grew, the same words re-parsed to a different
+ * duration, which is a different dedupe key, which is another timer. That is the "why is it
+ * creating timers again and again" report.
+ *
+ * So the first sentence is tried alone, and the wider span only when it yields nothing. A
+ * request that genuinely needs two ("Set a timer. Make it five minutes.") still gets them.
+ */
+function parseShortest(command, intents, now) {
+  const first = firstSentences(command, 1).trim();
+  if (first && first !== command) {
+    const narrow = intents.parse(first, { now });
+    if (narrow?.intent) return narrow;
+  }
+  return intents.parse(command, { now });
+}
+
+/**
+ * A command's words, reduced to what survives re-transcription.
+ *
+ * Case and spacing vary between flushes of the same sentence, and punctuation appears and
+ * disappears as the engine revises — so none of them may be part of an identity that is
+ * supposed to say "you have already done this".
+ */
+export const gistText = (text) => String(text || '')
+  .toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim().slice(0, 160);
+
+/**
+ * The OPENING of a request — a looser identity than its full words.
+ *
+ * A transcriber does not only append; it REVISES. "How is the weather in Seattle, Washington
+ * now?" became "How is the weather in Seattle, Washington?" on a later flush — different
+ * words, a different key, and the same question asked twice. The first few words are what a
+ * revision leaves alone.
+ *
+ * Six is chosen against the failure it exists to stop: long enough that two genuinely
+ * different requests rarely share an opening, short enough to survive the tail being rewritten.
+ */
+export const OPENING_WORDS = 6;
+export const gistOpening = (text) => gistText(text).split(' ').slice(0, OPENING_WORDS).join(' ');
+
 /** How many commands one transcript delta may produce. */
 export const MAX_COMMANDS_PER_DELTA = 3;
 
@@ -618,27 +1105,66 @@ export const MAX_COMMANDS_PER_DELTA = 3;
  */
 export function commandsFromSegments(segments, {
   wake = compileWake(), intents = defaultVoiceIntents(), isSelf = null,
-  sinceTs = 0, now = Date.now(), meetingId = '', max = MAX_COMMANDS_PER_DELTA,
+  sinceTs = 0, now = Date.now(), meetingId = '', max = MAX_COMMANDS_PER_DELTA, gate = null,
 } = {}) {
   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 });
+    // EVERY address in this caption, not just the first. A live caption carries a minute of
+    // speech, and a person addressing an assistant addresses it more than once in a minute —
+    // "…set a timer for 1 minute. Okay chat panel, go and search…" is two commands. Taking
+    // only the first also made that first command swallow the rest, which is how a one-minute
+    // timer became 720 hours: the duration parser found "30 days" four sentences later.
+    for (const found of findWakeCommands(seg.text, wake)) {
+    if (!found.command) continue; // a bare mention with nothing after it
+    const intent = parseShortest(found.command, intents, now);
+    // `rest` rides along: the deterministic intents parse only the tight span (that is what
+    // stops a duration being found four sentences away), but a MODEL asked to read an
+    // unrecognised request should see the words around it — the question often follows a
+    // sentence of preamble. Parse narrow, refine wide.
+    const parsed = intent && {
+      ...intent, wake: found.wake, heard: found.heard, at: found.at,
+      addressed: found.addressed, rest: found.rest,
+    };
     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.
+    // MENTIONED vs ADDRESSED — and this guard used to conflate them.
+    //
+    // parseCommand returns a shape for anything carrying the wake word, intent or not, so
+    // "we should talk about the chat panel roadmap next week" came back as a command and the
+    // caller acted on it: ordinary conversation quietly setting timers. Dropping every
+    // intentless utterance fixed that, and broke the opposite case just as badly — "Okay,
+    // chat panel. How is the weather in Lakeside?" is unmistakably a request, matches no
+    // built-in intent (there is no weather intent, and there should not be), and was
+    // discarded here. Nothing downstream ever saw it, which is why `needsModel` had no
+    // handler: it could not reach one.
+    //
+    // So the test is whether the assistant was SPOKEN TO. A passing mention still stops here.
+    // An address with no matching intent goes on with needsModel set, for a model to read —
+    // which is what the parser has always said should happen.
     //
-    // 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;
+    if (!parsed.intent && !parsed.addressed) continue;
+    // Does this read as a whole thought? Computed once, where the command's own words are:
+    // the guard below and the gate must never be able to answer that differently.
+    const finished = commandLooksFinished(found.command);
+    // WHETHER THE SENTENCE HAS ENDED IS NOT DECIDED HERE — when there is a gate.
+    //
+    // It used to be decided here, on the caption's terminal punctuation, and that is exactly
+    // what sent "Take the question and ask the." to a model as a request. This function sees
+    // ONE delivery of a caption; only something watching the same utterance across
+    // deliveries can tell a finished sentence from a punctuated fragment, and that is the
+    // gate below (`finished` is the hint it reads).
+    //
+    // A caller with no gate has no such thing, so it keeps the old conservative rule and
+    // gains the tail test on top of it: both, or the request waits for the next delivery.
+    // Getting LOOSER than the code being fixed would be a strange way to fix it.
+    if (!parsed.intent && !gate && !(finished && endsSentence(seg.text))) continue;
     const allowed = isSelf ? !!isSelf(seg.speaker) : false;
     out.push({
       ...parsed,
       allowed,
+      // Carried, so the gate reads the same answer this scan did.
+      finished,
       speaker: seg.speaker || '',
       t: seg.t || now,
       meetingId,
@@ -656,9 +1182,180 @@ export function commandsFromSegments(segments, {
       // 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 ?? ''}`,
+      // WHAT WAS ASKED, not which delivery of it carried the words.
+      //
+      // This used to key on the caption's identity (`sid`) and the wake word's offset. Both
+      // move: `sid` is re-minted whenever the caption engine loses the overlap between a
+      // growing line and the one before it, and a monologue keeps ONE entry alive for
+      // minutes — re-scanned on every flush, by design, so a half-heard command gets a
+      // second chance. So one spoken "set a timer for 30 seconds" kept arriving as a
+      // brand-new command and kept creating timers.
+      //
+      // The words are what does not move. Two different commands in one breath still differ;
+      // the same command through fifty flushes is one request.
+      // The OPENING, not the whole sentence: a live caption keeps growing ("…10 seconds",
+      // then "…10 seconds and then", then "…and then we moved on"), and gistText over the
+      // full text moves with every one of those — which is the very bug this key exists to
+      // stop, just later in the sentence. The intent and its resolved duration are already
+      // in the key, so two genuinely different commands still differ.
+      key: `voice:${meetingId}:${parsed.intent || 'ask'}:${parsed.ms ?? parsed.when ?? ''}:${gistOpening(found.command)}`,
     });
-    if (out.length >= max) break; // a pathological transcript cannot fire fifty actions
+    }
   }
-  return out;
+  // THE NEWEST, not the first.
+  //
+  // The cap exists so a pathological transcript cannot fire fifty actions, and it used to
+  // stop scanning once it had `max` — counting from the START of the caption. A caption entry
+  // in a monologue lives for minutes and is re-scanned on every flush, accumulating every
+  // address spoken into it, so the first three (long since acted on) consumed the whole
+  // budget and everything said AFTER them was never returned at all. The request you just
+  // made was the one thrown away.
+  //
+  // The newest are both the most likely to be fresh and the ones a person is waiting on, so
+  // the cap keeps those. The already-acted ones are dropped downstream by the dedupe anyway.
+  const found = out.length > max ? out.slice(-max) : out;
+  // WITH A GATE, nothing is returned until the words stop moving — see createUtteranceGate.
+  // Without one the old behaviour stands, so a host that has not adopted it (or a test asking
+  // what the grammar sees) is unchanged.
+  return gate ? gate.offer(found, now).due(now) : found;
+}
+
+// ---------------------------------------------------------------------------
+// One utterance, one action
+// ---------------------------------------------------------------------------
+
+/**
+ * How long a command's words must stop changing before it is acted on.
+ *
+ * LONGER THAN THE CAPTURE'S FLUSH INTERVAL, and that is the whole calculation. Captions reach
+ * a client in batches — the extension debounces its flush by 4s — so "these words have not
+ * changed for 1s" says nothing except that no batch arrived in the last second. Only a wait
+ * that outlasts a flush can distinguish "they stopped talking" from "we have not been told
+ * what they said next".
+ */
+export const UTTERANCE_SETTLE_MS = 5_000;
+
+/**
+ * How long a command that ends MID-THOUGHT waits instead.
+ *
+ * "Set a timer for" is not a request yet; the duration is in the breath after it. Waiting the
+ * ordinary window and acting on it is exactly the bug this file exists to stop. But the tail
+ * test is a word list, not grammar, and "tell me what that is" ends on 'is' — so a dangling
+ * command is DELAYED, never dropped. If the speaker really did stop there, it still runs.
+ */
+export const UTTERANCE_DANGLING_MS = 12_000;
+
+// How long an utterance is remembered after it was last heard. A caption entry in a monologue
+// is re-delivered for minutes, and every one of those redeliveries has to find the record
+// saying "this one is done" — that record IS the one-utterance-one-action guarantee.
+const UTTERANCE_FORGET_MS = 3 * 60_000;
+// A cap, because a long meeting must not grow this without bound. Small: only utterances
+// still in flight or recently acted on matter, and the caller has its own longer-lived record
+// of what has been done.
+const UTTERANCE_TRACKED_MAX = 24;
+
+/**
+ * Is this the same spoken request as that one, a moment later?
+ *
+ * Two relations, because a transcriber does both. It APPENDS — "let's summar" becomes "let's
+ * summarize the notes" — which is a prefix. And it REVISES — "…in Seattle, Washington now?"
+ * came back as "…in Seattle, Washington?" — which is not, but keeps the opening.
+ */
+export function sameUtterance(a, b) {
+  if (!a || !b) return false;
+  if (a === b || a.startsWith(b) || b.startsWith(a)) return true;
+  const oa = a.split(' ').slice(0, OPENING_WORDS);
+  const ob = b.split(' ').slice(0, OPENING_WORDS);
+  // A short opening is not enough evidence: "set a timer" opens half the commands ever
+  // spoken, and collapsing two of them into one utterance loses the second silently.
+  return oa.length >= OPENING_WORDS && oa.join(' ') === ob.join(' ');
+}
+
+/**
+ * The thing that makes a growing caption ONE request.
+ *
+ * THE BUG THIS IS. A live caption is re-delivered as it grows, and every delivery was acted
+ * on the moment it parsed. So a single spoken "Okay ChatPanel, set a timer for 30 seconds"
+ * arrived first as "set a timer for." — no duration, no intent, addressed, punctuated by the
+ * transcriber — and went to the model as a QUESTION; then, seconds later, arrived whole and
+ * became a TIMER. One thing said, two things done, and the user reasonably reported it as
+ * "it set the timer but it also sent a message". Nothing downstream could relate the two:
+ * they had different words, different intents, and therefore different dedupe keys.
+ *
+ * They can only be related by watching them, so this is the one stateful thing in the file —
+ * and it is still clock-free (`now` is passed in, like everywhere else) and platform-free.
+ * The host owns exactly two things: keeping the object, and calling back when the wait is up.
+ *
+ *     const gate = createUtteranceGate();
+ *     const ready = commandsFromSegments(segments, { …, gate });   // offers and drains
+ *     const later = gate.nextDueIn();      // ms until something becomes actionable, or null
+ *     …setTimeout(() => act(gate.due()), later)                     // silence needs a nudge
+ *
+ * Note what does NOT come out of `due()`: an utterance that already fired. It stays in the
+ * gate, matching its own redeliveries, so the completed version of a request that was already
+ * acted on cannot act again as something else.
+ */
+export function createUtteranceGate({
+  settleMs = UTTERANCE_SETTLE_MS,
+  danglingMs = UTTERANCE_DANGLING_MS,
+  forgetMs = UTTERANCE_FORGET_MS,
+  max = UTTERANCE_TRACKED_MAX,
+} = {}) {
+  let live = [];
+  const waitFor = (e) => (e.command.finished === false ? danglingMs : settleMs);
+  const find = (command, gist) => live.find(
+    (e) => e.meetingId === (command.meetingId || '') && sameUtterance(e.gist, gist),
+  );
+  return {
+    /** Offer this delta's commands. Chainable, so a scan reads as one expression. */
+    offer(commands, now = Date.now()) {
+      for (const command of commands || []) {
+        const gist = gistText(command.command);
+        if (!gist) continue;
+        const entry = find(command, gist);
+        if (!entry) {
+          live.push({ meetingId: command.meetingId || '', gist, command, changedAt: now, seenAt: now, done: false });
+          continue;
+        }
+        entry.seenAt = now;
+        if (entry.done) continue; // said once, done once — however many more words arrive
+        if (gist === entry.gist) continue; // unchanged: the clock keeps running, untouched
+        // Still growing (or being revised). The newest wording is the one to act on, and the
+        // wait starts again from here — which is what makes a pause, not a full stop, the
+        // signal that someone has finished.
+        entry.gist = gist;
+        entry.command = command;
+        entry.changedAt = now;
+      }
+      live = live.filter((e) => now - e.seenAt <= forgetMs);
+      if (live.length > max) live = live.slice(-max);
+      return this;
+    },
+    /** The commands whose words have stopped moving. Each is returned exactly once. */
+    due(now = Date.now()) {
+      const out = [];
+      for (const e of live) {
+        if (e.done || now - e.changedAt < waitFor(e)) continue;
+        e.done = true;
+        out.push(e.command);
+      }
+      return out;
+    },
+    /**
+     * ms until the earliest waiting command becomes actionable, or null when none is waiting.
+     * The host needs this because silence produces no deltas to re-scan on: the last thing
+     * said before someone stops talking is exactly the thing they are waiting to see happen.
+     */
+    nextDueIn(now = Date.now()) {
+      let soonest = null;
+      for (const e of live) {
+        if (e.done) continue;
+        const left = Math.max(0, waitFor(e) - (now - e.changedAt));
+        if (soonest === null || left < soonest) soonest = left;
+      }
+      return soonest;
+    },
+    /** How many utterances are still waiting — for tests and for a diagnostics line. */
+    get waiting() { return live.filter((e) => !e.done).length; },
+  };
 }