sentinelayer-cli 0.28.3 → 0.29.0

package/package.json

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

package/src/commands/omargate.js

@@ -20,6 +20,8 @@ export function registerOmarGateCommand(program, invokeLegacy) {
     .option("--model <id>", "LLM model override (default: gpt-5.3-codex)")
     .option("--provider <name>", "LLM provider: sentinelayer, openai, anthropic")
     .option("--max-cost <usd>", "Maximum AI layer cost in USD (default: 5.0)")
+    .option("--notify-session <session-id>", "Write Omar Deep billing-grade usage entries into this Senti session")
+    .option("--require-usage-ledger", "Fail if Omar Deep AI calls cannot write billing-grade session_usage")
     .option("--persona <csv>", "Only run these personas (comma-separated IDs); unknown IDs are dropped + warned")
     .option("--skip-persona <csv>", "Skip these personas (comma-separated IDs)")
     .option("--stream", "Emit NDJSON events to stdout as personas run")

package/src/legacy-cli.js

@@ -1298,6 +1298,8 @@ async function runLocalOmarGateCommand(args) {
   const maxCostUsd = parseFloat(getCommandOptionValue(args, "--max-cost") || "5.0") || 5.0;
   const modelOverride = getCommandOptionValue(args, "--model") || "";
   const providerOverride = getCommandOptionValue(args, "--provider") || "";
+  const notifySession = getCommandOptionValue(args, "--notify-session") || "";
+  const requireUsageLedger = hasCommandOption(args, "--require-usage-ledger");
   const scanMode = getCommandOptionValue(args, "--scan-mode") || "deep";
   const maxParallel = parseInt(getCommandOptionValue(args, "--max-parallel") || "4", 10) || 4;
   const streamEnabled = hasCommandOption(args, "--stream");
@@ -1388,6 +1390,8 @@ async function runLocalOmarGateCommand(args) {
         onEvent: streamHandler,
         includeOnly: includeOnly.length > 0 ? includeOnly : null,
         skipPersonas: skipPersonas.length > 0 ? skipPersonas : null,
+        usageSessionId: notifySession,
+        requireUsageLedger,
       });
 
       // Use orchestrator results as the AI layer. aiResult represents ONLY
@@ -1415,6 +1419,7 @@ async function runLocalOmarGateCommand(args) {
           status: p.status,
           findings: p.findings || 0,
           costUsd: p.costUsd || 0,
+          billing: p.billing || null,
           durationMs: p.durationMs || 0,
           error: p.error || null,
         })),
