@chatpanel/events 0.21.0 → 0.22.0

package/index.js

@@ -17,6 +17,7 @@ export {
 
 export { REF_KINDS, RESOLUTION, makeRef, isRef, resolveRef } from './ref.js';
 export { linearize, compareEvents, causesAreWellFormed } from './order.js';
+export { pendingQueue, isQueued, dequeue, moveQueued, promoteQueued } from './queue.js';
 export { UPCASTERS, upcast, upcastAll } from './upcast.js';
 export {
   validateCapability, validateInvocation, canSatisfy,
@@ -59,6 +60,7 @@ export {
   timerTrigger, meetingStartedTrigger, meetingEndedTrigger, personJoinedTrigger,
   phraseTrigger, topicTrigger, questionTrigger, voiceCommandTrigger,
   defineJob, dueJobs, jobsForEvent, occurrenceKey,
+  clipText, matchSummary,
 } from './schedule.js';
 export { defineMeetingAnalyzer, createAnalyzerRegistry, CADENCES, AnalyzerError } from './meeting-analyzers.js';
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "The canonical ChatPanel event-log and capability contracts — 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",
@@ -20,6 +20,7 @@
     "./meeting-analyzers.js": "./meeting-analyzers.js",
     "./memory.js": "./memory.js",
     "./order.js": "./order.js",
+    "./queue.js": "./queue.js",
     "./ref.js": "./ref.js",
     "./registry.js": "./registry.js",
     "./route-graph.js": "./route-graph.js",
@@ -68,6 +69,7 @@
     "memory.js",
     "observability.js",
     "order.js",
+    "queue.js",
     "ref.js",
     "registry.js",
     "route-graph.js",

package/queue.js

@@ -0,0 +1,98 @@
+// THE SEND QUEUE — what someone typed while a reply was still streaming, and what they are
+// allowed to do about it before it is answered.
+//
+// Typing over a running answer is not a mistake to be prevented; it is how people think. But
+// a queue you can only ADD to is a trap, and in three specific ways:
+//
+//   • the thought that arrives mid-answer is often the URGENT one — it should not have to
+//     wait out a reply it was meant to redirect (steer);
+//   • the reply frequently answers a queued question before it is ever sent, and sending it
+//     anyway spends a turn on something nobody wants any more (dequeue);
+//   • the order things occur to you is not the order they should be asked in (reorder).
+//
+// The queue is deliberately NOT a second list living beside the transcript. It IS the
+// trailing run of user messages that has no reply after it — exactly the set a client
+// answers when the current stream ends. One definition means what is drawn and what is sent
+// can never disagree, and a message cannot be "in the queue" but missing from the turn.
+//
+// Every function here is a pure transform: it returns a NEW array, or the array it was given
+// (by identity) when the operation was a no-op, so a caller can tell "nothing changed" from
+// "changed" without diffing. No clock, no ids minted, no DOM, no storage — the panel, a
+// mobile client, the gateway and the bridge can all reason about the same queue.
+//
+// STEERING, honestly: no engine we speak to accepts new input into a run already in flight
+// (the bridge closes a CLI's stdin with the prompt; HTTP streaming has no upstream channel).
+// So "send now" is promote-then-interrupt: the partial answer stays in the transcript as
+// context, and the next turn opens with the message the user wanted read first. This module
+// owns the ORDER half of that — the client owns the abort.
+
+const isUser = (m) => !!m && m.role === 'user';
+
+/**
+ * The pending queue: the trailing run of user messages with no reply after it.
+ *
+ * Returned oldest-first — the order they will be sent in — as
+ * `{ message, id, index, position }`, where `index` is the position in the whole
+ * transcript and `position` the position within the queue.
+ */
+export function pendingQueue(messages) {
+  const list = Array.isArray(messages) ? messages : [];
+  let start = list.length;
+  while (start > 0 && isUser(list[start - 1])) start--;
+  const out = [];
+  for (let i = start; i < list.length; i++) {
+    out.push({ message: list[i], id: list[i].id, index: i, position: i - start });
+  }
+  return out;
+}
+
+/** Is this message currently in the queue (rather than already answered)? */
+export function isQueued(messages, id) {
+  return pendingQueue(messages).some((e) => e.id === id);
+}
+
+/**
+ * Drop a queued message — the question the running reply already answered.
+ *
+ * Only ever removes from the pending run: an id from further up the transcript is a
+ * no-op, so a stale click can never delete a turn that has already been answered.
+ */
+export function dequeue(messages, id) {
+  const queue = pendingQueue(messages);
+  const hit = queue.find((e) => e.id === id);
+  if (!hit) return messages;
+  const next = messages.slice();
+  next.splice(hit.index, 1);
+  return next;
+}
+
+/** Move a queued message by `delta` places (-1 up, +1 down). Clamped: past either end is a no-op. */
+export function moveQueued(messages, id, delta) {
+  const queue = pendingQueue(messages);
+  const from = queue.findIndex((e) => e.id === id);
+  if (from < 0) return messages;
+  const step = Math.trunc(Number(delta) || 0);
+  const to = from + step;
+  if (!step || to < 0 || to >= queue.length) return messages;
+  return reordered(messages, queue, from, to);
+}
+
+/**
+ * Put a queued message at the FRONT — the ordering half of "send now".
+ *
+ * The rest of the queue keeps its relative order behind it: steering is a statement about
+ * what to read first, not an instruction to throw away everything else that was typed.
+ */
+export function promoteQueued(messages, id) {
+  const queue = pendingQueue(messages);
+  const from = queue.findIndex((e) => e.id === id);
+  if (from <= 0) return messages; // absent, or already first
+  return reordered(messages, queue, from, 0);
+}
+
+function reordered(messages, queue, from, to) {
+  const block = queue.map((e) => e.message);
+  const [moved] = block.splice(from, 1);
+  block.splice(to, 0, moved);
+  return messages.slice(0, queue[0].index).concat(block);
+}

package/schedule.js

@@ -162,6 +162,25 @@ export const MIN_PHRASE_CHARS = 3;
 
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
+/**
+ * Shorten text a person is meant to READ.
+ *
+ * A hard `slice` lands mid-word — "…with the informati" — and reads as a bug in whatever
+ * wrote it rather than as an abbreviation. Backing up to the last word boundary costs
+ * nothing and is the whole difference. Exported because three places shorten the same kinds
+ * of strings (a trigger's reason, a batch summary, a job named after its own instruction)
+ * and three hard slices is how they drift apart.
+ */
+export function clipText(text, max = 120) {
+  const t = String(text || '').replace(/\s+/g, ' ').trim();
+  if (t.length <= max) return t;
+  const cut = t.slice(0, max);
+  const at = cut.lastIndexOf(' ');
+  // Only back up when there is a boundary worth backing up TO. A single long token — a URL,
+  // an id — has none, and shrinking it to nothing helps nobody.
+  return `${(at > max * 0.6 ? cut.slice(0, at) : cut).replace(/[\s,;:.!?—-]+$/, '')}…`;
+}
+
 /**
  * Whole-word containment, not `includes`.
  *
@@ -386,7 +405,13 @@ export const questionTrigger = defineTrigger({
       if (!speakerAllowed(params.speaker || 'anyone', 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 };
+      // The QUESTION itself, not only who asked it. Every sibling trigger names what it
+      // fired on — the phrase, the spoken command, the people who joined — and "question
+      // from Alex" leaves the answer under it looking like an answer to nothing. This
+      // string is the row in the thread, the toast, and the line in the job's run log.
+      if (text.includes('?') || QUESTION.test(text)) {
+        return { why: `question from ${seg.speaker || 'someone'}: “${clipText(text, 100)}”`, segment: seg };
+      }
     }
     return null;
   },
@@ -545,6 +570,31 @@ export function matchTexts(matches = []) {
     .filter(Boolean);
 }
 
+/**
+ * One line saying what a batch of matches actually fired on.
+ *
+ * "3 questions" is a count, and a count is exactly the part the reader already knows — three
+ * answers are about to appear underneath it. What they cannot recover is WHICH three, so the
+ * questions themselves are the summary and the number is the prefix.
+ *
+ * `noun` is the plural word for what these are ('questions', 'matches'), since the trigger
+ * that produced them is not carried on a match.
+ */
+export function matchSummary(matches = [], { noun = 'matches', max = 3, chars = 180 } = {}) {
+  const list = (matches || []).filter(Boolean);
+  if (!list.length) return '';
+  // One match already has a human reason written by its own trigger — that reason is better
+  // than anything a generic formatter can say about it.
+  if (list.length === 1) return String(list[0].why || '') || clipText(list[0]?.segment?.text, chars);
+  const texts = matchTexts(list);
+  if (!texts.length) return `${list.length} ${noun}`;
+  const shown = texts.slice(0, max);
+  const per = Math.max(40, Math.floor(chars / shown.length));
+  const rest = texts.length - shown.length;
+  return `${texts.length} ${noun}: ${shown.map((t) => `“${clipText(t, per)}”`).join(' · ')}`
+    + (rest > 0 ? ` +${rest} more` : '');
+}
+
 export function jobsForEvent(jobs, event, { registry, ctx = {}, admit = null } = {}) {
   const out = [];
   for (const job of jobs || []) {