sentinelayer-cli 0.20.0 → 0.21.0

package/package.json

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

package/src/commands/session.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import process from "node:process";
 import { setTimeout as sleep } from "node:timers/promises";
 import { createHash, randomUUID } from "node:crypto";
+import { spawn as defaultSpawn } from "node:child_process";
 
 import pc from "picocolors";
 
@@ -63,6 +64,7 @@ import {
 import { readSessionPreview } from "../session/preview.js";
 import {
   createSessionMessageAction,
+  fetchSessionPinnedMessages,
   listSessionMessageActions,
   listSessionsFromApi,
   probeSessionAccess,
@@ -1537,6 +1539,102 @@ export function shouldBlockImplicitCliUserSessionSay(identity = {}) {
   return identity?.source === "fallback" && normalizeString(identity?.agentId) === "cli-user";
 }
 
+/**
+ * Wake hook for `session listen --wake "<command>"`. This is the reusable
+ * notify->resume bridge: when the listener emits an event addressed to this
+ * agent (or broadcast — including low-noise actions like ack/like), it runs a
+ * host command so the host can resume/wake its agent. The event JSON is piped
+ * to the command's stdin and key fields are exposed as SL_WAKE_* env vars.
+ *
+ * Bursts are coalesced: if a wake is already running, the latest event is
+ * queued and fired once when the current one finishes, so a flood of activity
+ * triggers one trailing wake instead of a storm of processes.
+ */
+export function createSessionWakeRunner({
+  command,
+  sessionId,
+  agentId,
+  emit = () => {},
+  spawnImpl = defaultSpawn,
+} = {}) {
+  const wakeCommand = normalizeString(command);
+  let busy = false;
+  let pending = null;
+
+  const run = (event) => {
+    if (!wakeCommand) return;
+    if (busy) {
+      pending = event ?? {};
+      return;
+    }
+    busy = true;
+    const env = {
+      ...process.env,
+      SL_WAKE_SESSION_ID: normalizeString(sessionId),
+      SL_WAKE_AGENT_ID: normalizeString(agentId),
+      SL_WAKE_EVENT_TYPE: normalizeString(event?.event),
+      SL_WAKE_EVENT_CURSOR: normalizeString(event?.cursor),
+      SL_WAKE_EVENT_SEQUENCE: String(event?.sequenceId ?? event?.sequence_id ?? ""),
+      SL_WAKE_ACTOR_ID: normalizeString(event?.agent?.id || event?.agentId),
+    };
+    let child;
+    try {
+      child = spawnImpl(wakeCommand, { shell: true, env, stdio: ["pipe", "ignore", "ignore"] });
+    } catch (error) {
+      busy = false;
+      emit({ status: "error", reason: normalizeString(error?.message) || "spawn_failed" });
+      return;
+    }
+    emit({
+      status: "fired",
+      eventType: env.SL_WAKE_EVENT_TYPE,
+      cursor: env.SL_WAKE_EVENT_CURSOR,
+      actorId: env.SL_WAKE_ACTOR_ID,
+    });
+    try {
+      if (child && child.stdin) {
+        child.stdin.write(JSON.stringify(event ?? {}));
+        child.stdin.end();
+      }
+    } catch {
+      // Broken pipe (command ignored stdin) is non-fatal for a wake hook.
+    }
+    const finish = (reason) => {
+      busy = false;
+      if (reason) emit({ status: "error", reason });
+      const next = pending;
+      pending = null;
+      if (next !== null) run(next);
+    };
+    if (child && typeof child.on === "function") {
+      child.on("error", (error) => finish(normalizeString(error?.message) || "wake_failed"));
+      child.on("exit", (code) => finish(code && code !== 0 ? `exit_${code}` : ""));
+    } else {
+      finish("");
+    }
+  };
+
+  return { trigger: run, hasCommand: Boolean(wakeCommand) };
+}
+
+// Message actions (ack/like/dislike/reply/view/working_on) must be authored by
+// a concrete agent identity. The CLI's bare `cli-user` default is a reserved
+// label the API rejects (api_422), so treat it as "unset" and resolve the real
+// agent the same way `session say` does (explicit --agent > SENTINELAYER_AGENT_ID
+// > the single joined agent). Returns the resolved identity; callers should use
+// shouldBlockImplicitCliUserSessionSay() to refuse the implicit cli-user
+// fallback before sending a request that is guaranteed to fail.
+export async function resolveMessageActionIdentity({
+  sessionId,
+  optionAgent = "",
+  targetPath = process.cwd(),
+  env = process.env,
+} = {}) {
+  const explicit = normalizeString(optionAgent);
+  const agentSeed = explicit && explicit.toLowerCase() !== "cli-user" ? explicit : "";
+  return resolveSessionSayIdentity({ sessionId, agentId: agentSeed, targetPath, env });
+}
+
 async function ensureSessionSayAgentRegistered(
   sessionId,
   agent = {},
@@ -2879,7 +2977,23 @@ export function registerSessionCommand(program) {
     }
     await ensureLocalSessionForRemoteCommand(normalizedSessionId, { targetPath });
     const note = normalizeString(noteOverride) || normalizeString(options.note);
-    const agentId = await defaultAgentId(options.agent, targetPath);
+    // Resolve the authoring agent. The bare `cli-user` default is rejected by
+    // the API (api_422); resolveMessageActionIdentity treats it as unset and
+    // falls back to the joined agent. If no concrete identity resolves, fail
+    // with actionable guidance instead of firing a request guaranteed to 422.
+    const identity = await resolveMessageActionIdentity({
+      sessionId: normalizedSessionId,
+      optionAgent: options.agent,
+      targetPath,
+      env: process.env,
+    });
+    if (shouldBlockImplicitCliUserSessionSay(identity)) {
+      throw new Error(
+        identity.identityWarning ||
+          `${commandName} requires an agent identity; pass --agent <id>, set SENTINELAYER_AGENT_ID, or run session join --agent <id> first.`,
+      );
+    }
+    const agentId = identity.agentId;
     const idempotencyKey =
       normalizeString(options.idempotencyKey) ||
       defaultActionIdempotencyKey({
@@ -2970,7 +3084,7 @@ export function registerSessionCommand(program) {
     .option("--target-cursor <cursor>", "Target event cursor")
     .option("--target-action-id <uuid>", "Target a threaded reply/action by action UUID")
     .option("--note <text>", "Optional action note or reply body")
-    .option("--agent <id>", "Agent id for local idempotency metadata", "cli-user")
+    .option("--agent <id>", "Agent id authoring the action (defaults to the joined session agent)")
     .option("--idempotency-key <key>", "Explicit idempotency key")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
@@ -2984,7 +3098,7 @@ export function registerSessionCommand(program) {
     .option("--target-sequence <n>", "Target event sequence id")
     .option("--target-cursor <cursor>", "Target event cursor")
     .option("--target-action-id <uuid>", "Target a threaded reply/action by action UUID")
-    .option("--agent <id>", "Agent id for local idempotency metadata", "cli-user")
+    .option("--agent <id>", "Agent id authoring the action (defaults to the joined session agent)")
     .option("--idempotency-key <key>", "Explicit idempotency key")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
@@ -3005,7 +3119,7 @@ export function registerSessionCommand(program) {
   session
     .command("reply <sessionId> <targetSequenceId> <message...>")
     .description("Reply to a target session event using the message-action channel")
-    .option("--agent <id>", "Agent id for local idempotency metadata", "cli-user")
+    .option("--agent <id>", "Agent id authoring the action (defaults to the joined session agent)")
     .option("--idempotency-key <key>", "Explicit idempotency key")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
@@ -3025,7 +3139,7 @@ export function registerSessionCommand(program) {
   session
     .command("comment <sessionId> <targetSequenceId> <message...>")
     .description("Alias for `session reply`; add a threaded comment to a target event")
-    .option("--agent <id>", "Agent id for local idempotency metadata", "cli-user")
+    .option("--agent <id>", "Agent id authoring the action (defaults to the joined session agent)")
     .option("--idempotency-key <key>", "Explicit idempotency key")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
@@ -3045,7 +3159,7 @@ export function registerSessionCommand(program) {
   session
     .command("view <sessionId> <targetSequenceId>")
     .description("Manually backfill a read receipt for a target session event")
-    .option("--agent <id>", "Agent id for local idempotency metadata", "cli-user")
+    .option("--agent <id>", "Agent id authoring the action (defaults to the joined session agent)")
     .option("--idempotency-key <key>", "Explicit idempotency key")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
@@ -3060,6 +3174,57 @@ export function registerSessionCommand(program) {
       });
     });
 
+  session
+    .command("pins <sessionId>")
+    .description("List the session's pinned messages with their content so agents can read them")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      await ensureLocalSessionForRemoteCommand(normalizedSessionId, { targetPath });
+      const result = await fetchSessionPinnedMessages(normalizedSessionId, { targetPath });
+      if (!result.ok) {
+        throw new Error(`Could not load pinned messages (${result.reason || "unknown"}).`);
+      }
+      const pinLimit = result.pinLimit || 10;
+      const payload = {
+        command: "session pins",
+        sessionId: normalizedSessionId,
+        pinLimit,
+        count: result.count,
+        pins: result.pins,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return payload;
+      }
+      if (!result.count) {
+        console.log(pc.gray("No pinned messages in this session."));
+        return payload;
+      }
+      console.log(pc.bold(`📌 Pinned messages (${result.count}/${pinLimit})`));
+      for (const pin of result.pins) {
+        const seqLabel = pin.targetSequenceId ? `#${pin.targetSequenceId}` : "(unknown sequence)";
+        const author = pin.author || "unknown";
+        const pinnedBy = pin.pinnedBy ? ` · pinned by ${pin.pinnedBy}` : "";
+        const when = pin.pinnedAt ? ` · ${pin.pinnedAt}` : "";
+        console.log("");
+        console.log(pc.cyan(`${seqLabel}  ${author}${pinnedBy}${when}`));
+        if (pin.content) {
+          for (const line of String(pin.content).split("\n")) {
+            console.log(`  ${line}`);
+          }
+        } else {
+          console.log(pc.gray("  (no readable text content for this pinned event)"));
+        }
+      }
+      return payload;
+    });
+
   session
     .command("listen")
     .description("Background-poll a session for events addressed to this agent or broadcast")
@@ -3103,6 +3268,10 @@ export function registerSessionCommand(program) {
     .option("--from-now", "Advance the listen cursor to the latest durable event before polling")
     .option("--replay", "Emit matching historical events on the first poll")
     .option("--max-polls <n>", "Stop after N poll cycles (useful for tests and smoke checks)")
+    .option(
+      "--wake <command>",
+      "Wake hook: run this shell command on each matched event (notify->resume bridge). Event JSON is piped to stdin; SL_WAKE_* env vars are set.",
+    )
     .action(async (options) => {
       const normalizedSessionId = resolveSessionIdOption(options);
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
@@ -3126,6 +3295,32 @@ export function registerSessionCommand(program) {
       if (!["ndjson", "text"].includes(emitFormat)) {
         throw new Error("--emit must be one of: ndjson, text.");
       }
+      // Optional wake hook: run a host command on each matched event so the
+      // host can resume/wake its agent (the notify->resume bridge).
+      const emitWakeNotice = (payload = {}) => {
+        if (emitFormat === "ndjson") {
+          console.log(
+            JSON.stringify(
+              createAgentEvent({
+                event: "session_wake_hook",
+                agentId,
+                sessionId: normalizedSessionId,
+                payload,
+              }),
+            ),
+          );
+        } else {
+          const status = normalizeString(payload.status) || "fired";
+          const detail = payload.reason ? ` (${payload.reason})` : payload.eventType ? ` ${payload.eventType}` : "";
+          console.log(pc.cyan(`wake hook ${status}${detail}`));
+        }
+      };
+      const wakeRunner = createSessionWakeRunner({
+        command: options.wake,
+        sessionId: normalizedSessionId,
+        agentId,
+        emit: emitWakeNotice,
+      });
       const requestedTransport = normalizeString(options.transport).toLowerCase() || "auto";
       if (!["auto", "stream", "poll"].includes(requestedTransport)) {
         throw new Error("--transport must be one of: auto, stream, poll.");
@@ -3214,6 +3409,9 @@ export function registerSessionCommand(program) {
             } else {
               console.log(formatEventLine(event));
             }
+            // Fire the wake hook for any matched event (incl. ack/like) so the
+            // host can resume its agent.
+            wakeRunner.trigger(event);
           },
           onError: async (result) => {
             const reason = normalizeString(result?.reason) || "poll_failed";

package/src/legacy-cli.js

@@ -226,6 +226,8 @@ function printUsage() {
   console.log("  sl session comment <id> <seq> \"msg\"  Alias for threaded reply");
   console.log("  sl session read <id> --remote --agent <id>  Read stream events and auto-record views");
   console.log("  sl session view <id> <seq>          Manually backfill a read receipt");
+  console.log("  sl session pins <id> --json         List pinned messages with content (readable by agents)");
+  console.log("  sl session listen --session <id> --agent <id>  Background-poll a session for new events");
   console.log("  sl session recap now <id> --remote --json  Summarize current owners, locks, and work");
   console.log("  sl session daemon --session <id>    Run Senti recaps/checkpoints for long rooms");
   console.log("  sl session read <id> --tail 20      Read local session stream events");

package/src/session/sync.js

@@ -1643,6 +1643,123 @@ export async function listSessionMessageActions(
   }
 }
 
+function pinnedEventContentText(event = {}) {
+  const payload = event && typeof event === "object" ? event.payload || {} : {};
+  return (
+    normalizeString(payload.note) ||
+    normalizeString(payload.message) ||
+    normalizeString(payload.text) ||
+    normalizeString(payload.content) ||
+    normalizeString(payload.summary) ||
+    ""
+  );
+}
+
+function pinnedEventAuthorId(event = {}) {
+  const agent = event && typeof event === "object" ? event.agent || {} : {};
+  return normalizeString(agent.id || agent.agentId) || normalizeString(event.agentId) || "";
+}
+
+/**
+ * Resolve the session's active pinned messages, enriched with each pinned
+ * message's author and content so a CLI agent can actually read them (not just
+ * see sequence numbers). Pins come from the action projection
+ * (`projection.pinnedMessages`, capped at `projection.pinLimit`); content is
+ * resolved per pinned sequence via `/events/before`. Bounded by the pin cap
+ * (<= 10), so at most ~10 single-event lookups.
+ */
+export async function fetchSessionPinnedMessages(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    resolveAuthSession = resolveActiveAuthSession,
+    fetchImpl = fetchWithTimeout,
+    nowMs = Date.now,
+    listActions = listSessionMessageActions,
+    fetchEventsBefore = pollSessionEventsBefore,
+  } = {}
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return { ok: false, reason: "invalid_session_id", pins: [], pinLimit: 0, count: 0 };
+  }
+
+  const actionsResult = await listActions(normalizedSessionId, {
+    targetPath,
+    timeoutMs,
+    resolveAuthSession,
+    fetchImpl,
+    nowMs,
+  });
+  if (!actionsResult || !actionsResult.ok) {
+    return {
+      ok: false,
+      reason: normalizeString(actionsResult?.reason) || "actions_read_failed",
+      pins: [],
+      pinLimit: 0,
+      count: 0,
+    };
+  }
+
+  const projection = actionsResult.projection && typeof actionsResult.projection === "object"
+    ? actionsResult.projection
+    : {};
+  const pinLimit = Number(projection.pinLimit) || 0;
+  const pinnedActions = Array.isArray(projection.pinnedMessages) ? projection.pinnedMessages : [];
+
+  const pins = await Promise.all(
+    pinnedActions.map(async (action) => {
+      const targetSequenceId = Number(action?.targetSequenceId) || 0;
+      const base = {
+        targetSequenceId,
+        targetCursor: normalizeString(action?.targetCursor) || null,
+        pinnedBy: normalizeString(action?.actorId) || "",
+        pinnedByKind: normalizeString(action?.actorKind) || "",
+        pinnedAt: normalizeString(action?.createdAt) || "",
+        author: "",
+        content: "",
+        resolved: false,
+      };
+      if (targetSequenceId <= 0) {
+        return base;
+      }
+      const eventsResult = await fetchEventsBefore(normalizedSessionId, {
+        targetPath,
+        beforeSequence: targetSequenceId + 1,
+        limit: 1,
+        timeoutMs,
+        resolveAuthSession,
+        fetchImpl,
+        nowMs,
+      });
+      if (eventsResult && eventsResult.ok && Array.isArray(eventsResult.events)) {
+        const match =
+          eventsResult.events.find(
+            (event) => Number(event?.sequenceId) === targetSequenceId,
+          ) ||
+          eventsResult.events[eventsResult.events.length - 1] ||
+          null;
+        if (match) {
+          base.author = pinnedEventAuthorId(match);
+          base.content = pinnedEventContentText(match);
+          base.resolved = true;
+        }
+      }
+      return base;
+    }),
+  );
+
+  return {
+    ok: true,
+    reason: "",
+    sessionId: normalizedSessionId,
+    pins,
+    pinLimit,
+    count: pins.length,
+  };
+}
+
 export async function createSessionMessageAction(
   sessionId,
   {