sentinelayer-cli 0.30.11 → 0.30.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.30.11",
+  "version": "0.30.13",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/session.js

@@ -1712,6 +1712,47 @@ function canPublishListenerPresence(agentId) {
   );
 }
 
+const SESSION_OBSERVATION_SEVERITIES = new Set(["info", "p3", "p2", "p1", "p0"]);
+const SESSION_OBSERVATION_KINDS = new Set([
+  "ux",
+  "process",
+  "reliability",
+  "security",
+  "billing",
+  "coordination",
+  "architecture",
+  "testing",
+  "release",
+  "other",
+]);
+const SESSION_OBSERVATION_SUMMARY_MAX_LENGTH = 4_000;
+const SESSION_OBSERVATION_OPTION_MAX_LENGTH = 512;
+const SESSION_OBSERVATION_PROPOSAL_MAX_LENGTH = 2_000;
+
+function requireGrantedNonHumanAgentId(rawAgentId, commandName) {
+  const agentId = normalizeAgentId(rawAgentId, "");
+  if (!agentId || !canPublishListenerPresence(agentId)) {
+    throw new Error(`${commandName} requires a granted non-human agent id.`);
+  }
+  return agentId;
+}
+
+function normalizeSessionObservationChoice(rawValue, allowedValues, fallbackValue, fieldName) {
+  const value = normalizeString(rawValue || fallbackValue).toLowerCase();
+  if (!allowedValues.has(value)) {
+    throw new Error(`${fieldName} must be one of: ${[...allowedValues].join(", ")}.`);
+  }
+  return value;
+}
+
+function normalizeSessionObservationText(rawValue, fieldName, maxLength) {
+  const value = normalizeString(rawValue);
+  if (value.length > maxLength) {
+    throw new Error(`${fieldName} must be ${maxLength} characters or fewer.`);
+  }
+  return value;
+}
+
 function listenerLifecycleEventName(type = "") {
   const normalized = normalizeString(type).toLowerCase();
   if (normalized === "started") return "session_listener_started";
@@ -3660,6 +3701,174 @@ export function registerSessionCommand(program) {
       console.log(formatEventLine(persisted));
     });
 
