sentinelayer-cli 0.16.0 → 0.17.1

package/src/review/investor-dd-progress.js

@@ -0,0 +1,351 @@
+export const INVESTOR_DD_PROGRESS_VERSION = "investor_dd_progress_v1";
+
+export const INVESTOR_DD_EXPECTED_PERSONAS = Object.freeze([
+  "security",
+  "backend",
+  "code-quality",
+  "testing",
+  "data-layer",
+  "reliability",
+  "release",
+  "observability",
+  "infrastructure",
+  "supply-chain",
+  "documentation",
+  "ai-governance",
+  "frontend",
+]);
+
+const REQUIRED_FOR_SELLABLE = Object.freeze([
+  "persona_roster",
+  "persona_agentic_loops",
+  "senti_streaming",
+  "usage_margin_telemetry",
+  "live_reconciliation",
+  "devtestbot_runtime",
+  "report_email",
+  "artifact_bundle",
+]);
+
+function uniqueStrings(values) {
+  return Array.from(new Set((values || []).map((value) => String(value || "").trim()).filter(Boolean)));
+}
+
+function compactBudgetState(budgetState) {
+  if (!budgetState || typeof budgetState !== "object") return null;
+  return {
+    spentUsd: Number.isFinite(budgetState.spentUsd) ? budgetState.spentUsd : 0,
+    maxUsd: Number.isFinite(budgetState.maxUsd) ? budgetState.maxUsd : null,
+    toolCalls: Number.isFinite(budgetState.toolCalls) ? budgetState.toolCalls : 0,
+    llmCalls: Number.isFinite(budgetState.llmCalls) ? budgetState.llmCalls : 0,
+  };
+}
+
+function usageLedgerKey(entry) {
+  return [
+    entry?.ledgerEntry?.ledgerEntryId,
+    entry?.action,
+    entry?.ledgerEntry?.idempotencyKey,
+    entry?.inputTokens,
+    entry?.outputTokens,
+  ].map((value) => String(value || "")).join(":");
+}
+
+function collectSessionUsageLedgerEntries({ budgetState = null, devTestBotPhase = null, usageLedgerEntries = [] }) {
+  const candidates = [
+    ...(Array.isArray(usageLedgerEntries) ? usageLedgerEntries : []),
+    ...(Array.isArray(budgetState?.sessionUsageLedgerEntries) ? budgetState.sessionUsageLedgerEntries : []),
+    devTestBotPhase?.plan?.usageLedger,
+  ].filter((entry) => entry?.ok);
+  const seen = new Set();
+  const entries = [];
+  for (const entry of candidates) {
+    const key = usageLedgerKey(entry);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    entries.push(entry);
+  }
+  return entries;
+}
+
+function byId(capabilities, id) {
+  return capabilities.find((capability) => capability.id === id);
+}
+
+function addCapability(capabilities, capability) {
+  capabilities.push({
+    requiredForSellable: REQUIRED_FOR_SELLABLE.includes(capability.id),
+    evidence: [],
+    gaps: [],
+    ...capability,
+  });
+}
+
+function countByStatus(capabilities, status) {
+  return capabilities.filter((capability) => capability.status === status).length;
+}
+
+export function summarizeInvestorDdProgress(capabilities) {
+  const required = capabilities.filter((capability) => capability.requiredForSellable);
+  const blockingGaps = required
+    .filter((capability) => capability.status !== "complete")
+    .flatMap((capability) => capability.gaps.map((gap) => ({ capabilityId: capability.id, gap })));
+
+  return {
+    total: capabilities.length,
+    complete: countByStatus(capabilities, "complete"),
+    partial: countByStatus(capabilities, "partial"),
+    deferred: countByStatus(capabilities, "deferred"),
+    notConfigured: countByStatus(capabilities, "not_configured"),
+    requiredTotal: required.length,
+    requiredComplete: required.filter((capability) => capability.status === "complete").length,
+    blockingGapCount: blockingGaps.length,
+    blockingGaps,
+  };
+}
+
+export function buildInvestorDdProgress({
+  runId,
+  generatedAt = new Date().toISOString(),
+  personas = [],
+  dryRun = false,
+  routing = {},
+  byPersona = {},
+  findings = [],
+  compliance = null,
+  reconciliationAvailable = false,
+  liveValidator = null,
+  devTestBotPhase = null,
+  reportEmailConfigured = false,
+  reportEmailResult = null,
+  notification = null,
+  artifactFiles = [],
+  budgetState = null,
+  usageLedgerEntries = [],
+} = {}) {
+  const activePersonas = uniqueStrings(personas);
+  const missingPersonas = INVESTOR_DD_EXPECTED_PERSONAS.filter(
+    (personaId) => !activePersonas.includes(personaId),
+  );
+  const extraPersonas = activePersonas.filter(
+    (personaId) => !INVESTOR_DD_EXPECTED_PERSONAS.includes(personaId),
+  );
+  const capabilities = [];
+
+  addCapability(capabilities, {
+    id: "persona_roster",
+    label: "13-persona DD roster",
+    status: missingPersonas.length === 0 ? "complete" : "partial",
+    evidence: [
+      `activePersonas=${activePersonas.length}`,
+      `expectedPersonas=${INVESTOR_DD_EXPECTED_PERSONAS.length}`,
+    ],
+    gaps: missingPersonas.length
+      ? [`missing expected personas: ${missingPersonas.join(", ")}`]
+      : [],
+    metadata: { activePersonas, expectedPersonas: INVESTOR_DD_EXPECTED_PERSONAS, missingPersonas, extraPersonas },
+  });
+
+  const personaRecords = activePersonas.filter((personaId) => byPersona && byPersona[personaId]);
+  const allActivePersonasRecorded =
+    activePersonas.length > 0 && personaRecords.length === activePersonas.length;
+  addCapability(capabilities, {
+    id: "persona_agentic_loops",
+    label: "Per-persona file loop execution",
+    status: dryRun ? "deferred" : allActivePersonasRecorded ? "complete" : "partial",
+    evidence: dryRun
+      ? ["dryRun=true"]
+      : [`personaRecords=${personaRecords.length}/${activePersonas.length}`],
+    gaps: dryRun
+      ? ["dry-run skips persona execution"]
+      : allActivePersonasRecorded
+        ? []
+        : ["not every active persona produced a persona artifact"],
+  });
+
+  const streamPresent = artifactFiles.includes("stream.ndjson");
+  addCapability(capabilities, {
+    id: "senti_streaming",
+    label: "Senti session streaming and progress spine",
+    status: streamPresent ? "partial" : "not_configured",
+    evidence: streamPresent ? ["stream.ndjson artifact present"] : [],
+    gaps: [
+      "orchestrator emits local NDJSON but does not record an attached Senti session id",
+      "live web/session token counters are not part of the DD summary contract",
+    ],
+  });
+
+  const compactBudget = compactBudgetState(budgetState);
+  const sessionUsageLedgerEntries = collectSessionUsageLedgerEntries({
+    budgetState,
+    devTestBotPhase,
+    usageLedgerEntries,
+  });
+  const hasSessionUsageLedger = sessionUsageLedgerEntries.length > 0;
+  addCapability(capabilities, {
+    id: "usage_margin_telemetry",
+    label: "Billing-grade per-agent usage, token, time, LOC, and margin telemetry",
+    status: compactBudget || hasSessionUsageLedger ? "partial" : dryRun ? "deferred" : "not_configured",
+    evidence: compactBudget || hasSessionUsageLedger
+      ? [
+          ...(compactBudget
+            ? [
+                `localBudgetSpentUsd=${compactBudget.spentUsd}`,
+                `localBudgetToolCalls=${compactBudget.toolCalls}`,
+                `localBudgetLlmCalls=${compactBudget.llmCalls}`,
+              ]
+            : []),
+          `sessionUsageLedger=${hasSessionUsageLedger}`,
+          ...sessionUsageLedgerEntries.map((entry) =>
+            `usageLedgerEntry=${entry.ledgerEntry?.ledgerEntryId || "recorded"}`
+          ),
+        ]
+      : dryRun
+        ? ["dryRun=true"]
+        : [],
+    gaps: [
+      hasSessionUsageLedger
+        ? "only optional DD planner calls are wired to billing-grade session_usage"
+        : "budgetState is a local run governor, not the billing-grade session_usage ledger",
+      "summary does not include per-agent token totals",
+      "summary does not include per-agent runtime, LOC scanned, customer price, or margin",
+    ],
+  });
+
+  addCapability(capabilities, {
+    id: "compliance_pack",
+    label: "Compliance pack dispatch",
+    requiredForSellable: false,
+    status: compliance ? "complete" : dryRun ? "deferred" : "not_configured",
+    evidence: compliance
+      ? [`totalCovered=${compliance.totalCovered || 0}`, `totalGaps=${compliance.totalGaps || 0}`]
+      : dryRun
+        ? ["dryRun=true"]
+        : [],
+    gaps: compliance ? [] : ["compliance pack did not run for this invocation"],
+  });
+
+  addCapability(capabilities, {
+    id: "live_reconciliation",
+    label: "Live product validation and reconciliation",
+    status: reconciliationAvailable ? "complete" : liveValidator ? "partial" : "not_configured",
+    evidence: reconciliationAvailable
+      ? ["live-observations.json and reconciliation verdicts available"]
+      : liveValidator
+        ? ["liveValidator config supplied"]
+        : [],
+    gaps: reconciliationAvailable
+      ? []
+      : ["findings were not reconciled against live product observations"],
+  });
+
+  const devSkipped = Boolean(devTestBotPhase?.skipped);
+  addCapability(capabilities, {
+    id: "devtestbot_runtime",
+    label: "devTestBot/AIdenID runtime phase",
+    status: devTestBotPhase
+      ? devSkipped
+        ? "partial"
+        : "complete"
+      : dryRun
+        ? "deferred"
+        : "not_configured",
+    evidence: devTestBotPhase
+      ? [
+          `skipped=${devSkipped}`,
+          `findingCount=${devTestBotPhase.findingCount || 0}`,
+          `artifactRoot=${devTestBotPhase.artifactRoot || ""}`,
+        ]
+      : dryRun
+        ? ["dryRun=true"]
+        : [],
+    gaps: devTestBotPhase && !devSkipped
+      ? []
+      : ["devTestBot runtime evidence is missing or skipped for this run"],
+  });
+
+  addCapability(capabilities, {
+    id: "report_email",
+    label: "Investor report email delivery",
+    status: reportEmailResult?.queued
+      ? "complete"
+      : reportEmailConfigured
+        ? "partial"
+        : dryRun
+          ? "deferred"
+          : "not_configured",
+    evidence: reportEmailResult
+      ? [
+          `queued=${Boolean(reportEmailResult.queued)}`,
+          `skipped=${Boolean(reportEmailResult.skipped)}`,
+          `code=${reportEmailResult.code || ""}`,
+        ]
+      : dryRun
+        ? ["dryRun=true"]
+        : [],
+    gaps: reportEmailResult?.queued
+      ? []
+      : ["no queued DD report email is recorded for this run"],
+  });
+
+  const artifactRequired = dryRun
+    ? ["plan.json", "stream.ndjson", "summary.json", "report.md", "report.html"]
+    : ["plan.json", "stream.ndjson", "summary.json", "report.md", "report.html", "findings.json"];
+  const missingArtifacts = artifactRequired.filter((file) => !artifactFiles.includes(file));
+  addCapability(capabilities, {
+    id: "artifact_bundle",
+    label: "Portable artifact bundle",
+    status: missingArtifacts.length === 0 ? "complete" : "partial",
+    evidence: [`artifactFiles=${artifactFiles.length}`, "manifest.json is written after progress.json"],
+    gaps: missingArtifacts.map((file) => `missing artifact: ${file}`),
+  });
+
+  addCapability(capabilities, {
+    id: "notification_delivery",
+    label: "Dashboard/email notification delivery",
+    requiredForSellable: false,
+    status: notification ? "partial" : "not_configured",
+    evidence: notification ? ["notification config supplied"] : [],
+    gaps: notification
+      ? ["notification result is not captured in summary.json/progress.json"]
+      : ["notification clients were not configured for this invocation"],
+  });
+
+  const progressSummary = summarizeInvestorDdProgress(capabilities);
+  const sellableReady = progressSummary.requiredComplete === progressSummary.requiredTotal;
+
+  return {
+    version: INVESTOR_DD_PROGRESS_VERSION,
+    generatedAt,
+    runId: runId || "",
+    overallStatus: sellableReady ? "complete" : "partial",
+    sellableReady,
+    truthfulClaim: sellableReady ? "sellable_ready" : "not_sellable_ready",
+    summary: progressSummary,
+    requiredCapabilityIds: REQUIRED_FOR_SELLABLE,
+    activePersonaCount: activePersonas.length,
+    plannedPersonaCount: INVESTOR_DD_EXPECTED_PERSONAS.length,
+    missingPersonas,
+    capabilities,
+    routingSummary: {
+      routedPersonas: Object.keys(routing || {}).length,
+      routedFiles: Object.values(routing || {}).reduce(
+        (count, files) => count + (Array.isArray(files) ? files.length : 0),
+        0,
+      ),
+    },
+    findingCount: Array.isArray(findings) ? findings.length : 0,
+    nextRecommendedSlices: byId(capabilities, "persona_roster")?.status === "complete"
+      ? [
+          "wire Senti session id and live usage counters into Investor-DD runs",
+          "add per-agent token/time/LOC/customer-price/margin telemetry",
+          "require live reconciliation and report-email proof for sellable DD closeout",
+        ]
+      : [
+          "add the missing frontend/Jules persona to the default Investor-DD roster",
+          "wire Senti session id and live usage counters into Investor-DD runs",
+          "add per-agent token/time/LOC/customer-price/margin telemetry",
+          "require live reconciliation and report-email proof for sellable DD closeout",
+        ],
+  };
+}

