sentinelayer-cli 0.9.5 → 0.9.7

package/package.json

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

package/src/billing/ledger-entry.js

@@ -0,0 +1,162 @@
+import crypto from "node:crypto";
+
+import { redactEventPayload } from "../session/redact.js";
+import { computeProviderCost, PRICE_BOOK_VERSION } from "./price-book.js";
+
+export const PRICED_ACTIONS = Object.freeze([
+  "audit_run",
+  "audit_security",
+  "audit_frontend",
+  "omargate_deep",
+]);
+
+const OMIT_METADATA_KEYS = new Set([
+  "content",
+  "input",
+  "message",
+  "messages",
+  "output",
+  "prompt",
+  "prompts",
+  "raw",
+  "rawtext",
+  "response",
+  "responses",
+  "text",
+]);
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeTokenCount(value, field) {
+  const parsed = Number(value || 0);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`${field} must be a non-negative number.`);
+  }
+  return Math.floor(parsed);
+}
+
+function normalizeIsoTimestamp(value, fallbackIso = new Date().toISOString()) {
+  const normalized = normalizeString(value);
+  if (!normalized) return fallbackIso;
+  const epoch = Date.parse(normalized);
+  if (!Number.isFinite(epoch)) {
+    throw new Error("createdAt must be an ISO timestamp.");
+  }
+  return new Date(epoch).toISOString();
+}
+
+export function stableHash(value) {
+  return crypto.createHash("sha256").update(String(value || "")).digest("hex");
+}
+
+function sanitizeMetadataValue(value, depth = 0) {
+  if (depth > 8) return "[REDACTED]";
+  if (Array.isArray(value)) {
+    return value
+      .map((item) => sanitizeMetadataValue(item, depth + 1))
+      .filter((item) => item !== undefined);
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, inner] of Object.entries(value)) {
+      const normalizedKey = normalizeString(key).toLowerCase().replace(/[^a-z0-9]/g, "");
+      if (!normalizedKey || OMIT_METADATA_KEYS.has(normalizedKey)) {
+        continue;
+      }
+      const sanitized = sanitizeMetadataValue(inner, depth + 1);
+      if (sanitized !== undefined) {
+        out[key] = sanitized;
+      }
+    }
+    return out;
+  }
+  return value;
+}
+
+export function sanitizeBillingMetadata(metadata = {}) {
+  const sanitized = sanitizeMetadataValue(metadata);
+  const redacted = redactEventPayload({ payload: sanitized });
+  return redacted?.payload && typeof redacted.payload === "object" ? redacted.payload : {};
+}
+
+export function buildBillingRunId({
+  sessionId,
+  invocationTimestamp,
+  configHash,
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedTimestamp = normalizeString(invocationTimestamp);
+  const normalizedConfigHash = normalizeString(configHash);
+  if (!normalizedSessionId) throw new Error("sessionId is required.");
+  if (!normalizedTimestamp) throw new Error("invocationTimestamp is required.");
+  if (!normalizedConfigHash) throw new Error("configHash is required.");
+  return stableHash(`${normalizedSessionId}|${normalizedTimestamp}|${normalizedConfigHash}`).slice(0, 16);
+}
+
+export function buildCallIdempotencyKey({ runId, callIndex = 0 } = {}) {
+  const normalizedRunId = normalizeString(runId);
+  if (!normalizedRunId) throw new Error("runId is required.");
+  const normalizedCallIndex = normalizeTokenCount(callIndex, "callIndex");
+  return `${normalizedRunId}:${normalizedCallIndex}`;
+}
+
+export function buildLedgerEntry({
+  sessionId,
+  agentId,
+  action,
+  model,
+  inputTokens = 0,
+  outputTokens = 0,
+  idempotencyKey,
+  billingTier = "internal",
+  metadata = {},
+  createdAt = "",
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedAgentId = normalizeString(agentId);
+  const normalizedAction = normalizeString(action);
+  const normalizedModel = normalizeString(model);
+  const normalizedIdempotencyKey = normalizeString(idempotencyKey);
+  if (!normalizedSessionId) throw new Error("sessionId is required.");
+  if (!normalizedAgentId) throw new Error("agentId is required.");
+  if (!normalizedAction) throw new Error("action is required.");
+  if (!normalizedModel) throw new Error("model is required.");
+  if (!normalizedIdempotencyKey) throw new Error("idempotencyKey is required.");
+
+  const priced = computeProviderCost({
+    model: normalizedModel,
+    inputTokens,
+    outputTokens,
+  });
+  const createdIso = normalizeIsoTimestamp(createdAt);
+  return {
+    ledgerEntryId: `bill_${stableHash(normalizedIdempotencyKey).slice(0, 16)}`,
+    schema: "billing/v1",
+    sessionId: normalizedSessionId,
+    agentId: normalizedAgentId,
+    action: normalizedAction,
+    model: normalizedModel,
+    canonicalModel: priced.canonicalModel,
+    priceBookVersion: PRICE_BOOK_VERSION,
+    inputTokens: priced.inputTokens,
+    outputTokens: priced.outputTokens,
+    totalTokens: priced.totalTokens,
+    providerCostUsd: priced.providerCostUsd,
+    customerCostUsd: null,
+    billingTier: normalizeString(billingTier) || "internal",
+    idempotencyKey: normalizedIdempotencyKey,
+    unpriced: Boolean(priced.unpriced),
+    createdAt: createdIso,
+    metadata: sanitizeBillingMetadata(metadata),
+  };
+}
+
+export function countPricedUsageEvents(events = [], pricedActions = PRICED_ACTIONS) {
+  const actions = new Set((Array.isArray(pricedActions) ? pricedActions : []).map(normalizeString));
+  return (Array.isArray(events) ? events : []).filter((event) => {
+    const payload = event?.payload || {};
+    return event?.event === "session_usage" && payload.schema === "billing/v1" && actions.has(normalizeString(payload.action));
+  }).length;
+}

package/src/billing/price-book.js

@@ -0,0 +1,123 @@
+export const PRICE_BOOK_VERSION = "2026-05-19";
+
+export const PRICE_BOOK_SOURCES = Object.freeze({
+  openai: "https://platform.openai.com/docs/pricing",
+  openaiCodex: "https://developers.openai.com/api/docs/models/gpt-5.3-codex",
+  anthropic: "https://docs.anthropic.com/en/docs/about-claude/pricing",
+});
+
+const RATE = (inputPerMTok, outputPerMTok, source, aliases = []) =>
+  Object.freeze({
+    inputPerMTok,
+    outputPerMTok,
+    currency: "USD",
+    source,
+    aliases,
+  });
+
+export const PRICE_BOOK = Object.freeze({
+  "gpt-5.4-mini": RATE(0.75, 4.5, "openai"),
+  "gpt-5.3-codex": RATE(1.75, 14, "openaiCodex"),
+  "gpt-5.2-codex": RATE(1.75, 14, "openai"),
+  "gpt-5.1-codex": RATE(1.25, 10, "openai"),
+  "gpt-5-codex": RATE(1.25, 10, "openai"),
+  "gpt-4.1-mini": RATE(0.4, 1.6, "openai"),
+  "claude-opus-4.1": RATE(15, 75, "anthropic", ["claude-opus-4-7"]),
+  "claude-opus-4": RATE(15, 75, "anthropic", ["claude-opus-4-6"]),
+  "claude-sonnet-4": RATE(3, 15, "anthropic", ["claude-sonnet-4-6"]),
+  "claude-sonnet-3.7": RATE(3, 15, "anthropic"),
+  "claude-sonnet-3.5": RATE(3, 15, "anthropic"),
+  "claude-haiku-3.5": RATE(0.8, 4, "anthropic"),
+  "claude-haiku-3": RATE(0.25, 1.25, "anthropic"),
+});
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeModel(value) {
+  return normalizeString(value).toLowerCase();
+}
+
+function normalizeTokenCount(value, field) {
+  const parsed = Number(value || 0);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`${field} must be a non-negative number.`);
+  }
+  return Math.floor(parsed);
+}
+
+function round6(value) {
+  return Math.round((Number(value || 0) + Number.EPSILON) * 1_000_000) / 1_000_000;
+}
+
+const ALIAS_TO_MODEL = Object.freeze(
+  Object.entries(PRICE_BOOK).reduce((acc, [model, rate]) => {
+    acc[model] = model;
+    for (const alias of rate.aliases || []) {
+      acc[normalizeModel(alias)] = model;
+    }
+    return acc;
+  }, {}),
+);
+
+export function resolvePriceBookRate(model) {
+  const requestedModel = normalizeString(model);
+  const normalized = normalizeModel(requestedModel);
+  const canonicalModel = ALIAS_TO_MODEL[normalized] || normalized;
+  const rate = PRICE_BOOK[canonicalModel] || null;
+  if (!rate) {
+    return {
+      model: requestedModel,
+      canonicalModel: normalized || requestedModel,
+      rate: null,
+      unpriced: true,
+      priceBookVersion: PRICE_BOOK_VERSION,
+    };
+  }
+  return {
+    model: requestedModel || canonicalModel,
+    canonicalModel,
+    rate,
+    unpriced: false,
+    priceBookVersion: PRICE_BOOK_VERSION,
+  };
+}
+
+export function computeProviderCost({
+  model,
+  inputTokens = 0,
+  outputTokens = 0,
+} = {}) {
+  const input = normalizeTokenCount(inputTokens, "inputTokens");
+  const output = normalizeTokenCount(outputTokens, "outputTokens");
+  const resolved = resolvePriceBookRate(model);
+  if (resolved.unpriced) {
+    return {
+      model: resolved.model,
+      canonicalModel: resolved.canonicalModel,
+      priceBookVersion: PRICE_BOOK_VERSION,
+      providerCostUsd: null,
+      unpriced: true,
+      inputTokens: input,
+      outputTokens: output,
+      totalTokens: input + output,
+    };
+  }
+  const providerCostUsd = round6(
+    (input / 1_000_000) * resolved.rate.inputPerMTok +
+      (output / 1_000_000) * resolved.rate.outputPerMTok,
+  );
+  return {
+    model: resolved.model,
+    canonicalModel: resolved.canonicalModel,
+    priceBookVersion: PRICE_BOOK_VERSION,
+    providerCostUsd,
+    unpriced: false,
+    inputTokens: input,
+    outputTokens: output,
+    totalTokens: input + output,
+    currency: resolved.rate.currency,
+    source: resolved.rate.source,
+  };
+}

