sentinelayer-cli 0.34.6 → 0.35.0

package/src/session/sync.js

@@ -1479,6 +1479,7 @@ export async function pollSessionEvents(
  * @param {object} [options]
  * @param {string|null} [options.since] - durable cursor to resume after
  * @param {AbortSignal} [options.signal]
+ * @param {number} [options.idleTimeoutMs] - abort a connected stream after this many silent milliseconds
  * @param {(event: object) => Promise<void>|void} [options.onEvent]
  * @param {(payload: object) => Promise<void>|void} [options.onError]
  * @param {() => Promise<void>|void} [options.onHeartbeat]
@@ -1490,6 +1491,7 @@ export async function streamSessionEvents(
     targetPath = process.cwd(),
     since = null,
     timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    idleTimeoutMs = 0,
     signal = undefined,
     resolveAuthSession = resolveActiveAuthSession,
     fetchImpl = fetch,
@@ -1545,10 +1547,26 @@ export async function streamSessionEvents(
   const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/stream${suffix}`;
   const controller = new AbortController();
   const normalizedTimeoutMs = normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS);
+  const normalizedIdleTimeoutMs = normalizePositiveInteger(idleTimeoutMs, 0);
   const timeoutHandle = setTimeout(() => controller.abort(), normalizedTimeoutMs);
   if (typeof timeoutHandle.unref === "function") {
     timeoutHandle.unref();
   }
+  let idleTimeoutHandle = null;
+  let idleTimedOut = false;
+  const clearIdleTimeout = () => {
+    if (!idleTimeoutHandle) return;
+    clearTimeout(idleTimeoutHandle);
+    idleTimeoutHandle = null;
+  };
+  const armIdleTimeout = () => {
+    if (!normalizedIdleTimeoutMs) return;
+    clearIdleTimeout();
+    idleTimeoutHandle = setTimeout(() => {
+      idleTimedOut = true;
+      controller.abort();
+    }, normalizedIdleTimeoutMs);
+  };
   const forwardAbort = () => controller.abort(signal?.reason);
   if (signal) {
     if (signal.aborted) {
@@ -1574,10 +1592,13 @@ export async function streamSessionEvents(
     );
   } catch (error) {
     clearTimeout(timeoutHandle);
+    clearIdleTimeout();
     if (signal) signal.removeEventListener("abort", forwardAbort);
     return {
       ok: false,
-      reason: isAbortLike(error) || signal?.aborted ? "aborted" : normalizeString(error?.message) || "stream_failed",
+      reason: idleTimedOut
+        ? "stream_idle_timeout"
+        : isAbortLike(error) || signal?.aborted ? "aborted" : normalizeString(error?.message) || "stream_failed",
       cursor: normalizedSince,
       eventCount: 0,
       errorCount: 0,
@@ -1621,7 +1642,9 @@ export async function streamSessionEvents(
       };
     }
 
+    armIdleTimeout();
     for await (const chunk of readResponseTextChunks(response)) {
+      armIdleTimeout();
       buffer += decoder.decode(chunk, { stream: true });
       buffer = buffer.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
       const blocks = buffer.split("\n\n");
@@ -1637,13 +1660,16 @@ export async function streamSessionEvents(
   } catch (error) {
     return {
       ok: false,
-      reason: isAbortLike(error) || signal?.aborted ? "aborted" : normalizeString(error?.message) || "stream_failed",
+      reason: idleTimedOut
+        ? "stream_idle_timeout"
+        : isAbortLike(error) || signal?.aborted ? "aborted" : normalizeString(error?.message) || "stream_failed",
       cursor,
       eventCount,
       errorCount,
       aborted: Boolean(signal?.aborted || isAbortLike(error)),
     };
   } finally {
+    clearIdleTimeout();
     if (signal) signal.removeEventListener("abort", forwardAbort);
   }
 

package/src/session/transcript.js

@@ -425,6 +425,7 @@ export function computeTranscriptStats({
       usageEntries: resolvedUsageLedger.entries.length,
       duplicatesSkipped: resolvedUsageLedger.duplicatesSkipped,
       unpriced: resolvedUsageLedger.totals.unpriced,
+      estimatedEntries: resolvedUsageLedger.totals.estimatedEntries,
       priceBookVersions: resolvedUsageLedger.priceBookVersions,
     },
     sentiActions,
@@ -504,6 +505,12 @@ function rollupsByCostAndTokens(map) {
   ));
 }
 
+function estimateNote(count) {
+  const normalized = Math.max(0, Math.floor(Number(count || 0)));
+  if (normalized <= 0) return "";
+  return `${normalized.toLocaleString("en-US")} estimated`;
+}
+
 function recentUsageEntries(entries, limit = 10) {
   return entries
     .map((entry, index) => ({ entry, index }))
@@ -561,7 +568,15 @@ function appendUsageLedgerSection(lines, usageLedger) {
   );
   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)}`);
+  const estimateText = totals.estimatedEntries > 0
+    ? ` · Estimated entries: ${intCell(totals.estimatedEntries)}`
+    : "";
+  lines.push(
+    `Duplicates skipped: ${intCell(usageLedger.duplicatesSkipped)} · Unpriced entries: ${intCell(totals.unpriced)}${estimateText}`,
+  );
+  if (totals.estimatedEntries > 0) {
+    lines.push("_Estimated entries are output-text estimates from non-human session messages, not billing-grade provider usage._");
+  }
   lines.push("");
 
   appendUsageRollupTable(lines, {
@@ -580,8 +595,11 @@ function appendUsageLedgerSection(lines, usageLedger) {
   lines.push("| Time | Agent | Action | Model | Tokens | Provider cost | Customer cost | Idempotency key |");
   lines.push("|---|---|---|---|---:|---:|---:|---|");
   for (const entry of recentUsageEntries(usageLedger.entries)) {
+    const action = entry.estimated
+      ? `${entry.action} (${estimateNote(1)})`
+      : entry.action;
     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))} |`,
+      `| ${tableText(timestampOnly(entry.timestamp)) || "—"} | ${codeCell(entry.agentId)} | ${codeCell(action)} | ${codeCell(entry.model)} | ${intCell(entry.totalTokens)} | ${usdCell(entry.providerCostUsd)} | ${optionalUsdCell(entry.customerCostUsd, entry.customerCostUsd != null)} | ${codeCell(shortenIdempotencyKey(entry.idempotencyKey))} |`,
     );
   }
   lines.push("");
@@ -608,8 +626,10 @@ export function buildTranscriptMarkdown({
   speakerProfiles = new Map(),
   options = {},
 } = {}) {
+  const estimateMessageUsage = options.estimateMessageUsage !== false;
   const usageLedger = buildSessionUsageLedger(events, {
     sessionId: normalize(sessionMeta.sessionId),
+    includeEstimatedMessages: estimateMessageUsage,
   });
   const includeSystemEvents = options.includeSystemEvents !== false;
   const stats = computeTranscriptStats({ sessionMeta, events, speakerProfiles, usageLedger });
@@ -628,8 +648,12 @@ export function buildTranscriptMarkdown({
       stats.totals.customerCostTotalUsd == null
         ? ""
         : ` · Billable: $${stats.totals.customerCostTotalUsd.toFixed(4)}`;
+    const estimatedText =
+      stats.totals.estimatedEntries > 0
+        ? ` · Estimated entries: ${stats.totals.estimatedEntries.toLocaleString("en-US")}`
+        : "";
     lines.push(
-      `Tokens: ${stats.totals.tokenTotal.toLocaleString("en-US")} · Cost: $${stats.totals.costTotalUsd.toFixed(4)}${billableText}`,
+      `Tokens: ${stats.totals.tokenTotal.toLocaleString("en-US")} · Cost: $${stats.totals.costTotalUsd.toFixed(4)}${billableText}${estimatedText}`,
     );
   }
   lines.push("");

package/src/session/usage-report.js

@@ -116,6 +116,7 @@ function rollupToJson(rollup) {
     providerCostUsd: rollup.providerCostUsd,
     customerCostUsd: rollup.hasCustomerCost ? rollup.customerCostUsd : null,
     unpriced: rollup.unpriced,
+    estimatedEntries: rollup.estimatedEntries || 0,
   };
 }
 
@@ -133,6 +134,7 @@ function hostedRollupToJson(rollup, fallbackLabel = "") {
       ? money(bag.customerCostUsd ?? bag.customer_cost_usd ?? bag.billableCostUsd ?? bag.billable_cost_usd) ?? 0
       : null,
     unpriced: nonNegativeInt(bag.unpriced),
+    estimatedEntries: nonNegativeInt(bag.estimatedEntries ?? bag.estimated_entries),
   };
 }
 
@@ -155,6 +157,7 @@ function entryToJson(entry) {
     providerCostUsd: entry.providerCostUsd,
     customerCostUsd: entry.customerCostUsd,
     unpriced: entry.unpriced,
+    estimated: Boolean(entry.estimated),
   };
 }
 
@@ -181,6 +184,7 @@ function hostedEntryToJson(entry) {
     providerCostUsd: money(bag.providerCostUsd ?? bag.provider_cost_usd ?? bag.costUsd ?? bag.cost_usd ?? bag.cost) ?? 0,
     customerCostUsd: money(bag.customerCostUsd ?? bag.customer_cost_usd ?? bag.billableCostUsd ?? bag.billable_cost_usd),
     unpriced: Boolean(bag.unpriced),
+    estimated: Boolean(bag.estimated),
   };
 }
 
@@ -214,8 +218,12 @@ export function buildSessionUsageReport({
   sessionId = "",
   events = [],
   recentLimit = DEFAULT_RECENT_LIMIT,
+  estimateMessageUsage = true,
 } = {}) {
-  const ledger = buildSessionUsageLedger(events, { sessionId: normalize(sessionId) });
+  const ledger = buildSessionUsageLedger(events, {
+    sessionId: normalize(sessionId),
+    includeEstimatedMessages: estimateMessageUsage,
+  });
   const limit = clampRecentLimit(recentLimit);
   return {
     schema: SESSION_USAGE_REPORT_SCHEMA,
@@ -230,6 +238,7 @@ export function buildSessionUsageReport({
       providerCostUsd: ledger.totals.providerCostUsd,
       customerCostUsd: ledger.totals.hasCustomerCost ? ledger.totals.customerCostUsd : null,
       unpriced: ledger.totals.unpriced,
+      estimatedEntries: ledger.totals.estimatedEntries || 0,
       priceBookVersions: ledger.priceBookVersions,
     },
     perAgent: sortRollups(ledger.perAgent).map(rollupToJson),
@@ -281,6 +290,7 @@ export function buildSessionUsageReportFromLedgerPayload({
       providerCostUsd: totals.providerCostUsd,
       customerCostUsd: totals.customerCostUsd,
       unpriced: totals.unpriced,
+      estimatedEntries: nonNegativeInt(source.estimatedEntries ?? source.estimated_entries ?? sourceTotals.estimatedEntries ?? sourceTotals.estimated_entries),
       priceBookVersions: resolvedPriceBookVersions,
     },
     perAgent: sourceArray(
@@ -343,7 +353,12 @@ export function renderSessionUsageMarkdown(report = {}) {
     `Provider cost: ${usdCell(totals.providerCostUsd)} - Customer cost: ${optionalUsdCell(totals.customerCostUsd, totals.customerCostUsd != null)}`,
   );
   lines.push(`Price books: ${(totals.priceBookVersions || []).map(tableText).filter(Boolean).join(", ") || "-"}`);
-  lines.push(`Duplicates skipped: ${intCell(totals.duplicatesSkipped)} - Unpriced entries: ${intCell(totals.unpriced)}`);
+  lines.push(
+    `Duplicates skipped: ${intCell(totals.duplicatesSkipped)} - Unpriced entries: ${intCell(totals.unpriced)} - Estimated entries: ${intCell(totals.estimatedEntries)}`,
+  );
+  if (totals.estimatedEntries > 0) {
+    lines.push("_Estimated entries are output-text estimates from non-human session messages, not billing-grade provider usage._");
+  }
   lines.push("");
 
   appendRollupTable(lines, {
@@ -366,8 +381,9 @@ export function renderSessionUsageMarkdown(report = {}) {
     lines.push(`| - | - | - | - | 0 | ${usdCell(0)} | - | - | - |`);
   } else {
     for (const entry of entries) {
+      const action = entry.estimated ? `${entry.action} (estimated)` : entry.action;
       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(entry.ledgerEntryId)} | ${codeCell(entry.idempotencyKeyHash)} |`,
+        `| ${tableText(timestampOnly(entry.timestamp)) || "-"} | ${codeCell(entry.agentId)} | ${codeCell(action)} | ${codeCell(entry.model)} | ${intCell(entry.totalTokens)} | ${usdCell(entry.providerCostUsd)} | ${optionalUsdCell(entry.customerCostUsd, entry.customerCostUsd != null)} | ${codeCell(entry.ledgerEntryId)} | ${codeCell(entry.idempotencyKeyHash)} |`,
       );
     }
   }
