sentinelayer-cli 0.12.3 → 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.3",
+  "version": "0.12.5",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/billing/ledger-entry.js

@@ -7,7 +7,10 @@ export const PRICED_ACTIONS = Object.freeze([
   "audit_run",
   "audit_security",
   "audit_frontend",
+  "chat_ask",
   "omargate_deep",
+  "scan_precheck",
+  "spec_generate_ai",
 ]);
 
 const OMIT_METADATA_KEYS = new Set([

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

@@ -0,0 +1,91 @@
+import { buildBillingRunId, buildCallIdempotencyKey, stableHash } from "./ledger-entry.js";
+import { recordSessionUsage } from "./session-usage.js";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function nonNegativeInteger(value) {
+  const parsed = Number(value || 0);
+  if (!Number.isFinite(parsed) || parsed < 0) return 0;
+  return Math.floor(parsed);
+}
+
+export function usageNumber(value, fallback = 0) {
+  const parsed = Number(value);
+  if (Number.isFinite(parsed) && parsed >= 0) return parsed;
+  const parsedFallback = Number(fallback || 0);
+  return Number.isFinite(parsedFallback) && parsedFallback >= 0 ? parsedFallback : 0;
+}
+
+export async function recordCliLlmSessionUsage({
+  sessionId,
+  agentId,
+  action,
+  model,
+  inputTokens = 0,
+  outputTokens = 0,
+  startedAtIso = "",
+  targetPath,
+  billingTier = "internal",
+  sourceCommand = "",
+  provider = "",
+  metadata = {},
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedAgentId = normalizeString(agentId);
+  const normalizedAction = normalizeString(action);
+  const normalizedModel = normalizeString(model);
+  const createdAt = normalizeString(startedAtIso) || new Date().toISOString();
+  const safeInputTokens = nonNegativeInteger(inputTokens);
+  const safeOutputTokens = nonNegativeInteger(outputTokens);
+
+  if (!normalizedSessionId || !normalizedAgentId || !normalizedAction || !normalizedModel) {
+    return { ok: false, reason: "missing_session_usage_fields" };
+  }
+  if (safeInputTokens + safeOutputTokens <= 0) {
+    return { ok: false, reason: "zero_tokens" };
+  }
+
+  try {
+    const configHash = stableHash(
+      JSON.stringify({
+        action: normalizedAction,
+        agentId: normalizedAgentId,
+        model: normalizedModel,
+        provider: normalizeString(provider),
+        sourceCommand: normalizeString(sourceCommand),
+        metadata,
+      }),
+    );
+    const billingRunId = buildBillingRunId({
+      sessionId: normalizedSessionId,
+      invocationTimestamp: createdAt,
+      configHash,
+    });
+    return await recordSessionUsage(
+      normalizedSessionId,
+      {
+        agentId: normalizedAgentId,
+        action: normalizedAction,
+        model: normalizedModel,
+        inputTokens: safeInputTokens,
+        outputTokens: safeOutputTokens,
+        idempotencyKey: buildCallIdempotencyKey({ runId: billingRunId, callIndex: 0 }),
+        billingTier,
+        createdAt,
+        metadata: {
+          sourceCommand,
+          provider,
+          ...metadata,
+        },
+      },
+      { targetPath },
+    );
+  } catch (error) {
+    return {
+      ok: false,
+      reason: error instanceof Error ? error.message : String(error || "session_usage_failed"),
+    };
+  }
+}

package/src/commands/chat.js

@@ -9,7 +9,9 @@ import {
   resolveModel,
   resolveProvider,
 } from "../ai/client.js";
+import { recordCliLlmSessionUsage, usageNumber } from "../billing/llm-session-usage.js";
 import { resolveOutputRoot } from "../config/service.js";
+import { estimateModelCost } from "../cost/tracker.js";
 import { estimateTokens } from "../cost/tokenizer.js";
 
 function shouldEmitJson(options, command) {
@@ -92,7 +94,9 @@ export function registerChatCommand(program) {
       });
 
       const startedAt = Date.now();
+      const startedAtIso = new Date(startedAt).toISOString();
       let responseText = "";
+      let invocation = null;
 
       if (options.dryRun) {
         responseText = `DRY_RUN_RESPONSE: ${prompt.slice(0, 240)}`;
@@ -100,7 +104,7 @@ export function registerChatCommand(program) {
         const streamEnabled = Boolean(options.stream);
         let streamedText = "";
         const client = createMultiProviderApiClient();
-        const invocation = await client.invoke({
+        invocation = await client.invoke({
           provider,
           model,
           prompt,
@@ -125,8 +129,31 @@ export function registerChatCommand(program) {
 
       const durationMs = Date.now() - startedAt;
       const generatedAt = new Date().toISOString();
-      const inputTokens = estimateTokens(prompt, { model });
-      const outputTokens = estimateTokens(responseText, { model });
+      const estimatedInputTokens = estimateTokens(prompt, { model });
+      const estimatedOutputTokens = estimateTokens(responseText, { model });
+      const inputTokens = usageNumber(invocation?.usage?.inputTokens, estimatedInputTokens);
+      const outputTokens = usageNumber(invocation?.usage?.outputTokens, estimatedOutputTokens);
+      const modelCost = estimateModelCost({ modelId: invocation?.model || model, inputTokens, outputTokens });
+      const costUsd = usageNumber(invocation?.usage?.costUsd, modelCost.costUsd);
+
+      const sessionUsageLedger = options.dryRun
+        ? { ok: false, reason: "dry_run" }
+        : await recordCliLlmSessionUsage({
+            sessionId,
+            agentId: "chat-cli",
+            action: "chat_ask",
+            model: invocation?.model || model,
+            inputTokens,
+            outputTokens,
+            startedAtIso,
+            targetPath,
+            sourceCommand: "chat ask",
+            provider: invocation?.provider || provider,
+            metadata: {
+              streamed: Boolean(options.stream),
+              pricingFound: modelCost.pricingFound,
+            },
+          });
 
       await appendTranscriptEntries({
         transcriptPath,
@@ -154,8 +181,8 @@ export function registerChatCommand(program) {
       const payload = {
         command: "chat ask",
         sessionId,
-        provider,
-        model,
+        provider: invocation?.provider || provider,
+        model: invocation?.model || model,
         dryRun: Boolean(options.dryRun),
         streamed: Boolean(options.stream),
         transcriptPath,
@@ -165,8 +192,10 @@ export function registerChatCommand(program) {
           inputTokens,
           outputTokens,
           totalTokens: inputTokens + outputTokens,
+          costUsd,
           durationMs,
         },
+        billing: sessionUsageLedger,
       };
 
       if (emitJson) {
@@ -179,6 +208,6 @@ export function registerChatCommand(program) {
       }
       console.log(pc.gray(`session: ${sessionId}`));
       console.log(pc.gray(`transcript: ${transcriptPath}`));
-      console.log(pc.gray(`usage: input=${inputTokens} output=${outputTokens} duration_ms=${durationMs}`));
+      console.log(pc.gray(`usage: input=${inputTokens} output=${outputTokens} cost_usd=${costUsd.toFixed(6)} duration_ms=${durationMs}`));
     });
 }

package/src/commands/scan.js

@@ -11,6 +11,7 @@ import {
   resolveModel,
   resolveProvider,
 } from "../ai/client.js";
+import { recordCliLlmSessionUsage, usageNumber } from "../billing/llm-session-usage.js";
 import { loadConfig, resolveOutputRoot } from "../config/service.js";
 import { evaluateBudget } from "../cost/budget.js";
 import { appendCostEntry, summarizeCostHistory } from "../cost/history.js";
@@ -585,6 +586,7 @@ export function registerScanCommand(program) {
         profile,
       });
 
+      const startedAtIso = new Date().toISOString();
       const startedAtMs = Date.now();
       const client = createMultiProviderApiClient();
       const response = await client.invoke({
@@ -615,13 +617,16 @@ export function registerScanCommand(program) {
       await fsp.mkdir(path.dirname(reportPath), { recursive: true });
       await fsp.writeFile(reportPath, reportMarkdown, "utf-8");
 
-      const inputTokens = estimateTokens(prompt, { model: response.model });
-      const outputTokens = estimateTokens(aiMarkdown, { model: response.model });
+      const estimatedInputTokens = estimateTokens(prompt, { model: response.model });
+      const estimatedOutputTokens = estimateTokens(aiMarkdown, { model: response.model });
+      const inputTokens = usageNumber(response.usage?.inputTokens, estimatedInputTokens);
+      const outputTokens = usageNumber(response.usage?.outputTokens, estimatedOutputTokens);
       const modelCost = maybeEstimateModelCost({
         modelId: response.model,
         inputTokens,
         outputTokens,
       });
+      const costUsd = usageNumber(response.usage?.costUsd, modelCost.costUsd);
       const sessionId = String(options.sessionId || "scan-ai-precheck").trim() || "scan-ai-precheck";
 
       const appendedCost = await appendCostEntry(
@@ -639,7 +644,7 @@ export function registerScanCommand(program) {
           cacheWriteTokens: 0,
           durationMs,
           toolCalls: 1,
-          costUsd: modelCost.costUsd,
+          costUsd,
           progressScore: aiMarkdown ? 1 : 0,
         }
       );
@@ -682,7 +687,7 @@ export function registerScanCommand(program) {
             outputTokens,
             cacheReadTokens: 0,
             cacheWriteTokens: 0,
-            costUsd: modelCost.costUsd,
+            costUsd,
             durationMs,
             toolCalls: 1,
           },
@@ -727,9 +732,28 @@ export function registerScanCommand(program) {
               invocationId: appendedCost.entry.invocationId,
             },
           }
-        );
+          );
       }
 
+      const sessionUsageLedger = await recordCliLlmSessionUsage({
+        sessionId,
+        agentId: "scan-precheck",
+        action: "scan_precheck",
+        model: response.model,
+        inputTokens,
+        outputTokens,
+        startedAtIso,
+        targetPath,
+        sourceCommand: "scan precheck",
+        provider: response.provider,
+        metadata: {
+          specPath,
+          profile,
+          policyPackId: activePolicy.selected?.id || "",
+          pricingFound: modelCost.pricingFound,
+        },
+      });
+
       const payload = {
         command: "scan precheck",
         targetPath,
@@ -749,10 +773,11 @@ export function registerScanCommand(program) {
           usage: {
             inputTokens,
             outputTokens,
-            costUsd: modelCost.costUsd,
+            costUsd,
             durationMs,
             toolCalls: 1,
           },
+          billing: sessionUsageLedger,
           budget,
           cost: {
             filePath: appendedCost.filePath,

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/commands/spec.js

@@ -9,6 +9,7 @@ import {
   resolveModel,
   resolveProvider,
 } from "../ai/client.js";
+import { recordCliLlmSessionUsage, usageNumber } from "../billing/llm-session-usage.js";
 import { loadConfig } from "../config/service.js";
 import { evaluateBudget } from "../cost/budget.js";
 import { appendCostEntry, summarizeCostHistory } from "../cost/history.js";
@@ -273,6 +274,7 @@ async function maybeEnhanceSpecWithAi({
     ingest,
   });
 
+  const startedAtIso = new Date().toISOString();
   const startedAtMs = Date.now();
   const client = createMultiProviderApiClient();
   const result = await client.invoke({
@@ -288,13 +290,16 @@ async function maybeEnhanceSpecWithAi({
   const normalizedText = String(result.text || "").trim();
   const enhancedMarkdown = normalizedText || baseSpecMarkdown;
 
-  const inputTokens = estimateTokens(prompt, { model: result.model });
-  const outputTokens = estimateTokens(enhancedMarkdown, { model: result.model });
+  const estimatedInputTokens = estimateTokens(prompt, { model: result.model });
+  const estimatedOutputTokens = estimateTokens(enhancedMarkdown, { model: result.model });
+  const inputTokens = usageNumber(result.usage?.inputTokens, estimatedInputTokens);
+  const outputTokens = usageNumber(result.usage?.outputTokens, estimatedOutputTokens);
   const modelCost = maybeEstimateModelCost({
     modelId: result.model,
     inputTokens,
     outputTokens,
   });
+  const costUsd = usageNumber(result.usage?.costUsd, modelCost.costUsd);
 
   const sessionId = String(options.sessionId || "spec-generate-ai").trim() || "spec-generate-ai";
   const appendedCost = await appendCostEntry(
@@ -312,7 +317,7 @@ async function maybeEnhanceSpecWithAi({
       cacheWriteTokens: 0,
       durationMs,
       toolCalls: 1,
-      costUsd: modelCost.costUsd,
+      costUsd,
       progressScore: normalizedText ? 1 : 0,
     }
   );
@@ -355,7 +360,7 @@ async function maybeEnhanceSpecWithAi({
         outputTokens,
         cacheReadTokens: 0,
         cacheWriteTokens: 0,
-        costUsd: modelCost.costUsd,
+        costUsd,
         durationMs,
         toolCalls: 1,
       },
@@ -403,6 +408,24 @@ async function maybeEnhanceSpecWithAi({
     );
   }
 
+  const sessionUsageLedger = await recordCliLlmSessionUsage({
+    sessionId,
+    agentId: "spec-generator",
+    action: "spec_generate_ai",
+    model: result.model,
+    inputTokens,
+    outputTokens,
+    startedAtIso,
+    targetPath,
+    sourceCommand: "spec generate --ai",
+    provider: result.provider,
+    metadata: {
+      template: template?.id || template?.name || "",
+      projectType: template?.projectType || "",
+      pricingFound: modelCost.pricingFound,
+    },
+  });
+
   return {
     markdown: enhancedMarkdown,
     ai: {
@@ -413,10 +436,11 @@ async function maybeEnhanceSpecWithAi({
       usage: {
         inputTokens,
         outputTokens,
-        costUsd: modelCost.costUsd,
+        costUsd,
         durationMs,
         toolCalls: 1,
       },
+      billing: sessionUsageLedger,
       budget,
       cost: {
         filePath: appendedCost.filePath,

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.",
   "",