sentinelayer-cli 0.12.4 → 0.13.0

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.13.0",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/billing/llm-session-usage.js

@@ -31,6 +31,7 @@ export async function recordCliLlmSessionUsage({
   sourceCommand = "",
   provider = "",
   metadata = {},
+  syncRemote = true,
 } = {}) {
   const normalizedSessionId = normalizeString(sessionId);
   const normalizedAgentId = normalizeString(agentId);
@@ -80,7 +81,7 @@ export async function recordCliLlmSessionUsage({
           ...metadata,
         },
       },
-      { targetPath },
+      { targetPath, syncRemote },
     );
   } catch (error) {
     return {

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. Use --target-action-id <uuid> to react to a threaded reply.",
+  },
+  {
+    type: "dislike",
+    command: "sl session react <id> dislike --target-sequence <n>",
+    description: "Negative lightweight feedback. Use --target-action-id <uuid> to react to a threaded reply.",
+  },
+  {
+    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;
@@ -145,6 +190,10 @@ function actionTargetCursor(action = {}) {
   return normalizeString(action.targetCursor ?? action.target_cursor);
 }
 
+function actionTargetActionId(action = {}) {
+  return normalizeString(action.targetActionId ?? action.target_action_id);
+}
+
 function actionActorId(action = {}) {
   return normalizeString(action.actorId ?? action.actor_id) || "unknown";
 }
@@ -156,7 +205,11 @@ function actionCreatedAt(action = {}) {
 function actionDisplayMessage(action = {}) {
   const actionType = normalizeString(action.actionType ?? action.action_type).toLowerCase();
   const targetSequence = actionTargetSequence(action);
-  const targetLabel = targetSequence ? `#${targetSequence}` : actionTargetCursor(action) || "target";
+  const targetActionId = actionTargetActionId(action);
+  const parentLabel = targetSequence ? `#${targetSequence}` : actionTargetCursor(action) || "";
+  const targetLabel = targetActionId
+    ? `action:${targetActionId}${parentLabel ? ` (${parentLabel})` : ""}`
+    : parentLabel || "target";
   const note = normalizeString(action.note);
   if (note) return `${actionType} ${targetLabel}: ${note}`;
   return `${actionType} ${targetLabel}`;
@@ -172,6 +225,7 @@ function buildSessionActionEvent(sessionId, action = {}) {
         actionType,
         targetSequenceId: actionTargetSequence(action),
         targetCursor: actionTargetCursor(action),
+        targetActionId: actionTargetActionId(action),
         actorId: actionActorId(action),
         note: normalizeString(action.note),
         createdAt: actionCreatedAt(action),
@@ -192,6 +246,7 @@ function buildSessionActionEvent(sessionId, action = {}) {
       actionType,
       targetSequenceId: actionTargetSequence(action),
       targetCursor: actionTargetCursor(action) || null,
+      targetActionId: actionTargetActionId(action) || null,
       note: normalizeString(action.note) || null,
       message: actionDisplayMessage(action),
       source: "session_action",
@@ -259,10 +314,15 @@ function defaultActionIdempotencyKey({
   actionType,
   targetSequenceId,
   targetCursor,
+  targetActionId,
   note,
   agentId,
 } = {}) {
-  const target = targetSequenceId ? `seq:${targetSequenceId}` : `cursor:${normalizeString(targetCursor)}`;
+  const target = normalizeString(targetActionId)
+    ? `action:${normalizeString(targetActionId)}`
+    : targetSequenceId
+      ? `seq:${targetSequenceId}`
+      : `cursor:${normalizeString(targetCursor)}`;
   const noteHash = note ? shortSha256(note) : "none";
   const actor = normalizeString(agentId) || "user";
   return `cli:${normalizeString(actionType).toLowerCase()}:${target}:${actor}:${noteHash}`;
@@ -1768,6 +1828,7 @@ export function registerSessionCommand(program) {
     commandName = "session action",
     targetSequenceId: targetSequenceIdOverride = null,
     targetCursor: targetCursorOverride = "",
+    targetActionId: targetActionIdOverride = "",
     note: noteOverride = "",
   } = {}) {
     const normalizedSessionId = normalizeString(sessionId);
@@ -1780,8 +1841,9 @@ export function registerSessionCommand(program) {
       targetSequenceIdOverride ||
       parseOptionalPositiveInteger(options.targetSequence, "target-sequence");
     const targetCursor = normalizeString(targetCursorOverride) || normalizeString(options.targetCursor);
-    if (!targetSequenceId && !targetCursor) {
-      throw new Error("Provide --target-sequence or --target-cursor.");
+    const targetActionId = normalizeString(targetActionIdOverride) || normalizeString(options.targetActionId);
+    if (!targetSequenceId && !targetCursor && !targetActionId) {
+      throw new Error("Provide --target-sequence, --target-cursor, or --target-action-id.");
     }
     await ensureLocalSessionForRemoteCommand(normalizedSessionId, { targetPath });
     const note = normalizeString(noteOverride) || normalizeString(options.note);
@@ -1792,6 +1854,7 @@ export function registerSessionCommand(program) {
         actionType: normalizedActionType,
         targetSequenceId,
         targetCursor,
+        targetActionId,
         note,
         agentId,
       });
@@ -1801,6 +1864,7 @@ export function registerSessionCommand(program) {
       targetPath,
       targetSequenceId,
       targetCursor,
+      targetActionId,
       note,
       metadata: {
         source: "cli",
@@ -1837,11 +1901,37 @@ 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("--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("--idempotency-key <key>", "Explicit idempotency key")
@@ -1856,6 +1946,7 @@ export function registerSessionCommand(program) {
     .description("React to or acknowledge a target session event with ack, like, or dislike")
     .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("--idempotency-key <key>", "Explicit idempotency key")
     .option("--path <path>", "Workspace path for the session", ".")
@@ -1894,6 +1985,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.",
   "",

package/src/session/sync.js

@@ -1245,6 +1245,7 @@ export async function listSessionMessageActions(
   {
     targetPath = process.cwd(),
     targetSequenceId = null,
+    targetActionId = "",
     limit = SESSION_ACTION_FETCH_LIMIT,
     timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
     forceCircuitProbe = false,
@@ -1294,6 +1295,10 @@ export async function listSessionMessageActions(
   if (Number.isFinite(normalizedTargetSequence) && normalizedTargetSequence > 0) {
     query.set("targetSequenceId", String(Math.floor(normalizedTargetSequence)));
   }
+  const normalizedTargetActionId = normalizeString(targetActionId);
+  if (normalizedTargetActionId) {
+    query.set("targetActionId", normalizedTargetActionId);
+  }
   query.set(
     "limit",
     String(Math.max(1, Math.min(SESSION_ACTION_FETCH_LIMIT, normalizePositiveInteger(limit, 200))))
@@ -1351,6 +1356,7 @@ export async function createSessionMessageAction(
     targetPath = process.cwd(),
     targetSequenceId = null,
     targetCursor = "",
+    targetActionId = "",
     note = "",
     metadata = {},
     idempotencyKey = "",
@@ -1402,6 +1408,10 @@ export async function createSessionMessageAction(
   if (normalizedTargetCursor) {
     body.targetCursor = normalizedTargetCursor;
   }
+  const normalizedTargetActionId = normalizeString(targetActionId);
+  if (normalizedTargetActionId) {
+    body.targetActionId = normalizedTargetActionId;
+  }
   const normalizedNote = normalizeString(note);
   if (normalizedNote) {
     body.note = normalizedNote;

package/src/session/transcript.js

@@ -155,7 +155,63 @@ function eventTimestamp(event) {
   return normalize(event?.ts || event?.timestamp);
 }
 
+function actionTargetLabel(payload = {}) {
+  const targetActionId = normalize(payload.targetActionId || payload.target_action_id);
+  const targetSequence = Number(payload.targetSequenceId || payload.target_sequence_id || 0);
+  const targetCursor = normalize(payload.targetCursor || payload.target_cursor);
+  const parent =
+    Number.isFinite(targetSequence) && targetSequence > 0
+      ? `#${Math.floor(targetSequence)}`
+      : targetCursor
+        ? `cursor ${targetCursor}`
+        : "";
+  if (targetActionId) {
+    return parent ? `reply action ${targetActionId} under ${parent}` : `reply action ${targetActionId}`;
+  }
+  return parent || "target";
+}
+
+function actionBody(event) {
+  const payload = event && typeof event.payload === "object" ? event.payload : {};
+  const kind = normalize(event?.event || event?.type);
+  const actionType = normalize(payload.actionType || payload.action_type || kind.replace(/^session_/, ""));
+  const target = actionTargetLabel(payload);
+  const actionId = normalize(payload.actionId || payload.action_id);
+  const note = normalize(payload.note);
+  const metadata = [];
+  if (actionId) metadata.push(`Action ID: \`${actionId}\``);
+  if (actionType) metadata.push(`Action: \`${actionType}\``);
+  if (kind === "session_reply") {
+    return [
+      `**Reply to:** \`${target}\``,
+      ...metadata,
+      note ? "" : null,
+      note || normalize(payload.message),
+    ].filter((line) => line !== null && line !== "").join("\n");
+  }
+  if (kind === "session_reaction") {
+    return [
+      `**Reaction:** \`${actionType || "reaction"}\` on \`${target}\``,
+      ...metadata,
+      note ? `Note: ${note}` : null,
+    ].filter(Boolean).join("\n");
+  }
+  if (kind === "session_action") {
+    return [
+      `**Session action:** \`${actionType || "action"}\` on \`${target}\``,
+      ...metadata,
+      note ? "" : null,
+      note,
+    ].filter((line) => line !== null && line !== "").join("\n");
+  }
+  return "";
+}
+
 function eventBody(event) {
+  const kind = normalize(event?.event || event?.type);
+  if (kind === "session_action" || kind === "session_reply" || kind === "session_reaction") {
+    return actionBody(event);
+  }
   const payload = event && typeof event.payload === "object" ? event.payload : {};
   // session_usage carries the response inside payload.response.text
   const responseText =