@stage5/lumine 0.2.68 → 0.2.70

package/README.md

@@ -158,6 +158,20 @@ Replay listing and status are available without exposing private playback
 grants. A creator or app owner can remove one with
 `lumine sdk call live.deleteReplay '{"replayId":"..."}' --allow-write`.
 
+`Twinkle.rewards` is callable too, on the same server-verified endpoints the
+published app uses — the CLI holds no award logic. `lumine sdk call
+rewards.getStatus '{}' --build <id>` is read-only and works for the build owner
+without `--allow-write` (the endpoint accepts only the `rewards:claim` scope,
+which is minted for it, but only the status operation is sent).
+`rewards.start '{"ruleId":"..."}'` and
+`rewards.claim '{"challengeId":"...","answers":[1,2]}'` mutate real XP/Coins
+state and require `--allow-write`. Every rewards call first reads the
+published-runtime reward grant from the canonical `GET /build/:id/runtime`
+payload for the signed-in account; when the server issues none (draft,
+private, unapproved or superseded release — the cases where the app itself
+sees preview mode) the call stops with an explanatory error and nothing is
+sent. `--path api/rewards/...` is refused like every other curated endpoint.
+
 ## Assets and AI image generation
 
 Binary media never lives in the workspace — assets are uploaded to Twinkle and
@@ -166,19 +180,22 @@ audio, and MIDI data (`.mid`/`.midi`; playback still needs an app-side parser
 or synth); `lumine assets list` prints your uploads and refreshes
 `.twinkle/assets.json`.
 
-`lumine assets generate "<prompt>" --model <gpt-image-2|nano-banana>` creates
+`lumine assets generate "<prompt>" --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana>` creates
 an AI-generated image asset instead of uploading one. `--model` is required
-(gpt-image-2 = best quality, slower, pricier; nano-banana = Gemini, faster,
-cheaper). Generation spends your Twinkle AI Battery, so the CLI shows the
-estimated cost and asks for confirmation first — non-interactive runs must pass
-`--yes` to consent. `--quality low|medium|high` applies to gpt-image-2 only.
+(Flare = fast generation; Sunburst = precise editing; gpt-image-2 = original
+model; nano-banana = Gemini). Generation spends your Twinkle AI Battery, so the
+CLI shows the estimated cost and asks for confirmation first — non-interactive
+runs must pass
+`--yes` to consent. `--quality low|medium|high|xhigh|max` applies to GPT Image
+models; `xhigh` and `max` require a 2.5 model. Estimates describe image output;
+actual battery usage also includes prompt and reference input.
 
 ## Thumbnails
 
 `lumine thumbnail set <file>` uploads a jpg/png/webp (max 8MB) as the build's
 thumbnail. `lumine thumbnail capture` screenshots the running app server-side
 and sets the result (add `--out <file>` to keep a local copy).
-`lumine thumbnail generate ["<prompt>"] --model <gpt-image-2|nano-banana>`
+`lumine thumbnail generate ["<prompt>"] --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana>`
 generates an AI image and sets it as the thumbnail (the image is also kept as a
 normal reusable asset); without a prompt the server composes one from the build
 title and description. Replacing an existing thumbnail asks for confirmation;

package/lib/admin-featured-history.js