package/src/review/investor-dd-usage.js

@@ -0,0 +1,227 @@
+import { recordCliLlmSessionUsage, usageNumber } from "../billing/llm-session-usage.js";
+import { sanitizeBillingMetadata } from "../billing/ledger-entry.js";
+
+export const INVESTOR_DD_USAGE_ACTIONS = Object.freeze({
+  devTestBotPlanner: "investor_dd_devtestbot_planner",
+  filePlanner: "investor_dd_file_planner",
+});
+
+export class InvestorDdUsageLedgerError extends Error {
+  constructor(message, result = null) {
+    super(message);
+    this.name = "InvestorDdUsageLedgerError";
+    this.code = "INVESTOR_DD_USAGE_LEDGER_FAILED";
+    this.result = result;
+  }
+}
+
+export function isInvestorDdUsageLedgerError(error) {
+  return error instanceof InvestorDdUsageLedgerError
+    || String(error?.code || "") === "INVESTOR_DD_USAGE_LEDGER_FAILED";
+}
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function plainObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function normalizeBool(value) {
+  return value === true || value === "true" || value === "1";
+}
+
+function modelFrom(response, fallback) {
+  return normalizeString(response?.usage?.model)
+    || normalizeString(response?.model)
+    || normalizeString(fallback)
+    || "gpt-5.3-codex";
+}
+
+function providerFrom(response, fallback) {
+  return normalizeString(response?.usage?.provider)
+    || normalizeString(response?.provider)
+    || normalizeString(fallback);
+}
+
+function normalizeUsageContext(usageContext = {}, defaults = {}) {
+  const context = plainObject(usageContext);
+  const fallback = plainObject(defaults);
+  return {
+    sessionId: normalizeString(context.sessionId || fallback.sessionId),
+    agentId: normalizeString(context.agentId || fallback.agentId),
+    model: normalizeString(context.model || fallback.model),
+    provider: normalizeString(context.provider || fallback.provider),
+    targetPath: normalizeString(context.targetPath || fallback.targetPath),
+    billingTier: normalizeString(context.billingTier || fallback.billingTier) || "internal",
+    sourceCommand: normalizeString(context.sourceCommand || fallback.sourceCommand) || "omargate investor-dd",
+    syncRemote: context.syncRemote !== undefined ? context.syncRemote !== false : fallback.syncRemote !== false,
+    required: normalizeBool(context.required ?? fallback.required),
+    recorder: typeof context.recorder === "function"
+      ? context.recorder
+      : typeof fallback.recorder === "function"
+        ? fallback.recorder
+        : recordCliLlmSessionUsage,
+  };
+}
+
+function firstProviderUsageNumber(usage, keys) {
+  const source = plainObject(usage);
+  for (const key of keys) {
+    if (!Object.prototype.hasOwnProperty.call(source, key)) continue;
+    const parsed = Number(source[key]);
+    if (Number.isFinite(parsed) && parsed >= 0) {
+      return { found: true, value: Math.floor(parsed) };
+    }
+  }
+  return { found: false, value: 0 };
+}
+
+function usageFailure(context, reason, message) {
+  const result = {
+    ok: false,
+    reason,
+    required: context.required,
+  };
+  if (context.required) {
+    throw new InvestorDdUsageLedgerError(message, result);
+  }
+  return result;
+}
+
+export function assertInvestorDdUsageContextReady({
+  usageContext = {},
+  defaults = {},
+  action,
+  agentId = "",
+  model = "",
+  targetPath = "",
+} = {}) {
+  const context = normalizeUsageContext(usageContext, {
+    ...defaults,
+    agentId,
+    model,
+    targetPath,
+  });
+  if (!context.required) {
+    return { ok: true, required: false };
+  }
+  const normalizedAction = normalizeString(action);
+  const normalizedAgentId = normalizeString(agentId || context.agentId);
+  const normalizedModel = normalizeString(model || context.model);
+  if (!context.sessionId || !normalizedAgentId || !normalizedAction || !normalizedModel) {
+    throw new InvestorDdUsageLedgerError(
+      "Investor-DD required usage ledger context is incomplete before planner spend.",
+      {
+        ok: false,
+        reason: "missing_session_usage_context",
+        required: true,
+      },
+    );
+  }
+  return { ok: true, required: true };
+}
+
+export async function recordInvestorDdLlmUsage({
+  usageContext = {},
+  defaults = {},
+  action,
+  agentId = "",
+  phase = "",
+  response = "",
+  model = "",
+  provider = "",
+  startedAtIso = "",
+  targetPath = "",
+  metadata = {},
+} = {}) {
+  const context = normalizeUsageContext(usageContext, {
+    ...defaults,
+    agentId,
+    model,
+    provider,
+    targetPath,
+  });
+  const normalizedAction = normalizeString(action);
+  const normalizedAgentId = normalizeString(agentId || context.agentId);
+  const normalizedModel = modelFrom(response, model || context.model);
+  const normalizedProvider = providerFrom(response, provider || context.provider);
+  const createdAt = normalizeString(startedAtIso) || new Date().toISOString();
+
+  if (!context.sessionId || !normalizedAgentId || !normalizedAction || !normalizedModel) {
+    const result = {
+      ok: false,
+      reason: "missing_session_usage_context",
+      required: context.required,
+    };
+    if (context.required) {
+      throw new InvestorDdUsageLedgerError("Investor-DD session usage context is required.", result);
+    }
+    return result;
+  }
+
+  const usage = plainObject(response?.usage);
+  const input = firstProviderUsageNumber(usage, ["inputTokens", "input_tokens", "tokens_in"]);
+  const output = firstProviderUsageNumber(usage, ["outputTokens", "output_tokens", "tokens_out"]);
+  if (!input.found && !output.found) {
+    return usageFailure(
+      context,
+      "missing_provider_usage",
+      "Investor-DD planner response did not include provider token usage.",
+    );
+  }
+  const inputTokens = usageNumber(input.value, 0);
+  const outputTokens = usageNumber(output.value, 0);
+  if (inputTokens + outputTokens <= 0) {
+    return usageFailure(
+      context,
+      "zero_provider_tokens",
+      "Investor-DD planner response reported zero provider tokens.",
+    );
+  }
+
+  try {
+    const result = await context.recorder({
+      sessionId: context.sessionId,
+      agentId: normalizedAgentId,
+      action: normalizedAction,
+      model: normalizedModel,
+      inputTokens,
+      outputTokens,
+      startedAtIso: createdAt,
+      targetPath: context.targetPath,
+      billingTier: context.billingTier,
+      sourceCommand: context.sourceCommand,
+      provider: normalizedProvider,
+      syncRemote: context.syncRemote,
+      metadata: sanitizeBillingMetadata({
+        phase,
+        ...plainObject(metadata),
+      }),
+    });
+    if ((!result || result.ok === false) && context.required) {
+      throw new InvestorDdUsageLedgerError(
+        `Investor-DD session usage ledger failed: ${result?.reason || "unknown"}`,
+        result || null,
+      );
+    }
+    return {
+      ...(result || { ok: false, reason: "missing_result" }),
+      inputTokens,
+      outputTokens,
+      action: normalizedAction,
+    };
+  } catch (error) {
+    if (error instanceof InvestorDdUsageLedgerError) throw error;
+    const result = {
+      ok: false,
+      reason: error instanceof Error ? error.message : String(error || "session_usage_failed"),
+      required: context.required,
+    };
+    if (context.required) {
+      throw new InvestorDdUsageLedgerError(result.reason, result);
+    }
+    return result;
+  }
+}