package/src/billing/session-usage.js

@@ -0,0 +1,80 @@
+import process from "node:process";
+
+import { createAgentEvent } from "../events/schema.js";
+import { createSession } from "../session/store.js";
+import { appendToStream } from "../session/stream.js";
+import { buildLedgerEntry } from "./ledger-entry.js";
+
+const SESSION_USAGE_EVENT = "session_usage";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+async function appendUsageEvent(sessionId, envelope, { targetPath, syncRemote }) {
+  return appendToStream(sessionId, envelope, {
+    targetPath,
+    syncRemote,
+  });
+}
+
+export async function recordSessionUsage(
+  sessionId,
+  params = {},
+  {
+    targetPath = process.cwd(),
+    // Billing events originate in the CLI and must reach the API for server-side
+    // ledger/quota projection; this intentionally defaults to remote sync.
+    syncRemote = true,
+    ensureLocalSession = true,
+    append = appendUsageEvent,
+  } = {},
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) throw new Error("sessionId is required.");
+  const entry = buildLedgerEntry({
+    ...params,
+    sessionId: normalizedSessionId,
+  });
+  const envelope = createAgentEvent({
+    event: SESSION_USAGE_EVENT,
+    sessionId: normalizedSessionId,
+    agentId: entry.agentId,
+    agentModel: entry.model,
+    payload: {
+      ...entry,
+      costUsd: entry.providerCostUsd ?? 0,
+      usage: {
+        totalTokens: entry.totalTokens,
+        inputTokens: entry.inputTokens,
+        outputTokens: entry.outputTokens,
+        costUsd: entry.providerCostUsd ?? 0,
+        providerCostUsd: entry.providerCostUsd,
+        customerCostUsd: entry.customerCostUsd,
+      },
+    },
+    ts: entry.createdAt,
+  });
+
+  try {
+    await append(normalizedSessionId, envelope, { targetPath, syncRemote });
+  } catch (error) {
+    if (!ensureLocalSession || !/was not found/i.test(error?.message || "")) {
+      throw error;
+    }
+    await createSession({
+      sessionId: normalizedSessionId,
+      targetPath,
+      title: `Billing usage ${normalizedSessionId}`,
+      createdAt: entry.createdAt,
+      lastInteractionAt: entry.createdAt,
+    });
+    await append(normalizedSessionId, envelope, { targetPath, syncRemote });
+  }
+
+  return {
+    ok: true,
+    event: SESSION_USAGE_EVENT,
+    ledgerEntry: entry,
+  };
+}

