sentinelayer-cli 0.12.4 → 0.12.5

package/README.md

@@ -104,6 +104,7 @@ Inputs for non-interactive mode:
 Sentinelayer includes a deterministic session coordination surface for multi-agent coding loops:
 
 - session event stream and replay (`start`, `join`, `say`, `read`, `status`, `leave`, `list`, `kill`)
+- low-noise message actions (`react ack|like|dislike`, `action working_on|disregard`, `reply`/`comment`, `view`, `actions`)
 - agent lifecycle controls (join/heartbeat/leave/kill)
 - recap and context briefing for late-joining agents
 - analytics + lineage artifacts at session closeout

package/package.json

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

package/src/commands/session.js

@@ -107,13 +107,58 @@ const SESSION_MESSAGE_ACTION_TYPES = new Set([
   "like",
   "dislike",
   "disregard",
+  "view",
+]);
+
+const SESSION_MESSAGE_ACTION_ALIASES = new Map([
+  ["comment", "reply"],
+]);
+
+const SESSION_MESSAGE_ACTION_DESCRIPTIONS = Object.freeze([
+  {
+    type: "ack",
+    command: "sl session react <id> ack --target-sequence <n>",
+    description: "Acknowledge that you read a message without adding a top-level post.",
+  },
+  {
+    type: "working_on",
+    command: "sl session action <id> working_on --target-sequence <n> --note \"scope\"",
+    description: "Claim active ownership of a target message or task.",
+  },
+  {
+    type: "reply",
+    alias: "comment",
+    command: "sl session reply <id> <sequence> \"message\"",
+    description: "Thread a substantive response under a specific message.",
+  },
+  {
+    type: "like",
+    command: "sl session react <id> like --target-sequence <n>",
+    description: "Positive lightweight feedback.",
+  },
+  {
+    type: "dislike",
+    command: "sl session react <id> dislike --target-sequence <n>",
+    description: "Negative lightweight feedback.",
+  },
+  {
+    type: "disregard",
+    command: "sl session action <id> disregard --target-sequence <n>",
+    description: "Mark a message as intentionally ignored or superseded.",
+  },
+  {
+    type: "view",
+    command: "sl session view <id> <sequence>",
+    description: "Record a read receipt for a target message.",
+  },
 ]);
 
 function normalizeSessionMessageActionType(value) {
-  const normalized = normalizeString(value).toLowerCase();
+  const raw = normalizeString(value).toLowerCase();
+  const normalized = SESSION_MESSAGE_ACTION_ALIASES.get(raw) || raw;
   if (!SESSION_MESSAGE_ACTION_TYPES.has(normalized)) {
     throw new Error(
-      `action type must be one of: ${[...SESSION_MESSAGE_ACTION_TYPES].join(", ")}.`,
+      `action type must be one of: ${[...SESSION_MESSAGE_ACTION_TYPES].join(", ")}; aliases: comment=reply.`,
     );
   }
   return normalized;
@@ -1837,9 +1882,34 @@ export function registerSessionCommand(program) {
     return payload;
   }
 
+  session
+    .command("actions")
+    .description("List supported low-noise message actions with examples")
+    .option("--json", "Emit machine-readable output")
+    .action((options, command) => {
+      const payload = {
+        command: "session actions",
+        actions: SESSION_MESSAGE_ACTION_DESCRIPTIONS,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return payload;
+      }
+      console.log(pc.bold("Supported session message actions"));
+      for (const action of SESSION_MESSAGE_ACTION_DESCRIPTIONS) {
+        const alias = action.alias ? ` (alias: ${action.alias})` : "";
+        console.log(`${pc.cyan(action.type)}${alias}`);
+        console.log(`  ${action.description}`);
+        console.log(pc.gray(`  ${action.command}`));
+      }
+      return payload;
+    });
+
   session
     .command("action <sessionId> <actionType>")
-    .description("Create a message action for a target session event")
+    .description(
+      "Create a message action for a target session event (ack, working_on, reply/comment, like, dislike, disregard, view)",
+    )
     .option("--target-sequence <n>", "Target event sequence id")
     .option("--target-cursor <cursor>", "Target event cursor")
     .option("--note <text>", "Optional action note or reply body")
@@ -1894,6 +1964,44 @@ 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("--idempotency-key <key>", "Explicit idempotency key")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, targetSequenceId, messageParts, options, command) => {
+      const message = Array.isArray(messageParts) ? messageParts.join(" ") : messageParts;
+      await runMessageActionCommand({
+        sessionId,
+        actionType: "reply",
+        options,
+        command,
+        commandName: "session comment",
+        targetSequenceId: parsePositiveInteger(targetSequenceId, "targetSequenceId", 0),
+        note: message,
+      });
+    });
+
+  session
+    .command("view <sessionId> <targetSequenceId>")
+    .description("Record a read receipt for a target session event")
+    .option("--agent <id>", "Agent id for local idempotency metadata", "cli-user")
+    .option("--idempotency-key <key>", "Explicit idempotency key")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, targetSequenceId, options, command) => {
+      await runMessageActionCommand({
+        sessionId,
+        actionType: "view",
+        options,
+        command,
+        commandName: "session view",
+        targetSequenceId: parsePositiveInteger(targetSequenceId, "targetSequenceId", 0),
+      });
+    });
+
   session
     .command("listen")
     .description("Background-poll a session for events addressed to this agent or broadcast")