@@ -387,6 +403,9 @@ export function renderSessionUsageSummary(report = {}) {
   lines.push(
     `priceBooks=${(totals.priceBookVersions || []).map(tableText).filter(Boolean).join(",") || "-"} duplicatesSkipped=${intCell(totals.duplicatesSkipped)} unpriced=${intCell(totals.unpriced)}`,
   );
+  if (totals.estimatedEntries > 0) {
+    lines.push(`estimatedEntries=${intCell(totals.estimatedEntries)} (output-text estimates; not billing-grade)`);
+  }
   const agents = Array.isArray(report.perAgent) ? report.perAgent.slice(0, 8) : [];
   if (agents.length) {
     lines.push("");
@@ -403,7 +422,7 @@ export function renderSessionUsageSummary(report = {}) {
     lines.push("Recent:");
     for (const entry of entries) {
       lines.push(
-        `- ${timestampOnly(entry.timestamp) || "-"} ${entry.agentId} ${entry.action} ${intCell(entry.totalTokens)} tokens ${usdCell(entry.providerCostUsd)} ledger=${entry.ledgerEntryId}`,
+        `- ${timestampOnly(entry.timestamp) || "-"} ${entry.agentId} ${entry.action}${entry.estimated ? " (estimated)" : ""} ${intCell(entry.totalTokens)} tokens ${usdCell(entry.providerCostUsd)} ledger=${entry.ledgerEntryId}`,
       );
     }
   }

package/src/session/usage.js

@@ -241,8 +241,8 @@ export async function emitLLMInteraction(
  *   totals: { totalTokens, inputTokens, outputTokens, costUsd, interactions },
  * }}
  */
-export function aggregateSessionUsage(events = []) {
-  const ledger = buildSessionUsageLedger(events);
+export function aggregateSessionUsage(events = [], options = {}) {
+  const ledger = buildSessionUsageLedger(events, options);
   const perAgent = new Map();
   const totals = {
     totalTokens: 0,