sentinelayer-cli 0.16.0 → 0.17.1

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

@@ -14,6 +14,12 @@ import crypto from "node:crypto";
 import { recordProvisionedIdentity } from "../ai/identity-store.js";
 import { runDevTestBotSession } from "../agents/devtestbot/tool.js";
 import { checkBudget } from "./investor-dd-file-loop.js";
+import {
+  INVESTOR_DD_USAGE_ACTIONS,
+  assertInvestorDdUsageContextReady,
+  isInvestorDdUsageLedgerError,
+  recordInvestorDdLlmUsage,
+} from "./investor-dd-usage.js";
 
 export const DEVTESTBOT_PHASE_MAX_CONCURRENT = 4;
 export const DEVTESTBOT_PHASE_DEFAULT_SCOPE = "smoke";
@@ -80,23 +86,69 @@ function buildPlannerPrompt({ rootPath, files = [], findings = [], budget = {} }
   ].join("\n");
 }
 
-async function callPlannerClient({ plannerClient, rootPath, files, findings, budget }) {
-  if (!plannerClient) return {};
+async function callPlannerClient({ plannerClient, rootPath, files, findings, budget, sessionUsage }) {
+  if (!plannerClient) return { planned: {}, usageLedger: null };
   const prompt = buildPlannerPrompt({ rootPath, files, findings, budget });
   if (typeof plannerClient.decideDevTestBotPhase === "function") {
-    return plannerClient.decideDevTestBotPhase({ rootPath, files, findings, budget, prompt });
+    return {
+      planned: await plannerClient.decideDevTestBotPhase({ rootPath, files, findings, budget, prompt }),
+      usageLedger: null,
+    };
   }
+  if (sessionUsage) {
+    assertInvestorDdUsageContextReady({
+      usageContext: sessionUsage,
+      action: INVESTOR_DD_USAGE_ACTIONS.devTestBotPlanner,
+      agentId: "investor-dd-devtestbot-planner",
+      targetPath: rootPath,
+    });
+  }
+  const startedAtIso = new Date().toISOString();
   if (typeof plannerClient.invoke === "function") {
     const response = await plannerClient.invoke({ prompt, stream: false });
-    return parsePlannerJson(response?.text || response);
+    const usageLedger = sessionUsage
+      ? await recordInvestorDdLlmUsage({
+          usageContext: sessionUsage,
+          action: INVESTOR_DD_USAGE_ACTIONS.devTestBotPlanner,
+          agentId: "investor-dd-devtestbot-planner",
+          phase: "devtestbot_planner",
+          prompt,
+          response,
+          model: response?.model,
+          provider: response?.provider,
+          startedAtIso,
+          targetPath: rootPath,
+          metadata: {
+            plannerClient: "invoke",
+          },
+        })
+      : null;
+    return { planned: parsePlannerJson(response?.text || response), usageLedger };
   }
   if (typeof plannerClient.generatePlan === "function") {
     const response = await plannerClient.generatePlan([{ role: "user", content: prompt }], {
       phase: "devtestbot",
     });
-    return parsePlannerJson(response?.text || response?.content || response);
+    const usageLedger = sessionUsage
+      ? await recordInvestorDdLlmUsage({
+          usageContext: sessionUsage,
+          action: INVESTOR_DD_USAGE_ACTIONS.devTestBotPlanner,
+          agentId: "investor-dd-devtestbot-planner",
+          phase: "devtestbot_planner",
+          messages: [{ role: "user", content: prompt }],
+          response,
+          model: response?.model,
+          provider: response?.provider,
+          startedAtIso,
+          targetPath: rootPath,
+          metadata: {
+            plannerClient: "generatePlan",
+          },
+        })
+      : null;
+    return { planned: parsePlannerJson(response?.text || response?.content || response), usageLedger };
   }
-  return {};
+  return { planned: {}, usageLedger: null };
 }
 
 function chooseScope({ requestedScope, files = [], findings = [], plannedScope }) {
@@ -135,6 +187,7 @@ function normalizePhaseOptions(options = {}) {
     runner: source.runner || null,
     provisionIdentity: source.provisionIdentity || null,
     maxConcurrentAgents: source.maxConcurrentAgents,
+    sessionUsage: source.sessionUsage || null,
   };
 }
 
@@ -178,15 +231,22 @@ export async function planDevTestBotPhase({
   }
 
   let planned = {};
+  let usageLedger = null;
   try {
-    planned = await callPlannerClient({
+    const plannerResult = await callPlannerClient({
       plannerClient: normalized.plannerClient,
       rootPath,
       files,
       findings,
       budget,
+      sessionUsage: normalized.sessionUsage,
     });
-  } catch {
+    planned = plannerResult.planned || {};
+    usageLedger = plannerResult.usageLedger || null;
+  } catch (error) {
+    if (isInvestorDdUsageLedgerError(error)) {
+      throw error;
+    }
     planned = {};
   }
   const swarmCount = clampInt(normalized.swarmCount ?? planned.swarmCount, {
@@ -236,6 +296,7 @@ export async function planDevTestBotPhase({
     baseUrl: normalized.baseUrl,
     recordVideo: normalized.recordVideo !== false,
     maxConcurrentAgents,
+    usageLedger,
   };
 }
 
@@ -415,6 +476,20 @@ export async function runDevTestBotPhase({
       maxConcurrentAgents: plan.maxConcurrentAgents,
     },
   });
+  if (plan.usageLedger?.ok) {
+    onEvent({
+      type: "devtestbot_planner_usage_recorded",
+      phase: "devtestbot",
+      action: INVESTOR_DD_USAGE_ACTIONS.devTestBotPlanner,
+      ledgerEntryId: plan.usageLedger.ledgerEntry?.ledgerEntryId || "",
+    });
+  } else if (plan.usageLedger?.ok === false) {
+    onEvent({
+      type: "devtestbot_planner_usage_unrecorded",
+      phase: "devtestbot",
+      reason: plan.usageLedger.reason || "unknown",
+    });
+  }
 
   if (!plan.enabled) {
     const skipped = {

package/src/review/investor-dd-file-loop.js

@@ -18,6 +18,11 @@
  */
 
 import { runEnvelopeLoop } from "../agents/envelope/index.js";
+import {
+  INVESTOR_DD_USAGE_ACTIONS,
+  assertInvestorDdUsageContextReady,
+  recordInvestorDdLlmUsage,
+} from "./investor-dd-usage.js";
 
 export const INVESTOR_DD_DEFAULT_MAX_TURNS_PER_FILE = 6;
 export const INVESTOR_DD_DEFAULT_STUCK_THRESHOLD = 2;
@@ -122,21 +127,75 @@ function meterTools(tools, budget, onToolCall) {
   }));
 }
 
+function rememberUsageLedgerEntry(budget, entry) {
+  if (!budget || typeof budget !== "object" || !entry?.ok) return;
+  if (!Array.isArray(budget.sessionUsageLedgerEntries)) {
+    budget.sessionUsageLedgerEntries = [];
+  }
+  budget.sessionUsageLedgerEntries.push(entry);
+}
+
 /**
  * Wrap the caller's LLM client so every generatePlan call increments the
- * llmCalls counter. Cost accounting for LLM calls is the client's
- * responsibility (it knows the model and tokens), so the client adds to
- * `budget.spentUsd` directly.
+ * llmCalls counter. Billing-grade token accounting is recorded only from
+ * provider-returned usage after the planner returns.
  *
  * @param {object} client
  * @param {InvestorDdBudgetState} budget
  */
-function meterClient(client, budget) {
+function meterClient(client, budget, { personaId, sessionUsage, onEvent }) {
   return {
     ...client,
     generatePlan: async (messages, options) => {
+      const startedAtIso = new Date().toISOString();
+      if (sessionUsage) {
+        try {
+          assertInvestorDdUsageContextReady({
+            usageContext: sessionUsage,
+            action: INVESTOR_DD_USAGE_ACTIONS.filePlanner,
+            agentId: `investor-dd-${personaId}`,
+          });
+        } catch (error) {
+          budget.usageLedgerError = error;
+          throw error;
+        }
+      }
       budget.llmCalls += 1;
-      return client.generatePlan(messages, options);
+      const response = await client.generatePlan(messages, options);
+      if (!sessionUsage) {
+        return response;
+      }
+      const usageResult = await recordInvestorDdLlmUsage({
+        usageContext: sessionUsage,
+        action: INVESTOR_DD_USAGE_ACTIONS.filePlanner,
+        agentId: `investor-dd-${personaId}`,
+        phase: "persona_file_loop",
+        messages,
+        response,
+        startedAtIso,
+        metadata: {
+          personaId,
+          turn: options?.turn || 0,
+        },
+      }).catch((error) => {
+        budget.usageLedgerError = error;
+        throw error;
+      });
+      if (usageResult?.ok === false) {
+        onEvent({
+          type: "persona_llm_usage_unrecorded",
+          personaId,
+          reason: usageResult.reason || "unknown",
+        });
+      } else if (usageResult?.ok) {
+        rememberUsageLedgerEntry(budget, usageResult);
+        onEvent({
+          type: "persona_llm_usage_recorded",
+          personaId,
+          action: INVESTOR_DD_USAGE_ACTIONS.filePlanner,
+        });
+      }
+      return response;
     },
   };
 }
@@ -157,6 +216,7 @@ function meterClient(client, budget) {
  * @param {object} [params.options]
  * @param {number} [params.options.maxTurnsPerFile]
  * @param {number} [params.options.stuckThreshold]
+ * @param {object} [params.sessionUsage]         - Optional billing-grade Senti usage context.
  * @returns {Promise<InvestorDdFileLoopResult>}
  */
 export async function runPerFileReviewLoop({
@@ -167,6 +227,7 @@ export async function runPerFileReviewLoop({
   buildInitialMessages,
   budget,
   onEvent = () => {},
+  sessionUsage = null,
   options = {},
 } = {}) {
   if (!personaId || typeof personaId !== "string") {
@@ -193,7 +254,9 @@ export async function runPerFileReviewLoop({
     : INVESTOR_DD_DEFAULT_STUCK_THRESHOLD;
 
   const safeBudget = budget || createBudgetState();
-  const meteredClient = meterClient(client, safeBudget);
+  const initialUsageLedgerEntryCount = Array.isArray(safeBudget.sessionUsageLedgerEntries)
+    ? safeBudget.sessionUsageLedgerEntries.length
+    : 0;
 
   const perFile = [];
   const allFindings = [];
@@ -225,6 +288,11 @@ export async function runPerFileReviewLoop({
       emit({ type: "persona_file_tool_call", personaId, file, tool, input });
     });
     const initialMessages = buildInitialMessages(file);
+    const meteredClient = meterClient(client, safeBudget, {
+      personaId,
+      sessionUsage,
+      onEvent: emit,
+    });
 
     let loopResult;
     try {
@@ -256,7 +324,13 @@ export async function runPerFileReviewLoop({
           },
         },
       });
+      if (safeBudget.usageLedgerError) {
+        throw safeBudget.usageLedgerError;
+      }
     } catch (err) {
+      if (safeBudget.usageLedgerError && err === safeBudget.usageLedgerError) {
+        throw err;
+      }
       terminationReason = "client-error";
       emit({
         type: "persona_file_error",
@@ -298,6 +372,9 @@ export async function runPerFileReviewLoop({
     findings: allFindings,
     visited,
     skipped,
+    usageLedgerEntries: Array.isArray(safeBudget.sessionUsageLedgerEntries)
+      ? safeBudget.sessionUsageLedgerEntries.slice(initialUsageLedgerEntryCount).filter((entry) => entry?.ok)
+      : [],
     terminationReason,
   };
 }

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

@@ -10,6 +10,7 @@
  *   persona-<id>.json  — per-persona findings + coverage proof
  *   findings.json      — flat list across all personas (dedup in PR-29)
  *   summary.json       — run metadata (timings, cost, terminationReason)
+ *   progress.json      — truthful sellable-readiness capability ledger
  *   report.md          — human-readable summary
  *   manifest.json      — SHA-256 chain of every artifact
  *
@@ -39,6 +40,7 @@ import { attachReproducibilityChain } from "./reproducibility-chain.js";
 import { renderInvestorDdHtml } from "./investor-dd-html-report.js";
 import { runDevTestBotPhase } from "./investor-dd-devtestbot.js";
 import { redactDdEmailError } from "./dd-report-email-client.js";
+import { buildInvestorDdProgress } from "./investor-dd-progress.js";
 
 const INVESTOR_DD_PERSONAS = Object.freeze([
   "security",
@@ -271,6 +273,7 @@ async function triggerReportEmail({ reportEmail, runResult, dryRun, emit }) {
  * @param {object} [params.liveValidator.aidenid]       - AIdenID client.
  * @param {number} [params.liveValidator.maxInteractions]
  * @param {object|false} [params.devTestBot]     - Automated devTestBot phase config.
+ * @param {object|null} [params.sessionUsage]    - Optional Senti session_usage context for DD LLM calls.
  * @param {object|null} [params.reportEmail]     - Optional API-side report email trigger.
  * @param {string} [params.reportEmail.to]
  * @param {object} [params.reportEmail.client]   - { send({ runId, to, run }) }.
@@ -290,6 +293,7 @@ export async function runInvestorDd({
   compliancePacks = COMPLIANCE_PACK_CATALOG,
   liveValidator = null,
   devTestBot = {},
+  sessionUsage = null,
   reportEmail = null,
   notification = null,
 } = {}) {
@@ -382,7 +386,12 @@ export async function runInvestorDd({
       files,
       findings,
       budget: budgetState,
-      options: devTestBot === false ? { enabled: false } : devTestBot || {},
+      options: devTestBot === false
+        ? { enabled: false }
+        : {
+            ...(devTestBot || {}),
+            sessionUsage,
+          },
       onEvent: emit,
     });
     findings.push(...(devTestBotPhase.findings || []));
@@ -503,6 +512,38 @@ export async function runInvestorDd({
     });
   }
 
+  const artifactFilesBeforeManifest = await fsp.readdir(artifactBase);
+  const ddProgress = buildInvestorDdProgress({
+    runId,
+    personas,
+    dryRun,
+    routing,
+    byPersona,
+    findings,
+    compliance,
+    reconciliationAvailable,
+    liveValidator,
+    devTestBotPhase,
+    reportEmailConfigured: Boolean(reportEmail),
+    reportEmailResult: runResult.reportEmail || null,
+    notification,
+    artifactFiles: artifactFilesBeforeManifest,
+    budgetState,
+  });
+  summary.ddProgress = {
+    version: ddProgress.version,
+    overallStatus: ddProgress.overallStatus,
+    sellableReady: ddProgress.sellableReady,
+    complete: ddProgress.summary.complete,
+    requiredComplete: ddProgress.summary.requiredComplete,
+    requiredTotal: ddProgress.summary.requiredTotal,
+    blockingGapCount: ddProgress.summary.blockingGapCount,
+    artifact: "progress.json",
+  };
+  runResult.progress = ddProgress;
+  await writeJson(path.join(artifactBase, "progress.json"), ddProgress);
+  await writeJson(path.join(artifactBase, "summary.json"), summary);
+
   await streamHandle.close();
 
   const artifactFiles = await fsp.readdir(artifactBase);