+  session
+    .command("observe <sessionId> [summary...]")
+    .description("Record a durable product/process observation in the session")
+    .requiredOption("--agent <id>", "Granted non-human agent id to record the observation as")
+    .option("--model <model>", "Agent model/provider hint", "cli")
+    .option("--display-name <name>", "Human-readable agent display name")
+    .option("--role <role>", "Agent role metadata", "observer")
+    .option(
+      "--kind <kind>",
+      `Observation kind: ${[...SESSION_OBSERVATION_KINDS].join(", ")}`,
+      "process",
+    )
+    .option(
+      "--severity <level>",
+      `Observation severity: ${[...SESSION_OBSERVATION_SEVERITIES].join(", ")}`,
+      "info",
+    )
+    .option("--owner <owner>", "Suggested owner/team for follow-up")
+    .option("--batch <batch>", "Suggested PR batch or backlog lane")
+    .option("--target-sequence <n>", "Anchor the observation to a session sequence id")
+    .option("--target-cursor <cursor>", "Anchor the observation to a session event cursor")
+    .option("--proposal <text>", "Suggested remediation or next step")
+    .option("--message-file <path>", "Read the observation summary from a UTF-8 file")
+    .option("--stdin", "Read the observation summary from stdin")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, summaryParts, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const summary = normalizeSessionObservationText(
+        await resolveSessionSayMessageInput(summaryParts, options),
+        "summary",
+        SESSION_OBSERVATION_SUMMARY_MAX_LENGTH,
+      );
+      if (!summary) {
+        throw new Error("summary is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const agentId = requireGrantedNonHumanAgentId(options.agent, "observe");
+      const kind = normalizeSessionObservationChoice(
+        options.kind,
+        SESSION_OBSERVATION_KINDS,
+        "process",
+        "kind",
+      );
+      const severity = normalizeSessionObservationChoice(
+        options.severity,
+        SESSION_OBSERVATION_SEVERITIES,
+        "info",
+        "severity",
+      );
+      const owner = normalizeSessionObservationText(
+        options.owner,
+        "owner",
+        SESSION_OBSERVATION_OPTION_MAX_LENGTH,
+      );
+      const proposedBatch = normalizeSessionObservationText(
+        options.batch,
+        "batch",
+        SESSION_OBSERVATION_OPTION_MAX_LENGTH,
+      );
+      const proposal = normalizeSessionObservationText(
+        options.proposal,
+        "proposal",
+        SESSION_OBSERVATION_PROPOSAL_MAX_LENGTH,
+      );
+      const targetSequenceId = parseOptionalPositiveInteger(options.targetSequence, "target-sequence");
+      const targetCursor = normalizeSessionObservationText(
+        options.targetCursor,
+        "target-cursor",
+        SESSION_OBSERVATION_OPTION_MAX_LENGTH,
+      );
+      const localSession = await ensureLocalSessionForRemoteCommand(normalizedSessionId, {
+        targetPath,
+      });
+      const clientMessageId = `cli-observation-${randomUUID()}`;
+      const eventPayload = {
+        schema: "session_observation/v1",
+        summary,
+        message: summary,
+        kind,
+        severity,
+        channel: "session",
+        source: "session_observe",
+        clientKind: "cli",
+        clientMessageId,
+      };
+      if (owner) eventPayload.owner = owner;
+      if (proposedBatch) eventPayload.proposedBatch = proposedBatch;
+      if (proposal) eventPayload.proposal = proposal;
+      if (targetSequenceId) eventPayload.targetSequenceId = targetSequenceId;
+      if (targetCursor) eventPayload.targetCursor = targetCursor;
+
+      const agent = await resolveSessionAgentEnvelope(normalizedSessionId, agentId, {
+        targetPath,
+        model: options.model,
+        role: normalizeString(options.role) || "observer",
+        displayName: options.displayName,
+      });
+      agent.role = normalizeString(agent.role) || "observer";
+      agent.model = normalizeString(agent.model) || "cli";
+      agent.clientKind = normalizeString(agent.clientKind) || "cli";
+
+      const event = createAgentEvent({
+        event: "session_observation",
+        agent,
+        sessionId: normalizedSessionId,
+        payload: eventPayload,
+      });
+      event.eventId = clientMessageId;
+      event.idempotencyToken = clientMessageId;
+
+      const remoteConfirmationAnchor = await readSessionConfirmationAnchor(normalizedSessionId, {
+        targetPath,
+      });
+      if (!remoteConfirmationAnchor?.ok) {
+        if (remoteConfirmationAnchor?.reason === "api_403") {
+          throw new Error(
+            `Observation failed (api_403). Ensure this user has an active grant for '${agentId}'.`,
+          );
+        }
+        throw new Error(
+          `Observation confirmation anchor failed (${remoteConfirmationAnchor?.reason || "unknown"}); local cache was not updated.`,
+        );
+      }
+      const remoteSync = await syncSessionEventToApi(normalizedSessionId, event, {
+        targetPath,
+      });
+      if (!remoteSync?.synced) {
+        throw new Error(
+          `Observation failed (${remoteSync?.reason || "unknown"}). Ensure this user has an active grant for '${agentId}'.`,
+        );
+      }
+      const remoteConfirmation = await confirmSessionEventVisible(normalizedSessionId, clientMessageId, {
+        targetPath,
+        anchorCursor: remoteConfirmationAnchor?.cursor,
+      });
+      if (!remoteConfirmation?.confirmed) {
+        throw new Error(
+          `Observation was accepted but not visible in canonical session events (${remoteConfirmation?.reason || "not_visible"}); local cache was not updated.`,
+        );
+      }
+
+      const persisted = await appendToStream(normalizedSessionId, event, {
+        targetPath,
+        syncRemote: false,
+      });
+      const payload = {
+        command: "session observe",
+        targetPath,
+        sessionId: normalizedSessionId,
+        agentId,
+        event: persisted,
+        materializedLocalSession: localSession.materialized,
+        refreshedLocalSession: Boolean(localSession.refreshed),
+        remoteSync,
+        remoteConfirmationAnchor,
+        remoteConfirmation,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(formatEventLine(persisted));
+    });
+
   async function runMessageActionCommand({
     sessionId,
     actionType,

package/src/session/daemon.js

@@ -71,6 +71,7 @@ const CHECKPOINT_MEANINGFUL_EVENT_NAMES = new Set([
   "help_response",
   "session_admin_kill",
   "session_message",
+  "session_observation",
   "task_accepted",
   "task_assign",
   "task_blocked",

package/src/session/listener.js

@@ -38,6 +38,10 @@ function normalizePositiveInteger(value, fallbackValue) {
   return Math.floor(normalized);
 }
 
+function isListenerStopDirective(event = {}) {
+  return normalizeString(event?.event) === "listener_stop";
+}
+
 function isPlainObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -255,6 +259,8 @@ export async function listenSessionEvents({
   _readCursor = readSyncCursor,
   _writeCursor = writeSyncCursor,
   _sleep = defaultSleep,
+  _setInterval = setInterval,
+  _clearInterval = clearInterval,
   _nowMs = Date.now,
 } = {}) {
   const normalizedSessionId = normalizeString(sessionId);
@@ -394,6 +400,7 @@ export async function listenSessionEvents({
     const visibleEvents = [];
     let preStartEventCount = 0;
     for (const event of events) {
+      if (!isPlainObject(event)) continue;
       const timestampMs = eventTimestampMs(event);
       if (!timestampMs || timestampMs < startedAtMs) {
         preStartEventCount += 1;
@@ -402,6 +409,7 @@ export async function listenSessionEvents({
       if (isRecentActivity(activityMs, observedAtMs, activeWindowMs)) {
         lastHumanActivityMs = Math.max(lastHumanActivityMs, activityMs);
       }
+      if (timestampMs && timestampMs < startedAtMs && isListenerStopDirective(event)) continue;
       if (isSessionListenerLifecycleEvent(event)) continue;
       if (!eventMatchesAgent(event, normalizedAgentId)) continue;
       visibleEvents.push(event);
@@ -441,9 +449,14 @@ export async function listenSessionEvents({
       if (emittedKeys.has(key)) continue;
       matched += 1;
       if (!shouldEmitBatch && eventTimestampMs(event) < startedAtMs) continue;
-      await onEvent(event);
       emittedKeys.add(key);
-      emitted += 1;
+      try {
+        await onEvent(event);
+        emitted += 1;
+      } catch (error) {
+        emittedKeys.delete(key);
+        throw error;
+      }
     }
 
     if (nextCursor && nextCursor !== cursor) {
@@ -473,6 +486,32 @@ export async function listenSessionEvents({
     return humanActive;
   }
 
+  let streamHeartbeatTimer = null;
+  let streamHeartbeatInFlight = false;
+  const streamHeartbeatMs = Math.max(1_000, Math.min(idleSleepMs, 60_000));
+
+  function stopStreamHeartbeatTimer() {
+    if (!streamHeartbeatTimer) return;
+    _clearInterval(streamHeartbeatTimer);
+    streamHeartbeatTimer = null;
+  }
+
+  function startStreamHeartbeatTimer() {
+    stopStreamHeartbeatTimer();
+    streamHeartbeatTimer = _setInterval(async () => {
+      if (signal?.aborted || streamHeartbeatInFlight) return;
+      streamHeartbeatInFlight = true;
+      try {
+        await notifyHeartbeat({ nextPollMs: null });
+      } finally {
+        streamHeartbeatInFlight = false;
+      }
+    }, streamHeartbeatMs);
+    if (streamHeartbeatTimer && typeof streamHeartbeatTimer.unref === "function") {
+      streamHeartbeatTimer.unref();
+    }
+  }
+
   await notifyLifecycle(
     lifecycleSnapshot("started", {
       startedAt: new Date(startedAtMs).toISOString(),
@@ -484,6 +523,7 @@ export async function listenSessionEvents({
     if (normalizedTransport !== "poll") {
       streamAttempted = true;
       activeTransport = "stream";
+      startStreamHeartbeatTimer();
       const streamResult = await _stream(normalizedSessionId, {
         targetPath,
         since: cursor,
@@ -502,6 +542,8 @@ export async function listenSessionEvents({
         onHeartbeat: async () => {
           await notifyHeartbeat({ nextPollMs: null });
         },
+      }).finally(() => {
+        stopStreamHeartbeatTimer();
       });
       if (!streamResult?.ok) {
         streamFallbackReason = normalizeString(streamResult?.reason) || lastReason || "stream_failed";

package/src/session/preview.js

@@ -12,6 +12,7 @@ const PREVIEW_EVENTS = new Set([
   "session_message",
   "session_say",
   "agent_response",
+  "session_observation",
   "human_relay",
   "daemon_alert",
   "session_admin_kill",
@@ -45,6 +46,7 @@ export function pickLatestPreview(events = []) {
     if (!kind || !PREVIEW_EVENTS.has(kind)) continue;
     const payload = event.payload && typeof event.payload === "object" ? event.payload : {};
     const text =
+      payload.summary ||
       payload.message ||
       payload.response ||
       payload.alert ||

package/src/session/transcript.js

@@ -47,6 +47,7 @@ const TRANSCRIPT_EVENT_KINDS = new Set([
   "session_reply",
   "session_reaction",
   "session_usage",
+  "session_observation",
   "human_relay",
   "agent_join",
   "agent_left",
@@ -209,11 +210,56 @@ function actionBody(event) {
   return "";
 }
 
+function boundedMarkdownText(value, { maxLength = 2_000 } = {}) {
+  const text = normalize(value).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (!maxLength || text.length <= maxLength) return text;
+  const head = Math.max(120, Math.floor((maxLength - 3) * 0.75));
+  const tail = Math.max(40, maxLength - 3 - head);
+  return `${text.slice(0, head)}...${text.slice(-tail)}`;
+}
+
+function observationTargetLabel(payload = {}) {
+  const targetSequence = Number(payload.targetSequenceId || payload.target_sequence_id || 0);
+  if (Number.isFinite(targetSequence) && targetSequence > 0) {
+    return `#${Math.floor(targetSequence)}`;
+  }
+  const targetCursor = tableText(payload.targetCursor || payload.target_cursor, { maxLength: 96 });
+  return targetCursor ? `cursor ${targetCursor}` : "";
+}
+
+function observationBody(event) {
+  const payload = event && typeof event.payload === "object" ? event.payload : {};
+  const severity = tableText(payload.severity || "info", { maxLength: 16 }).toLowerCase();
+  const kind = tableText(payload.kind || "process", { maxLength: 32 }).toLowerCase();
+  const summary = boundedMarkdownText(payload.summary || payload.message || payload.text, {
+    maxLength: 4_000,
+  });
+  const proposal = boundedMarkdownText(payload.proposal || payload.recommendation, {
+    maxLength: 2_000,
+  });
+  const owner = tableText(payload.owner || payload.assignee, { maxLength: 96 });
+  const proposedBatch = tableText(payload.proposedBatch || payload.batch, { maxLength: 96 });
+  const target = observationTargetLabel(payload);
+  const metadata = [];
+  if (owner) metadata.push(`Owner: \`${owner}\``);
+  if (proposedBatch) metadata.push(`Batch: \`${proposedBatch}\``);
+  if (target) metadata.push(`Target: \`${target}\``);
+
+  const lines = [`**Observation:** \`${severity || "info"}\` · \`${kind || "process"}\``];
+  if (metadata.length) lines.push(metadata.join(" · "));
+  if (summary) lines.push("", summary);
+  if (proposal) lines.push("", "**Proposal:**", proposal);
+  return lines.join("\n");
+}
+
 function eventBody(event) {
   const kind = normalize(event?.event || event?.type);
   if (kind === "session_action" || kind === "session_reply" || kind === "session_reaction") {
     return actionBody(event);
   }
+  if (kind === "session_observation") {
+    return observationBody(event);
+  }
   const payload = event && typeof event.payload === "object" ? event.payload : {};
   // session_usage carries the response inside payload.response.text
   const responseText =