sentinelayer-cli 0.14.0 → 0.16.0

package/package.json

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

package/src/commands/session.js

@@ -948,6 +948,50 @@ async function hydrateAfterCheckpointMutation(sessionId, { targetPath } = {}) {
   }));
 }
 
+async function hydrateJoinBriefingContext(sessionId, { targetPath, limit = 100 } = {}) {
+  const normalizedLimit = Math.max(1, Math.min(200, parsePositiveInteger(limit, "limit", 100)));
+  try {
+    const remoteTail = await pollSessionEventsBefore(sessionId, {
+      targetPath,
+      limit: normalizedLimit,
+      timeoutMs: 15_000,
+      forceCircuitProbe: true,
+    });
+    if (!remoteTail?.ok) {
+      return {
+        ok: false,
+        reason: normalizeString(remoteTail?.reason) || "remote_tail_unavailable",
+        remoteEvents: 0,
+        appended: 0,
+        skipped: 0,
+        failed: 0,
+      };
+    }
+    const appended = await appendMissingRemoteEvents(sessionId, remoteTail.events, {
+      targetPath,
+    });
+    return {
+      ok: true,
+      reason: "",
+      remoteEvents: Array.isArray(remoteTail.events) ? remoteTail.events.length : 0,
+      appended: appended.appended,
+      skipped: appended.skipped,
+      failed: appended.failed,
+      cursor: remoteTail.cursor || null,
+      beforeSequence: remoteTail.beforeSequence || null,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: normalizeString(error?.message) || "join_context_hydrate_failed",
+      remoteEvents: 0,
+      appended: 0,
+      skipped: 0,
+      failed: 0,
+    };
+  }
+}
+
 async function appendMissingRemoteEvents(sessionId, remoteEvents = [], { targetPath } = {}) {
   const events = Array.isArray(remoteEvents) ? remoteEvents : [];
   if (events.length === 0) {
@@ -1577,6 +1621,9 @@ export function registerSessionCommand(program) {
         skipRemoteProbe: true,
         remoteSession,
       });
+      const joinHydration = await hydrateJoinBriefingContext(normalizedSessionId, {
+        targetPath,
+      });
 
       const explicitAgent = normalizeString(options.agent);
       const agentSeed = explicitAgent || normalizeString(options.name);
@@ -1630,6 +1677,7 @@ export function registerSessionCommand(program) {
         materializedLocalSession: localSession.materialized,
         refreshedLocalSession: Boolean(localSession.refreshed),
         verificationSource: verification.source,
+        joinHydration,
         eventCount: Number.isFinite(eventCount) ? eventCount : 0,
         agentCount: Number.isFinite(agentCount) ? agentCount : 0,
         lastActivityAt: lastActivityIso || null,

package/src/session/recap.js

@@ -7,6 +7,7 @@ import { dedupeSessionEvents } from "./event-identity.js";
 import { resolveSessionPaths } from "./paths.js";
 import { appendToStream, readStream } from "./stream.js";
 import { getSession } from "./store.js";
+import { aggregateSessionUsage } from "./usage.js";
 
 const SENTI_AGENT_ID = "senti";
 const SENTI_MODEL = "gpt-5.4-mini";
@@ -349,6 +350,7 @@ function buildRecapText({
   activeLocks = 0,
   pendingTasks = 0,
   taskLedger = emptyTaskLedgerSummary(),
+  usageSummary = normalizeUsageSummary(),
   snippets = [],
 } = {}) {
   const agentText =
@@ -360,8 +362,9 @@ function buildRecapText({
   const pendingText =
     pendingTasks > 0 ? `You have ${pendingTasks} pending task${pendingTasks === 1 ? "" : "s"}.` : "";
   const taskText = buildTaskLedgerText(taskLedger);
+  const usageText = buildUsageLedgerText(usageSummary);
   const snippetText = snippets.length > 0 ? `Recent: ${snippets.join(" | ")}` : "";
-  return `While you were away: ${agentText}. ${findingText}. ${lockText}. ${pendingText} ${taskText}. ${snippetText}`.replace(
+  return `While you were away: ${agentText}. ${findingText}. ${lockText}. ${pendingText} ${taskText}. ${usageText} ${snippetText}`.replace(
     /\s+/g,
     " "
   ).trim();
@@ -402,6 +405,70 @@ function buildTaskLedgerText(taskLedger = emptyTaskLedgerSummary()) {
     .join(". ");
 }
 
+function roundCurrency(value) {
+  const normalized = Number(value || 0);
+  if (!Number.isFinite(normalized) || normalized < 0) {
+    return 0;
+  }
+  return Math.round(normalized * 1_000_000) / 1_000_000;
+}
+
+function normalizeUsageSummary(events = []) {
+  const aggregate = aggregateSessionUsage(events);
+  const totals = {
+    totalTokens: Number(aggregate.totals.totalTokens || 0),
+    inputTokens: Number(aggregate.totals.inputTokens || 0),
+    outputTokens: Number(aggregate.totals.outputTokens || 0),
+    costUsd: roundCurrency(aggregate.totals.costUsd),
+    interactions: Number(aggregate.totals.interactions || 0),
+  };
+  const topAgents = [...aggregate.perAgent.values()]
+    .filter(
+      (agent) =>
+        Number(agent.totalTokens || 0) > 0 ||
+        Number(agent.costUsd || 0) > 0 ||
+        Number(agent.interactions || 0) > 0,
+    )
+    .sort((left, right) => {
+      const costDelta = Number(right.costUsd || 0) - Number(left.costUsd || 0);
+      if (costDelta !== 0) return costDelta;
+      const tokenDelta = Number(right.totalTokens || 0) - Number(left.totalTokens || 0);
+      if (tokenDelta !== 0) return tokenDelta;
+      return normalizeString(left.agentId).localeCompare(normalizeString(right.agentId));
+    })
+    .slice(0, 3)
+    .map((agent) => ({
+      agentId: normalizeString(agent.agentId) || "unknown",
+      model: normalizeString(agent.model) || "unknown",
+      totalTokens: Number(agent.totalTokens || 0),
+      inputTokens: Number(agent.inputTokens || 0),
+      outputTokens: Number(agent.outputTokens || 0),
+      costUsd: roundCurrency(agent.costUsd),
+      interactions: Number(agent.interactions || 0),
+    }));
+  return { totals, topAgents };
+}
+
+function buildUsageLedgerText(usageSummary = {}) {
+  const totals = usageSummary.totals && typeof usageSummary.totals === "object" ? usageSummary.totals : {};
+  const totalTokens = Number(totals.totalTokens || 0);
+  const costUsd = roundCurrency(totals.costUsd);
+  if (totalTokens <= 0 && costUsd <= 0) {
+    return "";
+  }
+  const topAgents = Array.isArray(usageSummary.topAgents) ? usageSummary.topAgents : [];
+  const topText =
+    topAgents.length > 0
+      ? ` Top agents: ${topAgents
+          .map(
+            (agent) =>
+              `${agent.agentId} ${Number(agent.totalTokens || 0).toLocaleString("en-US")} tokens/$${roundCurrency(agent.costUsd).toFixed(4)}`,
+          )
+          .join("; ")}.`
+      : "";
+  return `Usage: ${totalTokens.toLocaleString("en-US")} tokens / $${costUsd.toFixed(4)}.${topText}`;
+}
+
 // Multi-agent session etiquette + read-path rules surfaced in the
 // context_briefing payload an agent receives on first join. Web
 // renders this as markdown (see sentinelayer-web Session.tsx
@@ -444,7 +511,14 @@ function buildPeriodicText(recap = {}) {
   const lastActor = normalizeString(summary.lastActorId);
   const actorText = lastActor ? `${lastActor} active` : "no active actor";
   const taskText = buildTaskLedgerText(summary.taskLedger);
-  return `Session active for ${elapsedMinutes}m. ${activeAgents} agents. ${totalFindings} findings. ${activeLocks} locks. ${taskText}. ${actorText}.`;
+  const usageText = buildUsageLedgerText({
+    totals: summary.usageTotals,
+    topAgents: summary.usageTopAgents,
+  });
+  return `Session active for ${elapsedMinutes}m. ${activeAgents} agents. ${totalFindings} findings. ${activeLocks} locks. ${taskText}. ${usageText} ${actorText}.`.replace(
+    /\s+/g,
+    " ",
+  ).trim();
 }
 
 export async function buildSessionRecap(
@@ -475,9 +549,9 @@ export async function buildSessionRecap(
   } catch {
     sessionMetadata = null;
   }
-  const events = sortEventsByConversationTime(dedupeSessionEvents(allEvents), normalizedNow).slice(
-    -normalizedMaxEvents,
-  );
+  const sortedEvents = sortEventsByConversationTime(dedupeSessionEvents(allEvents), normalizedNow);
+  const usageSummary = normalizeUsageSummary(sortedEvents);
+  const events = sortedEvents.slice(-normalizedMaxEvents);
   const visibleEvents = (Array.isArray(events) ? events : []).filter((event) => {
     const agentId = normalizeString(event.agent?.id || event.agentId);
     if (!agentId) {
@@ -524,6 +598,7 @@ export async function buildSessionRecap(
     activeLocks,
     pendingTasks,
     taskLedger,
+    usageSummary,
     snippets,
   });
 
@@ -543,6 +618,8 @@ export async function buildSessionRecap(
       activeLocks,
       pendingTasksForAgent: pendingTasks,
       taskLedger,
+      usageTotals: usageSummary.totals,
+      usageTopAgents: usageSummary.topAgents,
       snippets,
       elapsedMinutes,
       windowElapsedMinutes,
@@ -589,6 +666,7 @@ export async function emitContextBriefing(
       ephemeral: true,
       style: RECAP_STYLE,
       generatedAt: recap.generatedAt,
+      summary: recap.summary,
     },
   });
   const persisted = await appendToStream(sessionId, event, {
@@ -773,6 +851,7 @@ export function emitPeriodicRecap(
         ephemeral: true,
         style: RECAP_STYLE,
         generatedAt: nowIso,
+        summary: recap.summary,
       },
     });
     const persisted = await appendToStream(state.sessionId, event, {

package/src/session/usage.js

@@ -55,6 +55,21 @@ function num(value) {
   return Number.isFinite(v) && v >= 0 ? v : 0;
 }
 
+function plainObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function firstUsageNumber(payload = {}, keys = []) {
+  const usage = plainObject(payload.usage);
+  for (const key of keys) {
+    const direct = num(payload[key]);
+    if (direct > 0) return direct;
+    const nested = num(usage[key]);
+    if (nested > 0) return nested;
+  }
+  return 0;
+}
+
 function clipText(text, max = 4000) {
   const s = n(text);
   if (s.length <= max) return s;
@@ -179,10 +194,36 @@ export function aggregateSessionUsage(events = []) {
     const payload = event.payload || {};
     const agentId = n(payload.agentId || event.agent?.id);
     if (!agentId) continue;
+    const model = n(payload.model || event.agent?.model) || "unknown";
+    const inputTokens = firstUsageNumber(payload, [
+      "inputTokens",
+      "input_tokens",
+      "tokensIn",
+      "tokens_in",
+    ]);
+    const outputTokens = firstUsageNumber(payload, [
+      "outputTokens",
+      "output_tokens",
+      "tokensOut",
+      "tokens_out",
+    ]);
+    const explicitTotalTokens = firstUsageNumber(payload, [
+      "totalTokens",
+      "total_tokens",
+      "tokens",
+    ]);
+    const totalTokens = explicitTotalTokens || inputTokens + outputTokens;
+    const costUsd = firstUsageNumber(payload, [
+      "costUsd",
+      "cost_usd",
+      "providerCostUsd",
+      "provider_cost_usd",
+      "cost",
+    ]);
     if (!perAgent.has(agentId)) {
       perAgent.set(agentId, {
         agentId,
-        model: n(payload.model || event.agent?.model) || "unknown",
+        model,
         totalTokens: 0,
         inputTokens: 0,
         outputTokens: 0,
@@ -191,16 +232,19 @@ export function aggregateSessionUsage(events = []) {
       });
     }
     const record = perAgent.get(agentId);
-    record.totalTokens += num(payload.totalTokens);
-    record.inputTokens += num(payload.inputTokens);
-    record.outputTokens += num(payload.outputTokens);
-    record.costUsd += num(payload.costUsd);
+    if (record.model === "unknown" && model !== "unknown") {
+      record.model = model;
+    }
+    record.totalTokens += totalTokens;
+    record.inputTokens += inputTokens;
+    record.outputTokens += outputTokens;
+    record.costUsd += costUsd;
     record.interactions += 1;
 
-    totals.totalTokens += num(payload.totalTokens);
-    totals.inputTokens += num(payload.inputTokens);
-    totals.outputTokens += num(payload.outputTokens);
-    totals.costUsd += num(payload.costUsd);
+    totals.totalTokens += totalTokens;
+    totals.inputTokens += inputTokens;
+    totals.outputTokens += outputTokens;
+    totals.costUsd += costUsd;
     totals.interactions += 1;
   }
   totals.costUsd = Math.round(totals.costUsd * 1_000_000) / 1_000_000;