sentinelayer-cli 0.17.1 → 0.18.1

package/package.json

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

package/src/cost/tracker.js

@@ -1,6 +1,8 @@
 import { estimateTokens } from "./tokenizer.js";
 
-const DEFAULT_MODEL_PRICING = Object.freeze({
+export const DEFAULT_PRICE_BOOK_VERSION = "2026-05-24";
+
+export const DEFAULT_MODEL_PRICING = Object.freeze({
   "gpt-4o": Object.freeze({
     inputPerMillionUsd: 2.5,
     outputPerMillionUsd: 10.0,

package/src/legacy-cli.js

@@ -2338,11 +2338,18 @@ jobs:
           fi
       - name: Run Omar Gate
         id: omar
-        uses: mrrCarter/sentinelayer-v1-action@4cb3063e04e3b899981b25f6918b26f70d35a8d4
+        uses: mrrCarter/sentinelayer-v1-action@8595c4ad41e7b710ff6b1de0603da6ad8c0c3c07
         with:
+          github_token: \${{ github.token }}
           sentinelayer_token: \${{ secrets.${normalizedSecret} }}${specIdBindingLine}
+          sentinelayer_managed_llm: "false"
+          openai_api_key: \${{ secrets.OPENAI_API_KEY }}
           scan_mode: \${{ github.event_name == 'workflow_dispatch' && inputs.scan_mode || 'deep' }}
           severity_gate: \${{ github.event_name == 'workflow_dispatch' && inputs.severity_gate || 'P1' }}
+          model: gpt-5.3-codex
+          codex_model: gpt-5.3-codex
+          model_fallback: gpt-5.2-codex
+          llm_failure_policy: block
       - name: Enforce Omar reviewer merge thresholds
         shell: bash
         env:

package/src/scan/generator.js

@@ -2,7 +2,7 @@ import YAML from "yaml";
 
 export const DEFAULT_SCAN_WORKFLOW_PATH = ".github/workflows/omar-gate.yml";
 export const DEFAULT_SCAN_SECRET_NAME = "SENTINELAYER_TOKEN";
-export const SENTINELAYER_ACTION_REF = "mrrCarter/sentinelayer-v1-action@4cb3063e04e3b899981b25f6918b26f70d35a8d4";
+export const SENTINELAYER_ACTION_REF = "mrrCarter/sentinelayer-v1-action@8595c4ad41e7b710ff6b1de0603da6ad8c0c3c07";
 export const SUPPORTED_E2E_HINTS = Object.freeze(["auto", "yes", "no"]);
 export const SUPPORTED_PLAYWRIGHT_MODES = Object.freeze(["auto", "off", "baseline", "audit"]);
 
@@ -224,9 +224,16 @@ export function buildSecurityReviewWorkflow({ secretName = DEFAULT_SCAN_SECRET_N
             id: "omar",
             uses: SENTINELAYER_ACTION_REF,
             with: {
+              github_token: "${{ github.token }}",
               sentinelayer_token: `\${{ secrets.${normalizedSecret} }}`,
+              sentinelayer_managed_llm: "false",
+              openai_api_key: "${{ secrets.OPENAI_API_KEY }}",
               scan_mode: profile.scanMode || "deep",
               severity_gate: profile.severityGate || "P1",
+              model: "gpt-5.3-codex",
+              codex_model: "gpt-5.3-codex",
+              model_fallback: "gpt-5.2-codex",
+              llm_failure_policy: "block",
               playwright_mode: profile.playwrightMode || "off",
               sbom_mode: profile.sbomMode || "off",
               wait_for_completion: "true",

package/src/session/pricing-ledger.js

@@ -0,0 +1,272 @@
+import { createHash } from "node:crypto";
+
+import {
+  DEFAULT_PRICE_BOOK_VERSION,
+  estimateModelCost,
+} from "../cost/tracker.js";
+
+const SESSION_USAGE_EVENT = "session_usage";
+export const BILLING_SESSION_USAGE_SCHEMA = "billing/v1";
+export const LOCAL_SESSION_USAGE_SCHEMA = "session_usage/local-v1";
+const LEGACY_SESSION_USAGE_SCHEMAS = new Set(["", "session_usage/v0"]);
+const SUPPORTED_SESSION_USAGE_SCHEMAS = new Set([
+  BILLING_SESSION_USAGE_SCHEMA,
+  LOCAL_SESSION_USAGE_SCHEMA,
+  ...LEGACY_SESSION_USAGE_SCHEMAS,
+]);
+
+function n(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+function object(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function nonNegativeNumber(value) {
+  if (value == null || value === "") return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+}
+
+function nonNegativeInt(value) {
+  const parsed = nonNegativeNumber(value);
+  return parsed == null ? null : Math.floor(parsed);
+}
+
+function money(value) {
+  const parsed = nonNegativeNumber(value);
+  return parsed == null ? null : Math.round(parsed * 1_000_000) / 1_000_000;
+}
+
+function pick(sources, keys) {
+  for (const source of sources) {
+    const bag = object(source);
+    for (const key of keys) {
+      if (bag[key] != null && bag[key] !== "") return bag[key];
+    }
+  }
+  return null;
+}
+
+function pickText(sources, keys) {
+  return n(pick(sources, keys));
+}
+
+function pickInt(sources, keys) {
+  return nonNegativeInt(pick(sources, keys)) ?? 0;
+}
+
+function pickMoney(sources, keys) {
+  return money(pick(sources, keys));
+}
+
+function roundUsd(value) {
+  return Math.round(Number(value || 0) * 1_000_000) / 1_000_000;
+}
+
+export function createSessionUsageLedgerId({
+  sessionId = "",
+  agentId = "",
+  action = "",
+  idempotencyKey = "",
+} = {}) {
+  const digest = createHash("sha256")
+    .update([sessionId, agentId, action, idempotencyKey].map(n).join("\x1f"))
+    .digest("hex")
+    .slice(0, 32);
+  return `bill_${digest}`;
+}
+
+function fallbackIdempotencyKey({ sessionId, event, agentId, action, model, totalTokens }) {
+  const sequence = n(event.sequenceId ?? event.sequence_id);
+  if (sequence) return `seq:${sequence}`;
+  const timestamp = n(event.ts || event.timestamp);
+  const interaction = n(object(event.payload).interactionId || object(event.payload).interaction_id);
+  const source = [sessionId, timestamp, agentId, action, model, totalTokens, interaction].join("\x1f");
+  return `event:${createHash("sha256").update(source).digest("hex").slice(0, 32)}`;
+}
+
+function providerCostFromPriceBook({ model, inputTokens, outputTokens, explicitProviderCost }) {
+  if (explicitProviderCost != null) {
+    return { providerCostUsd: explicitProviderCost, unpriced: false };
+  }
+  if (inputTokens <= 0 && outputTokens <= 0) {
+    return { providerCostUsd: 0, unpriced: false };
+  }
+  try {
+    return {
+      providerCostUsd: estimateModelCost({ modelId: model, inputTokens, outputTokens }),
+      unpriced: false,
+    };
+  } catch {
+    return { providerCostUsd: 0, unpriced: true };
+  }
+}
+
+export function buildUsageLedgerEntry(
+  event,
+  { sessionId = "", priceBookVersion = DEFAULT_PRICE_BOOK_VERSION, billingTier = "unknown" } = {},
+) {
+  const kind = n(event?.event || event?.type);
+  if (kind !== SESSION_USAGE_EVENT) return null;
+
+  const payload = object(event?.payload);
+  const schema = n(payload.schema);
+  if (!SUPPORTED_SESSION_USAGE_SCHEMAS.has(schema)) return null;
+
+  const usage = object(payload.usage);
+  const prompt = object(payload.prompt);
+  const response = object(payload.response);
+  const agent = object(event?.agent);
+  const sources = [payload, usage];
+
+  const agentId =
+    pickText(sources, ["agentId", "agent_id"]) ||
+    n(agent.id || event?.agentId) ||
+    "unknown";
+  const model =
+    pickText(sources, ["model", "modelId", "model_id"]) ||
+    n(agent.model || event?.agentModel) ||
+    "unknown";
+  const action =
+    pickText(sources, ["action", "operation", "kind", "billingAction", "billing_action"]) ||
+    "agent_message";
+  const resolvedPriceBook =
+    pickText(sources, ["priceBookVersion", "price_book_version", "pricingVersion", "pricing_version"]) ||
+    priceBookVersion;
+  const resolvedBillingTier =
+    pickText(sources, ["billingTier", "billing_tier", "tier"]) ||
+    n(billingTier) ||
+    "unknown";
+
+  const inputTokens =
+    pickInt(sources, ["inputTokens", "input_tokens", "tokensIn", "tokens_in", "promptTokens", "prompt_tokens"]) ||
+    pickInt([prompt], ["tokens", "tokenCount", "token_count"]);
+  const outputTokens =
+    pickInt(sources, ["outputTokens", "output_tokens", "tokensOut", "tokens_out", "completionTokens", "completion_tokens"]) ||
+    pickInt([response], ["tokens", "tokenCount", "token_count"]);
+  const explicitTotalTokens = pickInt(sources, ["totalTokens", "total_tokens", "tokens", "tokenTotal", "token_total"]);
+  const totalTokens = explicitTotalTokens || inputTokens + outputTokens;
+  const explicitProviderCost = pickMoney(sources, ["providerCostUsd", "provider_cost_usd", "costUsd", "cost_usd", "cost"]);
+  const customerCostUsd = pickMoney(sources, ["customerCostUsd", "customer_cost_usd", "billableCostUsd", "billable_cost_usd"]);
+  const { providerCostUsd, unpriced } = providerCostFromPriceBook({
+    model,
+    inputTokens,
+    outputTokens,
+    explicitProviderCost,
+  });
+
+  const idempotencyKey =
+    pickText(sources, ["idempotencyKey", "idempotency_key", "runKey", "run_key"]) ||
+    pickText(sources, ["interactionId", "interaction_id"]) ||
+    fallbackIdempotencyKey({ sessionId, event, agentId, action, model, totalTokens });
+  const ledgerEntryId =
+    pickText(sources, ["ledgerEntryId", "ledger_entry_id", "billingEventId", "billing_event_id"]) ||
+    createSessionUsageLedgerId({ sessionId, agentId, action, idempotencyKey });
+
+  return {
+    ledgerEntryId,
+    idempotencyKey,
+    schema: schema || "legacy",
+    sessionId: n(sessionId),
+    agentId,
+    action,
+    model,
+    priceBookVersion: resolvedPriceBook,
+    billingTier: resolvedBillingTier,
+    provider: pickText(sources, ["provider", "providerName", "provider_name"]),
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    providerCostUsd: roundUsd(providerCostUsd),
+    customerCostUsd,
+    unpriced,
+    timestamp: n(event?.ts || event?.timestamp),
+    sequenceId: nonNegativeInt(event?.sequenceId ?? event?.sequence_id),
+  };
+}
+
+function newRollup(label) {
+  return {
+    label,
+    entries: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+    providerCostUsd: 0,
+    customerCostUsd: 0,
+    hasCustomerCost: false,
+    unpriced: 0,
+  };
+}
+
+function addToRollup(rollup, entry) {
+  rollup.entries += 1;
+  rollup.inputTokens += entry.inputTokens;
+  rollup.outputTokens += entry.outputTokens;
+  rollup.totalTokens += entry.totalTokens;
+  rollup.providerCostUsd += entry.providerCostUsd;
+  if (entry.customerCostUsd != null) {
+    rollup.customerCostUsd += entry.customerCostUsd;
+    rollup.hasCustomerCost = true;
+  }
+  if (entry.unpriced) rollup.unpriced += 1;
+}
+
+function finalizeRollup(rollup) {
+  rollup.providerCostUsd = roundUsd(rollup.providerCostUsd);
+  rollup.customerCostUsd = roundUsd(rollup.customerCostUsd);
+  return rollup;
+}
+
+export function buildSessionUsageLedger(events = [], options = {}) {
+  if (!Array.isArray(events)) {
+    throw new Error("events must be an array.");
+  }
+  const entries = [];
+  const totals = newRollup("session");
+  const perAgent = new Map();
+  const perAction = new Map();
+  const priceBookVersions = new Set();
+  const seenKeys = new Set();
+  let duplicatesSkipped = 0;
+
+  for (const event of events) {
+    const entry = buildUsageLedgerEntry(event, options);
+    if (!entry) continue;
+    const dedupeKeys = [
+      entry.idempotencyKey ? `idem:${entry.idempotencyKey}` : "",
+      entry.ledgerEntryId ? `ledger:${entry.ledgerEntryId}` : "",
+    ].filter(Boolean);
+    if (dedupeKeys.some((dedupeKey) => seenKeys.has(dedupeKey))) {
+      duplicatesSkipped += 1;
+      continue;
+    }
+    for (const dedupeKey of dedupeKeys) seenKeys.add(dedupeKey);
+    entries.push(entry);
+    priceBookVersions.add(entry.priceBookVersion);
+    addToRollup(totals, entry);
+
+    if (!perAgent.has(entry.agentId)) perAgent.set(entry.agentId, newRollup(entry.agentId));
+    addToRollup(perAgent.get(entry.agentId), entry);
+
+    if (!perAction.has(entry.action)) perAction.set(entry.action, newRollup(entry.action));
+    addToRollup(perAction.get(entry.action), entry);
+  }
+
+  finalizeRollup(totals);
+  for (const rollup of perAgent.values()) finalizeRollup(rollup);
+  for (const rollup of perAction.values()) finalizeRollup(rollup);
+
+  return {
+    entries,
+    totals,
+    perAgent,
+    perAction,
+    priceBookVersions: [...priceBookVersions].sort(),
+    duplicatesSkipped,
+  };
+}
+
+export { DEFAULT_PRICE_BOOK_VERSION };

package/src/session/usage.js

@@ -1,13 +1,20 @@
 /**
- * Session usage emitter — records every LLM interaction inside a session
- * as a `session_usage` event so consumers (web dashboard, transcript
- * download, telemetry sync) can surface live, accurate token + cost
- * counters per-agent + session-wide.
+ * Session usage emitter — records local transcript/live-stats LLM
+ * interactions inside a session as `session_usage` events so consumers
+ * (web dashboard, transcript download, local recap) can surface live token
+ * + cost counters per-agent + session-wide.
  *
  * Senti orchestrator philosophy: "tokens on point every time any LLM
  * interacts." Every persona / Jules / Codex / Claude call inside a
  * session should land here so the running tally is authoritative.
  *
+ * Important contract split: this module is NOT the API billing ledger.
+ * API-durable billable rows must go through `src/billing/session-usage.js`
+ * and emit `payload.schema = "billing/v1"` with the API-supported price
+ * book. This module emits `session_usage/local-v1`, which is intentionally
+ * ignored by API quota/billing projection while still remaining visible in
+ * transcripts and local aggregate counters.
+ *
  * Event shape:
  *
  *   {
@@ -41,6 +48,13 @@ import process from "node:process";
 import { randomUUID } from "node:crypto";
 
 import { createAgentEvent } from "../events/schema.js";
+import { estimateModelCost } from "../cost/tracker.js";
+import {
+  DEFAULT_PRICE_BOOK_VERSION,
+  LOCAL_SESSION_USAGE_SCHEMA,
+  buildSessionUsageLedger,
+  createSessionUsageLedgerId,
+} from "./pricing-ledger.js";
 import { resolveSessionPaths } from "./paths.js";
 import { appendToStream } from "./stream.js";
 
@@ -55,19 +69,8 @@ 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 money(value) {
+  return Math.round(num(value) * 1_000_000) / 1_000_000;
 }
 
 function clipText(text, max = 4000) {
@@ -76,6 +79,17 @@ function clipText(text, max = 4000) {
   return `${s.slice(0, max)}…`;
 }
 
+function computedCost({ model, inputTokens, outputTokens }) {
+  try {
+    return {
+      costUsd: estimateModelCost({ modelId: model, inputTokens, outputTokens }),
+      unpriced: false,
+    };
+  } catch {
+    return { costUsd: 0, unpriced: inputTokens + outputTokens > 0 };
+  }
+}
+
 /**
  * Emit a `session_usage` event into the session's NDJSON stream.
  *
@@ -87,7 +101,12 @@ function clipText(text, max = 4000) {
  * @param {number} [params.inputTokens]
  * @param {number} [params.outputTokens]
  * @param {number} [params.costUsd]
+ * @param {number} [params.customerCostUsd]
  * @param {number} [params.durationMs]
+ * @param {string} [params.action]
+ * @param {string} [params.provider]
+ * @param {string} [params.billingTier]
+ * @param {string} [params.priceBookVersion]
  * @param {string} [params.prompt]            full prompt text (clipped)
  * @param {string} [params.response]          full response text (clipped)
  * @param {string} [params.interactionId]     opaque id for cross-event correlation
@@ -102,8 +121,13 @@ export async function emitLLMInteraction(
     role = "",
     inputTokens = 0,
     outputTokens = 0,
-    costUsd = 0,
+    costUsd = undefined,
+    customerCostUsd = undefined,
     durationMs = 0,
+    action = "agent_message",
+    provider = "",
+    billingTier = "unknown",
+    priceBookVersion = DEFAULT_PRICE_BOOK_VERSION,
     prompt = "",
     response = "",
     interactionId = "",
@@ -121,20 +145,45 @@ export async function emitLLMInteraction(
   const inT = Math.floor(num(inputTokens));
   const outT = Math.floor(num(outputTokens));
   const totalT = inT + outT;
-  const cost = Math.round(num(costUsd) * 1_000_000) / 1_000_000;
+  const model = n(agentModel) || "unknown";
+  const providedCost = costUsd != null && costUsd !== "";
+  const estimate = providedCost
+    ? { costUsd: num(costUsd), unpriced: false }
+    : computedCost({ model, inputTokens: inT, outputTokens: outT });
+  const cost = money(estimate.costUsd);
+  const customerCost = customerCostUsd == null || customerCostUsd === "" ? null : money(customerCostUsd);
+  const actionName = n(action) || "agent_message";
+  const tier = n(billingTier) || "unknown";
+  const priceBook = n(priceBookVersion) || DEFAULT_PRICE_BOOK_VERSION;
+  const ledgerEntryId = createSessionUsageLedgerId({
+    sessionId: paths.sessionId,
+    agentId: aid,
+    action: actionName,
+    idempotencyKey: id,
+  });
 
   const promptText = clipText(prompt);
   const responseText = clipText(response);
 
   const payload = {
+    schema: LOCAL_SESSION_USAGE_SCHEMA,
     interactionId: id,
+    idempotencyKey: id,
+    ledgerEntryId,
     agentId: aid,
-    model: n(agentModel) || "unknown",
+    model,
     role: n(role) || "observer",
+    action: actionName,
+    provider: n(provider) || undefined,
+    billingTier: tier,
+    priceBookVersion: priceBook,
     inputTokens: inT,
     outputTokens: outT,
     totalTokens: totalT,
     costUsd: cost,
+    providerCostUsd: cost,
+    customerCostUsd: customerCost ?? undefined,
+    unpriced: estimate.unpriced,
     durationMs: Math.max(0, Math.floor(num(durationMs))),
     prompt: { tokens: inT, chars: promptText.length },
     response: {
@@ -147,15 +196,24 @@ export async function emitLLMInteraction(
     usage: {
       totalTokens: totalT,
       costUsd: cost,
+      providerCostUsd: cost,
+      customerCostUsd: customerCost ?? undefined,
       inputTokens: inT,
       outputTokens: outT,
+      action: actionName,
+      provider: n(provider) || undefined,
+      billingTier: tier,
+      priceBookVersion: priceBook,
+      ledgerEntryId,
+      idempotencyKey: id,
+      unpriced: estimate.unpriced,
     },
   };
 
   const envelope = createAgentEvent({
     event: SESSION_USAGE_EVENT,
     agentId: aid,
-    agentModel: n(agentModel) || "unknown",
+    agentModel: model,
     sessionId: paths.sessionId,
     payload,
     ts,
@@ -165,6 +223,7 @@ export async function emitLLMInteraction(
   return {
     event: SESSION_USAGE_EVENT,
     interactionId: id,
+    ledgerEntryId,
     totalTokens: totalT,
     costUsd: cost,
   };
@@ -181,6 +240,7 @@ export async function emitLLMInteraction(
  * }}
  */
 export function aggregateSessionUsage(events = []) {
+  const ledger = buildSessionUsageLedger(events);
   const perAgent = new Map();
   const totals = {
     totalTokens: 0,
@@ -189,37 +249,8 @@ export function aggregateSessionUsage(events = []) {
     costUsd: 0,
     interactions: 0,
   };
-  for (const event of events) {
-    if (!event || event.event !== SESSION_USAGE_EVENT) continue;
-    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",
-    ]);
+  for (const entry of ledger.entries) {
+    const { agentId, model, inputTokens, outputTokens, totalTokens, providerCostUsd } = entry;
     if (!perAgent.has(agentId)) {
       perAgent.set(agentId, {
         agentId,
@@ -238,13 +269,13 @@ export function aggregateSessionUsage(events = []) {
     record.totalTokens += totalTokens;
     record.inputTokens += inputTokens;
     record.outputTokens += outputTokens;
-    record.costUsd += costUsd;
+    record.costUsd += providerCostUsd;
     record.interactions += 1;
 
     totals.totalTokens += totalTokens;
     totals.inputTokens += inputTokens;
     totals.outputTokens += outputTokens;
-    totals.costUsd += costUsd;
+    totals.costUsd += providerCostUsd;
     totals.interactions += 1;
   }
   totals.costUsd = Math.round(totals.costUsd * 1_000_000) / 1_000_000;