@@ -1445,8 +1450,17 @@ async function runLocalOmarGateCommand(args) {
         outputDir: outputDirArg,
         provider: providerOverride || undefined,
         model: modelOverride || undefined,
+        sessionId: notifySession,
         maxCostUsd,
         dryRun: aiDryRun,
+        requireUsageLedger,
+        sourceCommand: "omargate deep",
+        billingAgentId: "omargate-orchestrator",
+        billingAction: "omargate_deep",
+        billingMetadata: {
+          scanMode,
+        },
+        usageFailureLabel: "OmarGate AI",
         env: process.env,
       });
     } catch (aiError) {

package/src/review/ai-review.js

@@ -8,7 +8,7 @@ import {
   resolveProvider,
 } from "../ai/client.js";
 import { computeProviderCost } from "../billing/price-book.js";
-import { buildBillingRunId, buildCallIdempotencyKey } from "../billing/ledger-entry.js";
+import { buildBillingRunId, buildCallIdempotencyKey, sanitizeBillingMetadata } from "../billing/ledger-entry.js";
 import { recordSessionUsage } from "../billing/session-usage.js";
 import { loadConfig } from "../config/service.js";
 import { evaluateBudget } from "../cost/budget.js";
@@ -488,6 +488,12 @@ export async function runAiReviewLayer({
   dryRun = false,
   requireUsageLedger = false,
   usageRecorder = recordSessionUsage,
+  sourceCommand = "review",
+  billingAgentId = "audit-orchestrator",
+  billingAction = "audit_run",
+  billingTier = "internal",
+  billingMetadata = {},
+  usageFailureLabel = "Review AI",
   env = process.env,
 } = {}) {
   const normalizedTargetPath = path.resolve(String(targetPath || "."));
@@ -499,6 +505,12 @@ export async function runAiReviewLayer({
   );
   const normalizedRunId = normalizeString(runId) || "review-ai";
   const normalizedRequireUsageLedger = Boolean(requireUsageLedger);
+  const normalizedSourceCommand = normalizeString(sourceCommand) || "review";
+  const normalizedBillingAgentId = normalizeString(billingAgentId) || "audit-orchestrator";
+  const normalizedBillingAction = normalizeString(billingAction) || "audit_run";
+  const normalizedBillingTier = normalizeString(billingTier) || "internal";
+  const normalizedBillingMetadata = sanitizeBillingMetadata(billingMetadata);
+  const normalizedUsageFailureLabel = normalizeString(usageFailureLabel) || "Review AI";
 
   const config = await loadConfig({ cwd: normalizedTargetPath, env });
   let resolvedProvider = resolveProvider({
@@ -641,7 +653,7 @@ export async function runAiReviewLayer({
         toolCalls: 1,
       },
       metadata: {
-        sourceCommand: "review",
+        sourceCommand: normalizedSourceCommand,
         layer: "ai_reasoning",
         provider: resolvedProvider,
         model: resolvedModel,
@@ -657,28 +669,31 @@ export async function runAiReviewLayer({
       sessionId: normalizedSessionId,
       invocationTimestamp: startedAtIso,
       configHash: stableConfigHash({
-        sourceCommand: "review",
+        sourceCommand: normalizedSourceCommand,
         layer: "ai_reasoning",
         provider: resolvedProvider,
         model: resolvedModel,
         mode: normalizedMode,
         runId: normalizedRunId,
         dryRun: Boolean(dryRun),
+        billingAgentId: normalizedBillingAgentId,
+        billingAction: normalizedBillingAction,
       }),
     });
     sessionUsageLedger = await usageRecorder(
       normalizedSessionId,
       {
-        agentId: "audit-orchestrator",
-        action: "audit_run",
+        agentId: normalizedBillingAgentId,
+        action: normalizedBillingAction,
         model: resolvedModel,
         inputTokens,
         outputTokens,
         idempotencyKey: buildCallIdempotencyKey({ runId: billingRunId, callIndex: 0 }),
-        billingTier: "internal",
+        billingTier: normalizedBillingTier,
         createdAt: startedAtIso,
         metadata: {
-          sourceCommand: "review",
+          ...normalizedBillingMetadata,
+          sourceCommand: normalizedSourceCommand,
           layer: "ai_reasoning",
           provider: resolvedProvider,
           mode: normalizedMode,
@@ -698,7 +713,7 @@ export async function runAiReviewLayer({
     };
     if (normalizedRequireUsageLedger) {
       throw new Error(
-        `Review AI usage ledger recording failed: ${sessionUsageLedger.reason || "unknown"}.`
+        `${normalizedUsageFailureLabel} usage ledger recording failed: ${sessionUsageLedger.reason || "unknown"}.`
       );
     }
   }
@@ -729,7 +744,7 @@ export async function runAiReviewLayer({
           reasonCodes: budget.reasons.map((reason) => reason.code),
         },
         metadata: {
-          sourceCommand: "review",
+          sourceCommand: normalizedSourceCommand,
           layer: "ai_reasoning",
           provider: resolvedProvider,
           model: resolvedModel,

package/src/review/omargate-orchestrator.js

@@ -423,6 +423,10 @@ function omargateConfidenceFloorForPersona(personaId) {
   return OMARGATE_CONFIDENCE_FLOORS[personaId] || OMARGATE_DEFAULT_CONFIDENCE_FLOOR;
 }
 
+function isUsageLedgerFailure(message = "") {
+  return /usage ledger/i.test(String(message || ""));
+}
+
 async function runOmarPersonaSwarm({
   personaId,
   identity,
@@ -436,6 +440,9 @@ async function runOmarPersonaSwarm({
   perPersonaCost,
   dryRun,
   onEvent,
+  usageSessionId = "",
+  requireUsageLedger = false,
+  usageRecorder = undefined,
 } = {}) {
   const scope = buildPersonaFileScope({ deterministic });
   const decision = decideSwarm({ scope });
@@ -537,10 +544,26 @@ async function runOmarPersonaSwarm({
           outputDir,
           provider: provider || undefined,
           model: model || undefined,
-          sessionId: `${subagentRunId}-ai`,
+          sessionId: usageSessionId || `${subagentRunId}-ai`,
           maxCostUsd: budget.maxCostUsd,
           systemPrompt,
           dryRun,
+          requireUsageLedger,
+          usageRecorder,
+          sourceCommand: "omargate deep",
+          billingAgentId: `omargate-${personaId}-subagent-${subagentIndex}`,
+          billingAction: "omargate_deep",
+          billingMetadata: {
+            personaId,
+            subagentIndex,
+            partitionCount: partitions.length,
+            parentRunId: runId,
+            swarmRunId,
+            subagentRunId,
+            scanMode: mode,
+            fileCount: scopedFiles.length,
+          },
+          usageFailureLabel: "OmarGate AI",
           env: process.env,
         });
 
@@ -610,6 +633,7 @@ async function runOmarPersonaSwarm({
           summary: result?.summary || summarizeFindings(findings),
           costUsd: result?.usage?.costUsd || 0,
           model: result?.model || model || null,
+          billing: result?.billing || null,
           artifacts: result?.artifacts || null,
           durationMs: Date.now() - subagentStart,
         };
@@ -671,6 +695,41 @@ async function runOmarPersonaSwarm({
   const summary = summarizeFindings(findings);
   const okCount = settledSubagents.filter((result) => result.status === "ok").length;
   const errorCount = settledSubagents.filter((result) => result.status === "error").length;
+  const usageLedgerErrors = settledSubagents.filter((result) =>
+    result.status === "error" && isUsageLedgerFailure(result.error)
+  );
+  if (requireUsageLedger && usageLedgerErrors.length > 0) {
+    return {
+      personaId,
+      status: "error",
+      findings: [],
+      summary: { P0: 0, P1: 0, P2: 0, P3: 0, blocking: false },
+      costUsd: totalCostUsd,
+      model: model || null,
+      durationMs: Date.now() - startedAt,
+      error: `OmarGate required usage ledger failed for ${usageLedgerErrors.length}/${settledSubagents.length} subagent(s).`,
+      swarm: {
+        runId: swarmRunId,
+        decision,
+        subagentCount: settledSubagents.length,
+        ok: okCount,
+        error: errorCount,
+        partitionSizes: partitions.map((files) => files.length),
+        blackboardEntries: blackboard.length,
+        subagents: settledSubagents.map((result) => ({
+          id: result.agentId,
+          index: result.subagentIndex,
+          status: result.status,
+          files: result.files,
+          findings: (result.findings || []).length,
+          costUsd: result.costUsd || 0,
+          durationMs: result.durationMs || 0,
+          error: result.error || null,
+          artifacts: result.artifacts || null,
+        })),
+      },
+    };
+  }
 
   if (onEvent) {
     onEvent(createAgentEvent({
@@ -723,6 +782,7 @@ async function runOmarPersonaSwarm({
         files: result.files,
         findings: (result.findings || []).length,
         costUsd: result.costUsd || 0,
+        billing: result.billing || null,
         durationMs: result.durationMs || 0,
         error: result.error || null,
         artifacts: result.artifacts || null,
@@ -747,6 +807,8 @@ async function runOmarPersonaSwarm({
  * @param {Function} [options.onEvent] - Event callback for streaming
  * @param {string[] | null} [options.includeOnly] - Only run these persona IDs (filters scan-mode roster).
  * @param {string[] | null} [options.skipPersonas] - Skip these persona IDs (filters scan-mode roster).
+ * @param {boolean} [options.requireUsageLedger] - Fail if Omar Deep AI calls cannot write billing-grade session_usage.
+ * @param {string} [options.usageSessionId] - Optional shared Senti session id for billing-grade usage entries.
  * @returns {Promise<object>} Orchestrated results
  */
 export async function runOmarGateOrchestrator({
@@ -762,6 +824,9 @@ export async function runOmarGateOrchestrator({
   onEvent = null,
   includeOnly = null,
   skipPersonas = null,
+  requireUsageLedger = false,
+  usageSessionId = "",
+  usageRecorder = undefined,
 } = {}) {
   const runId = `omargate-${Date.now()}-${randomUUID().slice(0, 8)}`;
   const startTime = Date.now();
@@ -931,6 +996,9 @@ export async function runOmarGateOrchestrator({
         perPersonaCost,
         dryRun,
         onEvent,
+        requireUsageLedger,
+        usageSessionId,
+        usageRecorder,
       });
 
       if (swarmResult) {
@@ -999,9 +1067,21 @@ export async function runOmarGateOrchestrator({
         outputDir,
         provider: provider || undefined,
         model: model || undefined,
+        sessionId: usageSessionId || `${runId}-${personaId}-ai`,
         maxCostUsd: perPersonaCost,
         systemPrompt,
         dryRun,
+        requireUsageLedger,
+        usageRecorder,
+        sourceCommand: "omargate deep",
+        billingAgentId: `omargate-${personaId}`,
+        billingAction: "omargate_deep",
+        billingMetadata: {
+          personaId,
+          parentRunId: runId,
+          scanMode: mode,
+        },
+        usageFailureLabel: "OmarGate AI",
         env: process.env,
       });
 
@@ -1062,6 +1142,7 @@ export async function runOmarGateOrchestrator({
         summary: result?.summary || { P0: 0, P1: 0, P2: 0, P3: 0 },
         costUsd: personaCost,
         model: result?.model || model || null,
+        billing: result?.billing || null,
         artifacts: result?.artifacts || null,
         durationMs: Date.now() - personaStart,
       };
@@ -1106,6 +1187,18 @@ export async function runOmarGateOrchestrator({
           durationMs: 0,
         })
   );
+  const usageLedgerFailures = settled.filter((r) =>
+    r.status === "error" && isUsageLedgerFailure(r.error)
+  );
+  if (requireUsageLedger && usageLedgerFailures.length > 0) {
+    const examples = usageLedgerFailures
+      .slice(0, 3)
+      .map((r) => `${r.personaId}: ${r.error}`)
+      .join("; ");
+    throw new Error(
+      `OmarGate required usage ledger recording failed for ${usageLedgerFailures.length}/${settled.length} persona(s).${examples ? ` ${examples}` : ""}`
+    );
+  }
 
   // Reconcile AI findings with deterministic findings — canonical single list.
   // Confidence boost when multiple layers agree; deterministic findings get
@@ -1183,6 +1276,7 @@ export async function runOmarGateOrchestrator({
       costUsd: r.costUsd,
       durationMs: r.durationMs,
       model: r.model || null,
+      billing: r.billing || null,
       error: r.error || null,
       swarm: r.swarm || null,
       artifacts: r.artifacts || null,

package/src/session/listener.js

@@ -311,6 +311,7 @@ export async function listenSessionEvents({
     const latest = await _pollLatest(normalizedSessionId, {
       targetPath,
       limit: 1,
+      forceCircuitProbe: true,
     });
     if (!latest?.ok) {
       throw new Error(`Unable to start listener from the latest event (${latest?.reason || "unknown"}).`);