sentinelayer-cli 0.9.0 → 0.9.2

package/src/legacy-cli.js

@@ -2316,7 +2316,7 @@ jobs:
           fi
       - name: Run Omar Gate
         id: omar
-        uses: mrrCarter/sentinelayer-v1-action@55a2c158f637d7d92e26ab0ef3ba81db791da4be
+        uses: mrrCarter/sentinelayer-v1-action@b13504565105b2496c5b1dbb7a3e9bf914c2a9f8
         with:
           sentinelayer_token: \${{ secrets.${normalizedSecret} }}${specIdBindingLine}
           scan_mode: \${{ github.event_name == 'workflow_dispatch' && inputs.scan_mode || 'deep' }}

package/src/scan/generator.js

@@ -2,7 +2,7 @@ import YAML from "yaml";
 
 export const DEFAULT_SCAN_WORKFLOW_PATH = ".github/workflows/omar-gate.yml";
 export const DEFAULT_SCAN_SECRET_NAME = "SENTINELAYER_TOKEN";
-export const SENTINELAYER_ACTION_REF = "mrrCarter/sentinelayer-v1-action@55a2c158f637d7d92e26ab0ef3ba81db791da4be";
+export const SENTINELAYER_ACTION_REF = "mrrCarter/sentinelayer-v1-action@b13504565105b2496c5b1dbb7a3e9bf914c2a9f8";
 export const SUPPORTED_E2E_HINTS = Object.freeze(["auto", "yes", "no"]);
 export const SUPPORTED_PLAYWRIGHT_MODES = Object.freeze(["auto", "off", "baseline", "audit"]);
 

package/src/session/coordination-guidance.js