package/src/commands/session.js

@@ -77,6 +77,11 @@ import {
   getTemplateRegistry,
   resolveSessionTemplate,
 } from "../session/templates.js";
+import {
+  createSessionCheckpoint,
+  generateSessionCheckpoint,
+  listSessionCheckpoints,
+} from "../session/checkpoints.js";
 import { authLoginHint } from "../ui/command-hints.js";
 import { parseCsvTokens } from "./ai/shared.js";
 
@@ -561,6 +566,53 @@ function formatEventLine(event = {}) {
   return `${ts} ${agentId} ${type}`;
 }
 
+function checkpointSequenceRange(checkpoint = {}) {
+  const start = Number(checkpoint.startSequence || 0);
+  const end = Number(checkpoint.endSequence || 0);
+  if (Number.isFinite(start) && start > 0 && Number.isFinite(end) && end > 0) {
+    return `#${Math.floor(start)}-${Math.floor(end)}`;
+  }
+  if (Number.isFinite(start) && start > 0) {
+    return `#${Math.floor(start)}`;
+  }
+  return "anchor pending";
+}
+
+function formatCheckpointLine(checkpoint = {}) {
+  const id = normalizeString(checkpoint.checkpointId) || "checkpoint";
+  const kind = normalizeString(checkpoint.kind) || "summary";
+  const title = normalizeString(checkpoint.title) || "Untitled checkpoint";
+  const byline = normalizeString(checkpoint.createdByAgentId || checkpoint.createdBy);
+  const by = byline ? ` by ${byline}` : "";
+  return `${checkpointSequenceRange(checkpoint)} ${id} [${kind}] ${title}${by}`;
+}
+
+async function readCheckpointSummaryOption(options = {}, { targetPath } = {}) {
+  const inlineSummary = normalizeString(options.summary);
+  const summaryFile = normalizeString(options.summaryFile);
+  if (inlineSummary && summaryFile) {
+    throw new Error("Use either --summary or --summary-file, not both.");
+  }
+  if (summaryFile) {
+    const resolved = path.resolve(targetPath || process.cwd(), summaryFile);
+    return fsp.readFile(resolved, "utf-8");
+  }
+  return inlineSummary;
+}
+
+async function hydrateAfterCheckpointMutation(sessionId, { targetPath } = {}) {
+  return hydrateSessionFromRemote({
+    sessionId,
+    targetPath,
+    probeOpenCircuit: false,
+    eventPageLimit: 200,
+    maxEventPages: 5,
+  }).catch((error) => ({
+    ok: false,
+    reason: error instanceof Error ? error.message : "hydrate_failed",
+  }));
+}
+
 async function appendMissingRemoteEvents(sessionId, remoteEvents = [], { targetPath } = {}) {
   const events = Array.isArray(remoteEvents) ? remoteEvents : [];
   if (events.length === 0) {
@@ -1884,6 +1936,155 @@ export function registerSessionCommand(program) {
       }
     });
 
