sentinelayer-cli 0.1.0

package/src/cost/budget.js

@@ -0,0 +1,235 @@
+function normalizeNumber(value, field) {
+  const normalized = Number(value || 0);
+  if (!Number.isFinite(normalized) || normalized < 0) {
+    throw new Error(`${field} must be a non-negative number.`);
+  }
+  return normalized;
+}
+
+function formatNumber(value, decimals = 0) {
+  return Number(value || 0).toFixed(decimals);
+}
+
+function normalizeWarningThresholdPercent(value) {
+  const normalized = Number(value || 0);
+  if (!Number.isFinite(normalized) || normalized < 0 || normalized > 100) {
+    throw new Error("warningThresholdPercent must be between 0 and 100.");
+  }
+  return normalized;
+}
+
+function collectLimitStatusWithThreshold({
+  reasons,
+  warnings,
+  usageValue,
+  limitValue,
+  warningThresholdPercent,
+  stopCode,
+  warningCode,
+  stopMessage,
+  warningMessage,
+}) {
+  const normalizedUsage = normalizeNumber(usageValue, "usageValue");
+  const normalizedLimit = normalizeNumber(limitValue, "limitValue");
+  const normalizedWarningThresholdPercent =
+    normalizeWarningThresholdPercent(warningThresholdPercent);
+
+  if (normalizedLimit <= 0) {
+    return;
+  }
+
+  if (normalizedUsage > normalizedLimit) {
+    reasons.push({
+      code: stopCode,
+      message: stopMessage(normalizedUsage, normalizedLimit),
+    });
+    return;
+  }
+
+  if (normalizedWarningThresholdPercent <= 0) {
+    return;
+  }
+
+  const thresholdValue = (normalizedWarningThresholdPercent / 100) * normalizedLimit;
+  if (normalizedUsage >= thresholdValue) {
+    warnings.push({
+      code: warningCode,
+      message: warningMessage(normalizedUsage, normalizedLimit, normalizedWarningThresholdPercent),
+    });
+  }
+}
+
+/**
+ * Evaluate runtime/cost/token/tool/no-progress budgets and return deterministic stop/warning signals.
+ *
+ * @param {{
+ *   sessionSummary?: {
+ *     costUsd?: number,
+ *     outputTokens?: number,
+ *     noProgressStreak?: number,
+ *     durationMs?: number,
+ *     toolCalls?: number
+ *   },
+ *   maxCostUsd?: number,
+ *   maxOutputTokens?: number,
+ *   maxNoProgress?: number,
+ *   maxRuntimeMs?: number,
+ *   maxToolCalls?: number,
+ *   warningThresholdPercent?: number
+ * }} [options]
+ * @returns {{
+ *   blocking: boolean,
+ *   warnings: Array<{ code: string, message: string }>,
+ *   reasons: Array<{ code: string, message: string }>,
+ *   limits: {
+ *     maxCostUsd: number,
+ *     maxOutputTokens: number,
+ *     maxNoProgress: number,
+ *     maxRuntimeMs: number,
+ *     maxToolCalls: number,
+ *     warningThresholdPercent: number
+ *   },
+ *   usage: {
+ *     costUsd: number,
+ *     outputTokens: number,
+ *     noProgressStreak: number,
+ *     runtimeMs: number,
+ *     toolCalls: number
+ *   }
+ * }}
+ */
+export function evaluateBudget({
+  sessionSummary = {},
+  maxCostUsd = 1.0,
+  maxOutputTokens = 0,
+  maxNoProgress = 3,
+  maxRuntimeMs = 0,
+  maxToolCalls = 0,
+  warningThresholdPercent = 80,
+} = {}) {
+  const normalizedMaxCost = normalizeNumber(maxCostUsd, "maxCostUsd");
+  const normalizedMaxOutputTokens = normalizeNumber(maxOutputTokens, "maxOutputTokens");
+  const normalizedMaxNoProgress = Math.max(1, normalizeNumber(maxNoProgress, "maxNoProgress"));
+  const normalizedMaxRuntimeMs = normalizeNumber(maxRuntimeMs, "maxRuntimeMs");
+  const normalizedMaxToolCalls = normalizeNumber(maxToolCalls, "maxToolCalls");
+  const normalizedWarningThresholdPercent = normalizeWarningThresholdPercent(
+    warningThresholdPercent
+  );
+
+  const totalCostUsd = normalizeNumber(sessionSummary.costUsd || 0, "sessionSummary.costUsd");
+  const totalOutputTokens = normalizeNumber(
+    sessionSummary.outputTokens || 0,
+    "sessionSummary.outputTokens"
+  );
+  const noProgressStreak = normalizeNumber(
+    sessionSummary.noProgressStreak || 0,
+    "sessionSummary.noProgressStreak"
+  );
+  const totalRuntimeMs = normalizeNumber(sessionSummary.durationMs || 0, "sessionSummary.durationMs");
+  const totalToolCalls = normalizeNumber(
+    sessionSummary.toolCalls || 0,
+    "sessionSummary.toolCalls"
+  );
+
+  const reasons = [];
+  const warnings = [];
+
+  collectLimitStatusWithThreshold({
+    reasons,
+    warnings,
+    usageValue: totalCostUsd,
+    limitValue: normalizedMaxCost,
+    warningThresholdPercent: normalizedWarningThresholdPercent,
+    stopCode: "MAX_COST_EXCEEDED",
+    warningCode: "COST_BUDGET_NEAR_LIMIT",
+    stopMessage: (usage, limit) =>
+      `Cost budget exceeded (${formatNumber(usage, 6)} > ${formatNumber(limit, 6)}).`,
+    warningMessage: (usage, limit, thresholdPercent) =>
+      `Cost budget near limit (${formatNumber(usage, 6)} / ${formatNumber(limit, 6)} at ${formatNumber(
+        thresholdPercent,
+        0
+      )}%).`,
+  });
+
+  collectLimitStatusWithThreshold({
+    reasons,
+    warnings,
+    usageValue: totalOutputTokens,
+    limitValue: normalizedMaxOutputTokens,
+    warningThresholdPercent: normalizedWarningThresholdPercent,
+    stopCode: "MAX_OUTPUT_TOKENS_EXCEEDED",
+    warningCode: "OUTPUT_TOKENS_NEAR_LIMIT",
+    stopMessage: (usage, limit) =>
+      `Output token budget exceeded (${formatNumber(usage, 0)} > ${formatNumber(limit, 0)}).`,
+    warningMessage: (usage, limit, thresholdPercent) =>
+      `Output token budget near limit (${formatNumber(usage, 0)} / ${formatNumber(
+        limit,
+        0
+      )} at ${formatNumber(thresholdPercent, 0)}%).`,
+  });
+
+  collectLimitStatusWithThreshold({
+    reasons,
+    warnings,
+    usageValue: totalRuntimeMs,
+    limitValue: normalizedMaxRuntimeMs,
+    warningThresholdPercent: normalizedWarningThresholdPercent,
+    stopCode: "MAX_RUNTIME_MS_EXCEEDED",
+    warningCode: "RUNTIME_MS_NEAR_LIMIT",
+    stopMessage: (usage, limit) =>
+      `Runtime budget exceeded (${formatNumber(usage, 0)}ms > ${formatNumber(limit, 0)}ms).`,
+    warningMessage: (usage, limit, thresholdPercent) =>
+      `Runtime budget near limit (${formatNumber(usage, 0)}ms / ${formatNumber(
+        limit,
+        0
+      )}ms at ${formatNumber(thresholdPercent, 0)}%).`,
+  });
+
+  collectLimitStatusWithThreshold({
+    reasons,
+    warnings,
+    usageValue: totalToolCalls,
+    limitValue: normalizedMaxToolCalls,
+    warningThresholdPercent: normalizedWarningThresholdPercent,
+    stopCode: "MAX_TOOL_CALLS_EXCEEDED",
+    warningCode: "TOOL_CALLS_NEAR_LIMIT",
+    stopMessage: (usage, limit) =>
+      `Tool-call budget exceeded (${formatNumber(usage, 0)} > ${formatNumber(limit, 0)}).`,
+    warningMessage: (usage, limit, thresholdPercent) =>
+      `Tool-call budget near limit (${formatNumber(usage, 0)} / ${formatNumber(
+        limit,
+        0
+      )} at ${formatNumber(thresholdPercent, 0)}%).`,
+  });
+
+  if (noProgressStreak >= normalizedMaxNoProgress) {
+    reasons.push({
+      code: "DIMINISHING_RETURNS",
+      message: `No-progress streak reached ${formatNumber(noProgressStreak, 0)} (threshold ${formatNumber(
+        normalizedMaxNoProgress,
+        0
+      )}).`,
+    });
+  }
+
+  return {
+    blocking: reasons.length > 0,
+    warnings,
+    reasons,
+    limits: {
+      maxCostUsd: normalizedMaxCost,
+      maxOutputTokens: normalizedMaxOutputTokens,
+      maxNoProgress: normalizedMaxNoProgress,
+      maxRuntimeMs: normalizedMaxRuntimeMs,
+      maxToolCalls: normalizedMaxToolCalls,
+      warningThresholdPercent: normalizedWarningThresholdPercent,
+    },
+    usage: {
+      costUsd: totalCostUsd,
+      outputTokens: totalOutputTokens,
+      noProgressStreak,
+      runtimeMs: totalRuntimeMs,
+      toolCalls: totalToolCalls,
+    },
+  };
+}

