sentinelayer-cli 0.19.0 → 0.21.0

package/src/session/sync.js

@@ -428,6 +428,95 @@ async function fetchWithTimeout(url, options, timeoutMs) {
   }
 }
 
+function isAbortLike(error) {
+  return Boolean(error?.name === "AbortError" || error?.code === "ABORT_ERR");
+}
+
+async function* readResponseTextChunks(response) {
+  const body = response?.body;
+  if (!body) return;
+
+  if (typeof body.getReader === "function") {
+    const reader = body.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value) yield value;
+      }
+    } finally {
+      try {
+        reader.releaseLock();
+      } catch {
+        // Best-effort cleanup only.
+      }
+    }
+    return;
+  }
+
+  if (typeof body[Symbol.asyncIterator] === "function") {
+    for await (const chunk of body) {
+      if (chunk) yield chunk;
+    }
+  }
+}
+
+function extractSseErrorReason(parsed) {
+  const error = parsed?.error && typeof parsed.error === "object" ? parsed.error : {};
+  return (
+    normalizeString(error.code) ||
+    normalizeString(error.message) ||
+    normalizeString(error.detail) ||
+    "session_stream_error"
+  );
+}
+
+async function processSseBlock(block, handlers) {
+  const normalizedBlock = normalizeString(block);
+  if (!normalizedBlock) return;
+
+  const dataLines = [];
+  let commentOnly = true;
+  for (const rawLine of String(block).split("\n")) {
+    const line = rawLine.trimEnd();
+    if (!line) continue;
+    if (line.startsWith(":")) continue;
+    commentOnly = false;
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice(5).trimStart());
+    }
+  }
+
+  if (dataLines.length === 0) {
+    if (commentOnly && typeof handlers.onHeartbeat === "function") {
+      await handlers.onHeartbeat();
+    }
+    return;
+  }
+
+  const rawData = dataLines.join("\n").trim();
+  if (!rawData) return;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(rawData);
+  } catch {
+    await handlers.onError?.({ reason: "malformed_stream_event", cursor: handlers.cursor() });
+    return;
+  }
+
+  if (parsed?.type === "error") {
+    await handlers.onError?.({
+      reason: extractSseErrorReason(parsed),
+      cursor: handlers.cursor(),
+      error: parsed.error || null,
+    });
+    return;
+  }
+
+  await handlers.onEvent?.(parsed);
+}
+
 function sanitizeHumanMessage(rawMessage) {
   const stripped = String(rawMessage || "")
     .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "")
@@ -1131,6 +1220,195 @@ export async function pollSessionEvents(
   }
 }
 
