@stage5/lumine 0.2.44 → 0.2.46

package/README.md

@@ -113,6 +113,21 @@ Reference folders are marked `readOnly` in `.twinkle/lumine-project.json`.
 Running `lumine save` from a reference folder is blocked; fork the source Build
 first if you want an editable workspace.
 
+## Using a published app over MCP
+
+`lumine app-mcp <published-app-url-or-id>` turns an opted-in published Build
+app into a standard stdio MCP server. Lumine pins the current published
+artifact, reads its `/app-tools.json` manifest, and opens a dedicated signed-in
+app tab. Tool calls run serially in that visible iframe through handlers the app
+registered with `Twinkle.appTools.register({ handlers })`, so the agent and
+viewer operate the same live UI and state. Keep that tab open while the MCP
+client is connected. Pass `--no-open` only when you will open the URL printed on
+stderr yourself.
+
+Discovery is static and fail-closed: runtime code cannot add tools that were
+not declared in the pinned manifest, and a session refuses to connect if any
+declared handler is missing.
+
 ## Inspecting Build SDK data
 
 `lumine sdk call <namespace.method> '<jsonArgs>'` calls a build's data SDK

package/lib/api.js

@@ -83,6 +83,63 @@ export async function loadBuildFiles({ options, auth, buildId, includeContent })
   });
 }
 
