sentinelayer-cli 0.30.9 → 0.30.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.30.9",
+  "version": "0.30.11",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {
@@ -9,7 +9,7 @@
     "docs:build": "node scripts/docs-build.mjs",
     "test": "npm run test:unit && npm run test:e2e",
     "test:unit": "node --import ./tests/setup-env.mjs --test tests/unit*.test.mjs",
-    "test:e2e": "node --import ./tests/setup-env.mjs --test tests/e2e.test.mjs",
+    "test:e2e": "node --import ./tests/setup-env.mjs --test tests/e2e*.test.mjs",
     "test:coverage": "c8 node --import ./tests/setup-env.mjs --test tests/unit*.test.mjs",
     "verify": "npm run check && npm run docs:build && npm run test:e2e && npm run test:coverage && npm pack --dry-run",
     "release:publish": "node scripts/release-publish.mjs"

package/src/commands/session.js

@@ -138,6 +138,49 @@ function normalizeString(value) {
   return String(value || "").trim();
 }
 
+function messagePartsHaveContent(messageParts) {
+  const parts = Array.isArray(messageParts) ? messageParts : [messageParts];
+  return parts.some((part) => normalizeString(part));
+}
+
+function joinMessageParts(messageParts) {
+  if (Array.isArray(messageParts)) {
+    return messageParts.length === 1 ? String(messageParts[0] || "") : messageParts.join(" ");
+  }
+  return String(messageParts || "");
+}
+
+async function readUtf8FromStdin(stdin = process.stdin) {
+  if (stdin.isTTY) {
+    throw new Error("--stdin requires piped input.");
+  }
+  stdin.setEncoding("utf8");
+  let text = "";
+  for await (const chunk of stdin) {
+    text += String(chunk);
+  }
+  return text;
+}
+
+async function resolveSessionSayMessageInput(messageParts, options = {}) {
+  const hasPositionalMessage = messagePartsHaveContent(messageParts);
+  const hasMessageFile = Boolean(normalizeString(options.messageFile));
+  const hasStdin = Boolean(options.stdin);
+  const sources = [hasPositionalMessage, hasMessageFile, hasStdin].filter(Boolean).length;
+  if (sources > 1) {
+    throw new Error("Use only one message source: positional message, --message-file, or --stdin.");
+  }
+  if (hasMessageFile) {
+    return normalizeString(
+      await fsp.readFile(path.resolve(process.cwd(), String(options.messageFile)), "utf-8"),
+    );
+  }
+  if (hasStdin) {
+    return normalizeString(await readUtf8FromStdin());
+  }
+  return normalizeString(joinMessageParts(messageParts));
+}
+
 function optionWasSetByCli(command, optionName) {
   if (!command || typeof command.getOptionValueSource !== "function") {
     return false;
@@ -3343,7 +3386,7 @@ export function registerSessionCommand(program) {
     });
 
   session
-    .command("say <sessionId> <message>")
+    .command("say <sessionId> [message...]")
     .description("Send a message to the session")
     .option(
       "--agent <id>",
@@ -3367,16 +3410,18 @@ export function registerSessionCommand(program) {
     .option("--to <agent>", "Direct the message to a specific agent id")
     .option("--reply-to <sequence>", "Mark this message as a reply to a target sequence id")
     .option("--reply-cursor <cursor>", "Mark this message as a reply to a target event cursor")
+    .option("--message-file <path>", "Read the message body from a UTF-8 file")
+    .option("--stdin", "Read the message body from stdin")
     .option("--force-cli-user", "Allow fallback sends as cli-user when no agent identity can be resolved")
     .option("--local-only", "Append only to the local session cache without remote send confirmation")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
-    .action(async (sessionId, message, options, command) => {
+    .action(async (sessionId, messageParts, options, command) => {
       const normalizedSessionId = normalizeString(sessionId);
       if (!normalizedSessionId) {
         throw new Error("session id is required.");
       }
-      const normalizedMessage = normalizeString(message);
+      const normalizedMessage = await resolveSessionSayMessageInput(messageParts, options);
       if (!normalizedMessage) {
         throw new Error("message is required.");
       }

package/src/session/pricing-ledger.js

@@ -138,7 +138,10 @@ export function buildUsageLedgerEntry(
   { sessionId = "", priceBookVersion = DEFAULT_PRICE_BOOK_VERSION, billingTier = "unknown" } = {},
 ) {
   const kind = n(event?.event || event?.type);
-  const payload = object(event?.payload);
+  const rawPayload = event?.payload;
+  const payload = object(rawPayload);
+  const payloadWasObject = rawPayload && typeof rawPayload === "object" && !Array.isArray(rawPayload);
+  if (kind === SESSION_USAGE_EVENT && !payloadWasObject) return null;
   const schema = n(payload.schema);
   const usage = object(payload.usage);
   const legacyUsageEvent = kind !== SESSION_USAGE_EVENT && hasUsageHints(usage);

package/src/session/transcript.js

@@ -237,7 +237,12 @@ function eventBody(event) {
  *  - totals: { tokenTotal, costTotalUsd } summed through the pricing ledger
  *  - sentiActions: count of orchestrator events
  */
-export function computeTranscriptStats({ sessionMeta = {}, events = [], speakerProfiles = new Map() } = {}) {
+export function computeTranscriptStats({
+  sessionMeta = {},
+  events = [],
+  speakerProfiles = new Map(),
+  usageLedger = null,
+} = {}) {
   const perAgent = new Map();
   let firstEventTs = null;
   let lastEventTs = null;
@@ -305,14 +310,14 @@ export function computeTranscriptStats({ sessionMeta = {}, events = [], speakerP
     if (epoch > record.lastSeenMs) record.lastSeenMs = epoch;
   }
 
-  const usageLedger = buildSessionUsageLedger(events, {
+  const resolvedUsageLedger = usageLedger || buildSessionUsageLedger(events, {
     sessionId: normalize(sessionMeta.sessionId),
   });
   const fallbackUsageEpoch =
     lastEventTs ??
     firstEventTs ??
     (Number.isFinite(Date.parse(sessionMeta?.createdAt)) ? Date.parse(sessionMeta.createdAt) : 0);
-  for (const entry of usageLedger.entries) {
+  for (const entry of resolvedUsageLedger.entries) {
     const entryEpoch = Number.isFinite(Date.parse(entry.timestamp))
       ? Date.parse(entry.timestamp)
       : fallbackUsageEpoch;
@@ -364,17 +369,17 @@ export function computeTranscriptStats({ sessionMeta = {}, events = [], speakerP
     sessionLiveSeconds,
     agents,
     totals: {
-      tokenTotal: usageLedger.totals.totalTokens,
-      inputTokens: usageLedger.totals.inputTokens,
-      outputTokens: usageLedger.totals.outputTokens,
-      costTotalUsd: usageLedger.totals.providerCostUsd,
-      customerCostTotalUsd: usageLedger.totals.hasCustomerCost
-        ? usageLedger.totals.customerCostUsd
+      tokenTotal: resolvedUsageLedger.totals.totalTokens,
+      inputTokens: resolvedUsageLedger.totals.inputTokens,
+      outputTokens: resolvedUsageLedger.totals.outputTokens,
+      costTotalUsd: resolvedUsageLedger.totals.providerCostUsd,
+      customerCostTotalUsd: resolvedUsageLedger.totals.hasCustomerCost
+        ? resolvedUsageLedger.totals.customerCostUsd
         : null,
-      usageEntries: usageLedger.entries.length,
-      duplicatesSkipped: usageLedger.duplicatesSkipped,
-      unpriced: usageLedger.totals.unpriced,
-      priceBookVersions: usageLedger.priceBookVersions,
+      usageEntries: resolvedUsageLedger.entries.length,
+      duplicatesSkipped: resolvedUsageLedger.duplicatesSkipped,
+      unpriced: resolvedUsageLedger.totals.unpriced,
+      priceBookVersions: resolvedUsageLedger.priceBookVersions,
     },
     sentiActions,
   };
@@ -408,6 +413,134 @@ function avatarMd(identity) {
   return identity.avatar || letterTile(identity.displayName || identity.agentId);
 }
 
+function intCell(value) {
+  return Math.max(0, Math.floor(Number(value || 0))).toLocaleString("en-US");
+}
+
+function usdCell(value) {
+  return `$${Number(value || 0).toFixed(6)}`;
+}
+
+function tableText(value, { maxLength = 160 } = {}) {
+  const escaped = normalize(value)
+    .replace(/\r?\n/g, " ")
+    .replace(/\|/g, "\\|")
+    .replace(/`/g, "'");
+  if (!maxLength || escaped.length <= maxLength) return escaped;
+  const head = Math.max(24, Math.floor((maxLength - 3) * 0.7));
+  const tail = Math.max(12, maxLength - 3 - head);
+  return `${escaped.slice(0, head)}...${escaped.slice(-tail)}`;
+}
+
+function codeCell(value) {
+  const text = tableText(value);
+  return text ? `\`${text}\`` : "—";
+}
+
+function optionalUsdCell(value, hasValue) {
+  return hasValue ? usdCell(value) : "—";
+}
+
+function shortenIdempotencyKey(value, maxLength = 36) {
+  const text = tableText(value, { maxLength: 0 });
+  if (!text || text.length <= maxLength) return text;
+  const head = Math.max(8, Math.floor((maxLength - 3) * 0.58));
+  const tail = Math.max(6, maxLength - 3 - head);
+  return `${text.slice(0, head)}...${text.slice(-tail)}`;
+}
+
+function rollupsByCostAndTokens(map) {
+  return [...map.values()].sort((a, b) => (
+    b.providerCostUsd - a.providerCostUsd ||
+    b.totalTokens - a.totalTokens ||
+    b.entries - a.entries ||
+    tableText(a.label).localeCompare(tableText(b.label))
+  ));
+}
+
+function recentUsageEntries(entries, limit = 10) {
+  return entries
+    .map((entry, index) => ({ entry, index }))
+    .sort((a, b) => {
+      const aSequence = Number.isFinite(a.entry.sequenceId) ? a.entry.sequenceId : null;
+      const bSequence = Number.isFinite(b.entry.sequenceId) ? b.entry.sequenceId : null;
+      if (aSequence != null && bSequence != null && aSequence !== bSequence) {
+        return bSequence - aSequence;
+      }
+      const aTime = Date.parse(a.entry.timestamp);
+      const bTime = Date.parse(b.entry.timestamp);
+      if (Number.isFinite(aTime) && Number.isFinite(bTime) && aTime !== bTime) {
+        return bTime - aTime;
+      }
+      return b.index - a.index;
+    })
+    .slice(0, limit)
+    .map(({ entry }) => entry);
+}
+
+function appendUsageRollupTable(lines, { title, labelHeader, rollups }) {
+  lines.push(`### ${title}`);
+  lines.push("");
+  lines.push(`| ${labelHeader} | Entries | Input | Output | Total | Provider cost | Customer cost | Unpriced |`);
+  lines.push("|---|---:|---:|---:|---:|---:|---:|---:|");
+  if (rollups.length === 0) {
+    lines.push(`| — | 0 | 0 | 0 | 0 | ${usdCell(0)} | — | 0 |`);
+  } else {
+    for (const rollup of rollups) {
+      lines.push(
+        `| ${codeCell(rollup.label)} | ${intCell(rollup.entries)} | ${intCell(rollup.inputTokens)} | ${intCell(rollup.outputTokens)} | ${intCell(rollup.totalTokens)} | ${usdCell(rollup.providerCostUsd)} | ${optionalUsdCell(rollup.customerCostUsd, rollup.hasCustomerCost)} | ${intCell(rollup.unpriced)} |`,
+      );
+    }
+  }
+  lines.push("");
+}
+
+function appendUsageLedgerSection(lines, usageLedger) {
+  const totals = usageLedger.totals;
+  lines.push("## Usage Ledger");
+  lines.push("");
+
+  if (usageLedger.entries.length === 0 && usageLedger.duplicatesSkipped === 0) {
+    lines.push("_No usage telemetry recorded._");
+    lines.push("");
+    return;
+  }
+
+  const customerCostText = totals.hasCustomerCost
+    ? `Customer cost: ${usdCell(totals.customerCostUsd)}`
+    : "Customer cost: —";
+  lines.push(`Accepted entries: ${intCell(usageLedger.entries.length)}`);
+  lines.push(
+    `Tokens: ${intCell(totals.totalTokens)} (input ${intCell(totals.inputTokens)} / output ${intCell(totals.outputTokens)})`,
+  );
+  lines.push(`Provider cost: ${usdCell(totals.providerCostUsd)} · ${customerCostText}`);
+  lines.push(`Price books: ${usageLedger.priceBookVersions.map(tableText).filter(Boolean).join(", ") || "—"}`);
+  lines.push(`Duplicates skipped: ${intCell(usageLedger.duplicatesSkipped)} · Unpriced entries: ${intCell(totals.unpriced)}`);
+  lines.push("");
+
+  appendUsageRollupTable(lines, {
+    title: "Per Agent",
+    labelHeader: "Agent",
+    rollups: rollupsByCostAndTokens(usageLedger.perAgent),
+  });
+  appendUsageRollupTable(lines, {
+    title: "Per Action",
+    labelHeader: "Action",
+    rollups: rollupsByCostAndTokens(usageLedger.perAction),
+  });
+
+  lines.push("### Recent Entries");
+  lines.push("");
+  lines.push("| Time | Agent | Action | Model | Tokens | Provider cost | Customer cost | Idempotency key |");
+  lines.push("|---|---|---|---|---:|---:|---:|---|");
+  for (const entry of recentUsageEntries(usageLedger.entries)) {
+    lines.push(
+      `| ${tableText(timestampOnly(entry.timestamp)) || "—"} | ${codeCell(entry.agentId)} | ${codeCell(entry.action)} | ${codeCell(entry.model)} | ${intCell(entry.totalTokens)} | ${usdCell(entry.providerCostUsd)} | ${optionalUsdCell(entry.customerCostUsd, entry.customerCostUsd != null)} | ${codeCell(shortenIdempotencyKey(entry.idempotencyKey))} |`,
+    );
+  }
+  lines.push("");
+}
+
 /**
  * Build the iMessage-style markdown transcript.
  *
@@ -429,8 +562,11 @@ export function buildTranscriptMarkdown({
   speakerProfiles = new Map(),
   options = {},
 } = {}) {
+  const usageLedger = buildSessionUsageLedger(events, {
+    sessionId: normalize(sessionMeta.sessionId),
+  });
   const includeSystemEvents = options.includeSystemEvents !== false;
-  const stats = computeTranscriptStats({ sessionMeta, events, speakerProfiles });
+  const stats = computeTranscriptStats({ sessionMeta, events, speakerProfiles, usageLedger });
 
   const lines = [];
   const sessionId = normalize(sessionMeta.sessionId) || "unknown";
@@ -496,15 +632,17 @@ export function buildTranscriptMarkdown({
   stats.participantCount = stats.agents.length + silentRegisteredAgents.length;
   lines.push("");
 
+  appendUsageLedgerSection(lines, usageLedger);
+
   // Conversation
   lines.push("## Conversation");
   lines.push("");
   for (const event of events) {
-    const kind = normalize(event.event || event.type);
+    const kind = normalize(event?.event || event?.type);
     if (!kind || !TRANSCRIPT_EVENT_KINDS.has(kind)) continue;
     if (!includeSystemEvents && SYSTEM_EVENT_KINDS.has(kind)) continue;
 
-    const agentId = normalize(event.agent?.id || event.agentId);
+    const agentId = normalize(event?.agent?.id || event?.agentId);
     const profile = speakerProfiles.get(agentId) || null;
     const identity = resolveSpeakerIdentity({
       agentId,