@stage5/lumine 0.2.66 → 0.2.67

package/lib/admin.js

@@ -20,6 +20,7 @@ import {
   parseBuildReviewReceipt,
   runManagedBuildReview,
 } from "./build-review.js";
+import { runAdminRuntimeLogWorkflow } from "./admin-runtime-logs.js";
 
 const MAX_EDITORIAL_FILE_BYTES = 256 * 1024;
 const MAX_COMPOSED_TEXT_FILE_BYTES = 64 * 1024;
@@ -242,7 +243,7 @@ export async function adminCommand(options) {
     options.idempotencyKey || (operation.mutates ? `cli:${randomUUID()}` : "");
   let result;
   try {
-    const fetchOperation = async (requestPath = operation.path) =>
+    const fetchOperation = async (requestPath = operation.path, signal) =>
       requestJson({
         method: operation.method,
         url: `${options.apiUrl}${requestPath}`,
@@ -252,14 +253,14 @@ export async function adminCommand(options) {
           ...(runId ? { "x-lumine-admin-run-id": String(runId) } : {}),
           ...(correctionSessionId
             ? {
-                "x-lumine-admin-correction-session-id": String(
-                  correctionSessionId,
-                ),
+                "x-lumine-admin-correction-session-id":
+                  String(correctionSessionId),
               }
             : {}),
           ...(requestId ? { "x-lumine-idempotency-key": requestId } : {}),
         },
         timeoutMs: options.timeoutMs,
+        signal,
       });
     const transformResult = (rawResult) =>
       transformAdminResult({
@@ -282,6 +283,13 @@ export async function adminCommand(options) {
         runId,
         parseTarget: parseRecommendationTarget,
       });
+    } else if (operation.name.startsWith("runtime-logs.")) {
+      result = await runAdminRuntimeLogWorkflow({
+        options,
+        operation,
+        authToken: auth.token,
+        requestId,
+      });
     } else if (options.adminAll) {
       if (options.adminCursor) {
         throw cliValidationError(
@@ -295,7 +303,7 @@ export async function adminCommand(options) {
         fetchPage: fetchOperation,
         transformPage: transformResult,
         recordCoverage: shouldRecordAdminQueueCoverage(runScope)
-          ? async (coverage) =>
+          ? async (coverage, signal) =>
               requestJson({
                 method: "POST",
                 url: `${options.apiUrl}/cli/admin/daily-runs/coverage`,
@@ -306,6 +314,7 @@ export async function adminCommand(options) {
                   "x-lumine-idempotency-key": `cli:queue-coverage:${runId}:${adminValueFingerprint(coverage).slice(0, 32)}`,
                 },
                 timeoutMs: options.timeoutMs,
+                signal,
               })
           : undefined,
       });
@@ -389,6 +398,9 @@ function transformAdminResult({
   if (operation.name === "recommendations.list") {
     assertRecommendationWindowResult({ operation, result: transformed });
   }
+  if (operation.name === "subjects.candidates") {
+    assertSubjectWindowResult({ operation, result: transformed });
+  }
   if (operation.name === "builds.candidates") {
     transformed = normalizeAdminBuildCandidatesResult({
       result: transformed,
@@ -438,6 +450,34 @@ export function assertRecommendationWindowResult({ operation, result }) {
   }
 }
 
+export function assertSubjectWindowResult({ operation, result }) {
+  const mode = operation?.pagination?.coverageMode;
+  if (!mode || mode === "legacy") return;
+  const after = result?.data?.pagination?.after;
+  const snapshotTimeStamp = result?.data?.pagination?.snapshotTimeStamp;
+  if (
+    !Number.isSafeInteger(after) ||
+    after < 0 ||
+    !Number.isSafeInteger(snapshotTimeStamp) ||
+    snapshotTimeStamp < 0
+  ) {
+    const error = new Error(
+      "The deployed API did not confirm the bounded Subject window and snapshot. Deploy the matching API before using this CLI; use --include-legacy only for an intentional historical scan.",
+    );
+    error.code = "LUMINE_ADMIN_SUBJECT_WINDOW_UNSUPPORTED";
+    error.data = {
+      ok: false,
+      status: "validation_error",
+      error: {
+        code: error.code,
+        message: error.message,
+        details: { requestedMode: mode },
+      },
+    };
+    throw error;
+  }
+}
+
 async function finishAdminOutput({ options, operation, result }) {
   const paginationStorage = getPaginatedResultStorage(result);
   if (options.json) {
@@ -717,7 +757,9 @@ export function canonicalAdminRunScope(run) {
   if (raw === undefined || raw === null || raw === "") return "full";
   const scope = String(raw);
   if (scope === "full" || scope === "featured") return scope;
-  throw cliValidationError("The API returned an invalid administrator run scope.");
+  throw cliValidationError(
+    "The API returned an invalid administrator run scope.",
+  );
 }
 
 export function shouldRecordAdminQueueCoverage(runScope) {
@@ -757,6 +799,9 @@ export function assertAdminOperationAllowedForRunScope({
 }
 
 function adminOperationRequiresRun(operation) {
+  if (typeof operation.requiresRun === "boolean") {
+    return operation.requiresRun;
+  }
   return (
     ![
       "identity.list",
@@ -773,6 +818,14 @@ function adminOperationRequiresRun(operation) {
       "escalation.list",
       "escalation.set",
       "notable.add",
+      "notable.status",
+      "runtime-logs.start",
+      "runtime-logs.status",
+      "runtime-logs.capture",
+      "runtime-logs.complete",
+      "runtime-logs.resume",
+      "runtime-logs.abandon",
+      "energy-budget.report",
     ].includes(operation.name) &&
     !operation.name.startsWith("ai-bucket.") &&
     !operation.name.startsWith("ai-email-policy.") &&
@@ -803,7 +856,10 @@ export function parseAdminOperation(options) {
 
   if (namespace === "correction" || namespace === "corrections") {
     if (!action || action === "status") {
-      return readOperation("correction.status", "/cli/admin/corrections/status");
+      return readOperation(
+        "correction.status",
+        "/cli/admin/corrections/status",
+      );
     }
     if (action === "start") {
       const commentId = parseRequiredInteger(target, "comment ID", 1);
@@ -1185,6 +1241,25 @@ export function parseAdminOperation(options) {
       return readOperation("daily-run.status", "/cli/admin/daily-runs/status");
     }
     if (action === "report") {
+      const positionalRun = String(target || "").trim();
+      const flaggedRun = String(options.adminRun || "").trim();
+      if (
+        extra ||
+        (positionalRun && flaggedRun && positionalRun !== flaggedRun)
+      ) {
+        throw cliValidationError(
+          "Usage: lumine admin daily-run report [--run <completed-run-id>] [--json].",
+        );
+      }
+      const historicalRun = positionalRun || flaggedRun;
+      if (historicalRun) {
+        const runId = parseRequiredInteger(historicalRun, "run ID", 1);
+        return readOperation(
+          "daily-run.report",
+          `/cli/admin/daily-runs/${runId}/report`,
+          { requiresRun: false, historicalRunId: runId },
+        );
+      }
       return readOperation("daily-run.report", "/cli/admin/daily-runs/report");
     }
     if (action === "escalation" && target === "add") {
@@ -1630,6 +1705,23 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (namespace === "notable" && action === "status" && !extra) {
+    const rawTarget = String(target || "").trim();
+    if (!rawTarget) {
+      throw cliValidationError(
+        "Usage: lumine admin notable status <userId|username>.",
+      );
+    }
+    const query = /^\d+$/.test(rawTarget)
+      ? { userId: parseRequiredInteger(rawTarget, "user ID", 1) }
+      : { username: rawTarget };
+    return readOperation(
+      "notable.status",
+      withQuery("/cli/admin/notable-users/status", query),
+      { requiresRun: false },
+    );
+  }
+
   if (namespace === "ai-costs") {
     if (action === "monthly" && !target && !extra) {
       if (options.adminDays) {
@@ -1639,7 +1731,105 @@ export function parseAdminOperation(options) {
       }
       return readOperation("ai-costs.monthly", "/cli/admin/ai-costs/monthly");
     }
-    throw cliValidationError("Usage: lumine admin ai-costs monthly [--json].");
+    if (action === "day" && !extra) {
+      if (options.adminDays) {
+        throw cliValidationError(
+          "ai-costs day reads one closed UTC day and does not accept --days.",
+        );
+      }
+      const positionalDay = String(target || "").trim();
+      const flaggedDay = String(options.adminDate || "").trim();
+      if (positionalDay && flaggedDay && positionalDay !== flaggedDay) {
+        throw cliValidationError(
+          "Pass the same UTC day once, either positionally or with --date.",
+        );
+      }
+      const dayKey = parseUtcDayKey(positionalDay || flaggedDay);
+      return readOperation(
+        "ai-costs.day",
+        `/cli/admin/ai-costs/day/${dayKey}`,
+        { requiresRun: false },
+      );
+    }
+    throw cliValidationError(
+      "Usage: lumine admin ai-costs monthly | ai-costs day <YYYY-MM-DD> [--json].",
+    );
+  }
+
+  if (namespace === "energy-budget" && !action) {
+    if (options.adminDays) {
+      const days = Number(options.adminDays);
+      if (!Number.isInteger(days) || days < 1 || days > 31) {
+        throw cliValidationError("--days must be an integer between 1 and 31.");
+      }
+    }
+    return readOperation(
+      "energy-budget.report",
+      withQuery("/cli/admin/energy-budget/report", { days: options.adminDays }),
+      { requiresRun: false },
+    );
+  }
+
+  if (namespace === "runtime-logs") {
+    if (
+      (action === "start" || action === "status" || action === "read") &&
+      !target &&
+      !extra
+    ) {
+      if (
+        action !== "start" &&
+        !String(options.adminReviewSession || "").trim()
+      ) {
+        throw cliValidationError(
+          "Pass the production-log review session with --review-session <file>.",
+        );
+      }
+      return {
+        name:
+          action === "read" ? "runtime-logs.capture" : `runtime-logs.${action}`,
+        method: action === "status" ? "GET" : "POST",
+        path: "",
+        body: undefined,
+        mutates: action !== "status",
+        requiresRun: false,
+        runtimeLogAction: action === "read" ? "capture" : action,
+      };
+    }
+    if ((action === "resume" || action === "abandon") && !target && !extra) {
+      return {
+        name: `runtime-logs.${action}`,
+        method: "POST",
+        path: "",
+        body: undefined,
+        mutates: true,
+        requiresRun: false,
+        runtimeLogAction: action,
+      };
+    }
+    if ((action === "finish" || action === "complete") && !target && !extra) {
+      if (!String(options.adminReviewSession || "").trim()) {
+        throw cliValidationError(
+          "Pass the production-log review session with --review-session <file>.",
+        );
+      }
+      if (!options.adminReviewed) {
+        throw cliValidationError(
+          "Inspect every downloaded runtime-log artifact, then confirm with --reviewed.",
+        );
+      }
+      return {
+        name: "runtime-logs.complete",
+        method: "POST",
+        path: "",
+        body: undefined,
+        mutates: true,
+        requiresRun: false,
+        runtimeLogAction: "complete",
+      };
+    }
+    throw cliValidationError(
+      "Usage: lumine admin runtime-logs start | status|read --review-session <file> | finish --review-session <file> --reviewed | resume | abandon [--review-session <file>].",
+    );
   }
 
   if (namespace === "media-costs") {
@@ -1891,16 +2081,19 @@ export function parseAdminOperation(options) {
   }
 
   throw cliValidationError(
-    "Usage: lumine admin identity|economy|rescue|sponsor|daily-run|escalation|todo|recommendations|builds|post|subjects|subject|featured|comment|announcement|chat|news|audit|brief|ai-costs|media-costs|bot-output|notable ...",
+    "Usage: lumine admin identity|economy|rescue|sponsor|daily-run|escalation|todo|recommendations|builds|post|subjects|subject|featured|comment|announcement|chat|news|audit|brief|ai-costs|media-costs|energy-budget|runtime-logs|bot-output|notable ...",
   );
 }
 
 function subjectsListOperation(options) {
   const operatorView = requestedOperatorViewFilter(options);
+  const subjectWindow = parseSubjectWindow(options);
   return readOperation(
     "subjects.candidates",
     withQuery("/cli/admin/subjects", {
-      after: options.adminAfter,
+      sinceRun: subjectWindow.mode === "since-run" ? "true" : "",
+      after: subjectWindow.mode === "after" ? subjectWindow.after : "",
+      includeLegacy: subjectWindow.mode === "legacy" ? "true" : "",
       cursor: options.adminCursor,
       effort: options.adminEffort,
       limit: options.limit,
@@ -1909,10 +2102,11 @@ function subjectsListOperation(options) {
       pagination: {
         collectionKey: "subjects",
         coverageQueue: "subjects",
-        coverageMode: options.adminAfter ? "after" : "all",
-        after: options.adminAfter
-          ? parseAfterForCoverage(options.adminAfter)
-          : null,
+        coverageMode: subjectWindow.mode,
+        after:
+          subjectWindow.mode === "after"
+            ? parseAfterForCoverage(subjectWindow.after)
+            : null,
         filters: {
           effort: options.adminEffort || "all",
           ...(operatorView ? { operatorView } : {}),
@@ -2007,10 +2201,7 @@ function featuredReorderOperation(options) {
 }
 
 function featuredAddOperation(options) {
-  const addIds = parseFeaturedSubjectIds(
-    options.adminIds,
-    "--subject-ids",
-  );
+  const addIds = parseFeaturedSubjectIds(options.adminIds, "--subject-ids");
   const postedAfter = String(options.adminPostedAfter || "").trim();
   if (!postedAfter) {
     throw cliValidationError(
@@ -2096,6 +2287,42 @@ export function parseRecommendationWindow(options) {
   return { mode, after: mode === "after" ? options.adminAfter : "" };
 }
 
+export function parseSubjectWindow(options) {
+  const selected = [
+    options.adminSinceRun ? "since-run" : "",
+    options.adminAfter ? "after" : "",
+    options.adminIncludeLegacy ? "legacy" : "",
+  ].filter(Boolean);
+  if (selected.length > 1) {
+    throw cliValidationError(
+      "Choose one Subject window: --since-run, --after, or --include-legacy.",
+    );
+  }
+  const mode = selected[0] || "since-run";
+  if (mode === "after") parseAfterForCoverage(options.adminAfter);
+  return { mode, after: mode === "after" ? options.adminAfter : "" };
+}
+
+function parseUtcDayKey(value) {
+  const dayKey = String(value || "").trim();
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dayKey);
+  if (!match) {
+    throw cliValidationError(
+      "Pass a real UTC calendar date in YYYY-MM-DD format.",
+    );
+  }
+  const parsed = new Date(`${dayKey}T00:00:00.000Z`);
+  if (
+    !Number.isFinite(parsed.getTime()) ||
+    parsed.toISOString().slice(0, 10) !== dayKey
+  ) {
+    throw cliValidationError(
+      "Pass a real UTC calendar date in YYYY-MM-DD format.",
+    );
+  }
+  return dayKey;
+}
+
 function parseAfterForCoverage(value) {
   const raw = String(value || "").trim();
   if (/^\d+$/.test(raw)) {
@@ -2387,7 +2614,9 @@ function parseCommentMode(value) {
 }
 
 function parseDailyRunScope(value) {
-  const scope = String(value || "full").trim().toLowerCase();
+  const scope = String(value || "full")
+    .trim()
+    .toLowerCase();
   if (!["full", "featured"].includes(scope)) {
     throw cliValidationError("--scope must be full or featured.");
   }
@@ -2698,6 +2927,48 @@ function printAdminMonthlyAiCosts(monthlyAiCosts) {
   }
 }
 
+function printAdminDailyAiCosts(dailyAiCosts) {
+  console.log(
+    `Application AI-cost ledger for ${dailyAiCosts.day.dayKey} (closed UTC day): ${formatAdminUsd(dailyAiCosts.summary?.estimatedCostUsd)} across ${Number(dailyAiCosts.summary?.requestCount || 0)} request(s).`,
+  );
+  for (const row of dailyAiCosts.byProviderModel || []) {
+    console.log(
+      `  ${row.provider || "unknown"}/${row.model || "unknown"}: ${formatAdminUsd(row.estimatedCostUsd)} · ${Number(row.totalTokens || 0)} token(s) · ${Number(row.requestCount || 0)} request(s).`,
+    );
+  }
+}
+
+function printAdminEnergyBudget(energyBudget) {
+  const headline = energyBudget.lastCompletedDay;
+  if (headline) {
+    console.log(
+      `AI Energy budget health, last completed UTC day ${headline.dayKey}: ${formatAdminUsd(headline.chargedUsd)} charged, ${formatAdminUsd(headline.overflowUsd)} overflow, ${headline.users} user(s), ${headline.recharges} recharge(s), ${headline.runs.total.runs} run(s), ${headline.telemetry.metrics.busy_refusal.count} busy refusal(s).`,
+    );
+  } else {
+    console.log("AI Energy budget health: no completed UTC day in the requested window.");
+  }
+  console.log(
+    "day        | charged | overflow | users | rechg | runs | calls/run avg/p90 | $/run avg/p90 | stops chg/unchg | busy | telemetry rows",
+  );
+  for (const day of energyBudget.byDay || []) {
+    const m = day.telemetry.metrics;
+    const runs = day.runs.total;
+    console.log(
+      `${day.dayKey}${day.inProgress ? "*" : " "}| ${formatAdminUsd(day.chargedUsd).padStart(7)} | ${formatAdminUsd(day.overflowUsd).padStart(8)} | ${String(day.users).padStart(5)} | ${String(day.recharges).padStart(5)} | ${String(runs.runs).padStart(4)} | ${String(runs.callsPerRun.avg).padStart(7)}/${String(runs.callsPerRun.p90).padEnd(9)} | ${formatAdminUsd(runs.usdPerRun.avg).padStart(6)}/${formatAdminUsd(runs.usdPerRun.p90).padEnd(6)} | ${String(m.budget_stop_changed.count).padStart(7)}/${String(m.budget_stop_unchanged.count).padEnd(7)} | ${String(m.busy_refusal.count).padStart(4)} | ${day.telemetry.rowCount}`,
+    );
+  }
+  console.log("* = in-progress UTC day; never headline it.");
+  const flags = energyBudget.flags || [];
+  if (flags.length === 0) {
+    console.log("Flags: none.");
+    return;
+  }
+  console.log(`Flags (${flags.length}) — record each as a carry-over todo and escalate; never auto-enforce:`);
+  for (const flag of flags) {
+    console.log(`  ${flag.dayKey} ${flag.code}: ${flag.message}`);
+  }
+}
+
 function formatAdminMediaUsd(value) {
   const amount = Number(value);
   if (!Number.isFinite(amount)) return "unavailable";
@@ -2959,6 +3230,28 @@ function printAdminResult({ operation, result }) {
     );
     return;
   }
+  if (data.review && data.artifacts?.reviewSessionPath) {
+    console.log(
+      `Production-log review #${data.review.id}: ${data.completionStatus || data.review.status}.`,
+    );
+    console.log(`Review session: ${data.artifacts.reviewSessionPath}`);
+    if (data.artifacts.latestSnapshot?.snapshotPath) {
+      console.log(
+        `Latest captured bytes: ${data.artifacts.latestSnapshot.snapshotPath}`,
+      );
+    }
+    if (
+      data.completionStatus === "needs_review" ||
+      data.completionStatus === "post_clear_review_required"
+    ) {
+      console.log(
+        data.completionStatus === "post_clear_review_required"
+          ? "The API error log was cleared in place. Review the post-clear snapshot, then rerun finish with --reviewed to close the lease."
+          : "New bytes arrived at the final boundary. Review the latest snapshot, then rerun finish with --reviewed.",
+      );
+    }
+    return;
+  }
   if (data.review) {
     console.log(
       `Confirmed Build #${data.review.buildId} runtime at published artifact #${data.review.publishedArtifactVersionId}.`,
@@ -2971,6 +3264,14 @@ function printAdminResult({ operation, result }) {
     printAdminMonthlyAiCosts(data.monthlyAiCosts);
     return;
   }
+  if (data.dailyAiCosts) {
+    printAdminDailyAiCosts(data.dailyAiCosts);
+    return;
+  }
+  if (data.energyBudget) {
+    printAdminEnergyBudget(data.energyBudget);
+    return;
+  }
   if (data.monthlyMediaCosts) {
     printAdminMonthlyMediaCosts(data.monthlyMediaCosts);
     return;
@@ -2990,8 +3291,9 @@ function printAdminResult({ operation, result }) {
   }
   if (data.report) {
     const report = data.report;
+    const historical = report.basis?.kind === "historical_reconstruction";
     console.log(
-      `Run #${report.run.id}: ${report.mutations.successfulMutationCount} successful mutation(s), ${report.queueCoverage.length} queue coverage record(s), ${report.escalations.length} escalation(s), ${report.carryoverTodos?.count || 0} unfinished todo(s).`,
+      `${historical ? "Historical reconstruction for run" : "Run"} #${report.run.id}: ${report.mutations.successfulMutationCount} successful mutation(s), ${report.queueCoverage.length} queue coverage record(s), ${report.escalations.length} escalation(s)${historical ? "." : `, ${report.carryoverTodos?.count || 0} unfinished todo(s).`}`,
     );
     for (const coverage of report.queueCoverage) {
       console.log(
@@ -3006,10 +3308,21 @@ function printAdminResult({ operation, result }) {
         `  ${String(escalation.severity || "attention").toUpperCase()} ${target} — ${escalation.summary}`,
       );
     }
-    printTodoItems(report.carryoverTodos?.items || [], "Unfinished work");
+    if (historical) {
+      console.log(
+        "The live brief and carry-over todo state were not snapshotted for this completed run.",
+      );
+    } else {
+      printTodoItems(report.carryoverTodos?.items || [], "Unfinished work");
+    }
     if (report.sponsorIntegrity) {
+      const pendingApplications = Number.isSafeInteger(
+        report.sponsorIntegrity.pendingApplications,
+      )
+        ? `; ${report.sponsorIntegrity.pendingApplications} pending application(s)`
+        : "; historical pending-application count unavailable";
       console.log(
-        `Sponsor integrity: ${report.sponsorIntegrity.scan?.status || "not started"}; ${report.sponsorIntegrity.cases?.open || 0} open case(s); ${report.sponsorIntegrity.pendingApplications || 0} pending application(s).`,
+        `Sponsor integrity: ${report.sponsorIntegrity.scan?.status || "not started"}; ${report.sponsorIntegrity.cases?.open || 0} open case(s)${pendingApplications}.`,
       );
     }
     const surfaces = report.brief?.engagementPulse?.surfaces;
@@ -3029,10 +3342,12 @@ function printAdminResult({ operation, result }) {
       if (deltas.length)
         console.log(`Engagement deltas: ${deltas.join(", ")}.`);
     }
-    const notableCount = Array.isArray(report.brief?.notableCandidates)
-      ? report.brief.notableCandidates.length
-      : 0;
-    console.log(`Notable-user candidates in this brief: ${notableCount}.`);
+    if (!historical) {
+      const notableCount = Array.isArray(report.brief?.notableCandidates)
+        ? report.brief.notableCandidates.length
+        : 0;
+      console.log(`Notable-user candidates in this brief: ${notableCount}.`);
+    }
     return;
   }
   if (data.inspection) {
@@ -3096,6 +3411,15 @@ function printAdminResult({ operation, result }) {
     printTodoItems([data.todo], "Canonical todo");
     return;
   }
+  if (Object.hasOwn(data, "isNotable") && data.user) {
+    console.log(
+      `${data.user.username} (user #${data.user.id}) is${data.isNotable ? "" : " not"} currently in Notable Users.`,
+    );
+    if (data.notableUser?.reason) {
+      console.log(`Reason: ${data.notableUser.reason}`);
+    }
+    return;
+  }
   if (data.bucket && Array.isArray(data.memberUserIds)) {
     const added = Array.isArray(data.accounts)
       ? `; added ${data.accounts.length} explicit account(s)`