package/src/cost/history.js

@@ -0,0 +1,188 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { resolveOutputRoot } from "../config/service.js";
+import { rollupUsage } from "./tracker.js";
+
+const HISTORY_VERSION = 1;
+const HISTORY_FILE_NAME = "cost-history.json";
+
+function normalizeNumber(value, field) {
+  const normalized = Number(value || 0);
+  if (!Number.isFinite(normalized) || normalized < 0) {
+    throw new Error(`${field} must be a non-negative number.`);
+  }
+  return normalized;
+}
+
+function normalizeProgressScore(value) {
+  const normalized = Number(value || 0);
+  if (!Number.isFinite(normalized)) {
+    return 0;
+  }
+  return normalized;
+}
+
+function normalizeEntry(entry) {
+  if (!entry || typeof entry !== "object") {
+    throw new Error("Cost entry must be an object.");
+  }
+
+  const provider = String(entry.provider || "").trim().toLowerCase();
+  const model = String(entry.model || "").trim();
+  if (!provider) {
+    throw new Error("Cost entry provider is required.");
+  }
+  if (!model) {
+    throw new Error("Cost entry model is required.");
+  }
+
+  const invocationId = String(entry.invocationId || "").trim() || randomUUID();
+  const sessionId = String(entry.sessionId || "").trim() || "default";
+  const timestamp = String(entry.timestamp || "").trim() || new Date().toISOString();
+
+  return {
+    invocationId,
+    sessionId,
+    timestamp,
+    provider,
+    model,
+    inputTokens: normalizeNumber(entry.inputTokens, "entry.inputTokens"),
+    outputTokens: normalizeNumber(entry.outputTokens, "entry.outputTokens"),
+    cacheReadTokens: normalizeNumber(entry.cacheReadTokens, "entry.cacheReadTokens"),
+    cacheWriteTokens: normalizeNumber(entry.cacheWriteTokens, "entry.cacheWriteTokens"),
+    durationMs: normalizeNumber(entry.durationMs, "entry.durationMs"),
+    toolCalls: normalizeNumber(entry.toolCalls, "entry.toolCalls"),
+    costUsd: normalizeNumber(entry.costUsd, "entry.costUsd"),
+    progressScore: normalizeProgressScore(entry.progressScore),
+  };
+}
+
+export async function resolveCostHistoryPath({
+  targetPath = ".",
+  outputDirOverride = "",
+  env,
+  homeDir,
+} = {}) {
+  const outputRoot = await resolveOutputRoot({
+    cwd: path.resolve(targetPath),
+    outputDirOverride,
+    env,
+    homeDir,
+  });
+  return path.join(outputRoot, HISTORY_FILE_NAME);
+}
+
+export async function loadCostHistory(options = {}) {
+  const filePath = await resolveCostHistoryPath(options);
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.entries)) {
+      throw new Error("Invalid cost history payload.");
+    }
+    return {
+      filePath,
+      history: {
+        version: Number(parsed.version || HISTORY_VERSION),
+        entries: parsed.entries,
+      },
+    };
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return {
+        filePath,
+        history: {
+          version: HISTORY_VERSION,
+          entries: [],
+        },
+      };
+    }
+    throw error;
+  }
+}
+
+export async function saveCostHistory({ filePath, history }) {
+  const payload = {
+    version: HISTORY_VERSION,
+    entries: Array.isArray(history?.entries) ? history.entries : [],
+  };
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
+  await fsp.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+}
+
+export async function appendCostEntry(options = {}, entry = {}) {
+  const normalizedEntry = normalizeEntry(entry);
+  const { filePath, history } = await loadCostHistory(options);
+  const nextHistory = {
+    version: HISTORY_VERSION,
+    entries: [...history.entries, normalizedEntry],
+  };
+  await saveCostHistory({ filePath, history: nextHistory });
+  return {
+    filePath,
+    entry: normalizedEntry,
+    history: nextHistory,
+  };
+}
+
+function summarizeSessionEntries(entries) {
+  const usageEntries = entries.map((item) => ({
+    inputTokens: item.inputTokens,
+    outputTokens: item.outputTokens,
+    costUsd: item.costUsd,
+  }));
+  const usage = rollupUsage(usageEntries);
+  const cacheReadTokens = entries.reduce((sum, item) => sum + Number(item.cacheReadTokens || 0), 0);
+  const cacheWriteTokens = entries.reduce((sum, item) => sum + Number(item.cacheWriteTokens || 0), 0);
+  const durationMs = entries.reduce((sum, item) => sum + Number(item.durationMs || 0), 0);
+  const toolCalls = entries.reduce((sum, item) => sum + Number(item.toolCalls || 0), 0);
+
+  let noProgressStreak = 0;
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    if (Number(entries[index].progressScore || 0) > 0) {
+      break;
+    }
+    noProgressStreak += 1;
+  }
+
+  return {
+    invocationCount: entries.length,
+    inputTokens: usage.inputTokens,
+    outputTokens: usage.outputTokens,
+    cacheReadTokens,
+    cacheWriteTokens,
+    durationMs,
+    toolCalls,
+    costUsd: usage.costUsd,
+    noProgressStreak,
+  };
+}
+
+export function summarizeCostHistory(history = {}) {
+  const entries = Array.isArray(history.entries) ? history.entries : [];
+  const sessionMap = new Map();
+  for (const entry of entries) {
+    const key = String(entry.sessionId || "default");
+    const existing = sessionMap.get(key) || [];
+    existing.push(entry);
+    sessionMap.set(key, existing);
+  }
+
+  const sessions = [...sessionMap.entries()]
+    .map(([sessionId, sessionEntries]) => ({
+      sessionId,
+      ...summarizeSessionEntries(sessionEntries),
+    }))
+    .sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+
+  const totals = summarizeSessionEntries(entries);
+
+  return {
+    sessionCount: sessions.length,
+    ...totals,
+    sessions,
+  };
+}
+