@@ -0,0 +1,185 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { readAdminJsonFile, writeAdminJsonFile } from "./admin-news.js";
+import {
+  acquireCheckpointLock,
+  releaseCheckpointLock,
+  runAutomaticPagination,
+  combinePaginatedResults,
+  writePaginatedResultFile,
+} from "./admin-workflows.js";
+
+// API read bound, deliberately unrelated to the delegated addition policy.
+export const FEATURED_HISTORY_BATCH_SIZE = 100;
+
+function invalid(message) {
+  const error = new Error(message);
+  error.code = "CLI_ADMIN_CLI_VALIDATION";
+  return error;
+}
+
+export async function runBatchedFeaturedHistory(args) {
+  const { options, operation, runId } = args;
+  if (options.adminCursor) {
+    throw invalid("Use --resume with --all, not a single-batch --cursor.");
+  }
+  const subjectIds = operation.pagination.filters.subjectIds;
+  const fingerprint = createHash("sha256")
+    .update(
+      JSON.stringify({
+        version: 1,
+        runId,
+        apiUrl: options.apiUrl,
+        path: operation.path,
+      }),
+    )
+    .digest("hex");
+  const checkpointPath = path.resolve(
+    options.adminCheckpoint ||
+      path.join(
+        os.tmpdir(),
+        `lumine-admin-run-${runId}-featured-history-${fingerprint}.json`,
+      ),
+  );
+  const outputPath = options.adminOutput
+    ? path.resolve(options.adminOutput)
+    : null;
+  if (
+    outputPath === checkpointPath ||
+    outputPath?.startsWith(`${checkpointPath}.`)
+  ) {
+    throw invalid(
+      "History output must not overwrite its checkpoint or batch files.",
+    );
+  }
+  const lock = acquireCheckpointLock(checkpointPath, fingerprint);
+  try {
+    let generation;
+    if (options.adminResume) {
+      const saved = readAdminJsonFile(
+        checkpointPath,
+        "the Featured history batch checkpoint",
+      );
+      if (
+        saved.kind !== "featured-history-batches" ||
+        saved.fingerprint !== fingerprint ||
+        !/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(
+          saved.generation || "",
+        )
+      ) {
+        throw invalid(
+          "The checkpoint does not belong to this run and exact history request.",
+        );
+      }
+      generation = saved.generation;
+    } else {
+      generation = randomUUID();
+      writeAdminJsonFile(
+        checkpointPath,
+        { kind: "featured-history-batches", fingerprint, generation },
+        { privateFile: true },
+      );
+    }
+    const results = [];
+    for (
+      let offset = 0;
+      offset < subjectIds.length;
+      offset += FEATURED_HISTORY_BATCH_SIZE
+    ) {
+      const ids = subjectIds.slice(
+        offset,
+        offset + FEATURED_HISTORY_BATCH_SIZE,
+      );
+      const batchIndex = offset / FEATURED_HISTORY_BATCH_SIZE;
+      const batchCheckpoint = `${checkpointPath}.${generation}.batch-${batchIndex}.json`;
+      const url = new URL(operation.path, "https://lumine.invalid");
+      url.searchParams.set("subjectIds", ids.join(","));
+      const result = await runAutomaticPagination({
+        ...args,
+        options: {
+          ...options,
+          adminOutput: undefined,
+          adminCheckpoint: batchCheckpoint,
+          adminResume: !!options.adminResume && existsSync(batchCheckpoint),
+        },
+        operation: {
+          ...operation,
+          path: `${url.pathname}${url.search}`,
+          pagination: { ...operation.pagination, filters: { subjectIds: ids } },
+        },
+      });
+      if (
+        JSON.stringify(result.data.subjects?.map((subject) => subject.id)) !==
+        JSON.stringify(ids)
+      ) {
+        throw invalid(
+          "The API did not return a canonical summary for every requested subject.",
+        );
+      }
+      results.push(result);
+    }
+    const firstCoverage = results[0].data.coverage;
+    const uniformCoverage = results.every(
+      (result) =>
+        result.data.coverage?.complete === firstCoverage.complete &&
+        result.data.coverage?.startedAt === firstCoverage.startedAt,
+    );
+    const result = combinePaginatedResults(
+      {
+        ok: true,
+        status: "success",
+        data: {
+          coverage: uniformCoverage
+            ? firstCoverage
+            : { complete: false, startedAt: null },
+          subjects: results.flatMap((result) => result.data.subjects),
+          pagination: {
+            nextCursor: null,
+            hasMore: false,
+            exhausted: true,
+            snapshotMaxId: null,
+            snapshotTimeStamp: null,
+            after: null,
+            snapshotScope: "per-batch",
+            eventOrder: "subject-batch-then-id-descending",
+          },
+          scan: {
+            checkpointPath,
+            resumed: !!options.adminResume,
+            pages: results.reduce(
+              (sum, result) => sum + result.data.scan.pages,
+              0,
+            ),
+            scannedCount: results.reduce(
+              (sum, result) => sum + result.data.scan.scannedCount,
+              0,
+            ),
+            candidateCount: results.reduce(
+              (sum, result) => sum + result.data.scan.candidateCount,
+              0,
+            ),
+            batches: results.map((result, index) => ({
+              subjectIds: subjectIds.slice(
+                index * FEATURED_HISTORY_BATCH_SIZE,
+                (index + 1) * FEATURED_HISTORY_BATCH_SIZE,
+              ),
+              coverage: result.data.coverage,
+              pagination: result.data.pagination,
+              scan: result.data.scan,
+            })),
+          },
+        },
+      },
+      results,
+    );
+    if (outputPath) {
+      result.data.scan.outputPath = outputPath;
+      await writePaginatedResultFile(outputPath, result);
+    }
+    return result;
+  } finally {
+    releaseCheckpointLock(lock);
+  }
+}