package/src/legacy-cli.js

@@ -218,6 +218,12 @@ function printUsage() {
   console.log("  sl session say <id> \"assign: @agent <task>\"  Create task assignment + lease");
   console.log("  sl session say <id> \"assign: @*:reviewer <task>\"  Wildcard route to least-busy role");
   console.log("  sl session say <id> \"accepted: task <task-id>\" / \"done: task <task-id>\"  Task transitions");
+  console.log("  sl session actions                  List low-noise actions and examples");
+  console.log("  sl session react <id> ack --target-sequence <n>  ACK/like/dislike without a new post");
+  console.log("  sl session action <id> working_on --target-sequence <n>  Claim work on a message");
+  console.log("  sl session reply <id> <seq> \"msg\"  Thread a response under a message");
+  console.log("  sl session comment <id> <seq> \"msg\"  Alias for threaded reply");
+  console.log("  sl session view <id> <seq>          Record a read receipt");
   console.log("  sl session read <id> --tail 20     Read session stream events");
   console.log("  sl session status <id> --json      Show session health, agents, runs, leases");
   console.log("  sl session leave <id>              Leave a session");

package/src/session/coordination-guidance.js

@@ -6,7 +6,7 @@ export const COORDINATION_ETIQUETTE_ITEMS = Object.freeze([
   "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 --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.",
-  "Use message actions for low-noise coordination: `sl session react <id> ack --target-sequence <n>` for ACKs, `sl session action <id> working_on --target-sequence <n>` for ownership, and `sl session reply <id> <sequence> \"<message>\"` or `sl session say <id> \"<message>\" --reply-to <sequence>` for threaded responses.",
+  "Use message actions for low-noise coordination before posting a new top-level message: `sl session react <id> ack --target-sequence <n>` for ACKs, `sl session action <id> working_on --target-sequence <n>` for ownership, `sl session view <id> <sequence>` for read receipts, and `sl session reply <id> <sequence> \"<message>\"` / `sl session comment <id> <sequence> \"<message>\"` for threaded responses. Run `sl session actions` to list all action types.",
   "Search before asking peers to restate context: `sl session search <id> \"<topic>\" --limit 10`.",
   "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.",

package/src/session/recap.js

@@ -418,7 +418,7 @@ const AGENT_JOIN_RULES = [
   "",
   "**Writing back** — You can use **markdown**: bold, italic, lists, fenced code, and `inline code`. The web dashboard renders it. Plain text also works. Keep posts terse and technical — link to the work, don't recap it.",
   "",
-  "**Actions and threading** — ACK or claim work with message actions instead of top-level chatter: `sl session react <id> ack --target-sequence <n>` or `sl session action <id> working_on --target-sequence <n>`. Reply to a specific message with `sl session reply <id> <sequence> \"<message>\"` or `sl session say <id> \"<message>\" --reply-to <sequence>`; only start a new top-level post for a new topic.",
+  "**Actions and threading** — ACK, view, react, or claim work with message actions instead of top-level chatter: `sl session react <id> ack --target-sequence <n>`, `sl session view <id> <sequence>`, or `sl session action <id> working_on --target-sequence <n>`. Reply to a specific message with `sl session reply <id> <sequence> \"<message>\"`, `sl session comment <id> <sequence> \"<message>\"`, or `sl session say <id> \"<message>\" --reply-to <sequence>`; only start a new top-level post for a new topic. Run `sl session actions` for the full list.",
   "",
   "**Search before asking** — Use `sl session search <id> \"<topic>\" --limit 10` to recover old context before asking another agent to re-paste or summarize what is already in the transcript.",
   "",