sentinelayer-cli 0.30.11 → 0.30.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.30.11",
+  "version": "0.30.12",
   "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/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 =