package/src/cost/tracker.js

@@ -0,0 +1,171 @@
+const DEFAULT_MODEL_PRICING = Object.freeze({
+  "gpt-4o": Object.freeze({
+    inputPerMillionUsd: 2.5,
+    outputPerMillionUsd: 10.0,
+  }),
+  "gpt-5.3-codex": Object.freeze({
+    inputPerMillionUsd: 1.5,
+    outputPerMillionUsd: 6.0,
+  }),
+  "claude-sonnet-4": Object.freeze({
+    inputPerMillionUsd: 3.0,
+    outputPerMillionUsd: 15.0,
+  }),
+  "claude-sonnet-4.5": Object.freeze({
+    inputPerMillionUsd: 3.0,
+    outputPerMillionUsd: 15.0,
+  }),
+  "gemini-2.5-pro": Object.freeze({
+    inputPerMillionUsd: 2.5,
+    outputPerMillionUsd: 10.0,
+  }),
+});
+
+function normalizeTokenCount(value, field) {
+  const normalized = Number(value || 0);
+  if (!Number.isFinite(normalized) || normalized < 0) {
+    throw new Error(`${field} must be a non-negative number.`);
+  }
+  return normalized;
+}
+
+function normalizeUsd(value, field) {
+  const normalized = Number(value || 0);
+  if (!Number.isFinite(normalized) || normalized < 0) {
+    throw new Error(`${field} must be a non-negative number.`);
+  }
+  return normalized;
+}
+
+function roundUsd(value) {
+  return Math.round((Number(value || 0) + Number.EPSILON) * 1_000_000) / 1_000_000;
+}
+
+/**
+ * Estimate cost in USD from token counts and per-million pricing inputs.
+ *
+ * @param {{
+ *   inputTokens?: number,
+ *   outputTokens?: number,
+ *   inputPerMillionUsd?: number,
+ *   outputPerMillionUsd?: number
+ * }} [options]
+ * @returns {number}
+ */
+export function estimateCostUsd({
+  inputTokens = 0,
+  outputTokens = 0,
+  inputPerMillionUsd = 0,
+  outputPerMillionUsd = 0,
+} = {}) {
+  const normalizedInputTokens = normalizeTokenCount(inputTokens, "inputTokens");
+  const normalizedOutputTokens = normalizeTokenCount(outputTokens, "outputTokens");
+  const normalizedInputRate = normalizeUsd(inputPerMillionUsd, "inputPerMillionUsd");
+  const normalizedOutputRate = normalizeUsd(outputPerMillionUsd, "outputPerMillionUsd");
+
+  const inputCost = (normalizedInputTokens / 1_000_000) * normalizedInputRate;
+  const outputCost = (normalizedOutputTokens / 1_000_000) * normalizedOutputRate;
+
+  return roundUsd(inputCost + outputCost);
+}
+
+/**
+ * Estimate cost in USD using a named model pricing table entry.
+ *
+ * @param {{
+ *   modelId: string,
+ *   inputTokens?: number,
+ *   outputTokens?: number,
+ *   pricingTable?: Record<string, { inputPerMillionUsd: number, outputPerMillionUsd: number }>
+ * }} [options]
+ * @returns {number}
+ */
+export function estimateModelCost({
+  modelId,
+  inputTokens = 0,
+  outputTokens = 0,
+  pricingTable = DEFAULT_MODEL_PRICING,
+} = {}) {
+  const normalizedModelId = String(modelId || "").trim();
+  if (!normalizedModelId) {
+    throw new Error("modelId is required for model-based cost estimation.");
+  }
+
+  const modelPricing = pricingTable[normalizedModelId];
+  if (!modelPricing) {
+    throw new Error(`No pricing data configured for model '${normalizedModelId}'.`);
+  }
+
+  return estimateCostUsd({
+    inputTokens,
+    outputTokens,
+    inputPerMillionUsd: modelPricing.inputPerMillionUsd,
+    outputPerMillionUsd: modelPricing.outputPerMillionUsd,
+  });
+}
+
+/**
+ * Aggregate usage rows into a single token and cost summary.
+ *
+ * @param {Array<{ inputTokens?: number, outputTokens?: number, costUsd?: number }>} [entries]
+ * @returns {{ inputTokens: number, outputTokens: number, costUsd: number }}
+ */
+export function rollupUsage(entries = []) {
+  if (!Array.isArray(entries)) {
+    throw new Error("entries must be an array.");
+  }
+
+  const totals = entries.reduce(
+    (accumulator, entry) => {
+      const inputTokens = normalizeTokenCount(entry?.inputTokens || 0, "entry.inputTokens");
+      const outputTokens = normalizeTokenCount(entry?.outputTokens || 0, "entry.outputTokens");
+      const costUsd = normalizeUsd(entry?.costUsd || 0, "entry.costUsd");
+
+      return {
+        inputTokens: accumulator.inputTokens + inputTokens,
+        outputTokens: accumulator.outputTokens + outputTokens,
+        costUsd: accumulator.costUsd + costUsd,
+      };
+    },
+    { inputTokens: 0, outputTokens: 0, costUsd: 0 }
+  );
+
+  return {
+    inputTokens: totals.inputTokens,
+    outputTokens: totals.outputTokens,
+    costUsd: roundUsd(totals.costUsd),
+  };
+}
+
+/**
+ * Evaluate whether cumulative cost has exceeded a configured budget.
+ *
+ * @param {{ totalCostUsd?: number, budgetUsd?: number }} [options]
+ * @returns {{ budgetUsd: number, totalCostUsd: number, remainingUsd: number, exceeded: boolean }}
+ */
+export function enforceCostBudget({ totalCostUsd = 0, budgetUsd = 0 } = {}) {
+  const normalizedTotal = normalizeUsd(totalCostUsd, "totalCostUsd");
+  const normalizedBudget = normalizeUsd(budgetUsd, "budgetUsd");
+  const remainingUsd = roundUsd(Math.max(0, normalizedBudget - normalizedTotal));
+
+  return {
+    budgetUsd: roundUsd(normalizedBudget),
+    totalCostUsd: roundUsd(normalizedTotal),
+    remainingUsd,
+    exceeded: normalizedTotal > normalizedBudget,
+  };
+}
+
+/**
+ * Return the built-in model pricing catalog for diagnostics and UI display.
+ *
+ * @returns {Array<{ modelId: string, inputPerMillionUsd: number, outputPerMillionUsd: number }>}
+ */
+export function listKnownModelPricing() {
+  return Object.entries(DEFAULT_MODEL_PRICING).map(([modelId, pricing]) => ({
+    modelId,
+    inputPerMillionUsd: pricing.inputPerMillionUsd,
+    outputPerMillionUsd: pricing.outputPerMillionUsd,
+  }));
+}
+