+/**
+ * Consume the API's durable session SSE stream.
+ *
+ * This is the wakeup-first companion to `pollSessionEvents`: the stream uses
+ * Redis wakeups server-side, while the listener can still fall back to durable
+ * `/events` polling if the stream is unavailable or closes.
+ *
+ * @param {string} sessionId
+ * @param {object} [options]
+ * @param {string|null} [options.since] - durable cursor to resume after
+ * @param {AbortSignal} [options.signal]
+ * @param {(event: object) => Promise<void>|void} [options.onEvent]
+ * @param {(payload: object) => Promise<void>|void} [options.onError]
+ * @param {() => Promise<void>|void} [options.onHeartbeat]
+ * @returns {Promise<{ok: boolean, reason: string, cursor: string|null, eventCount: number, errorCount: number, status?: number, aborted?: boolean}>}
+ */
+export async function streamSessionEvents(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    since = null,
+    timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    signal = undefined,
+    resolveAuthSession = resolveActiveAuthSession,
+    fetchImpl = fetch,
+    onEvent = async () => {},
+    onError = async () => {},
+    onHeartbeat = async () => {},
+  } = {}
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedSince = normalizeString(since) || null;
+  if (!normalizedSessionId) {
+    return {
+      ok: false,
+      reason: "invalid_session_id",
+      cursor: normalizedSince,
+      eventCount: 0,
+      errorCount: 0,
+    };
+  }
+
+  let session = null;
+  try {
+    session = await resolveAuthSession({
+      cwd: targetPath,
+      env: process.env,
+      autoRotate: false,
+    });
+  } catch {
+    return {
+      ok: false,
+      reason: "no_session",
+      cursor: normalizedSince,
+      eventCount: 0,
+      errorCount: 0,
+    };
+  }
+  if (!session || !session.token) {
+    return {
+      ok: false,
+      reason: "not_authenticated",
+      cursor: normalizedSince,
+      eventCount: 0,
+      errorCount: 0,
+    };
+  }
+
+  const apiBaseUrl = resolveApiBaseUrl(session);
+  const query = new URLSearchParams();
+  if (normalizedSince) {
+    query.set("after", normalizedSince);
+  }
+  const suffix = query.toString() ? `?${query.toString()}` : "";
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/stream${suffix}`;
+  const controller = new AbortController();
+  const normalizedTimeoutMs = normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS);
+  const timeoutHandle = setTimeout(() => controller.abort(), normalizedTimeoutMs);
+  if (typeof timeoutHandle.unref === "function") {
+    timeoutHandle.unref();
+  }
+  const forwardAbort = () => controller.abort(signal?.reason);
+  if (signal) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+    } else {
+      signal.addEventListener("abort", forwardAbort, { once: true });
+    }
+  }
+
+  let response;
+  try {
+    response = await fetchImpl(
+      endpoint,
+      {
+        method: "GET",
+        headers: {
+          Accept: "text/event-stream",
+          Authorization: `Bearer ${session.token}`,
+        },
+        signal: controller.signal,
+      },
+      normalizedTimeoutMs
+    );
+  } catch (error) {
+    clearTimeout(timeoutHandle);
+    if (signal) signal.removeEventListener("abort", forwardAbort);
+    return {
+      ok: false,
+      reason: isAbortLike(error) || signal?.aborted ? "aborted" : normalizeString(error?.message) || "stream_failed",
+      cursor: normalizedSince,
+      eventCount: 0,
+      errorCount: 0,
+      aborted: Boolean(signal?.aborted || isAbortLike(error)),
+    };
+  }
+  clearTimeout(timeoutHandle);
+
+  let cursor = normalizedSince;
+  let eventCount = 0;
+  let errorCount = 0;
+  let lastErrorReason = "";
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  const handlers = {
+    cursor: () => cursor,
+    onHeartbeat,
+    onError: async (payload) => {
+      errorCount += 1;
+      lastErrorReason = normalizeString(payload?.reason) || "session_stream_error";
+      await onError(payload);
+    },
+    onEvent: async (event) => {
+      const eventCursor = normalizeString(event?.cursor);
+      if (eventCursor) cursor = eventCursor;
+      eventCount += 1;
+      await onEvent(event);
+    },
+  };
+
+  try {
+    if (!response || !response.ok || !response.body) {
+      return {
+        ok: false,
+        reason: `api_${response ? response.status : "no_response"}`,
+        cursor,
+        eventCount,
+        errorCount,
+        status: response?.status,
+      };
+    }
+
+    for await (const chunk of readResponseTextChunks(response)) {
+      buffer += decoder.decode(chunk, { stream: true });
+      buffer = buffer.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+      const blocks = buffer.split("\n\n");
+      buffer = blocks.pop() || "";
+      for (const block of blocks) {
+        await processSseBlock(block, handlers);
+      }
+    }
+    buffer += decoder.decode();
+    if (normalizeString(buffer)) {
+      await processSseBlock(buffer, handlers);
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      reason: isAbortLike(error) || signal?.aborted ? "aborted" : normalizeString(error?.message) || "stream_failed",
+      cursor,
+      eventCount,
+      errorCount,
+      aborted: Boolean(signal?.aborted || isAbortLike(error)),
+    };
+  } finally {
+    if (signal) signal.removeEventListener("abort", forwardAbort);
+  }
+
+  return {
+    ok: !lastErrorReason,
+    reason: lastErrorReason,
+    cursor,
+    eventCount,
+    errorCount,
+    aborted: Boolean(signal?.aborted),
+  };
+}
+
 /**
  * Poll the latest durable session events page via the reverse-history endpoint.
  *
@@ -1365,6 +1643,123 @@ export async function listSessionMessageActions(
   }
 }
 
+function pinnedEventContentText(event = {}) {
+  const payload = event && typeof event === "object" ? event.payload || {} : {};
+  return (
+    normalizeString(payload.note) ||
+    normalizeString(payload.message) ||
+    normalizeString(payload.text) ||
+    normalizeString(payload.content) ||
+    normalizeString(payload.summary) ||
+    ""
+  );
+}
+
+function pinnedEventAuthorId(event = {}) {
+  const agent = event && typeof event === "object" ? event.agent || {} : {};
+  return normalizeString(agent.id || agent.agentId) || normalizeString(event.agentId) || "";
+}
+
+/**
+ * Resolve the session's active pinned messages, enriched with each pinned
+ * message's author and content so a CLI agent can actually read them (not just
+ * see sequence numbers). Pins come from the action projection
+ * (`projection.pinnedMessages`, capped at `projection.pinLimit`); content is
+ * resolved per pinned sequence via `/events/before`. Bounded by the pin cap
+ * (<= 10), so at most ~10 single-event lookups.
+ */
+export async function fetchSessionPinnedMessages(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    resolveAuthSession = resolveActiveAuthSession,
+    fetchImpl = fetchWithTimeout,
+    nowMs = Date.now,
+    listActions = listSessionMessageActions,
+    fetchEventsBefore = pollSessionEventsBefore,
+  } = {}
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return { ok: false, reason: "invalid_session_id", pins: [], pinLimit: 0, count: 0 };
+  }
+
+  const actionsResult = await listActions(normalizedSessionId, {
+    targetPath,
+    timeoutMs,
+    resolveAuthSession,
+    fetchImpl,
+    nowMs,
+  });
+  if (!actionsResult || !actionsResult.ok) {
+    return {
+      ok: false,
+      reason: normalizeString(actionsResult?.reason) || "actions_read_failed",
+      pins: [],
+      pinLimit: 0,
+      count: 0,
+    };
+  }
+
+  const projection = actionsResult.projection && typeof actionsResult.projection === "object"
+    ? actionsResult.projection
+    : {};
+  const pinLimit = Number(projection.pinLimit) || 0;
+  const pinnedActions = Array.isArray(projection.pinnedMessages) ? projection.pinnedMessages : [];
+
+  const pins = await Promise.all(
+    pinnedActions.map(async (action) => {
+      const targetSequenceId = Number(action?.targetSequenceId) || 0;
+      const base = {
+        targetSequenceId,
+        targetCursor: normalizeString(action?.targetCursor) || null,
+        pinnedBy: normalizeString(action?.actorId) || "",
+        pinnedByKind: normalizeString(action?.actorKind) || "",
+        pinnedAt: normalizeString(action?.createdAt) || "",
+        author: "",
+        content: "",
+        resolved: false,
+      };
+      if (targetSequenceId <= 0) {
+        return base;
+      }
+      const eventsResult = await fetchEventsBefore(normalizedSessionId, {
+        targetPath,
+        beforeSequence: targetSequenceId + 1,
+        limit: 1,
+        timeoutMs,
+        resolveAuthSession,
+        fetchImpl,
+        nowMs,
+      });
+      if (eventsResult && eventsResult.ok && Array.isArray(eventsResult.events)) {
+        const match =
+          eventsResult.events.find(
+            (event) => Number(event?.sequenceId) === targetSequenceId,
+          ) ||
+          eventsResult.events[eventsResult.events.length - 1] ||
+          null;
+        if (match) {
+          base.author = pinnedEventAuthorId(match);
+          base.content = pinnedEventContentText(match);
+          base.resolved = true;
+        }
+      }
+      return base;
+    }),
+  );
+
+  return {
+    ok: true,
+    reason: "",
+    sessionId: normalizedSessionId,
+    pins,
+    pinLimit,
+    count: pins.length,
+  };
+}
+
 export async function createSessionMessageAction(
   sessionId,
   {

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,