sentinelayer-cli 0.27.1 → 0.28.1

package/README.md

@@ -259,6 +259,7 @@ The `review` command can now add budget-governed AI reasoning on top of determin
 
 - `sl review --ai --provider openai --model gpt-5.3-codex`
 - `sl review --ai --ai-dry-run` (no provider call; deterministic synthetic output)
+- `sl review --ai --require-usage-ledger` (fail closed if billing-grade usage cannot be recorded)
 - `sl review --ai --max-cost 1.0 --max-tokens 0 --max-runtime-ms 0 --max-tool-calls 0`
 
 AI artifacts are persisted in the same run folder:

package/package.json

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

package/src/ai/proxy.js

@@ -15,6 +15,298 @@ const DEFAULT_PROXY_MODEL = "gpt-5.3-codex";
 const PROXY_TIMEOUT_MS = 120_000;
 const PROXY_MAX_RETRIES = 2;
 const PROXY_RETRY_STATUSES = new Set([429, 502, 503, 504]);
+const ACTIONABLE_PROXY_DENIAL_CODES = new Set([
+  "FREE_TRIAL_EXPIRED",
+  "DAILY_SCAN_LIMIT_EXCEEDED",
+  "WEEKLY_SCAN_LIMIT_EXCEEDED",
+  "DAILY_BUDGET_EXCEEDED",
+  "RATE_LIMIT_EXCEEDED",
+]);
+
+export class SentinelayerProxyError extends Error {
+  constructor(message, {
+    status = 0,
+    code = "PROXY_ERROR",
+    requestId = "",
+    retryAfterMs = undefined,
+    quota = null,
+    raw = null,
+  } = {}) {
+    super(message);
+    this.name = "SentinelayerProxyError";
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+    this.retryAfterMs = retryAfterMs;
+    this.quota = quota;
+    this.raw = raw;
+  }
+}
+
+export function serializeProxyError(error) {
+  if (!error || typeof error !== "object") {
+    return null;
+  }
+  const status = normalizeInteger(error.status);
+  const code = String(error.code || "").trim();
+  const requestId = String(error.requestId || "").trim();
+  const retryAfterMs = normalizeInteger(error.retryAfterMs);
+  const quota =
+    error.quota && typeof error.quota === "object" && !Array.isArray(error.quota)
+      ? JSON.parse(JSON.stringify(error.quota))
+      : null;
+  const serialized = {
+    status,
+    code: code || undefined,
+    requestId: requestId || undefined,
+    retryAfterMs,
+    quota,
+  };
+  for (const key of Object.keys(serialized)) {
+    if (serialized[key] === undefined || serialized[key] === null || serialized[key] === "") {
+      delete serialized[key];
+    }
+  }
+  return Object.keys(serialized).length > 0 ? serialized : null;
+}
+
+function normalizeNumber(value) {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : undefined;
+}
+
+function normalizeInteger(value) {
+  const numeric = normalizeNumber(value);
+  return numeric === undefined ? undefined : Math.max(0, Math.floor(numeric));
+}
+
+function getHeader(headers, name) {
+  if (!headers || typeof headers.get !== "function") {
+    return null;
+  }
+  return headers.get(name) || headers.get(name.toLowerCase()) || null;
+}
+
+function parseRetryAfterMs(raw) {
+  if (typeof raw !== "string") {
+    return undefined;
+  }
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const asSeconds = Number.parseFloat(trimmed);
+  if (Number.isFinite(asSeconds) && asSeconds >= 0) {
+    return Math.ceil(asSeconds * 1000);
+  }
+  const asDate = Date.parse(trimmed);
+  if (Number.isNaN(asDate)) {
+    return undefined;
+  }
+  return Math.max(0, asDate - Date.now());
+}
+
+function chooseObject(...candidates) {
+  for (const candidate of candidates) {
+    if (candidate && typeof candidate === "object" && !Array.isArray(candidate)) {
+      return candidate;
+    }
+  }
+  return {};
+}
+
+function normalizeQuotaDetails(details = {}, headers = null) {
+  const policy = String(details.policy || "").trim();
+  const scope = String(details.scope || "").trim();
+  const unit = String(details.unit || "").trim();
+  const resetAt = String(details.resetAt || details.reset_at || "").trim();
+  const upgradeUrl = String(details.upgradeUrl || details.upgrade_url || "").trim();
+  const checkoutMode = String(details.checkoutMode || details.checkout_mode || "").trim();
+  const limit =
+    normalizeInteger(details.limit) ??
+    normalizeInteger(getHeader(headers, "X-RateLimit-Limit"));
+  const remaining =
+    normalizeInteger(details.remaining) ??
+    normalizeInteger(getHeader(headers, "X-RateLimit-Remaining"));
+  const used = normalizeInteger(details.used);
+  const resetAfterSeconds =
+    normalizeInteger(details.resetAfterSeconds ?? details.reset_after_seconds) ??
+    normalizeInteger(details.retryAfterSeconds ?? details.retry_after_seconds);
+  const retryAfterSeconds =
+    normalizeInteger(details.retryAfterSeconds ?? details.retry_after_seconds) ??
+    normalizeInteger(resetAfterSeconds);
+  const retryAfterMs =
+    retryAfterSeconds !== undefined
+      ? retryAfterSeconds * 1000
+      : parseRetryAfterMs(getHeader(headers, "Retry-After"));
+  const headerReset = getHeader(headers, "X-RateLimit-Reset");
+  const headerPolicy = getHeader(headers, "X-RateLimit-Policy");
+
+  const quota = {
+    policy: policy || String(headerPolicy || "").trim() || undefined,
+    scope: scope || undefined,
+    limit,
+    remaining,
+    used,
+    unit: unit || undefined,
+    resetAfterSeconds,
+    resetAt: resetAt || String(headerReset || "").trim() || undefined,
+    retryAfterSeconds,
+    retryAfterMs,
+    upgradeUrl: upgradeUrl || undefined,
+    checkoutMode: checkoutMode || undefined,
+  };
+
+  for (const key of Object.keys(quota)) {
+    if (quota[key] === undefined || quota[key] === "") {
+      delete quota[key];
+    }
+  }
+
+  return Object.keys(quota).length > 0 ? quota : null;
+}
+
+function formatSeconds(seconds) {
+  const normalized = normalizeInteger(seconds);
+  if (normalized === undefined) {
+    return "";
+  }
+  if (normalized < 60) {
+    return `${normalized}s`;
+  }
+  const minutes = Math.ceil(normalized / 60);
+  if (minutes < 60) {
+    return `${minutes}m`;
+  }
+  const hours = Math.ceil(minutes / 60);
+  if (hours < 48) {
+    return `${hours}h`;
+  }
+  const days = Math.ceil(hours / 24);
+  return `${days}d`;
+}
+
+function buildProxyErrorMessage({ status, code, message, quota }) {
+  const parts = [`SentinelLayer LLM proxy error (${status}${code ? ` ${code}` : ""}): ${message || "Request denied"}`];
+  if (quota?.policy || quota?.scope) {
+    parts.push(`policy=${quota.policy || "unknown"}${quota.scope ? ` scope=${quota.scope}` : ""}`);
+  }
+  if (quota?.limit !== undefined || quota?.remaining !== undefined || quota?.used !== undefined) {
+    const unit = quota.unit ? ` ${quota.unit}` : "";
+    const limit = quota.limit !== undefined ? quota.limit : "?";
+    const remaining = quota.remaining !== undefined ? quota.remaining : "?";
+    const used = quota.used !== undefined ? quota.used : "?";
+    parts.push(`quota used=${used} remaining=${remaining} limit=${limit}${unit}`);
+  }
+  if (quota?.resetAt) {
+    parts.push(`resets at ${quota.resetAt}`);
+  } else if (quota?.resetAfterSeconds !== undefined) {
+    parts.push(`resets in ${formatSeconds(quota.resetAfterSeconds)}`);
+  } else if (quota?.retryAfterSeconds !== undefined) {
+    parts.push(`retry after ${formatSeconds(quota.retryAfterSeconds)}`);
+  }
+  if (quota?.upgradeUrl) {
+    parts.push(`upgrade: ${quota.upgradeUrl}`);
+  }
+  if (quota?.checkoutMode) {
+    parts.push(`checkout=${quota.checkoutMode}`);
+  }
+  return parts.join(" | ");
+}
+
+async function parseProxyErrorResponse(response) {
+  let payload = null;
+  let text = "";
+  try {
+    payload = await response.json();
+  } catch {
+    text = await response.text().catch(() => "");
+  }
+
+  const detailObject =
+    payload?.detail && typeof payload.detail === "object" && !Array.isArray(payload.detail)
+      ? payload.detail
+      : null;
+  const nestedError = chooseObject(payload?.error, detailObject?.error);
+  const details = chooseObject(
+    nestedError?.details,
+    nestedError?.detail,
+    payload?.details,
+    detailObject?.details,
+    detailObject
+  );
+  const code = String(
+    nestedError?.code ||
+      payload?.code ||
+      detailObject?.code ||
+      "PROXY_ERROR"
+  ).trim() || "PROXY_ERROR";
+  const message = String(
+    nestedError?.message ||
+      payload?.message ||
+      (typeof payload?.detail === "string" ? payload.detail : "") ||
+      detailObject?.message ||
+      text ||
+      "Request denied"
+  ).trim();
+  const requestId = String(
+    nestedError?.request_id ||
+      nestedError?.requestId ||
+      payload?.request_id ||
+      payload?.requestId ||
+      detailObject?.request_id ||
+      detailObject?.requestId ||
+      getHeader(response.headers, "x-request-id") ||
+      ""
+  ).trim();
+  const quota = normalizeQuotaDetails(details, response.headers);
+  const retryAfterMs =
+    quota?.retryAfterMs ??
+    parseRetryAfterMs(getHeader(response.headers, "Retry-After")) ??
+    normalizeInteger(nestedError?.retry_after_ms ?? payload?.retry_after_ms);
+
+  return {
+    code,
+    message,
+    requestId,
+    quota,
+    retryAfterMs,
+    raw: payload || text,
+  };
+}
+
+function isActionableProxyDenial(status, parsed) {
+  if (status === 402 || status === 403) {
+    return true;
+  }
+  if (ACTIONABLE_PROXY_DENIAL_CODES.has(String(parsed?.code || "").trim())) {
+    return true;
+  }
+  return Boolean(parsed?.quota?.policy || parsed?.quota?.upgradeUrl || parsed?.quota?.resetAt);
+}
+
+function buildProxyError(status, parsed) {
+  const retryAfterMs = parsed.retryAfterMs ?? parsed.quota?.retryAfterMs;
+  return new SentinelayerProxyError(
+    buildProxyErrorMessage({
+      status,
+      code: parsed.code,
+      message: parsed.message,
+      quota: parsed.quota,
+    }),
+    {
+      status,
+      code: parsed.code,
+      requestId: parsed.requestId,
+      retryAfterMs,
+      quota: parsed.quota,
+      raw: parsed.raw,
+    }
+  );
+}
 
 /**
  * Invoke LLM via SentinelLayer proxy.
@@ -128,15 +420,25 @@ export async function invokeViaProxy({
         clearTimeout(timeoutHandle);
       }
 
-      if (PROXY_RETRY_STATUSES.has(response.status) && attempt < PROXY_MAX_RETRIES) {
-        const retryAfter = response.headers.get("Retry-After");
-        const delay = retryAfter && !isNaN(retryAfter) ? Math.min(Number(retryAfter), 5) * 1000 : 500 * (attempt + 1);
+      if (response.ok) {
+        break;
+      }
+
+      const parsedError = await parseProxyErrorResponse(response);
+      const hardDenial = isActionableProxyDenial(response.status, parsedError);
+      if (!hardDenial && PROXY_RETRY_STATUSES.has(response.status) && attempt < PROXY_MAX_RETRIES) {
+        const retryAfter = getHeader(response.headers, "Retry-After");
+        const retryAfterSeconds = retryAfter && !Number.isNaN(Number(retryAfter)) ? Number(retryAfter) : null;
+        const delay = retryAfterSeconds !== null ? Math.min(retryAfterSeconds, 5) * 1000 : 500 * (attempt + 1);
         await new Promise((r) => setTimeout(r, delay));
         continue;
       }
 
-      break;
+      throw buildProxyError(response.status, parsedError);
     } catch (err) {
+      if (err instanceof SentinelayerProxyError) {
+        throw err;
+      }
       lastError = err;
       if (attempt >= PROXY_MAX_RETRIES) break;
       await new Promise((r) => setTimeout(r, 500 * (attempt + 1)));
@@ -147,17 +449,6 @@ export async function invokeViaProxy({
     throw new Error(`SentinelLayer LLM proxy request failed: ${lastError?.message || "no response"}`);
   }
 
-  if (!response.ok) {
-    let detail = "";
-    try {
-      const errBody = await response.json();
-      detail = errBody?.error?.message || errBody?.detail || JSON.stringify(errBody).slice(0, 200);
-    } catch {
-      detail = await response.text().catch(() => "");
-    }
-    throw new Error(`SentinelLayer LLM proxy error (${response.status}): ${detail}`);
-  }
-
   const result = await response.json();
 
   return {

package/src/audit/persona-loop.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import path from "node:path";
 
 import { createMultiProviderApiClient } from "../ai/client.js";
+import { serializeProxyError } from "../ai/proxy.js";
 import { evaluateBudget } from "../cost/budget.js";
 import { estimateTokens } from "../cost/tokenizer.js";
 import { createAgentEvent } from "../events/schema.js";
@@ -866,9 +867,11 @@ async function runSinglePersonaAgenticLoop({
       });
     } catch (error) {
       status = "llm_error_fallback";
+      const proxyError = serializeProxyError(error);
       emit("llm_error", {
         turn: turnCount,
         error: error instanceof Error ? error.message : String(error),
+        ...(proxyError ? { proxyError } : {}),
       });
       break;
     }

package/src/commands/review.js

@@ -120,6 +120,7 @@ async function executeReviewRun({
       maxNoProgress: aiConfig.maxNoProgress,
       warningThresholdPercent: aiConfig.warnAtPercent,
       dryRun: Boolean(aiConfig.aiDryRun),
+      requireUsageLedger: Boolean(aiConfig.requireUsageLedger),
       env: process.env,
     });
   }
@@ -146,6 +147,7 @@ async function executeReviewRun({
     invocation: {
       aiEnabled: Boolean(aiConfig.enable),
       aiDryRun: Boolean(aiConfig.aiDryRun),
+      requireUsageLedger: Boolean(aiConfig.requireUsageLedger),
       provider: aiConfig.provider,
       model: aiConfig.model,
       sessionId: aiConfig.sessionId,
@@ -209,6 +211,7 @@ async function executeReviewRun({
           budget: aiLayer.budget,
           cost: aiLayer.cost,
           telemetry: aiLayer.telemetry,
+          billing: aiLayer.billing,
         }
       : {
           enabled: false,
@@ -283,6 +286,7 @@ export function registerReviewCommand(program) {
     .option("--staged", "Alias for --mode staged")
     .option("--ai", "Enable AI reasoning layer over deterministic findings")
     .option("--ai-dry-run", "Run AI layer in dry-run mode (no provider call)")
+    .option("--require-usage-ledger", "Fail --ai review if billing-grade session_usage cannot be recorded")
     .option("--provider <name>", "AI provider override (openai|anthropic|google)")
     .option("--model <id>", "AI model override")
     .option("--api-key <key>", "Optional explicit API key override")
@@ -314,6 +318,7 @@ export function registerReviewCommand(program) {
         aiConfig: {
           enable: Boolean(options.ai),
           aiDryRun: Boolean(options.aiDryRun),
+          requireUsageLedger: Boolean(options.requireUsageLedger),
           provider: options.provider,
           model: options.model,
           apiKey: options.apiKey,

package/src/review/ai-review.js

@@ -486,6 +486,8 @@ export async function runAiReviewLayer({
   warningThresholdPercent = 80,
   systemPrompt = "",
   dryRun = false,
+  requireUsageLedger = false,
+  usageRecorder = recordSessionUsage,
   env = process.env,
 } = {}) {
   const normalizedTargetPath = path.resolve(String(targetPath || "."));
@@ -496,6 +498,7 @@ export async function runAiReviewLayer({
     Math.floor(Number(maxFindings || DEFAULT_AI_MAX_FINDINGS))
   );
   const normalizedRunId = normalizeString(runId) || "review-ai";
+  const normalizedRequireUsageLedger = Boolean(requireUsageLedger);
 
   const config = await loadConfig({ cwd: normalizedTargetPath, env });
   let resolvedProvider = resolveProvider({
@@ -663,7 +666,7 @@ export async function runAiReviewLayer({
         dryRun: Boolean(dryRun),
       }),
     });
-    sessionUsageLedger = await recordSessionUsage(
+    sessionUsageLedger = await usageRecorder(
       normalizedSessionId,
       {
         agentId: "audit-orchestrator",
@@ -693,6 +696,11 @@ export async function runAiReviewLayer({
       ok: false,
       reason: error instanceof Error ? error.message : String(error || "session_usage_failed"),
     };
+    if (normalizedRequireUsageLedger) {
+      throw new Error(
+        `Review AI usage ledger recording failed: ${sessionUsageLedger.reason || "unknown"}.`
+      );
+    }
   }
 
   let stopTelemetry = null;
@@ -754,6 +762,7 @@ export async function runAiReviewLayer({
     provider: resolvedProvider,
     model: resolvedModel,
     dryRun: Boolean(dryRun),
+    requireUsageLedger: normalizedRequireUsageLedger,
     usage,
     pricingFound: modelCost.pricingFound,
     sessionUsageLedger,

package/src/session/daemon.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import process from "node:process";
 import fsp from "node:fs/promises";
 
-import { invokeViaProxy } from "../ai/proxy.js";
+import { invokeViaProxy, serializeProxyError } from "../ai/proxy.js";
 import { createAgentEvent } from "../events/schema.js";
 import {
   buildDocumentsFromBlackboardEntries,
@@ -496,6 +496,7 @@ async function buildHelpResponseMessage(
   let llmText = "";
   let fallbackPath = false;
   let fallbackReason = "";
+  let proxyError = null;
   let usage = {
     inputTokens: 0,
     outputTokens: 0,
@@ -556,6 +557,7 @@ async function buildHelpResponseMessage(
   } catch (error) {
     fallbackPath = true;
     fallbackReason = normalizeString(error?.message || error) || "Senti model invocation failed.";
+    proxyError = serializeProxyError(error);
   }
 
   if (!usage.latencyMs) {
@@ -579,6 +581,7 @@ async function buildHelpResponseMessage(
     usage,
     fallbackPath,
     fallbackReason,
+    proxyError,
     contextSignals: {
       documentCount: documents.length,
       memoryHits: memoryHits.length,
@@ -641,6 +644,7 @@ async function maybeRespondToHelpRequest(
       latencyMs: response.usage.latencyMs,
       fallbackPath: Boolean(response.fallbackPath),
       fallbackReason: response.fallbackReason || null,
+      proxyError: response.proxyError || null,
       contextSignals: response.contextSignals,
     },
     {