+  const checkpoint = session
+    .command("checkpoint")
+    .description("List, create, and generate durable session checkpoints");
+
+  checkpoint
+    .command("list <sessionId>")
+    .description("List durable checkpoints for a remote session")
+    .option("--limit <n>", "Maximum checkpoints to return (default 100, max 200)", "100")
+    .option("--path <path>", "Workspace path for auth/session context", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const result = await listSessionCheckpoints(normalizedSessionId, {
+        targetPath,
+        limit: options.limit,
+      });
+      const payload = {
+        command: "session checkpoint list",
+        targetPath,
+        ...result,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      if (result.checkpoints.length === 0) {
+        console.log(pc.gray(`No checkpoints for session ${normalizedSessionId}.`));
+        return;
+      }
+      for (const item of result.checkpoints) {
+        console.log(formatCheckpointLine(item));
+      }
+    });
+
+  checkpoint
+    .command("create <sessionId>")
+    .description("Create a durable checkpoint anchored to a canonical sequence range")
+    .requiredOption("--start-sequence <n>", "First canonical event sequence included in the checkpoint")
+    .requiredOption("--end-sequence <n>", "Last canonical event sequence included in the checkpoint")
+    .requiredOption("--title <title>", "Short checkpoint title")
+    .option("--summary <text>", "Checkpoint summary text")
+    .option("--summary-file <file>", "Read checkpoint summary text from a file")
+    .option("--kind <kind>", "Checkpoint kind (summary, handoff, milestone, billing)", "summary")
+    .option("--checkpoint-id <id>", "Explicit checkpoint id; defaults to a stable hash of range/body")
+    .option("--agent <id>", "Optional agent id recorded as checkpoint creator")
+    .option("--token-start <n>", "Optional token-range start")
+    .option("--token-end <n>", "Optional token-range end")
+    .option("--path <path>", "Workspace path for auth/session context", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const agentId = normalizeString(options.agent)
+        ? await defaultAgentId(options.agent, targetPath)
+        : "";
+      const summary = await readCheckpointSummaryOption(options, { targetPath });
+      const result = await createSessionCheckpoint(normalizedSessionId, {
+        targetPath,
+        checkpointId: options.checkpointId,
+        startSequence: options.startSequence,
+        endSequence: options.endSequence,
+        kind: options.kind,
+        title: options.title,
+        summary,
+        createdByAgentId: agentId,
+        tokenStart: options.tokenStart,
+        tokenEnd: options.tokenEnd,
+      });
+      const hydration = await hydrateAfterCheckpointMutation(normalizedSessionId, { targetPath });
+      const payload = {
+        command: "session checkpoint create",
+        targetPath,
+        ...result,
+        hydration,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      const duplicate = result.duplicate ? "duplicate " : "";
+      console.log(pc.bold(`${duplicate}checkpoint created`));
+      if (result.checkpoint) {
+        console.log(formatCheckpointLine(result.checkpoint));
+      }
+      if (!hydration.ok) {
+        console.log(pc.gray(`Local hydrate skipped: ${hydration.reason || "unknown"}`));
+      }
+    });
+
+  checkpoint
+    .command("generate <sessionId>")
+    .description("Generate a checkpoint from the next uncheckpointed durable event window")
+    .option("--min-events <n>", "Minimum source events required before creating (default 20)", "20")
+    .option("--max-events <n>", "Maximum source events to summarize (default 80, max 200)", "80")
+    .option("--operation-id <key>", "Explicit retry key for this generate invocation")
+    .option("--agent <id>", "Optional agent id recorded as checkpoint creator")
+    .option("--path <path>", "Workspace path for auth/session context", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const agentId = normalizeString(options.agent)
+        ? await defaultAgentId(options.agent, targetPath)
+        : "";
+      const result = await generateSessionCheckpoint(normalizedSessionId, {
+        targetPath,
+        minEvents: options.minEvents,
+        maxEvents: options.maxEvents,
+        idempotencyKey: options.operationId,
+        createdByAgentId: agentId,
+      });
+      const hydration = result.checkpoint
+        ? await hydrateAfterCheckpointMutation(normalizedSessionId, { targetPath })
+        : null;
+      const payload = {
+        command: "session checkpoint generate",
+        targetPath,
+        ...result,
+        hydration: hydration || undefined,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      if (result.checkpoint) {
+        console.log(pc.bold(result.duplicate ? "checkpoint already covered" : "checkpoint generated"));
+        console.log(formatCheckpointLine(result.checkpoint));
+        if (hydration && !hydration.ok) {
+          console.log(pc.gray(`Local hydrate skipped: ${hydration.reason || "unknown"}`));
+        }
+        return;
+      }
+      console.log(
+        pc.gray(
+          `No checkpoint created: ${normalizeString(result.reason) || "not_needed"} (${Number(result.eventCount || 0)} events, min ${Number(result.minEvents || 0)}).`,
+        ),
+      );
+    });
+
   session
     .command("status <sessionId>")
     .description("Show session status, agents, and health")