package/lib/admin-featured.js

@@ -88,6 +88,14 @@ export function readFeaturedSelections(file) {
   });
   positive(raw?.reviewId, "Review ID");
   positive(raw?.coverageId, "Reviewed coverage ID");
+  // Review and coverage receipts are distinct audit rows, so equal IDs can
+  // only mean the review ID was copied into coverageId. Catch that locally
+  // instead of letting the server reject an unrelated-looking receipt.
+  if (raw.coverageId === raw.reviewId) {
+    throw invalid(
+      `coverageId ${raw.coverageId} is the review ID, not the acknowledged coverage receipt. Use data.reviewedCoverage.id from \`featured comments acknowledge --reviewed\` (or its data.decisionsTemplate / --decisions-template file).`,
+    );
+  }
   if (!Array.isArray(raw.selections) || raw.selections.length > 20_000) {
     throw invalid(
       "selections must be an array of at most 20000 agent-selected comments.",
@@ -530,6 +538,29 @@ export async function runFeaturedWorkflow({
       return call(`/reviews/${state.review.id}/report`);
     }
     const subjects = Object.values(state.subjects);
+    // The recommend step needs the review ID plus the acknowledged coverage
+    // receipt ID (never the review ID); hand back a ready-to-fill file so the
+    // agent does not assemble those identifiers by hand.
+    const decisionsTemplate = state.coverage
+      ? {
+          reviewId: state.review.id,
+          coverageId: state.coverage.id,
+          selections: [],
+        }
+      : null;
+    let decisionsTemplatePath = null;
+    if (options.adminDecisionsTemplate) {
+      if (workflow !== "acknowledge")
+        throw invalid(
+          "--decisions-template is written by `featured comments acknowledge --reviewed`.",
+        );
+      positive(decisionsTemplate?.coverageId, "Acknowledged coverage ID");
+      decisionsTemplatePath = path.resolve(options.adminDecisionsTemplate);
+      writeAdminJsonFile(decisionsTemplatePath, decisionsTemplate, {
+        privateFile: true,
+        maxBytes: MAX_BYTES,
+      });
+    }
     return {
       ok: true,
       status: "success",
@@ -537,6 +568,8 @@ export async function runFeaturedWorkflow({
       data: {
         review: state.review,
         checkpointPath: checkpoint,
+        decisionsTemplate,
+        decisionsTemplatePath,
         fetched: {
           complete: subjects.every((item) => item.complete),
           subjectsCompleted: subjects.filter((item) => item.complete).length,

package/lib/admin-runtime-logs.js

@@ -141,7 +141,7 @@ function startIntentPath(options) {
   );
 }
 
-function readStartIntent(intentPath, apiUrl) {
+function readStartIntent(intentPath, apiUrl, host = "primary") {
   if (!existsSync(intentPath)) return null;
   const intent = readAdminJsonFile(
     intentPath,
@@ -156,6 +156,11 @@ function readStartIntent(intentPath, apiUrl) {
   ) {
     return null;
   }
+  if ((intent.host || "primary") !== host) {
+    throw validationError(
+      `A ${intent.host || "primary"} runtime-log start has an unresolved outcome. Replay that host's start before choosing ${host}; its request key was preserved.`,
+    );
+  }
   return intent;
 }
 
@@ -185,6 +190,7 @@ function createSession({ options, apiUrl, review }) {
     kind: "lumine-admin-runtime-log-review",
     apiUrl,
     reviewId: review.id,
+    ...(review.ownerHostId ? { ownerHostId: review.ownerHostId } : {}),
     leaseToken: review.leaseToken,
     status: review.status,
     outputDirectory,
@@ -556,6 +562,21 @@ async function recoverPendingSnapshot({ options, authToken, session }) {
   return { status, recoveredArtifact };
 }
 
+// Only `completed` closes a review. `needs_review` and
+// `post_clear_review_required` both hand back another snapshot that must be
+// read before rerunning finish, so the top-level status says so instead of
+// reporting `success` for an unfinished review.
+export function completionStatusEnvelope(result) {
+  const completionStatus = String(result?.data?.completionStatus || "");
+  if (
+    completionStatus === "needs_review" ||
+    completionStatus === "post_clear_review_required"
+  ) {
+    return { ...result, status: "needs_review" };
+  }
+  return result;
+}
+
 function scrubLeaseToken(result, session, artifact) {
   const review = result?.data?.review || {};
   const { leaseToken: _leaseToken, ...safeReview } = review;
@@ -581,10 +602,14 @@ export async function runAdminRuntimeLogWorkflow({
 }) {
   const apiUrl = normalizeApiUrl(options.apiUrl);
   if (operation.runtimeLogAction === "start") {
+    const host = operation.runtimeLogHost || "primary";
+    if (!["primary", "target"].includes(host)) {
+      throw validationError("Invalid runtime-log host.");
+    }
     const intentPath = startIntentPath(options);
     const intent = options.idempotencyKey
       ? null
-      : readStartIntent(intentPath, apiUrl);
+      : readStartIntent(intentPath, apiUrl, host);
     const startRequestId = intent?.requestId || requestId;
     if (!intent) {
       writeAdminJsonFile(
@@ -592,6 +617,7 @@ export async function runAdminRuntimeLogWorkflow({
         {
           kind: "lumine-admin-runtime-log-review-start",
           apiUrl,
+          host,
           requestId: startRequestId,
           createdAt: new Date().toISOString(),
         },
@@ -602,7 +628,7 @@ export async function runAdminRuntimeLogWorkflow({
     try {
       result = await requestJson({
         method: "POST",
-        url: `${apiUrl}/cli/admin/runtime-logs/reviews`,
+        url: `${apiUrl}/cli/admin/runtime-logs${operation.runtimeLogHost ? `/hosts/${host}` : ""}/reviews`,
         authToken,
         body: {},
         headers: requestHeaders({ requestId: startRequestId }),
@@ -631,6 +657,15 @@ export async function runAdminRuntimeLogWorkflow({
       throw error;
     }
     const review = validateReview(result?.data?.review);
+    if (
+      operation.runtimeLogHost &&
+      (!/^i-[a-f0-9]{17}$/.test(review.ownerHostId || "") ||
+        review.ownerHostRole !== host)
+    ) {
+      throw validationError(
+        "The API did not confirm a host-owned review. Preserve the start intent and recover it; do not clear logs.",
+      );
+    }
     const session = createSession({ options, apiUrl, review });
     // The session now holds the lease; a later rerun must start fresh.
     clearStartIntent(intentPath);
@@ -722,13 +757,13 @@ export async function runAdminRuntimeLogWorkflow({
   });
   if (recovered.recoveredArtifact) {
     return scrubLeaseToken(
-      {
+      completionStatusEnvelope({
         ...recovered.status,
         data: {
           ...(recovered.status.data || {}),
           completionStatus: "needs_review",
         },
-      },
+      }),
       session,
       recovered.recoveredArtifact,
     );
@@ -782,5 +817,9 @@ export async function runAdminRuntimeLogWorkflow({
   }
   session.status = String(result?.data?.review?.status || session.status);
   writeSession(session);
-  return scrubLeaseToken(result, session, artifact);
+  return scrubLeaseToken(
+    action === "complete" ? completionStatusEnvelope(result) : result,
+    session,
+    artifact,
+  );
 }

package/lib/admin-workflows.js

@@ -282,6 +282,15 @@ function operationFingerprintValue({
     apiUrl: String(options.apiUrl || "").replace(/\/$/, ""),
     name: operation.name,
     path: pathWithCursor(operation.path, ""),
+    ...(operation.pagination.summaryKeys
+      ? { summaryKeys: operation.pagination.summaryKeys }
+      : {}),
+    // A completed pre-upgrade scan can still contain the old 30-day cap.
+    // Reject that checkpoint too: it would otherwise skip fetching entirely
+    // and record truncated coverage as a successful since-run scan.
+    ...(operation.pagination.coverageMode === "since-run"
+      ? { discoveryWindowContract: "stored-run-start-v1" }
+      : {}),
     ...(operation.name === "builds.candidates"
       ? {
           resultTransform: {
@@ -637,6 +646,16 @@ export async function forEachPaginatedResultItem(result, visit) {
       "The result does not contain spooled pagination data.",
     );
   }
+  if (storage.parts) {
+    let index = 0;
+    for (const part of storage.parts) {
+      await forEachPaginatedResultItem(
+        attachPaginationStorage({}, part),
+        async (item) => visit(item, index++),
+      );
+    }
+    return;
+  }
   verifyCandidateSpool({ ...storage, discardUnconfirmedTail: false });
   const input = createReadStream(storage.spoolPath, { encoding: "utf8" });
   const observedHash = createHash("sha256");
@@ -706,7 +725,7 @@ export async function writePaginatedResultJson({ result, write }) {
   await write("]}}\n");
 }
 
-async function writePaginatedResultFile(filePath, result) {
+export async function writePaginatedResultFile(filePath, result) {
   const resolved = path.resolve(String(filePath || "").trim());
   if (!String(filePath || "").trim()) {
     throw validationError("An output file path is required.");
@@ -743,9 +762,26 @@ async function writePaginatedResultFile(filePath, result) {
   return resolved;
 }
 
+// Keep large history event sets on disk when combining independently bounded
+// subject batches. Each part retains its own verified spool and snapshot.
+export function combinePaginatedResults(result, parts) {
+  const storages = parts.map(getPaginatedResultStorage);
+  if (
+    !storages.length ||
+    storages.some((entry) => !entry || entry.collectionKey !== storages[0].collectionKey)
+  ) {
+    throw validationError("Cannot combine incompatible paginated results.");
+  }
+  return attachPaginationStorage(result, {
+    collectionKey: storages[0].collectionKey,
+    candidateCount: storages.reduce((sum, entry) => sum + entry.candidateCount, 0),
+    parts: storages,
+  });
+}
+
 function aggregatePageResult({ operation, lastPage, checkpointPath, state }) {
   const last = lastPage || { ok: true, status: "success", data: {} };
-  const lastData = { ...(last.data || {}) };
+  const lastData = { ...(last.data || {}), ...state.summaryData };
   delete lastData[operation.pagination.collectionKey];
   const lastPagination = { ...(last.data?.pagination || {}) };
   const pageScannedCount = normalizeScannedCount(
@@ -809,6 +845,17 @@ function aggregatePageResult({ operation, lastPage, checkpointPath, state }) {
   });
 }
 
+function retainedSummaryData(operation, data) {
+  return Object.fromEntries(
+    (operation.pagination.summaryKeys || []).map((key) => {
+      if (!data || !Object.hasOwn(data, key)) {
+        throw validationError(`History scan is missing ${key} summary metadata. Start a fresh scan.`);
+      }
+      return [key, data[key]];
+    }),
+  );
+}
+
 export async function runAutomaticPagination(args) {
   const { options, operation, runId } = args;
   if (!operation.pagination) {
@@ -929,6 +976,7 @@ async function runAutomaticPaginationWithLock({
     filterSummariesComplete: true,
     clientFilter: null,
     operatorViewFilter: null,
+    summaryData: {},
     resumed: false,
     updatedAt: new Date().toISOString(),
   };
@@ -1059,6 +1107,7 @@ async function runAutomaticPaginationWithLock({
           savedPages > 0 && saved?.filterSummariesComplete === true
             ? normalizeOperatorViewFilterSummary(saved?.operatorViewFilter)
             : null,
+        summaryData: savedPages > 0 ? retainedSummaryData(operation, saved.summaryData) : {},
         resumed: true,
       };
       spoolHash = verifyCandidateSpool({
@@ -1215,6 +1264,7 @@ async function runAutomaticPaginationWithLock({
       spoolSha256: appended.spoolSha256,
       clientFilter,
       operatorViewFilter,
+      summaryData: retainedSummaryData(operation, data),
       nextCursor,
       exhausted: pagination.exhausted,
       updatedAt: new Date().toISOString(),