@stage5/lumine 0.2.92 → 0.2.95

package/lib/api.js

@@ -94,6 +94,38 @@ export async function createAppMcpSession({ options, auth, buildId }) {
   });
 }
 
+export async function claimAppMcpPairing({
+  options,
+  auth,
+  buildId,
+  code,
+  helperName,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/cli/build/${buildId}/app-mcp/pairings/claim`,
+    authToken: auth.token,
+    body: { code, helperName: helperName || null },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function setAppMcpHelperName({
+  options,
+  auth,
+  buildId,
+  sessionId,
+  helperName,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/cli/build/${buildId}/app-mcp/sessions/${sessionId}/helper`,
+    authToken: auth.token,
+    body: { helperName },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 export async function createAppMcpCall({
   options,
   auth,
@@ -288,6 +320,32 @@ export async function upgradeBuildProjectLimits({ options, auth, buildId }) {
   });
 }
 
+export async function getRuntimeStorageLimit({ options, auth }) {
+  return await requestJson({
+    url: `${options.apiUrl}/build/runtime-storage-limit`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function requestRuntimeStorageLimit({
+  options,
+  auth,
+  requestedBytes,
+  reason,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/runtime-storage-limit-request`,
+    authToken: auth.token,
+    body: {
+      ...(requestedBytes ? { requestedBytes } : {}),
+      ...(reason ? { reason } : {}),
+    },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 export async function saveProjectFiles({
   options,
   auth,

package/lib/app-mcp/server.js

@@ -2,10 +2,12 @@ import { spawn } from "node:child_process";
 import readline from "node:readline";
 
 import {
+  claimAppMcpPairing,
   closeAppMcpSession,
   createAppMcpCall,
   createAppMcpSession,
   loadAppMcpCall,
+  setAppMcpHelperName,
 } from "../api.js";
 import { assertAuthScope, resolveAuth } from "../auth.js";
 import { resolveRequiredBuildId } from "../util.js";
@@ -18,6 +20,77 @@ function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+const PAIRED_SESSION_ENDED_MESSAGE =
+  'The AI helper connection ended (the user clicked Disconnect or left the app). Ask them to click "Connect AI helper" in the app for a new code, then restart with lumine app-mcp <buildId> --code <code>.';
+
+function rethrowPairedSessionError(error) {
+  if (
+    Number(error?.status || 0) === 404 &&
+    /MCP session not found/i.test(String(error?.message || ""))
+  ) {
+    const ended = new Error(PAIRED_SESSION_ENDED_MESSAGE);
+    ended.status = 404;
+    throw ended;
+  }
+  throw error;
+}
+
+// MCP clients name themselves in initialize (clientInfo.name). This is only a
+// label for the viewer's "AI helper connected" badge.
+export function helperDisplayName(clientInfo) {
+  const raw = String(clientInfo?.name || "").trim();
+  if (!raw) return "";
+  const known = [
+    [/^claude[-_ ]?code/i, "Claude Code"],
+    [/^codex/i, "Codex"],
+    [/^claude/i, "Claude"],
+    [/^cursor/i, "Cursor"],
+  ];
+  for (const [pattern, label] of known) {
+    if (pattern.test(raw)) return label;
+  }
+  return raw.slice(0, 80);
+}
+
+// Read-only declarations travel to the MCP client as the standard
+// readOnlyHint, plus a plain note for tools whose action decides.
+export function toMcpTool(tool) {
+  const readOnlyWhen =
+    tool.readOnlyWhen && typeof tool.readOnlyWhen === "object"
+      ? Object.entries(tool.readOnlyWhen)[0]
+      : null;
+  const note =
+    readOnlyWhen && Array.isArray(readOnlyWhen[1])
+      ? ` (Works without "Allow edits" when ${readOnlyWhen[0]} is ${readOnlyWhen[1].join(", ")}.)`
+      : "";
+  return {
+    name: tool.name,
+    description: `${tool.description || ""}${note}`.trim(),
+    inputSchema: tool.inputSchema || {
+      type: "object",
+      additionalProperties: false,
+    },
+    ...(tool.readOnly === true ? { annotations: { readOnlyHint: true } } : {}),
+  };
+}
+
+function pairedInstructions(session) {
+  const readTools = (session.manifest?.tools || [])
+    .filter((tool) => tool.readOnly === true)
+    .map((tool) => tool.name);
+  return [
+    session.manifest?.description ||
+      `Use the semantic tools exposed by ${session.buildTitle}.`,
+    `You are attached to the user's own open ${session.buildTitle} tab: they see every change you make, live.`,
+    "Start with a read-only state tool; what the user has selected or is looking at is usually in it.",
+    session.allowEdits
+      ? "Edits are allowed right now; the user can switch them off at any time."
+      : `Edits are OFF until the user switches on "Allow edits" in the app. Until then only read-only calls work${
+          readTools.length ? ` (${readTools.join(", ")})` : ""
+        }; a write returns an "edits not allowed" error, so ask the user to switch it on.`,
+  ].join(" ");
+}
+
 function rethrowAppMcpSessionError(error) {
   const message = String(error?.message || error);
   if (
@@ -56,12 +129,23 @@ function openApp(url) {
 export async function appMcpCommand(options) {
   const buildId = resolveRequiredBuildId(options.target || options.buildIdFlag);
   if (!buildId) {
-    throw new Error("Usage: lumine app-mcp <published-app-url-or-id>");
+    throw new Error(
+      "Usage: lumine app-mcp <published-app-url-or-id> [--code <code>]",
+    );
   }
   const auth = await resolveAuth(options);
   await assertAuthScope({ options, auth, scope: "build:read" });
   await assertAuthScope({ options, auth, scope: "build:write" });
-  const created = await createAppMcpSession({ options, auth, buildId });
+  const paired = Boolean(options.pairingCode);
+  const created = paired
+    ? await claimAppMcpPairing({
+        options,
+        auth,
+        buildId,
+        code: options.pairingCode,
+        helperName: options.helperName || null,
+      })
+    : await createAppMcpSession({ options, auth, buildId });
   const session = created?.session;
   if (!session?.id || !session?.manifest?.tools?.length) {
     if (session?.id) {
@@ -75,26 +159,28 @@ export async function appMcpCommand(options) {
     throw new Error("Twinkle did not return an app MCP session.");
   }
   try {
-    if (options.openBrowser !== false) {
+    if (paired) {
+      process.stderr.write(
+        `lumine app-mcp: attached to your open ${session.buildTitle} tab. ` +
+          (session.allowEdits
+            ? "Edits are allowed.\n"
+            : 'Edits stay off until you switch on "Allow edits" in the app.\n'),
+      );
+    } else if (options.openBrowser !== false) {
       openApp(session.appUrl);
     } else {
       process.stderr.write(
         `lumine app-mcp: open this signed-in app tab: ${session.appUrl}\n`,
       );
     }
-    process.stderr.write(
-      `lumine app-mcp: ${session.buildTitle} is pinned to artifact ${session.artifactVersionId}. ` +
-        `Keep the opened Twinkle tab running.\n`,
-    );
+    if (!paired) {
+      process.stderr.write(
+        `lumine app-mcp: ${session.buildTitle} is pinned to artifact ${session.artifactVersionId}. ` +
+          `Keep the opened Twinkle tab running.\n`,
+      );
+    }
 
-    const tools = session.manifest.tools.map((tool) => ({
-      name: tool.name,
-      description: tool.description || "",
-      inputSchema: tool.inputSchema || {
-        type: "object",
-        additionalProperties: false,
-      },
-    }));
+    const tools = session.manifest.tools.map(toMcpTool);
     const input = readline.createInterface({
       input: process.stdin,
       crlfDelay: Infinity,
@@ -112,6 +198,7 @@ export async function appMcpCommand(options) {
           buildId,
           session,
           tools,
+          paired,
         });
       let isToolCall = false;
       try {
@@ -152,7 +239,9 @@ async function callAppTool({
   sessionId,
   name,
   arguments: toolArguments,
+  paired = false,
 }) {
+  const rethrow = paired ? rethrowPairedSessionError : rethrowAppMcpSessionError;
   const created = await createAppMcpCall({
     options,
     auth,
@@ -160,7 +249,7 @@ async function callAppTool({
     sessionId,
     name,
     arguments: toolArguments,
-  }).catch(rethrowAppMcpSessionError);
+  }).catch(rethrow);
   const callId = created?.call?.id;
   if (!callId) throw new Error("Twinkle did not create the app tool call.");
   const deadline = Date.now() + CALL_TIMEOUT_MS;
@@ -171,7 +260,7 @@ async function callAppTool({
       buildId,
       sessionId,
       callId,
-    }).catch(rethrowAppMcpSessionError);
+    }).catch(rethrow);
     const call = payload?.call;
     if (call?.status === "completed") return call.result;
     if (call?.status === "failed") {
@@ -185,7 +274,7 @@ async function callAppTool({
     buildId,
     sessionId,
     callId,
-  }).catch(rethrowAppMcpSessionError);
+  }).catch(rethrow);
   if (finalPayload?.call?.status === "completed") {
     return finalPayload.call.result;
   }
@@ -193,11 +282,21 @@ async function callAppTool({
     throw new Error(finalPayload.call.errorMessage || "App tool failed.");
   }
   throw new Error(
-    "App tool call timed out. Reload the appUrl tab, or restart the Lumine app-mcp driver and reopen its new appUrl.",
+    paired
+      ? "App tool call timed out. Ask the user to keep the app tab open in front (background tabs can pause), then retry."
+      : "App tool call timed out. Reload the appUrl tab, or restart the Lumine app-mcp driver and reopen its new appUrl.",
   );
 }
 
-async function handleMcpMessage({ line, options, auth, buildId, session, tools }) {
+async function handleMcpMessage({
+  line,
+  options,
+  auth,
+  buildId,
+  session,
+  tools,
+  paired = false,
+}) {
   let message;
   try {
     message = JSON.parse(line);
@@ -208,6 +307,17 @@ async function handleMcpMessage({ line, options, auth, buildId, session, tools }
   const method = String(message?.method || "");
   if (id === undefined || id === null) return;
   if (method === "initialize") {
+    const helperName = helperDisplayName(message?.params?.clientInfo);
+    if (paired && helperName && !options.helperName) {
+      // Label only; a failure here must never break the MCP handshake.
+      await setAppMcpHelperName({
+        options,
+        auth,
+        buildId,
+        sessionId: session.id,
+        helperName,
+      }).catch(() => {});
+    }
     return writeMcpResult(id, {
       protocolVersion: MCP_PROTOCOL_VERSION,
       capabilities: { tools: { listChanged: false } },
@@ -215,9 +325,10 @@ async function handleMcpMessage({ line, options, auth, buildId, session, tools }
         name: `lumine-app-${buildId}`,
         version: "1.0.0",
       },
-      instructions:
-        session.manifest.description ||
-        `Use the semantic tools exposed by ${session.buildTitle}.`,
+      instructions: paired
+        ? pairedInstructions(session)
+        : session.manifest.description ||
+          `Use the semantic tools exposed by ${session.buildTitle}.`,
     });
   }
   if (method === "ping") return writeMcpResult(id, {});
@@ -235,6 +346,7 @@ async function handleMcpMessage({ line, options, auth, buildId, session, tools }
         sessionId: session.id,
         name,
         arguments: message?.params?.arguments || {},
+        paired,
       });
       return writeMcpResult(id, {
         content: [{ type: "text", text: JSON.stringify(result) }],

package/lib/assets.js

@@ -16,12 +16,14 @@ import {
 import {
   buildApiJson,
   fetchAllRuntimeAssets,
+  getRuntimeStorageLimit,
   loadBuildFiles,
   mintBuildApiToken,
+  requestRuntimeStorageLimit,
 } from "./api.js";
 import { assertAuthScope, ensureAuth } from "./auth.js";
 import { resolveSdkBuildId } from "./sdk.js";
-import { formatBytes, sleep } from "./util.js";
+import { formatBytes, parseStorageSizeBytes, sleep } from "./util.js";
 import {
   collectWorkspaceTextFilesLenient,
   findLocalProjectMetadata,
@@ -55,8 +57,97 @@ export async function assetsCommand(options) {
     await assetsGenerate(options);
     return;
   }
+  if (subcommand === "storage") {
+    await assetsStorage(options);
+    return;
+  }
+  if (subcommand === "request-storage") {
+    await assetsRequestStorage(options);
+    return;
+  }
   throw new Error(
-    '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]',
+    '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] | lumine assets storage | lumine assets request-storage [--size 500MB|1GB|2GB] [--reason "<what it is for>"]',
+  );
+}
+
+// Lumine file storage is counted per user across all their Builds. Past the
+// default quota, Mikey approves more (like the per-project file-limit unlock).
+export function formatStorageApproval(approval) {
+  if (!approval) return [];
+  const lines = [
+    `Storage limit: ${formatBytes(approval.maxRuntimeFileStorageBytes)}${approval.hasOverride ? " (approved by Mikey)" : ""} · ${formatBytes(approval.runtimeFileStorageBytes || 0)} used across ${Number(approval.runtimeFileCount || 0)} file(s) in all your builds`,
+  ];
+  const latest = approval.latestRequest;
+  if (latest?.status === "pending") {
+    lines.push(
+      `Request #${latest.requestId} for ${formatBytes(latest.requestedMaxRuntimeFileStorageBytes)} is waiting for Mikey's review.`,
+    );
+  } else if (latest?.status === "rejected") {
+    lines.push(
+      `Request #${latest.requestId} was declined${latest.reviewReason ? `: ${latest.reviewReason}` : "."}`,
+    );
+  } else if (latest?.status === "approved") {
+    lines.push(
+      `Request #${latest.requestId} was approved (${formatBytes(latest.approvedMaxRuntimeFileStorageBytes || latest.requestedMaxRuntimeFileStorageBytes)}).`,
+    );
+  }
+  if (approval.canRequest && latest?.status !== "pending") {
+    lines.push(
+      `Need more? \`lumine assets request-storage --size <${(approval.requestTiers || []).map((tier) => formatBytes(tier).replace(".0 ", "")).join("|")}> --reason "<what it is for>"\` asks Mikey.`,
+    );
+  } else if (!approval.canRequest) {
+    lines.push("This is the most Lumine file storage that can be approved.");
+  }
+  return lines;
+}
+
+export async function assetsStorage(options) {
+  const auth = await ensureAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:read" });
+  const result = await getRuntimeStorageLimit({ options, auth });
+  const approval = result?.storageLimitApproval;
+  if (!approval) {
+    throw new Error("Twinkle did not return your storage limit.");
+  }
+  if (options.json) {
+    console.log(JSON.stringify(approval, null, 2));
+    return;
+  }
+  for (const line of formatStorageApproval(approval)) console.log(line);
+}
+
+export async function assetsRequestStorage(options) {
+  const requestedBytes = options.storageSize
+    ? parseStorageSizeBytes(options.storageSize)
+    : null;
+  const reason = String(options.adminReason || "").trim();
+  const auth = await ensureAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const result = await requestRuntimeStorageLimit({
+    options,
+    auth,
+    requestedBytes,
+    reason,
+  });
+  const request = result?.request;
+  const approval = result?.storageLimitApproval;
+  if (result?.success !== true || !request) {
+    throw new Error("Twinkle did not confirm the storage request.");
+  }
+  if (options.json) {
+    console.log(JSON.stringify({ request, storageLimitApproval: approval }, null, 2));
+    return;
+  }
+  if (request.status === "approved") {
+    console.log(
+      `Approved: your Lumine file storage is now ${formatBytes(approval?.maxRuntimeFileStorageBytes || request.approvedMaxRuntimeFileStorageBytes)}.`,
+    );
+    return;
+  }
+  console.log(
+    result.changed
+      ? `Sent storage request #${request.requestId} for ${formatBytes(request.requestedMaxRuntimeFileStorageBytes)} to Mikey. Nothing changes until he approves it.`
+      : `Storage request #${request.requestId} for ${formatBytes(request.requestedMaxRuntimeFileStorageBytes)} is already waiting for Mikey.`,
   );
 }
 

package/lib/commands.js

@@ -2384,6 +2384,8 @@ export function parseArgs(args) {
     "noReviewLoop",
     "acceptAgreement",
     "show",
+    "foreground",
+    "open",
   ]);
 
   for (let i = 0; i < rest.length; i += 1) {
@@ -2601,6 +2603,7 @@ export function parseArgs(args) {
     draftId: raw.draftId ? String(raw.draftId) : "",
     twinkles: raw.twinkles ? String(raw.twinkles) : "",
     adminReason: raw.reason ? String(raw.reason) : "",
+    storageSize: raw.size ? String(raw.size) : "",
     adminContextLimit: raw.limit === undefined ? 20 : Number(raw.limit),
     adminRun: raw.run ? String(raw.run) : "",
     adminTarget: raw.target ? String(raw.target) : "",
@@ -2611,6 +2614,9 @@ export function parseArgs(args) {
     adminEditionId: raw.editionId ? String(raw.editionId) : "",
     adminLeaseToken: raw.leaseToken ? String(raw.leaseToken) : "",
     adminFile: raw.file ? String(raw.file) : "",
+    adminPort: raw.port ? String(raw.port) : "",
+    adminForeground: Boolean(raw.foreground),
+    adminOpen: Boolean(raw.open),
     adminConfigFile: raw.config ? String(raw.config) : "",
     adminReviewedBuildVersion: raw.reviewedVersion
       ? String(raw.reviewedVersion)
@@ -2629,6 +2635,10 @@ export function parseArgs(args) {
       .map((scope) => scope.trim())
       .filter(Boolean),
     buildIdFlag: raw.build ? String(raw.build) : "",
+    // `lumine app-mcp <id> --code <code>` attaches to the viewer's own open
+    // app tab ("Connect AI helper") instead of opening a new tab.
+    pairingCode: raw.code ? String(raw.code).trim() : "",
+    helperName: raw.helperName ? String(raw.helperName).trim() : "",
     model: raw.model ? String(raw.model) : "",
     quality: raw.quality ? String(raw.quality) : "",
     assetName: raw.name ? String(raw.name) : "",
@@ -2916,6 +2926,7 @@ export function printHelp() {
   lumine sponsor job fail <job-id> --reason <text>
   lumine sponsor jobs
   lumine app-mcp <published-app-url-or-id> [--no-open]
+  lumine app-mcp <app-url-or-id> --code <code> [--helper-name <name>]
   lumine new [title]
   lumine rename [title] [--target <twinkle-build-url-or-id>]
   lumine describe [description] [--target <twinkle-build-url-or-id>]
@@ -2955,6 +2966,8 @@ export function printHelp() {
   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]
+  lumine assets storage [--json]
+  lumine assets request-storage [--size 500MB|1GB|2GB] [--reason <what it is for>]
   lumine chatlog [build] [--since 2h] [--limit 100] [--instance <id>] [--json]
   lumine chatlog enable|disable [build]
   lumine rewards check
@@ -2991,8 +3004,10 @@ export function printHelp() {
   lumine admin sponsor integrity cases [--status open|pending|held|flagged|cleared|disqualified] [--json]
   lumine admin sponsor integrity get <case-id> [--json]
   lumine admin sponsor integrity review <case-id> --decision clear|hold|flag|disqualify [--note <evidence>] [--json]
+  lumine admin review list [--type rewards|project|storage|cardcraft] [--status queue|pending|approved|rejected|all] [--cursor <c>] | show <type:id> [--dir <path>] | approve <type:id> [--config <rules.json>] [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject|revoke <type:id> [--reason <text>] | propose rewards:<id> --dir <edited-snapshot> --config <rules.json>
   lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] [--json]
   lumine admin cardcraft-review list [--status pending|approved|all] [--cursor <id>] | show <id> | approve|reject|revoke <id> [--reason <text>]
+  lumine admin storage list [--status pending|approved|rejected|all] [--cursor <id>] | show <user-id-or-username> | approve <request-id> [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <request-id> [--reason <text>] | grant <user-id-or-username> --size <500MB|1GB|2GB|n MB> [--reason <text>]
   lumine admin reward-activity [--date YYYY-MM-DD] [--days <1..31>] [--build <id>] [--json]
   lumine admin chat-reports list [--status pending|open|reviewing|resolved|dismissed|all] [--cursor <id>] [--json]
   lumine admin chat-reports show <report-id> [--json]   (reported message snapshot + surrounding context)
@@ -3008,6 +3023,9 @@ export function printHelp() {
   lumine admin reward-review reject|revoke <review-id> --reason <text> [--json]
   lumine admin recommendations list [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--content-types comment,dailyReflection] [--unviewed|--viewed] [--cursor <cursor>] [--json]
   lumine admin builds candidates [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--limit <number>] [--json]
+  lumine admin daily-run gather --output-dir <dir> [--date YYYY-MM-DD] [--json]   (all read-only daily reports + bot-output pages + bot-chats.txt)
+  lumine admin featured candidates [--days 7] [--after <iso>] [--json]   (recent, provably never-Featured Subjects with comment counts)
+  lumine admin report serve --file <report.md> [--port <n>] [--open] [--json]   (loopback report page with section nav)
   lumine admin builds review <build-url-or-id> [--output-dir <dir>] [--wait-ms <ms>] [--interact <steps.json>] [--browser-path <path>] [--json]
   lumine admin subjects candidates [--since-run|--after <date>|--include-legacy] [--effort unassigned] [--unviewed|--viewed] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
   lumine admin subject get|reveal <subject-url-or-id> [--json]

package/lib/constants.js

@@ -253,6 +253,11 @@ lumine save --summary "Describe the change"
   \`lumine assets prune\` deletes your uploads that nothing references (server
   checks draft files, published/version snapshots, and derived builds; local
   unsaved edits are scanned too). The server enforces storage quotas.
+- Storage is per user across all their builds (\`lumine assets storage\`
+  shows the limit and usage). If the quota blocks an upload and pruning is not
+  enough, tell the user and, with their OK, run
+  \`lumine assets request-storage --reason "<what the space is for>"\` to ask
+  Mikey for more (500MB/1GB/2GB tiers; nothing changes until he approves).
 - CAUTION: asset URLs an app stores in privateDb/sharedDb/user DBs at runtime
   (Twinkle.files uploads), or URLs referenced only inside uploaded files such as
   .gltf manifests, are invisible to prune. Keep those asset URLs in project