package/src/cost/tracker.js

@@ -6,8 +6,16 @@ const DEFAULT_MODEL_PRICING = Object.freeze({
     outputPerMillionUsd: 10.0,
   }),
   "gpt-5.3-codex": Object.freeze({
-    inputPerMillionUsd: 1.5,
-    outputPerMillionUsd: 6.0,
+    inputPerMillionUsd: 1.75,
+    outputPerMillionUsd: 14.0,
+  }),
+  "gpt-5.4-mini": Object.freeze({
+    inputPerMillionUsd: 0.75,
+    outputPerMillionUsd: 4.5,
+  }),
+  "gpt-4.1-mini": Object.freeze({
+    inputPerMillionUsd: 0.4,
+    outputPerMillionUsd: 1.6,
   }),
   "claude-sonnet-4": Object.freeze({
     inputPerMillionUsd: 3.0,
@@ -21,6 +29,14 @@ const DEFAULT_MODEL_PRICING = Object.freeze({
     inputPerMillionUsd: 3.0,
     outputPerMillionUsd: 15.0,
   }),
+  "claude-opus-4": Object.freeze({
+    inputPerMillionUsd: 15.0,
+    outputPerMillionUsd: 75.0,
+  }),
+  "claude-opus-4.1": Object.freeze({
+    inputPerMillionUsd: 15.0,
+    outputPerMillionUsd: 75.0,
+  }),
   "claude-opus-4-6": Object.freeze({
     inputPerMillionUsd: 15.0,
     outputPerMillionUsd: 75.0,
@@ -29,6 +45,14 @@ const DEFAULT_MODEL_PRICING = Object.freeze({
     inputPerMillionUsd: 15.0,
     outputPerMillionUsd: 75.0,
   }),
+  "claude-haiku-3.5": Object.freeze({
+    inputPerMillionUsd: 0.8,
+    outputPerMillionUsd: 4.0,
+  }),
+  "claude-haiku-3": Object.freeze({
+    inputPerMillionUsd: 0.25,
+    outputPerMillionUsd: 1.25,
+  }),
   "gemini-2.5-pro": Object.freeze({
     inputPerMillionUsd: 2.5,
     outputPerMillionUsd: 10.0,

package/src/review/ai-review.js

@@ -1,15 +1,18 @@
 import fsp from "node:fs/promises";
 import path from "node:path";
+import crypto from "node:crypto";
 
 import {
   createMultiProviderApiClient,
   resolveModel,
   resolveProvider,
 } from "../ai/client.js";
+import { computeProviderCost } from "../billing/price-book.js";
+import { buildBillingRunId, buildCallIdempotencyKey } from "../billing/ledger-entry.js";
+import { recordSessionUsage } from "../billing/session-usage.js";
 import { loadConfig } from "../config/service.js";
 import { evaluateBudget } from "../cost/budget.js";
 import { appendCostEntry, summarizeCostHistory } from "../cost/history.js";
-import { estimateModelCost } from "../cost/tracker.js";
 import { estimateTokens } from "../cost/tokenizer.js";
 import { appendRunEvent, deriveStopClassFromBudget } from "../telemetry/ledger.js";
 
@@ -329,21 +332,22 @@ export function buildAiReviewPrompt({
 }
 
 function maybeEstimateModelCost({ modelId, inputTokens, outputTokens }) {
-  try {
-    return {
-      costUsd: estimateModelCost({
-        modelId,
-        inputTokens,
-        outputTokens,
-      }),
-      pricingFound: true,
-    };
-  } catch {
-    return {
-      costUsd: 0,
-      pricingFound: false,
-    };
-  }
+  const priced = computeProviderCost({
+    model: modelId,
+    inputTokens,
+    outputTokens,
+  });
+  return {
+    costUsd: priced.providerCostUsd ?? 0,
+    providerCostUsd: priced.providerCostUsd,
+    pricingFound: !priced.unpriced,
+    priceBookVersion: priced.priceBookVersion,
+    canonicalModel: priced.canonicalModel,
+  };
+}
+
+function stableConfigHash(value = {}) {
+  return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex");
 }
 
 function composeAiReviewMarkdown({
@@ -529,6 +533,7 @@ export async function runAiReviewLayer({
   });
 
   const startedAt = Date.now();
+  const startedAtIso = new Date(startedAt).toISOString();
   const responseText = dryRun
     ? buildDryRunResponse({
         deterministicSummary: deterministic?.summary || {},
@@ -643,6 +648,53 @@ export async function runAiReviewLayer({
     }
   );
 
+  let sessionUsageLedger = null;
+  try {
+    const billingRunId = buildBillingRunId({
+      sessionId: normalizedSessionId,
+      invocationTimestamp: startedAtIso,
+      configHash: stableConfigHash({
+        sourceCommand: "review",
+        layer: "ai_reasoning",
+        provider: resolvedProvider,
+        model: resolvedModel,
+        mode: normalizedMode,
+        runId: normalizedRunId,
+        dryRun: Boolean(dryRun),
+      }),
+    });
+    sessionUsageLedger = await recordSessionUsage(
+      normalizedSessionId,
+      {
+        agentId: "audit-orchestrator",
+        action: "audit_run",
+        model: resolvedModel,
+        inputTokens,
+        outputTokens,
+        idempotencyKey: buildCallIdempotencyKey({ runId: billingRunId, callIndex: 0 }),
+        billingTier: "internal",
+        createdAt: startedAtIso,
+        metadata: {
+          sourceCommand: "review",
+          layer: "ai_reasoning",
+          provider: resolvedProvider,
+          mode: normalizedMode,
+          runId: normalizedRunId,
+          dryRun: Boolean(dryRun),
+          pricingFound: modelCost.pricingFound,
+        },
+      },
+      {
+        targetPath: normalizedTargetPath,
+      },
+    );
+  } catch (error) {
+    sessionUsageLedger = {
+      ok: false,
+      reason: error instanceof Error ? error.message : String(error || "session_usage_failed"),
+    };
+  }
+
   let stopTelemetry = null;
   if (budget.blocking) {
     stopTelemetry = await appendRunEvent(
@@ -704,6 +756,7 @@ export async function runAiReviewLayer({
     dryRun: Boolean(dryRun),
     usage,
     pricingFound: modelCost.pricingFound,
+    sessionUsageLedger,
     budget,
     deterministicSummary,
     aiSummary,
@@ -756,6 +809,7 @@ export async function runAiReviewLayer({
       usageEventId: usageTelemetry.event.eventId,
       stopEventId: stopTelemetry?.event?.eventId || null,
     },
+    billing: sessionUsageLedger,
   };
 }
 

package/src/session/checkpoints.js

@@ -0,0 +1,294 @@
+import crypto from "node:crypto";
+import process from "node:process";
+
+import { requestJson, requestJsonMutation } from "../auth/http.js";
+import { resolveActiveAuthSession } from "../auth/service.js";
+
+const DEFAULT_API_BASE_URL = "https://api.sentinelayer.com";
+const DEFAULT_CHECKPOINT_LIMIT = 100;
+const MAX_CHECKPOINT_LIMIT = 200;
+const DEFAULT_MIN_EVENTS = 20;
+const DEFAULT_MAX_EVENTS = 80;
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeApiUrl(value) {
+  return (normalizeString(value) || DEFAULT_API_BASE_URL).replace(/\/+$/g, "");
+}
+
+function parsePositiveInteger(value, field, fallbackValue = null) {
+  if (value === undefined || value === null || normalizeString(value) === "") {
+    if (fallbackValue !== null) return fallbackValue;
+    throw new Error(`${field} is required.`);
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${field} must be a positive integer.`);
+  }
+  return Math.floor(parsed);
+}
+
+function normalizeLimit(value) {
+  const parsed = parsePositiveInteger(value, "limit", DEFAULT_CHECKPOINT_LIMIT);
+  return Math.max(1, Math.min(MAX_CHECKPOINT_LIMIT, parsed));
+}
+
+function stableHash(value) {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify(stableJson(value)))
+    .digest("hex");
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => stableJson(item));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const out = {};
+  for (const key of Object.keys(value).sort()) {
+    const next = stableJson(value[key]);
+    if (next !== undefined && next !== null && next !== "") {
+      out[key] = next;
+    }
+  }
+  return out;
+}
+
+function buildCheckpointFingerprint(payload) {
+  return stableHash(stableJson(payload));
+}
+
+function buildStableCheckpointId(sessionId, payload) {
+  const fingerprint = buildCheckpointFingerprint({
+    sessionId: normalizeString(sessionId),
+    startSequence: payload.startSequence,
+    endSequence: payload.endSequence,
+    kind: payload.kind,
+    title: payload.title,
+    summary: payload.summary,
+    createdByAgentId: payload.createdByAgentId,
+    tokenRange: payload.tokenRange || null,
+  });
+  return `cp_cli_${fingerprint.slice(0, 24)}`;
+}
+
+function buildStableIdempotencyKey(sessionId, operation, payload) {
+  const fingerprint = buildCheckpointFingerprint({
+    sessionId: normalizeString(sessionId),
+    operation,
+    payload,
+  });
+  return `sl_cli_session_checkpoint_${fingerprint}`;
+}
+
+function buildInvocationIdempotencyKey(operation) {
+  let suffix;
+  try {
+    suffix = crypto.randomUUID();
+  } catch {
+    suffix = crypto.randomBytes(16).toString("hex");
+  }
+  return `sl_cli_session_checkpoint_${normalizeString(operation) || "mutation"}_${suffix}`;
+}
+
+function normalizeTokenRange({ tokenStart, tokenEnd } = {}) {
+  const hasStart = tokenStart !== undefined && normalizeString(tokenStart) !== "";
+  const hasEnd = tokenEnd !== undefined && normalizeString(tokenEnd) !== "";
+  if (!hasStart && !hasEnd) return null;
+  const start = hasStart ? parsePositiveInteger(tokenStart, "token-start") : null;
+  const end = hasEnd ? parsePositiveInteger(tokenEnd, "token-end") : null;
+  if (start !== null && end !== null && start > end) {
+    throw new Error("token-start must be less than or equal to token-end.");
+  }
+  return { start, end };
+}
+
+export function buildManualCheckpointPayload(sessionId, {
+  checkpointId = "",
+  startSequence,
+  endSequence,
+  kind = "summary",
+  title,
+  summary,
+  createdByAgentId = "",
+  tokenStart,
+  tokenEnd,
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+  const normalizedStart = parsePositiveInteger(startSequence, "start-sequence");
+  const normalizedEnd = parsePositiveInteger(endSequence, "end-sequence");
+  if (normalizedStart > normalizedEnd) {
+    throw new Error("start-sequence must be less than or equal to end-sequence.");
+  }
+  const normalizedTitle = normalizeString(title);
+  if (!normalizedTitle) {
+    throw new Error("title is required.");
+  }
+  const normalizedSummary = normalizeString(summary);
+  if (!normalizedSummary) {
+    throw new Error("summary is required.");
+  }
+  const normalizedKind = normalizeString(kind) || "summary";
+  const normalizedCreatedBy = normalizeString(createdByAgentId);
+  const tokenRange = normalizeTokenRange({ tokenStart, tokenEnd });
+  const body = {
+    startSequence: normalizedStart,
+    endSequence: normalizedEnd,
+    kind: normalizedKind,
+    title: normalizedTitle,
+    summary: normalizedSummary,
+  };
+  if (normalizedCreatedBy) {
+    body.createdByAgentId = normalizedCreatedBy;
+  }
+  if (tokenRange) {
+    body.tokenRange = tokenRange;
+  }
+  body.checkpointId = normalizeString(checkpointId) || buildStableCheckpointId(normalizedSessionId, body);
+  return {
+    body,
+    idempotencyKey: buildStableIdempotencyKey(normalizedSessionId, "create", body),
+  };
+}
+
+export function buildGenerateCheckpointPayload(sessionId, {
+  minEvents = DEFAULT_MIN_EVENTS,
+  maxEvents = DEFAULT_MAX_EVENTS,
+  createdByAgentId = "",
+  idempotencyKey = "",
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+  const normalizedMin = parsePositiveInteger(minEvents, "min-events", DEFAULT_MIN_EVENTS);
+  const normalizedMax = parsePositiveInteger(maxEvents, "max-events", DEFAULT_MAX_EVENTS);
+  if (normalizedMin > 200) {
+    throw new Error("min-events must be less than or equal to 200.");
+  }
+  if (normalizedMax > 200) {
+    throw new Error("max-events must be less than or equal to 200.");
+  }
+  if (normalizedMax < normalizedMin) {
+    throw new Error("max-events must be greater than or equal to min-events.");
+  }
+  const body = {
+    minEvents: normalizedMin,
+    maxEvents: normalizedMax,
+  };
+  const normalizedCreatedBy = normalizeString(createdByAgentId);
+  if (normalizedCreatedBy) {
+    body.createdByAgentId = normalizedCreatedBy;
+  }
+  return {
+    body,
+    idempotencyKey:
+      normalizeString(idempotencyKey) || buildInvocationIdempotencyKey("generate"),
+  };
+}
+
+async function resolveCheckpointApi({
+  targetPath = process.cwd(),
+  resolveAuthSession = resolveActiveAuthSession,
+} = {}) {
+  const auth = await resolveAuthSession({
+    cwd: targetPath,
+    env: process.env,
+    autoRotate: false,
+  });
+  if (!auth || !auth.token) {
+    throw new Error("Sentinelayer auth is required. Run `sl auth login` first.");
+  }
+  return {
+    apiUrl: normalizeApiUrl(auth.apiUrl),
+    headers: { Authorization: `Bearer ${auth.token}` },
+  };
+}
+
+export async function listSessionCheckpoints(sessionId, {
+  targetPath = process.cwd(),
+  limit = DEFAULT_CHECKPOINT_LIMIT,
+  resolveAuthSession = resolveActiveAuthSession,
+  request = requestJson,
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+  const { apiUrl, headers } = await resolveCheckpointApi({ targetPath, resolveAuthSession });
+  const params = new URLSearchParams({ limit: String(normalizeLimit(limit)) });
+  const response = await request(
+    `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/checkpoints?${params.toString()}`,
+    { method: "GET", headers },
+  );
+  const checkpoints = Array.isArray(response?.checkpoints) ? response.checkpoints : [];
+  return {
+    ok: true,
+    sessionId: normalizedSessionId,
+    apiUrl,
+    checkpoints,
+    count: Number(response?.count ?? checkpoints.length) || checkpoints.length,
+  };
+}
+
+export async function createSessionCheckpoint(sessionId, options = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const {
+    targetPath = process.cwd(),
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = options;
+  const { body, idempotencyKey } = buildManualCheckpointPayload(normalizedSessionId, options);
+  const { apiUrl, headers } = await resolveCheckpointApi({ targetPath, resolveAuthSession });
+  const response = await requestMutation(
+    `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/checkpoints`,
+    {
+      operationName: "session-checkpoint-create",
+      headers,
+      body,
+      idempotencyKey,
+    },
+  );
+  return {
+    ...response,
+    sessionId: normalizedSessionId,
+    apiUrl,
+    checkpoint: response?.checkpoint || null,
+    idempotencyKey,
+  };
+}
+
+export async function generateSessionCheckpoint(sessionId, options = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const {
+    targetPath = process.cwd(),
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = options;
+  const { body, idempotencyKey } = buildGenerateCheckpointPayload(normalizedSessionId, options);
+  const { apiUrl, headers } = await resolveCheckpointApi({ targetPath, resolveAuthSession });
+  const response = await requestMutation(
+    `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/checkpoints/generate`,
+    {
+      operationName: "session-checkpoint-generate",
+      headers,
+      body,
+      idempotencyKey,
+    },
+  );
+  return {
+    ...response,
+    sessionId: normalizedSessionId,
+    apiUrl,
+    checkpoint: response?.checkpoint || null,
+    idempotencyKey,
+  };
+}