sentinelayer-cli 0.18.2 → 0.20.0

package/src/session/transcript.js

@@ -7,7 +7,8 @@
  * Adds at render time:
  *   - Per-agent active duration (first → last event with that agent id)
  *   - Total session live-for (createdAt → last event)
- *   - Token + cost roll-up if events carry usage payloads
+ *   - Token + cost roll-up from session_usage events through the
+ *     pricing ledger, including idempotency dedupe
  *   - Avatar per speaker, picked from PERSONA_VISUALS / CLIENT_FAMILY_AVATARS,
  *     or a deterministic letter-tile fallback
  *   - Senti-orchestrator events tagged with the orchestrator avatar so
@@ -18,6 +19,7 @@
  */
 
 import { PERSONA_VISUALS, ORCHESTRATOR_VISUALS } from "../agents/persona-visuals.js";
+import { buildSessionUsageLedger } from "./pricing-ledger.js";
 
 /**
  * Avatar map for client families (the OUTSIDE-the-persona-set agents
@@ -232,45 +234,39 @@ function eventBody(event) {
  * Compute deterministic activity stats from the event log:
  *  - sessionLiveSeconds: created → last event
  *  - perAgent[agentId]: { firstSeen, lastSeen, eventCount, activeSeconds, family, displayName, model }
- *  - totals: { tokenTotal, costTotalUsd } summed from any payload.usage hints
+ *  - totals: { tokenTotal, costTotalUsd } summed through the pricing ledger
  *  - sentiActions: count of orchestrator events
  */
 export function computeTranscriptStats({ sessionMeta = {}, events = [], speakerProfiles = new Map() } = {}) {
   const perAgent = new Map();
   let firstEventTs = null;
   let lastEventTs = null;
-  let tokenTotal = 0;
-  let costTotalUsd = 0;
   let sentiActions = 0;
 
-  for (const event of events) {
-    const ts = eventTimestamp(event);
-    if (!ts) continue;
-    const epoch = Date.parse(ts);
-    if (!Number.isFinite(epoch)) continue;
-    if (firstEventTs == null || epoch < firstEventTs) firstEventTs = epoch;
-    if (lastEventTs == null || epoch > lastEventTs) lastEventTs = epoch;
-
-    const agentId = normalize(event.agent?.id || event.agentId);
-    if (!agentId) continue;
-    const lowerId = agentId.toLowerCase();
-    if (lowerId === "senti" || lowerId === "kai-chen") sentiActions += 1;
-
-    if (!perAgent.has(agentId)) {
-      const profile = speakerProfiles.get(agentId) || null;
+  const ensureAgentRecord = ({
+    agentId,
+    agentModel = "",
+    epoch,
+  } = {}) => {
+    const normalizedAgentId = normalize(agentId);
+    if (!normalizedAgentId || !Number.isFinite(epoch)) {
+      return null;
+    }
+    if (!perAgent.has(normalizedAgentId)) {
+      const profile = speakerProfiles.get(normalizedAgentId) || null;
       const identity = resolveSpeakerIdentity({
-        agentId,
-        agentModel: event.agent?.model || event.agentModel || "",
+        agentId: normalizedAgentId,
+        agentModel,
         profile,
       });
-      perAgent.set(agentId, {
-        agentId,
+      perAgent.set(normalizedAgentId, {
+        agentId: normalizedAgentId,
         family: identity.family,
         displayName: identity.displayName,
         avatar: identity.avatar,
         avatarUrl: identity.avatarUrl,
         color: identity.color,
-        model: event.agent?.model || event.agentModel || "",
+        model: agentModel,
         firstSeenMs: epoch,
         lastSeenMs: epoch,
         eventCount: 0,
@@ -278,21 +274,59 @@ export function computeTranscriptStats({ sessionMeta = {}, events = [], speakerP
         costUsd: 0,
       });
     }
-    const record = perAgent.get(agentId);
+    const record = perAgent.get(normalizedAgentId);
+    if (!record.model && agentModel) {
+      record.model = agentModel;
+    }
+    return record;
+  };
+
+  for (const event of events) {
+    const ts = eventTimestamp(event);
+    if (!ts) continue;
+    const epoch = Date.parse(ts);
+    if (!Number.isFinite(epoch)) continue;
+    if (firstEventTs == null || epoch < firstEventTs) firstEventTs = epoch;
+    if (lastEventTs == null || epoch > lastEventTs) lastEventTs = epoch;
+
+    const agentId = normalize(event.agent?.id || event.agentId);
+    if (!agentId) continue;
+    const lowerId = agentId.toLowerCase();
+    if (lowerId === "senti" || lowerId === "kai-chen") sentiActions += 1;
+
+    const record = ensureAgentRecord({
+      agentId,
+      agentModel: event.agent?.model || event.agentModel || "",
+      epoch,
+    });
+    if (!record) continue;
     record.eventCount += 1;
     if (epoch < record.firstSeenMs) record.firstSeenMs = epoch;
     if (epoch > record.lastSeenMs) record.lastSeenMs = epoch;
+  }
 
-    const usage = event?.payload?.usage;
-    if (usage && typeof usage === "object") {
-      const t =
-        Number(usage.totalTokens || usage.total_tokens || usage.tokens || 0) || 0;
-      const c = Number(usage.costUsd || usage.cost_usd || usage.cost || 0) || 0;
-      record.tokens += t;
-      record.costUsd += c;
-      tokenTotal += t;
-      costTotalUsd += c;
+  const 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) {
+    const entryEpoch = Number.isFinite(Date.parse(entry.timestamp))
+      ? Date.parse(entry.timestamp)
+      : fallbackUsageEpoch;
+    const record = ensureAgentRecord({
+      agentId: entry.agentId,
+      agentModel: entry.model,
+      epoch: entryEpoch,
+    });
+    if (!record) continue;
+    if ((!record.model || record.model === "unknown") && entry.model && entry.model !== "unknown") {
+      record.model = entry.model;
     }
+    record.tokens += entry.totalTokens;
+    record.costUsd = Math.round((record.costUsd + entry.providerCostUsd) * 1_000_000) / 1_000_000;
   }
 
   const createdAtMs = sessionMeta?.createdAt
@@ -329,7 +363,19 @@ export function computeTranscriptStats({ sessionMeta = {}, events = [], speakerP
     endedAt: lastEventTs ? new Date(lastEventTs).toISOString() : null,
     sessionLiveSeconds,
     agents,
-    totals: { tokenTotal, costTotalUsd },
+    totals: {
+      tokenTotal: usageLedger.totals.totalTokens,
+      inputTokens: usageLedger.totals.inputTokens,
+      outputTokens: usageLedger.totals.outputTokens,
+      costTotalUsd: usageLedger.totals.providerCostUsd,
+      customerCostTotalUsd: usageLedger.totals.hasCustomerCost
+        ? usageLedger.totals.customerCostUsd
+        : null,
+      usageEntries: usageLedger.entries.length,
+      duplicatesSkipped: usageLedger.duplicatesSkipped,
+      unpriced: usageLedger.totals.unpriced,
+      priceBookVersions: usageLedger.priceBookVersions,
+    },
     sentiActions,
   };
 }
@@ -396,8 +442,12 @@ export function buildTranscriptMarkdown({
   lines.push(`Live for: ${formatDuration(stats.sessionLiveSeconds)}`);
   lines.push(`Senti actions: ${stats.sentiActions}`);
   if (stats.totals.tokenTotal > 0 || stats.totals.costTotalUsd > 0) {
+    const billableText =
+      stats.totals.customerCostTotalUsd == null
+        ? ""
+        : ` · Billable: $${stats.totals.customerCostTotalUsd.toFixed(4)}`;
     lines.push(
-      `Tokens: ${stats.totals.tokenTotal.toLocaleString("en-US")} · Cost: $${stats.totals.costTotalUsd.toFixed(4)}`,
+      `Tokens: ${stats.totals.tokenTotal.toLocaleString("en-US")} · Cost: $${stats.totals.costTotalUsd.toFixed(4)}${billableText}`,
     );
   }
   lines.push("");

package/src/session/usage.js

@@ -39,9 +39,9 @@
  *   }
  *
  * Design choice: emit BOTH the convenient flat fields AND a
- * `payload.usage` block, so transcript.js's existing usage roll-up
- * picks it up without changes, while web UIs can display the structured
- * fields directly without re-parsing.
+ * `payload.usage` block. Transcript/download totals flow through
+ * pricing-ledger idempotency semantics, while web UIs can display the
+ * structured fields directly without re-parsing.
  */
 
 import process from "node:process";
@@ -191,8 +191,8 @@ export async function emitLLMInteraction(
       chars: responseText.length,
       text: responseText || undefined,
     },
-    // Mirror into payload.usage so transcript.js + telemetry sync pick
-    // it up via the same code path used for ad-hoc agent_response usage.
+    // Mirror into payload.usage for legacy readers and telemetry sync;
+    // transcript/download totals use the canonical pricing-ledger fields.
     usage: {
       totalTokens: totalT,
       costUsd: cost,

package/src/session/wake/claude.js

@@ -0,0 +1,175 @@
+// Claude Code host wake adapter (Wake-Up & Notification Bus, L1).
+//
+// One of the per-host adapters the future `sentid` daemon (L2) drives through a
+// single uniform interface:  { hostName, installWakeHook(opts), wake(target) }.
+// The daemon calls `adapter.wake(...)` without caring which CLI is behind it.
+//
+// Ground-truth this encodes (verified against Claude Code hook docs, 2026-05):
+//   * An external process CANNOT poke an idle/stopped Claude Code session in
+//     place. `asyncRewake` background hooks and `Stop`-hook `decision:"block"`
+//     are real, but they only act WITHIN an already-running session.
+//   * The only DETERMINISTIC external wake is for the daemon to own the agent
+//     lifecycle and (re)spawn `claude --resume <id> "<event>"` per message.
+// So `wake()` is implemented as a daemon-owned resume, while the hook builders
+// expose the in-session primitives for callers that keep a session parked.
+//
+// Borrowed by copy (no imports) from the reference agent-CLI wake patterns:
+// the deferred-hook-result absorption shape and the channel-notification policy
+// gate idea — adapted, not vendored.
+
+import { execFile } from "node:child_process";
+
+export const hostName = "claude";
+
+const DEFAULT_CLAUDE_BIN = "claude";
+const DEFAULT_RESUME_TIMEOUT_MS = 120_000;
+const DEFAULT_ASYNC_HOOK_TIMEOUT_S = 600;
+// Claude Code overrides a Stop hook after it blocks this many times in a row
+// without progress; our release helper mirrors that cap so a parked session
+// can never wedge itself.
+const STOP_BLOCK_CAP = 8;
+const MAX_MESSAGE_CHARS = 16_000;
+
+function requireNonEmptyString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`claude wake: ${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function normalizeMessage(message) {
+  const text = requireNonEmptyString(message, "message");
+  // Cap length so a runaway event payload can't blow the argv / context.
+  return text.length > MAX_MESSAGE_CHARS ? text.slice(0, MAX_MESSAGE_CHARS) : text;
+}
+
+/**
+ * Build the `claude` argv for a daemon-owned resume wake. Returns a plain
+ * argument array so callers invoke it via execFile (no shell), which is what
+ * keeps an untrusted event message from being interpreted as a command.
+ *
+ * @param {{ sessionId: string, message: string, print?: boolean, extraArgs?: string[] }} opts
+ * @returns {string[]}
+ */
+export function buildResumeArgs({ sessionId, message, print = true, extraArgs = [] } = {}) {
+  requireNonEmptyString(sessionId, "sessionId");
+  const text = normalizeMessage(message);
+  if (!Array.isArray(extraArgs) || extraArgs.some((a) => typeof a !== "string")) {
+    throw new TypeError("claude wake: extraArgs must be an array of strings");
+  }
+  const args = ["--resume", sessionId, ...extraArgs];
+  // `-p` runs headless/non-interactive, which is what a daemon-driven wake wants.
+  if (print) args.push("-p");
+  args.push(text);
+  return args;
+}
+
+/**
+ * Build an `asyncRewake` background command-hook fragment. An agent installs
+ * this so a long-running background task can wake it: the task exits with code
+ * 2 and Claude surfaces its stderr (or stdout) as a system reminder. Implies
+ * `async: true`.
+ *
+ * @param {{ command: string, timeoutSeconds?: number }} opts
+ */
+export function buildAsyncRewakeHook({ command, timeoutSeconds = DEFAULT_ASYNC_HOOK_TIMEOUT_S } = {}) {
+  requireNonEmptyString(command, "command");
+  if (!Number.isInteger(timeoutSeconds) || timeoutSeconds <= 0) {
+    throw new TypeError("claude wake: timeoutSeconds must be a positive integer");
+  }
+  return { type: "command", command, asyncRewake: true, timeout: timeoutSeconds };
+}
+
+/**
+ * Build the JSON a `Stop` hook returns to keep a parked session alive: Claude
+ * cannot finish the turn and is fed `reason` as the next-turn context.
+ *
+ * @param {{ reason: string }} opts
+ */
+export function buildStopBlockDecision({ reason } = {}) {
+  return { decision: "block", reason: requireNonEmptyString(reason, "reason") };
+}
+
+/**
+ * A Stop hook must release (allow the session to stop) once Claude reports it
+ * has already been blocked `stop_hook_active` times, or it would wedge at the
+ * built-in cap. Returns true when the hook should let the session stop.
+ *
+ * @param {{ stop_hook_active?: boolean, stopHookActive?: boolean, blockCount?: number }} hookInput
+ */
+export function shouldReleaseStopBlock(hookInput = {}) {
+  if (hookInput.stop_hook_active === true || hookInput.stopHookActive === true) return true;
+  if (Number.isInteger(hookInput.blockCount) && hookInput.blockCount >= STOP_BLOCK_CAP) return true;
+  return false;
+}
+
+/**
+ * Shared-interface method: produce the settings fragment that installs the
+ * wake hook. Returns the fragment (caller decides where to merge it) rather
+ * than mutating a user's settings file, so installation stays non-destructive.
+ *
+ * @param {{ command: string, timeoutSeconds?: number, event?: string }} opts
+ */
+export function installWakeHook({ command, timeoutSeconds, event = "Stop" } = {}) {
+  const hook = buildAsyncRewakeHook({ command, timeoutSeconds });
+  return { hooks: { [event]: [{ hooks: [hook] }] } };
+}
+
+/**
+ * Shared-interface method the L2 daemon calls. Deterministic external wake =
+ * daemon-owned resume: spawn `claude --resume <id> <message>` via execFile
+ * (argv array, no shell). Resolves to a structured result; never throws for a
+ * non-zero exit — the daemon inspects `ok` and decides whether to retry.
+ *
+ * @param {{ sessionId: string, message: string, print?: boolean, extraArgs?: string[] }} target
+ * @param {{ execFileImpl?: Function, claudeBin?: string, timeoutMs?: number, env?: object }} [deps]
+ * @returns {Promise<{ ok: boolean, hostName: string, sessionId: string, code: number|null, reason: string|null }>}
+ */
+export function wake(target = {}, deps = {}) {
+  const {
+    execFileImpl = execFile,
+    claudeBin = DEFAULT_CLAUDE_BIN,
+    timeoutMs = DEFAULT_RESUME_TIMEOUT_MS,
+    env = process.env,
+  } = deps;
+
+  // Build args first so validation errors reject the promise deterministically.
+  let args;
+  try {
+    args = buildResumeArgs(target);
+  } catch (error) {
+    return Promise.reject(error);
+  }
+  const sessionId = target.sessionId;
+
+  return new Promise((resolve) => {
+    execFileImpl(
+      claudeBin,
+      args,
+      { timeout: timeoutMs, env, windowsHide: true },
+      (error, _stdout, stderr) => {
+        if (!error) {
+          resolve({ ok: true, hostName, sessionId, code: 0, reason: null });
+          return;
+        }
+        const code = typeof error.code === "number" ? error.code : null;
+        const reason = error.killed
+          ? "resume_timeout"
+          : (typeof stderr === "string" && stderr.trim()) || error.message || "resume_failed";
+        resolve({ ok: false, hostName, sessionId, code, reason });
+      }
+    );
+  });
+}
+
+export const claudeWakeAdapter = {
+  hostName,
+  installWakeHook,
+  wake,
+  buildResumeArgs,
+  buildAsyncRewakeHook,
+  buildStopBlockDecision,
+  shouldReleaseStopBlock,
+};
+
+export default claudeWakeAdapter;