+export async function createAppMcpSession({ options, auth, buildId }) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/cli/build/${buildId}/app-mcp/sessions`,
+    authToken: auth.token,
+    body: {},
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function createAppMcpCall({
+  options,
+  auth,
+  buildId,
+  sessionId,
+  name,
+  arguments: toolArguments,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/cli/build/${buildId}/app-mcp/sessions/${sessionId}/calls`,
+    authToken: auth.token,
+    body: { name, arguments: toolArguments ?? {} },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function loadAppMcpCall({
+  options,
+  auth,
+  buildId,
+  sessionId,
+  callId,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/cli/build/${buildId}/app-mcp/sessions/${sessionId}/calls/${callId}/status`,
+    authToken: auth.token,
+    body: {},
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function closeAppMcpSession({
+  options,
+  auth,
+  buildId,
+  sessionId,
+}) {
+  return await requestJson({
+    method: "DELETE",
+    url: `${options.apiUrl}/cli/build/${buildId}/app-mcp/sessions/${sessionId}`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 export async function loadExternalAgentRuntime({
   options,
   auth,
@@ -412,9 +469,6 @@ export async function replaceMainWithContribution({
 }
 
 export async function publishBuild({ options, buildId, auth }) {
-  if (auth.releaseStatus?.state === "up_to_date") {
-    return { skipped: true };
-  }
   try {
     const result = await requestJson({
       method: "POST",

package/lib/app-mcp/server.js

@@ -0,0 +1,255 @@
+import { spawn } from "node:child_process";
+import readline from "node:readline";
+
+import {
+  closeAppMcpSession,
+  createAppMcpCall,
+  createAppMcpSession,
+  loadAppMcpCall,
+} from "../api.js";
+import { assertAuthScope, resolveAuth } from "../auth.js";
+import { resolveRequiredBuildId } from "../util.js";
+
+const MCP_PROTOCOL_VERSION = "2025-06-18";
+const CALL_POLL_MS = 250;
+const CALL_TIMEOUT_MS = 5 * 60 * 1000;
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function openApp(url) {
+  const command =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  const child = spawn(command[0], command[1], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  child.on("error", () => {
+    process.stderr.write(
+      `lumine app-mcp: open this signed-in app tab: ${url}\n`,
+    );
+  });
+}
+
+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>");
+  }
+  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 session = created?.session;
+  if (!session?.id || !session?.manifest?.tools?.length) {
+    if (session?.id) {
+      await closeAppMcpSession({
+        options,
+        auth,
+        buildId,
+        sessionId: session.id,
+      }).catch(() => {});
+    }
+    throw new Error("Twinkle did not return an app MCP session.");
+  }
+  try {
+    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`,
+    );
+
+    const tools = session.manifest.tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description || "",
+      inputSchema: tool.inputSchema || {
+        type: "object",
+        additionalProperties: false,
+      },
+    }));
+    const input = readline.createInterface({
+      input: process.stdin,
+      crlfDelay: Infinity,
+      terminal: false,
+    });
+    const pending = new Set();
+    let toolCallQueue = Promise.resolve();
+    input.on("line", (line) => {
+      if (!line.trim()) return;
+      const execute = () =>
+        handleMcpMessage({
+          line,
+          options,
+          auth,
+          buildId,
+          session,
+          tools,
+        });
+      let isToolCall = false;
+      try {
+        isToolCall = JSON.parse(line)?.method === "tools/call";
+      } catch {
+        // The normal handler returns the canonical JSON-RPC parse error.
+      }
+      // App mutations are stateful and the browser runtime can execute only one
+      // canonical call at a time. Preserve the MCP client's receive order so a
+      // burst never depends on UUID or second-resolution database ordering.
+      const operation = isToolCall
+        ? (toolCallQueue = toolCallQueue.then(execute, execute))
+        : execute();
+      const observed = operation.catch((error) => {
+        process.stderr.write(
+          `lumine app-mcp: ${String(error?.message || error)}\n`,
+        );
+      });
+      pending.add(observed);
+      observed.finally(() => pending.delete(observed));
+    });
+    await new Promise((resolve) => input.once("close", resolve));
+    await Promise.allSettled(Array.from(pending));
+  } finally {
+    await closeAppMcpSession({
+      options,
+      auth,
+      buildId,
+      sessionId: session.id,
+    }).catch(() => {});
+  }
+}
+
+async function callAppTool({
+  options,
+  auth,
+  buildId,
+  sessionId,
+  name,
+  arguments: toolArguments,
+}) {
+  const created = await createAppMcpCall({
+    options,
+    auth,
+    buildId,
+    sessionId,
+    name,
+    arguments: toolArguments,
+  });
+  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;
+  while (Date.now() < deadline) {
+    const payload = await loadAppMcpCall({
+      options,
+      auth,
+      buildId,
+      sessionId,
+      callId,
+    });
+    const call = payload?.call;
+    if (call?.status === "completed") return call.result;
+    if (call?.status === "failed") {
+      throw new Error(call.errorMessage || "App tool failed.");
+    }
+    await delay(CALL_POLL_MS);
+  }
+  const finalPayload = await loadAppMcpCall({
+    options,
+    auth,
+    buildId,
+    sessionId,
+    callId,
+  });
+  if (finalPayload?.call?.status === "completed") {
+    return finalPayload.call.result;
+  }
+  if (finalPayload?.call?.status === "failed") {
+    throw new Error(finalPayload.call.errorMessage || "App tool failed.");
+  }
+  throw new Error("App tool call timed out. Keep the MCP app tab open.");
+}
+
+async function handleMcpMessage({ line, options, auth, buildId, session, tools }) {
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch {
+    return writeMcpError(null, -32700, "Parse error");
+  }
+  const id = message?.id;
+  const method = String(message?.method || "");
+  if (id === undefined || id === null) return;
+  if (method === "initialize") {
+    return writeMcpResult(id, {
+      protocolVersion: MCP_PROTOCOL_VERSION,
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: {
+        name: `lumine-app-${buildId}`,
+        version: "1.0.0",
+      },
+      instructions:
+        session.manifest.description ||
+        `Use the semantic tools exposed by ${session.buildTitle}.`,
+    });
+  }
+  if (method === "ping") return writeMcpResult(id, {});
+  if (method === "tools/list") return writeMcpResult(id, { tools });
+  if (method === "tools/call") {
+    const name = String(message?.params?.name || "");
+    if (!tools.some((tool) => tool.name === name)) {
+      return writeMcpError(id, -32602, `Unknown tool: ${name}`);
+    }
+    try {
+      const result = await callAppTool({
+        options,
+        auth,
+        buildId,
+        sessionId: session.id,
+        name,
+        arguments: message?.params?.arguments || {},
+      });
+      return writeMcpResult(id, {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        structuredContent:
+          result && typeof result === "object" && !Array.isArray(result)
+            ? result
+            : { result },
+        isError: false,
+      });
+    } catch (error) {
+      return writeMcpResult(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              ok: false,
+              error: String(error?.message || error),
+            }),
+          },
+        ],
+        isError: true,
+      });
+    }
+  }
+  return writeMcpError(id, -32601, `Method not found: ${method}`);
+}
+
+function writeMcpResult(id, result) {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result })}\n`);
+}
+
+function writeMcpError(id, code, message) {
+  process.stdout.write(
+    `${JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } })}\n`,
+  );
+}

package/lib/commands.js

@@ -66,6 +66,7 @@ import { adminCommand } from "./admin.js";
 import { runBuildForumCommand } from "./forum.js";
 import { agentCommand } from "./agent.js";
 import { agentMcpCommand } from "./agent/mcp-server.js";
+import { appMcpCommand } from "./app-mcp/server.js";
 import {
   defaultMainCheckoutDir,
   defaultReferenceDir,
@@ -111,6 +112,10 @@ export async function main() {
     await agentMcpCommand(options);
     return;
   }
+  if (options.command === "app-mcp") {
+    await appMcpCommand(options);
+    return;
+  }
   options.lumineCli = await loadLumineCliVersionInfo({ options });
   if (options.help) {
     printHelp();
@@ -1104,7 +1109,13 @@ export async function save(options) {
     lastSavedAt: new Date().toISOString(),
     filesHash: typeof result.filesHash === "string" ? result.filesHash : null,
   });
-  printSaveResult({ result, build, dir, files });
+  printSaveResult({
+    result,
+    build,
+    dir,
+    files,
+    publishRequested: Boolean(options.publish),
+  });
 
   if (options.publish) {
     if (build?.canPublish === false) {
@@ -1119,6 +1130,9 @@ export async function save(options) {
     } else {
       console.log("Publish complete.");
     }
+    console.log(
+      `Release status: ${publish.build?.releaseStatus?.state || "unknown"}`,
+    );
     console.log(`App: ${options.siteUrl}/app/${buildId}`);
   }
 }
@@ -2043,7 +2057,13 @@ export function printForkResult({ forkResult, pullResult }) {
   printPullResult(pullResult);
 }
 
-export function printSaveResult({ result, build, dir, files }) {
+export function printSaveResult({
+  result,
+  build,
+  dir,
+  files,
+  publishRequested = false,
+}) {
   const entryPath = result.projectManifest?.entryPath || "unknown";
   const version = result.artifactVersion?.versionNumber
     ? ` v${result.artifactVersion.versionNumber}`
@@ -2054,7 +2074,8 @@ export function printSaveResult({ result, build, dir, files }) {
     `Uploaded ${files.length} file${files.length === 1 ? "" : "s"} from ${dir}`,
   );
   console.log(`Entry: ${entryPath}`);
-  console.log(`Release status: ${releaseState}`);
+  const willPublish = publishRequested && build?.canPublish !== false;
+  if (!willPublish) console.log(`Release status: ${releaseState}`);
   if (isContributionBranch(build) && build.canPublish === false) {
     console.log(
       'Next: notify the project owner with `lumine suggest branch "Ready for review"`.',
@@ -2062,7 +2083,7 @@ export function printSaveResult({ result, build, dir, files }) {
     console.log(
       "To offer this branch's thumbnail, run `lumine suggest thumbnail`.",
     );
-  } else {
+  } else if (!willPublish) {
     console.log(
       "Next: run `lumine launch` to publish, or `lumine save --publish` next time.",
     );
@@ -2668,6 +2689,7 @@ export function printHelp() {
   lumine whoami
   lumine logout
   lumine agent --provider <codex|claude-code> "<build request>"
+  lumine app-mcp <published-app-url-or-id> [--no-open]
   lumine new [title]
   lumine rename [title] [--target <twinkle-build-url-or-id>]
   lumine describe [description] [--target <twinkle-build-url-or-id>]

package/lib/constants.js

@@ -366,6 +366,7 @@ export const COMMANDS = new Set([
   "admin",
   "agent",
   "agent-mcp",
+  "app-mcp",
   "workspace",
   "login",
   "logout",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.44",
+  "version": "0.2.46",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/BUILD_SDK_INDEX.md

@@ -1,8 +1,8 @@
 # Build SDK Index
 
-Version: 1.33.0
-Updated: 2026-08-15
-Generated: 2026-08-15T03:00:24.685Z
+Version: 1.35.0
+Updated: 2026-08-18
+Generated: 2026-08-18T06:06:02.345Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -113,6 +113,16 @@ files:read, user:read, users:read, dailyReflections:read, content:read, content:
   - Use navigate() for routes inside the current Build and openContent() for Twinkle subjects, comments, apps, profiles, and other content pages.
   - Example: await Twinkle.app.openContent('https://www.twin-kle.com/subjects/432');
 
+### Twinkle.appTools
+- async register({ handlers }) | scopes: none
+  - Returns: { success, session } when opened by lumine app-mcp
+  - Register the live iframe handlers for the published app's static MCP tool manifest.
+  - Tool discovery comes only from /app-tools.json in the pinned published artifact; runtime code cannot add or rename tools.
+  - Every declared tool needs a same-named handler. Outside an app-mcp session, registration stores the handlers and resolves with active:false without starting a relay.
+  - Handlers run serially inside the visible app iframe and should return the confirmed post-action state.
+  - Do not synthesize server-owned state; await Twinkle SDK mutations before returning.
+  - Example: await Twinkle.appTools.register({ handlers: { get_state: () => ({ view, data }), open_view: ({ view }) => navigateTo(view) } });
+
 ### Twinkle.preview
 - getLayout() | scopes: none
   - Returns: { mode, viewport, stage, safeInsets, playfield }
@@ -302,6 +312,16 @@ console.log(analysis.bestMove, analysis.evaluation, analysis.mate);
   - Example: await Twinkle.files.delete(assetId);
 
 ### Twinkle.ai
+- async getUsagePolicy() | scopes: none
+  - Returns: BuildAiUsagePolicy | null
+  - Load the signed-in viewer's canonical current AI Energy battery policy.
+  - Signed-in viewers only.
+  - Returns canonical server state and does not consume AI Energy.
+  - Use energyPercent for a percentage meter and energySegments plus energySegmentsRemaining for segmented battery UI.
+  - The Build-safe response includes battery/day/usage fields only; account identity, email, risk, and recharge-eligibility metadata are not exposed to the app iframe.
+  - Successful AI calls return a newer aiUsagePolicy snapshot. Energy-related SDK errors expose the confirmed snapshot as error.aiUsagePolicy. Replace displayed state only from those confirmed values; do not decrement or synthesize battery state locally.
+  - Example: const policy = await Twinkle.ai.getUsagePolicy();
+renderBattery(policy?.energyPercent, policy?.energySegmentsRemaining);
 - async listPrompts() | scopes: none
   - Returns: Array<{ id, title, description }>
   - Legacy helper. Twinkle.ai.chat does not require promptId for default runtime text generation.
@@ -321,20 +341,25 @@ console.log(analysis.bestMove, analysis.evaluation, analysis.mate);
   - Use this for in-app AI replies instead of creating or fetching app-local endpoints such as /api/chat.
   - Example: const chatHistory = conversation.slice(-12).map((entry) => ({ role: entry.role === 'assistant' ? 'assistant' : 'user', content: entry.text }));
 const result = await Twinkle.ai.chat({ message, history: chatHistory, systemPrompt: 'You are a cheerful pirate helper who answers in one sentence.', onText: (text, meta) => renderReply(text), onStatus: (status) => setThinking(status === 'thinking') });
-- async generateObject({ prompt, expectedStructure, thinkingMode, mode, instructions, systemPrompt, webSearch } = {}) | scopes: none
-  - Returns: { object, result, model, provider, thinkingMode, requestedThinkingMode, webSearch, aiUsagePolicy }
-  - Generate a validated structured JSON object for app decisions, routing, grading, and game-state logic, optionally using live web search.
+- async generateObject({ prompt, expectedStructure, thinkingMode, mode, model, instructions, systemPrompt, webSearch, requestId, onText, onStatus } = {}) | scopes: none
+  - Returns: { object, result, model, provider, thinkingMode, requestedThinkingMode, requestedModel, webSearch, aiUsagePolicy }
+  - Generate a validated structured JSON object for app decisions, routing, grading, and game-state logic, with optional live output/status callbacks and web search.
   - Signed-in viewers only.
   - Use this instead of asking Twinkle.ai.chat to return JSON.
   - expectedStructure must be a JSON object that describes the exact returned object shape.
   - mode is accepted as an alias for thinkingMode, and mid is accepted as an alias for medium.
+  - Omit model to use the normal Lite/Medium/High routing. model accepts only claude-opus-5 or claude-fable-5, and either explicit model must be paired with thinkingMode: 'high'; unknown model IDs reject instead of silently falling back.
   - thinkingMode low uses GPT-5.6 Luna and consumes the viewer's AI Energy from confirmed provider usage; its smaller model is usually cheaper than Medium or High.
   - thinkingMode medium uses Grok 4.6 with medium reasoning and consumes normal AI Energy.
   - thinkingMode high uses GPT-5.6 Sol with high reasoning and consumes high AI Energy.
-  - When AI Energy is empty, Low, Medium, and High all reject before new provider work; there is no free fallback mode.
+  - claude-opus-5 uses Anthropic adaptive High thinking. claude-fable-5 uses Anthropic xhigh thinking and normally consumes more AI Energy for comparable token use. Both debit confirmed provider usage at the High tier.
+  - Pass onStatus and/or onText to stream progress from the same structured generation. onStatus receives high-level phases such as thinking, searching_web, responding, validating, and completed.
+  - onText receives accumulated structured-output text plus { done, delta, requestId, status }. Partial output is intentionally incomplete and may include provider formatting; parse only when done is true, when the callback receives the canonical object serialized as JSON, and use the resolved object as the source of truth.
+  - Streaming exposes app-visible structured output and high-level phases, not private model chain-of-thought. Put a user-facing field such as producerNotes in expectedStructure when the app should display model-authored commentary from the same generation.
+  - When AI Energy is empty, every automatic or named model choice rejects before new provider work; there is no free fallback mode.
   - Live web search is enabled by default in Medium and High modes. Pass webSearch: false to disable it for the app. Low/Lite Mode remains tool-free; explicitly forcing webSearch: true in Low Mode returns an error.
-  - The SDK validates shape and retries malformed JSON, but app code should still validate business-specific enum values.
-  - Example: const { object } = await Twinkle.ai.generateObject({ thinkingMode: 'medium', prompt: 'Classify the player intent from: ' + playerText, expectedStructure: { action: 'string', targetCharacter: 'string', confidence: 0, shouldAskFollowUp: false } });
+  - The server validates the final shape; automatic OpenAI/xAI routes can retry malformed output, while explicit Anthropic routes use native JSON Schema output. App code should still validate business-specific enum values.
+  - Example: const { object } = await Twinkle.ai.generateObject({ thinkingMode: 'high', model: 'claude-opus-5', prompt: 'Plan the next section from: ' + currentState, expectedStructure: { producerNotes: 'string', action: 'string', confidence: 0 }, onStatus: (phase) => showPhase(phase), onText: (partialJson, meta) => showStructuredProgress(partialJson, meta) });
 - onChatStatus(listener) | scopes: none
   - Returns: unsubscribe function
   - Listen to shared runtime AI chat stream events.

package/sdk/LUMINE_ADMIN.md

@@ -73,10 +73,12 @@ members. The response returns the canonical bucket, including its id for
 later `get` / `accounts add` / `note set` calls.
 
 `accounts add` accepts 1-500 unique positive user IDs, preflights the complete
-batch before writing, adds the canonical user and durable verified-email rules,
+batch before writing, adds one exact canonical user rule per requested account,
 re-attributes current-day AI usage, and returns the canonical bucket members.
-It is idempotent to retry. The API records the real operator in the private
-Lumine audit log; no public bot identity is involved.
+It never infers or adds email aliases: shared verified addresses can belong to
+unrelated accounts, so email rules require a separate explicit operator action.
+The command is idempotent to retry. The API records the real operator in the
+private Lumine audit log; no public bot identity is involved.
 
 `note set` records up to 255 characters of private operational context on the
 canonical bucket. Use it to distinguish quota bookkeeping from moderation;