@stage5/lumine 0.2.69 → 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.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

@@ -562,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;
@@ -742,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,
     );
@@ -802,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.js

@@ -3520,6 +3520,14 @@ function printAdminResult({ operation, result }) {
       `Confirmed Build #${data.review.buildId} runtime at published artifact #${data.review.publishedArtifactVersionId}.`,
     );
     console.log(`Screenshot: ${data.screenshotPath}`);
+    if (data.review.interaction) {
+      console.log(
+        `Interaction script: ${data.review.interaction.stepsCompleted}/${data.review.interaction.stepsPlanned} step(s) ${data.review.interaction.status}.`,
+      );
+    }
+    for (const shot of data.review.screenshots || []) {
+      console.log(`  Screenshot [${shot.label}]: ${shot.path}`);
+    }
     console.log(`Review receipt: ${data.receiptPath}`);
     return;
   }
@@ -3668,6 +3676,20 @@ function printAdminResult({ operation, result }) {
     );
     return;
   }
+  if (data.escalation?.summary) {
+    const target =
+      data.escalation.url ||
+      `${data.escalation.targetType || "target"}:${data.escalation.targetId || "?"}`;
+    console.log(
+      `Escalation${data.escalation.auditId ? ` #${data.escalation.auditId}` : ""} recorded: ${String(data.escalation.severity || "attention").toUpperCase()} ${target} — ${data.escalation.summary}`,
+    );
+    if (data.escalation.auditId) {
+      console.log(
+        `Set its disposition later with: lumine admin escalation set ${data.escalation.auditId} --status <status> --note <decision>`,
+      );
+    }
+    return;
+  }
   if (Array.isArray(data.todos)) {
     printTodoItems(data.todos, "Private carry-over work");
     if (data.truncated) {

package/lib/assets.js

@@ -56,7 +56,7 @@ export async function assetsCommand(options) {
     return;
   }
   throw new Error(
-    'Usage: lumine assets [list] | lumine assets upload <file...> | lumine assets generate "<prompt>" --model <gpt-image-2|nano-banana> | lumine assets delete <assetId> | lumine assets prune [--yes]',
+    'Usage: lumine assets [list] | lumine assets upload <file...> | lumine assets generate "<prompt>" --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana> | lumine assets delete <assetId> | lumine assets prune [--yes]',
   );
 }
 
@@ -65,18 +65,21 @@ export function resolveGenerateModel(options) {
   const model = GENERATE_MODEL_ALIASES[rawModel];
   if (!model) {
     throw new Error(
-      "--model is required: gpt-image-2 (best quality, slower, pricier) or nano-banana (Gemini — faster, cheaper). No default model is applied.",
+      "--model is required: gpt-image-2.5-flare (fast generation), gpt-image-2.5-sunburst (precise editing), gpt-image-2, or nano-banana. No default model is applied.",
     );
   }
   const rawQuality = String(options.quality || "").trim();
   if (rawQuality && !GENERATE_QUALITIES.has(rawQuality)) {
-    throw new Error("--quality must be low, medium, or high.");
+    throw new Error("--quality must be low, medium, high, xhigh, or max.");
   }
-  if (rawQuality && model !== "gpt-image-2") {
+  if (rawQuality && !model.startsWith("gpt-image-")) {
     throw new Error(
-      "--quality only applies to gpt-image-2; nano-banana has a single quality tier.",
+      "--quality only applies to GPT Image models; nano-banana has a single quality tier.",
     );
   }
+  if (model === "gpt-image-2" && ["xhigh", "max"].includes(rawQuality)) {
+    throw new Error("xhigh and max require a GPT Image 2.5 model.");
+  }
   return { model, quality: rawQuality || null };
 }
 
@@ -118,7 +121,7 @@ export async function assetsGenerate(options) {
   const prompt = String(options.positional[1] || "").trim();
   if (!prompt) {
     throw new Error(
-      'Usage: lumine assets generate "<prompt>" --model <gpt-image-2|nano-banana> [--quality low|medium|high] [--name <fileName>] [--yes]',
+      'Usage: lumine assets generate "<prompt>" --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana> [--quality low|medium|high|xhigh|max] [--name <fileName>] [--yes]',
     );
   }
   const { model, quality } = resolveGenerateModel(options);
@@ -161,8 +164,8 @@ export async function assetsGenerate(options) {
       (option) => option.model === model,
     );
     const costLine = selectedOption
-      ? `  Estimated battery cost: ${formatBatteryPercent(selectedOption.energyUnits, estimate?.fullBatteryUnits)} of a full AI battery (~$${Number(selectedOption.estimatedUsd || 0).toFixed(2)})`
-      : "  Estimated battery cost: unavailable";
+      ? `  Estimated image output: ${formatBatteryPercent(selectedOption.energyUnits, estimate?.fullBatteryUnits)} of a full AI battery (~$${Number(selectedOption.estimatedUsd || 0).toFixed(2)}). Prompt input uses additional energy.`
+      : "  Estimated image output: unavailable";
     const remainingLine = estimate
       ? `  Battery remaining now:  ${formatBatteryPercent(estimate.energyRemaining, estimate.fullBatteryUnits)}`
       : "";