sentinelayer-cli 0.8.12 → 0.9.2

package/src/session/listener.js

@@ -0,0 +1,330 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+import { pollSessionEvents } from "./sync.js";
+import { readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
+
+const BROADCAST_RECIPIENTS = new Set([
+  "*",
+  "all",
+  "broadcast",
+  "everyone",
+  "anyone",
+  "agents",
+  "all-agents",
+]);
+
+const DEFAULT_ACTIVE_INTERVAL_SECONDS = 5;
+const DEFAULT_ACTIVE_WINDOW_SECONDS = 300;
+const MAX_CLOCK_SKEW_MS = 60_000;
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeComparableId(value) {
+  return normalizeString(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function normalizePositiveInteger(value, fallbackValue) {
+  if (value === undefined || value === null || String(value).trim() === "") {
+    return fallbackValue;
+  }
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) return fallbackValue;
+  return Math.floor(normalized);
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function addRecipientValue(values, value) {
+  if (value === undefined || value === null) return;
+  if (Array.isArray(value)) {
+    for (const item of value) addRecipientValue(values, item);
+    return;
+  }
+  if (isPlainObject(value)) {
+    addRecipientValue(values, value.id || value.agentId || value.name);
+    return;
+  }
+  const raw = normalizeString(value);
+  if (!raw) return;
+  for (const token of raw.split(/[\s,;]+/g)) {
+    const normalized = normalizeString(token);
+    if (normalized) values.push(normalized);
+  }
+}
+
+export function collectSessionEventRecipients(event = {}) {
+  const values = [];
+  if (!isPlainObject(event)) return values;
+  const payload = isPlainObject(event.payload) ? event.payload : {};
+  for (const source of [
+    event.to,
+    event.recipient,
+    event.recipients,
+    event.targetAgent,
+    event.targetAgentId,
+    payload.to,
+    payload.recipient,
+    payload.recipients,
+    payload.targetAgent,
+    payload.targetAgentId,
+  ]) {
+    addRecipientValue(values, source);
+  }
+  return values;
+}
+
+export function eventMatchesAgent(event = {}, agentId = "") {
+  if (!isPlainObject(event)) return false;
+  const normalizedAgentId = normalizeComparableId(agentId);
+  if (!normalizedAgentId) return false;
+
+  const payload = isPlainObject(event.payload) ? event.payload : {};
+  if (event.broadcast === true || payload.broadcast === true) return true;
+
+  const recipients = collectSessionEventRecipients(event);
+  if (recipients.length === 0) return true;
+
+  for (const recipient of recipients) {
+    const rawRecipient = normalizeString(recipient).toLowerCase();
+    if (BROADCAST_RECIPIENTS.has(rawRecipient)) return true;
+    const normalizedRecipient = normalizeComparableId(recipient);
+    if (!normalizedRecipient) continue;
+    if (BROADCAST_RECIPIENTS.has(normalizedRecipient)) return true;
+    if (normalizedRecipient === normalizedAgentId) return true;
+  }
+  return false;
+}
+
+export function listenCursorSuffix(agentId = "") {
+  return `listen-${normalizeComparableId(agentId) || "agent"}`;
+}
+
+async function defaultSleep(ms, { signal } = {}) {
+  await delay(ms, undefined, { signal });
+}
+
+function shouldAbort(error, signal) {
+  return Boolean(signal?.aborted || error?.name === "AbortError" || error?.code === "ABORT_ERR");
+}
+
+function cursorFromEvents(events = [], fallbackCursor = null) {
+  let cursor = normalizeString(fallbackCursor) || null;
+  for (const event of events) {
+    const candidate = normalizeString(event?.cursor);
+    if (candidate) cursor = candidate;
+  }
+  return cursor;
+}
+
+function eventTimestampMs(event = {}) {
+  for (const key of ["ts", "timestamp", "createdAt", "at"]) {
+    const epoch = Date.parse(normalizeString(event?.[key]));
+    if (Number.isFinite(epoch)) return epoch;
+  }
+  return 0;
+}
+
+function normalizeLower(value) {
+  return normalizeString(value).toLowerCase();
+}
+
+function isHumanMarker(value) {
+  const raw = normalizeLower(value);
+  if (!raw) return false;
+  if (["human", "user", "operator"].includes(raw)) return true;
+  const comparable = normalizeComparableId(raw);
+  return Boolean(
+    comparable === "human" ||
+      comparable === "user" ||
+      comparable === "operator" ||
+      comparable.startsWith("human-") ||
+      comparable.startsWith("user-")
+  );
+}
+
+function isHumanAuthoredEvent(event = {}) {
+  if (!isPlainObject(event)) return false;
+  const payload = isPlainObject(event.payload) ? event.payload : {};
+  const agent = isPlainObject(event.agent) ? event.agent : {};
+  const markerCandidates = [
+    payload.source,
+    payload.authorType,
+    payload.senderType,
+    payload.model,
+    payload.role,
+    event.source,
+    event.authorType,
+    event.senderType,
+    event.model,
+    event.role,
+    agent.model,
+    agent.role,
+  ];
+  if (markerCandidates.some(isHumanMarker)) return true;
+
+  const idCandidates = [
+    agent.id,
+    event.agentId,
+    event.authorId,
+    event.senderId,
+    payload.agentId,
+    payload.authorId,
+    payload.senderId,
+  ];
+  return idCandidates.some(isHumanMarker);
+}
+
+function humanActivityTimestampMs(event = {}, nowMs = Date.now()) {
+  if (!isHumanAuthoredEvent(event)) return 0;
+  return eventTimestampMs(event) || nowMs;
+}
+
+function isRecentActivity(activityMs, nowMs, windowMs) {
+  return (
+    Number.isFinite(activityMs) &&
+    activityMs > 0 &&
+    activityMs <= nowMs + MAX_CLOCK_SKEW_MS &&
+    nowMs - activityMs <= windowMs
+  );
+}
+
+/**
+ * Poll session events in the background and emit only events addressed to
+ * the current agent or broadcast to everyone. The loop advances its cursor
+ * across non-matching events so direct listeners do not replay unrelated
+ * traffic forever.
+ */
+export async function listenSessionEvents({
+  sessionId,
+  targetPath = process.cwd(),
+  agentId = "cli-user",
+  intervalSeconds = 60,
+  activeIntervalSeconds = DEFAULT_ACTIVE_INTERVAL_SECONDS,
+  activeWindowSeconds = DEFAULT_ACTIVE_WINDOW_SECONDS,
+  limit = 200,
+  since = undefined,
+  replay = false,
+  maxPolls = null,
+  signal,
+  onEvent = async () => {},
+  onError = async () => {},
+  _poll = pollSessionEvents,
+  _readCursor = readSyncCursor,
+  _writeCursor = writeSyncCursor,
+  _sleep = defaultSleep,
+  _nowMs = Date.now,
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedAgentId = normalizeComparableId(agentId) || "cli-user";
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+
+  const cursorSuffix = listenCursorSuffix(normalizedAgentId);
+  let cursor =
+    typeof since === "string" || since === null
+      ? normalizeString(since) || null
+      : await _readCursor(normalizedSessionId, { targetPath, suffix: cursorSuffix });
+  let primed = Boolean(cursor) || Boolean(replay);
+  let pollCount = 0;
+  let emitted = 0;
+  let matched = 0;
+  let persistedCursor = false;
+  let lastReason = "";
+  const maxPollCount = normalizePositiveInteger(maxPolls, 0);
+  const pollLimit = normalizePositiveInteger(limit, 200);
+  const idleSleepMs = Math.max(1, normalizePositiveInteger(intervalSeconds, 60)) * 1000;
+  const activeSleepMs =
+    Math.max(1, normalizePositiveInteger(activeIntervalSeconds, DEFAULT_ACTIVE_INTERVAL_SECONDS)) *
+    1000;
+  const activeWindowMs =
+    Math.max(1, normalizePositiveInteger(activeWindowSeconds, DEFAULT_ACTIVE_WINDOW_SECONDS)) *
+    1000;
+  const startedAtMs = Number(_nowMs()) || Date.now();
+  let lastHumanActivityMs = 0;
+  let lastSleepMs = 0;
+
+  while (!signal?.aborted) {
+    pollCount += 1;
+    const result = await _poll(normalizedSessionId, {
+      targetPath,
+      since: cursor,
+      limit: pollLimit,
+    });
+
+    if (result?.ok) {
+      lastReason = "";
+      const events = Array.isArray(result.events) ? result.events : [];
+      const observedAtMs = Number(_nowMs()) || Date.now();
+      for (const event of events) {
+        const activityMs = humanActivityTimestampMs(event, observedAtMs);
+        if (isRecentActivity(activityMs, observedAtMs, activeWindowMs)) {
+          lastHumanActivityMs = Math.max(lastHumanActivityMs, activityMs);
+        }
+      }
+      const shouldEmitBatch = primed || Boolean(replay);
+      for (const event of events) {
+        if (!eventMatchesAgent(event, normalizedAgentId)) continue;
+        matched += 1;
+        if (!shouldEmitBatch && eventTimestampMs(event) < startedAtMs) continue;
+        await onEvent(event);
+        emitted += 1;
+      }
+
+      const nextCursor = normalizeString(result.cursor) || cursorFromEvents(events, cursor);
+      if (nextCursor && nextCursor !== cursor) {
+        const writeResult = await _writeCursor(normalizedSessionId, nextCursor, {
+          targetPath,
+          suffix: cursorSuffix,
+        }).catch(() => null);
+        persistedCursor = Boolean(writeResult?.written) || persistedCursor;
+        cursor = nextCursor;
+      }
+      primed = true;
+    } else {
+      lastReason = normalizeString(result?.reason) || "poll_failed";
+      await onError({
+        ok: false,
+        reason: lastReason,
+        cursor: result?.cursor || cursor || null,
+      });
+    }
+
+    if (maxPollCount > 0 && pollCount >= maxPollCount) break;
+    const sleepAtMs = Number(_nowMs()) || Date.now();
+    const humanActive = isRecentActivity(lastHumanActivityMs, sleepAtMs, activeWindowMs);
+    const nextSleepMs = humanActive ? Math.min(idleSleepMs, activeSleepMs) : idleSleepMs;
+    lastSleepMs = nextSleepMs;
+    try {
+      await _sleep(nextSleepMs, { signal });
+    } catch (error) {
+      if (shouldAbort(error, signal)) break;
+      throw error;
+    }
+  }
+
+  return {
+    ok: true,
+    sessionId: normalizedSessionId,
+    agentId: normalizedAgentId,
+    cursor,
+    cursorSuffix,
+    pollCount,
+    matched,
+    emitted,
+    persistedCursor,
+    idleIntervalSeconds: Math.round(idleSleepMs / 1000),
+    activeIntervalSeconds: Math.round(activeSleepMs / 1000),
+    activeWindowSeconds: Math.round(activeWindowMs / 1000),
+    lastHumanActivityAt: lastHumanActivityMs ? new Date(lastHumanActivityMs).toISOString() : null,
+    lastSleepMs,
+    reason: lastReason,
+  };
+}

package/src/session/live-source.js

@@ -20,12 +20,20 @@ import { setTimeout as sleep } from "node:timers/promises";
 
 import { resolveSessionPaths } from "./paths.js";
 import { readStream } from "./stream.js";
+import {
+  addSessionEventIdentityKeys,
+  dedupeSessionEvents,
+  sessionEventHasKnownIdentity,
+  sessionEventIdentityKeys,
+} from "./event-identity.js";
 
 const DEFAULT_RECONNECT_BACKOFF_MS = 2_000;
 const MAX_RECONNECT_BACKOFF_MS = 30_000;
 
 function eventKey(event) {
   if (!event || typeof event !== "object") return null;
+  const identityKeys = sessionEventIdentityKeys(event);
+  if (identityKeys.length > 0) return identityKeys[0];
   if (event.id) return `id:${event.id}`;
   if (event.eventId) return `id:${event.eventId}`;
   const ts = event.ts || event.timestamp;
@@ -57,7 +65,7 @@ export async function* watchLocalStream({
 
   // Replay the tail first so any caller getting the iterator catches
   // up with the in-flight context before live events start arriving.
-  const initial = await _readEvents(sessionId, { targetPath, tail: initialTail });
+  const initial = dedupeSessionEvents(await _readEvents(sessionId, { targetPath, tail: initialTail }));
   for (const event of initial) {
     const candidate = event.ts || event.timestamp;
     if (candidate) lastTs = candidate;
@@ -293,7 +301,8 @@ export async function* mergeLiveSources({
     if (item.event) {
       const key = eventKey(item.event);
       if (key) {
-        if (seen.has(key)) continue;
+        if (sessionEventHasKnownIdentity(item.event, seen) || seen.has(key)) continue;
+        addSessionEventIdentityKeys(seen, item.event);
         seen.add(key);
         if (seen.size > 5000) {
           // bound memory — older keys roll out

package/src/session/mentions.js

@@ -0,0 +1,130 @@
+/**
+ * Mention parsing for session events.
+ *
+ * Carter saw `@codex` and `@claude` in messages but nothing routed them —
+ * peers had no signal a message was addressed to them. Senti's daemon
+ * already handles `help_request` events and the listener already filters
+ * by `to / recipient / recipients / targetAgent / targetAgentId` (see
+ * `eventMatchesAgent` in `src/session/sync.js`); we just need to populate
+ * one of those fields when a human / agent writes `@<name>`.
+ *
+ * This module is the canonical, **deterministic**, **pure-function**
+ * mention parser. It runs at append-time (`appendToStream`) so every
+ * event flowing through the local + remote stream picks up `payload.to`
+ * for free. The web sidebar + listener can then highlight or notify
+ * without changing their own routing logic.
+ *
+ * Borrowing pattern (per the build spec — borrow, don't import):
+ *  - `eventMatchesAgent` style of multi-key recipient (we add to `to`,
+ *    which the listener already understands)
+ *  - `senti-naming.js` style of normalize-then-set (lowercase + strip
+ *    punctuation + cap length)
+ */
+
+// `@handle` is one or more identifier characters. We allow letters,
+// digits, `._-` so `@codex-1`, `@human-mrrcarter`, `@claude.verifier`
+// all work. Word boundary on the front avoids matching `you@example.com`.
+const MENTION_RE = /(?:^|[^A-Za-z0-9_.-])@([A-Za-z0-9][A-Za-z0-9._-]{0,63})/g;
+
+// Common false positives we should never surface as mentions: email-y
+// remnants and code annotations. We stop matching when the @ is preceded
+// by a non-whitespace alnum (handled by the regex), so this is just for
+// post-filter sanity.
+const RESERVED_HANDLES = new Set(["all", "everyone", "channel", "here"]);
+
+function normalizeString(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+/**
+ * Extract `@handle` mentions from a free-text string.
+ *
+ * - Returns lowercased handles.
+ * - Dedupes preserving first-seen order.
+ * - Filters reserved broadcast handles (`@all`, `@everyone`, `@channel`,
+ *   `@here`) into a separate `broadcast` array — the daemon decides
+ *   whether broadcasts should fan out or be ignored.
+ *
+ * @param {string} text
+ * @returns {{handles: string[], broadcast: string[]}}
+ */
+export function parseMentions(text) {
+  const raw = normalizeString(text);
+  if (!raw) return { handles: [], broadcast: [] };
+
+  const handles = [];
+  const broadcast = [];
+  const seenHandle = new Set();
+  const seenBroadcast = new Set();
+
+  for (const match of raw.matchAll(MENTION_RE)) {
+    const candidate = String(match[1] || "").trim().toLowerCase();
+    if (!candidate) continue;
+    if (RESERVED_HANDLES.has(candidate)) {
+      if (!seenBroadcast.has(candidate)) {
+        seenBroadcast.add(candidate);
+        broadcast.push(candidate);
+      }
+      continue;
+    }
+    if (seenHandle.has(candidate)) continue;
+    seenHandle.add(candidate);
+    handles.push(candidate);
+  }
+
+  return { handles, broadcast };
+}
+
+/**
+ * Look at an event and, if its payload carries human-readable text and
+ * doesn't already have a `to` field, populate `payload.to` from any
+ * `@<name>` mentions found in the text. Idempotent: if `to` is already
+ * set (caller-supplied), we leave it alone. The original message text
+ * is never mutated.
+ *
+ * Also surfaces the parse result on `payload.mentions = { handles, broadcast }`
+ * so dashboards can render a "this message addressed: @x, @y" badge
+ * without re-parsing.
+ *
+ * @template {object} E
+ * @param {E} event
+ * @returns {E} new event (shallow-merged) — NOT mutated in place
+ */
+export function enrichEventWithMentions(event) {
+  if (!event || typeof event !== "object" || Array.isArray(event)) return event;
+  const payload = event.payload && typeof event.payload === "object" && !Array.isArray(event.payload)
+    ? event.payload
+    : null;
+  if (!payload) return event;
+
+  // Already routed by an explicit caller — don't second-guess.
+  const hasExplicitTo =
+    Array.isArray(payload.to) ||
+    Array.isArray(payload.recipients) ||
+    typeof payload.recipient === "string" ||
+    typeof payload.targetAgent === "string" ||
+    typeof payload.targetAgentId === "string";
+
+  // We pull text from the standard fields the renderer already uses,
+  // matching the priority in `Session.tsx:payloadText`.
+  const text = normalizeString(payload.message)
+    || normalizeString(payload.text)
+    || normalizeString(payload.detail)
+    || normalizeString(payload.title);
+  if (!text) return event;
+
+  const parsed = parseMentions(text);
+  if (parsed.handles.length === 0 && parsed.broadcast.length === 0) {
+    return event;
+  }
+
+  const nextPayload = {
+    ...payload,
+    mentions: { handles: parsed.handles, broadcast: parsed.broadcast },
+  };
+  if (!hasExplicitTo && parsed.handles.length > 0) {
+    nextPayload.to = parsed.handles;
+  }
+
+  return { ...event, payload: nextPayload };
+}