@@ -2,9 +2,10 @@ export const COORDINATION_GUIDANCE_TITLE = "Multi-Agent Coordination Protocol";
 
 export const COORDINATION_ETIQUETTE_ITEMS = Object.freeze([
   "Find the recent Senti session for this codebase: run `sl session list --path .` and `sl session list --remote --path .`; join the right room with `sl session join <id> --name <your-name> --role coder`.",
+  "When you have an agent grant, post agent updates with `sl session post-agent <id> \"status: <update>\" --agent <your-agent-id>` so they render as the agent, not the human relay.",
   "Before implementation, post a short plan and file claims with `sl session say <id> \"plan: <scope>; files: <paths>\"`.",
   "Claim shared files before editing with `lock: <file> - <intent>` and release them with `unlock: <file> - done`.",
-  "Run a background listener for replies: `sl session listen --session <id> --agent <your-name> --interval 60 --emit ndjson`; if background polling is unavailable, fall back to `sl session sync <id> --json` then `sl session read <id> --tail 20 --json` every 5 minutes.",
+  "Run a background listener for replies: `sl session listen --session <id> --agent <your-name> --interval 60 --active-interval 5 --emit ndjson`; this idles at 60s and switches to 5s after human activity. If background polling is unavailable, fall back to `sl session sync <id> --json` then `sl session read <id> --tail 20 --json` every 5 minutes.",
   "Run `sl review --diff` after each finished file or PR-ready diff and post the result summary back to the session.",
   "Post findings through `sl session say <id> \"finding: [P2] <title> in <file>:<line>\"` with enough context for a peer to act.",
   "Ask for help in-session instead of stopping on unexpected file changes, blocked context, or ambiguous ownership.",

package/src/session/event-identity.js

@@ -0,0 +1,139 @@
+function keyString(value) {
+  return String(value || "").trim();
+}
+
+function timestampKey(...values) {
+  for (const value of values) {
+    const normalized = keyString(value);
+    if (!normalized) continue;
+    const epoch = Date.parse(normalized);
+    if (Number.isFinite(epoch)) {
+      return new Date(epoch).toISOString();
+    }
+    return normalized;
+  }
+  return "";
+}
+
+function stableJsonValue(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => stableJsonValue(item));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entryValue]) => [key, stableJsonValue(entryValue)])
+    );
+  }
+  return value;
+}
+
+function stableStringify(value) {
+  return JSON.stringify(stableJsonValue(value));
+}
+
+export function sessionEventIdentityKeys(event = {}) {
+  if (!event || typeof event !== "object") return [];
+  const keys = [];
+  const id = keyString(event.id);
+  if (id) {
+    keys.push(`id:${id}`);
+  }
+  if (typeof event.cursor === "string" && event.cursor.trim()) {
+    keys.push(`cursor:${event.cursor.trim()}`);
+  }
+  if (typeof event.eventId === "string" && event.eventId.trim()) {
+    keys.push(`event:${event.eventId.trim()}`);
+  }
+  if (typeof event.idempotencyToken === "string" && event.idempotencyToken.trim()) {
+    keys.push(`idempotency:${event.idempotencyToken.trim()}`);
+  }
+  const payload = event.payload && typeof event.payload === "object" ? event.payload : {};
+  const messageId = typeof payload.messageId === "string" ? payload.messageId.trim() : "";
+  if (messageId) {
+    keys.push(`message:${messageId}`);
+  }
+  const timestamp = timestampKey(event.ts, event.timestamp, event.at);
+  const hasPayloadSignal = Object.keys(payload).length > 0;
+  const hasFingerprintSignal =
+    id || messageId || keyString(event.eventId) || keyString(event.idempotencyToken) ||
+    keyString(event.agent?.id || event.agentId) || timestamp || hasPayloadSignal;
+  if (hasFingerprintSignal) {
+    try {
+      keys.push(`fingerprint:${stableStringify({
+        event: event.event || event.type || "",
+        id,
+        eventId: keyString(event.eventId),
+        idempotencyToken: keyString(event.idempotencyToken),
+        agent: event.agent?.id || event.agentId || "",
+        payload,
+        ts: timestamp,
+      })}`);
+    } catch {
+      // Best-effort duplicate suppression only.
+    }
+  }
+  const message = keyString(payload.message || payload.text || payload.body);
+  if (message) {
+    try {
+      keys.push(`content:${stableStringify({
+        event: keyString(event.event || event.type),
+        agent: keyString(event.agent?.id || event.agentId || payload.agentId || payload.authorId),
+        payload: {
+          channel: keyString(payload.channel),
+          clientKind: keyString(payload.clientKind),
+          message,
+          source: keyString(payload.source),
+          to: payload.to || payload.recipient || payload.mentions || null,
+        },
+        ts: timestampKey(event.ts, event.timestamp, event.at),
+      })}`);
+    } catch {
+      // Best-effort duplicate suppression only.
+    }
+  }
+  return keys;
+}
+
+export function sessionEventHasKnownIdentity(event = {}, knownKeys = new Set()) {
+  const keys = sessionEventIdentityKeys(event);
+  return keys.length > 0 && keys.some((key) => knownKeys.has(key));
+}
+
+export function addSessionEventIdentityKeys(knownKeys, event = {}) {
+  for (const key of sessionEventIdentityKeys(event)) {
+    knownKeys.add(key);
+  }
+}
+
+export function dedupeSessionEvents(events = []) {
+  const normalizedEvents = Array.isArray(events) ? events : [];
+  const deduped = [];
+  const indexByKey = new Map();
+
+  for (const event of normalizedEvents) {
+    const keys = sessionEventIdentityKeys(event);
+    const existingIndexes = keys
+      .map((key) => indexByKey.get(key))
+      .filter((index) => Number.isInteger(index) && index >= 0);
+    const existingIndex = existingIndexes.length > 0 ? Math.min(...existingIndexes) : -1;
+
+    if (existingIndex >= 0) {
+      deduped[existingIndex] = event;
+      for (const key of keys) {
+        indexByKey.set(key, existingIndex);
+      }
+      continue;
+    }
+
+    const nextIndex = deduped.length;
+    deduped.push(event);
+    for (const key of keys) {
+      indexByKey.set(key, nextIndex);
+    }
+  }
+
+  return deduped;
+}

package/src/session/listener.js

@@ -13,6 +13,10 @@ const BROADCAST_RECIPIENTS = new Set([
   "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();
 }
@@ -127,6 +131,70 @@ function eventTimestampMs(event = {}) {
   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
@@ -138,6 +206,8 @@ export async function listenSessionEvents({
   targetPath = process.cwd(),
   agentId = "cli-user",
   intervalSeconds = 60,
+  activeIntervalSeconds = DEFAULT_ACTIVE_INTERVAL_SECONDS,
+  activeWindowSeconds = DEFAULT_ACTIVE_WINDOW_SECONDS,
   limit = 200,
   since = undefined,
   replay = false,
@@ -170,8 +240,16 @@ export async function listenSessionEvents({
   let lastReason = "";
   const maxPollCount = normalizePositiveInteger(maxPolls, 0);
   const pollLimit = normalizePositiveInteger(limit, 200);
-  const sleepMs = Math.max(1, normalizePositiveInteger(intervalSeconds, 60)) * 1000;
+  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;
@@ -184,6 +262,13 @@ export async function listenSessionEvents({
     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;
@@ -213,8 +298,12 @@ export async function listenSessionEvents({
     }
 
     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(sleepMs, { signal });
+      await _sleep(nextSleepMs, { signal });
     } catch (error) {
       if (shouldAbort(error, signal)) break;
       throw error;
@@ -231,6 +320,11 @@ export async function listenSessionEvents({
     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 };
+}