@stage5/lumine 0.2.86 → 0.2.88

package/lib/sdk.js

@@ -22,6 +22,19 @@ export const SDK_CLI_METHODS = {
   "aiCards.get": { path: "api/content/ai-card", scopes: ["content:read"] },
   "grammarbles.listQuestions": { path: "api/content/grammarbles/questions", scopes: ["content:read"] },
   "grammarbles.getMyQuestionHistory": { path: "api/content/grammarbles/history", scopes: ["content:read"] },
+  "minecraft.getWorlds": { path: "api/minecraft/worlds", scopes: ["content:read"] },
+  "minecraft.getOnlinePlayers": { path: "api/minecraft/players", scopes: ["content:read"] },
+  "minecraft.getZero": { path: "api/minecraft/zero", scopes: ["content:read"] },
+  "minecraft.getZeroBuilds": { path: "api/minecraft/zero/builds", scopes: ["content:read"] },
+  "minecraft.getPeople": { path: "api/minecraft/people", scopes: ["content:read"] },
+  "minecraft.setPlayerRole": { path: "api/minecraft/people/role", scopes: ["content:write"], write: true },
+  "minecraft.getChat": { path: "api/minecraft/chat", scopes: ["content:read"] },
+  "minecraft.getChatHistory": { path: "api/minecraft/chat/history", scopes: ["content:read"] },
+  "minecraft.sendChat": { path: "api/minecraft/chat/send", scopes: ["content:write"], write: true },
+  "minecraft.muteChatUser": { path: "api/minecraft/chat/mute", scopes: ["content:write"], write: true },
+  "minecraft.getMyLink": { path: "api/minecraft/link", scopes: ["content:read"] },
+  "minecraft.createLinkCode": { path: "api/minecraft/link/code", scopes: ["content:write"], write: true },
+  "minecraft.unlinkMinecraft": { path: "api/minecraft/link/unlink", scopes: ["content:write"], write: true },
   "subjects.getMySubjects": { path: "api/content/my-subjects", scopes: ["content:read"] },
   "subjects.search": { path: "api/content/subjects/search", scopes: ["content:read"] },
   "subjects.getSubject": { path: "api/content/subject", scopes: ["content:read"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.86",
+  "version": "0.2.88",
   "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.47.0
-Updated: 2026-09-21
-Generated: 2026-09-23T02:44:06.901Z
+Version: 1.51.0
+Updated: 2026-09-24
+Generated: 2026-09-24T00:08:02.260Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -761,6 +761,91 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - A quiet edition with no editorial events does not call an AI provider and does not consume AI Energy.
   - A failed attempt may be queued again on the same day. A ready edition is immutable for ordinary viewers.
 
+### Twinkle.minecraft
+- async getWorlds() | scopes: content:read
+  - Returns: { worlds: [{ id, name, dimension, spawn: { x, z } | null, map: { tileUrlTemplate, minZoom, maxZoom, tilePixels, blocksPerTileAtMaxZoom, renderedAt } | null }], stale }
+  - List the server's worlds (world, world1, world2, world_nether, world_the_end) with squaremap tile info for drawing a top-down map.
+  - Tiles are 512x512 PNGs over HTTPS from www.twinklemc.site. At maxZoom one pixel is one block; blocksPerTile = blocksPerTileAtMaxZoom * 2 ** (maxZoom - z); tile x/y = floor(block x/z / blocksPerTile). Fill {z}, {x}, {y}. map.renderedAt tells how fresh the tiles are.
+  - Limited rollout: apps not enabled yet get 403 with code minecraft_sdk_not_enabled.
+  - stale: true means the Minecraft server was briefly unreachable and the data is a recent cached copy.
+  - Example: const { worlds } = await Twinkle.minecraft.getWorlds(); const w = worlds.find((x) => x.id === 'world'); const z = w.map.maxZoom; const blocksPerTile = w.map.blocksPerTileAtMaxZoom * 2 ** (w.map.maxZoom - z); const tx = Math.floor(blockX / blocksPerTile), ty = Math.floor(blockZ / blocksPerTile); const url = w.map.tileUrlTemplate.replace('{z}', z).replace('{x}', tx).replace('{y}', ty);
+- async getOnlinePlayers() | scopes: content:read
+  - Returns: { players: [{ name, world, x, y, z, isZero }], count, stale }
+  - List players currently online with their world and block coordinates. Zero appears with isZero: true and is not counted in count.
+  - Cached for about 5 seconds; poll no faster than every 5 seconds.
+  - Names are Minecraft usernames, not Twinkle usernames.
+  - Example: const { players, count } = await Twinkle.minecraft.getOnlinePlayers();
+- async getZero() | scopes: content:read
+  - Returns: { zero: { online, world, position: { x, y, z } | null, activity: 'idle'|'thinking'|'building'|'workshop', currentBuild: { id, title, status, placed, total, requester, world, bounds } | null, queue: [build], workshop: { world, min, max } | null, updatedAt }, stale }
+  - Where Zero is and what he is doing right now, including the build in progress and its progress.
+  - Cached for about 3 seconds.
+  - bounds are { min: [x, y, z], max: [x, y, z] } in world block coordinates.
+  - Example: const { zero } = await Twinkle.minecraft.getZero(); if (zero.currentBuild) console.log(zero.currentBuild.title, zero.currentBuild.placed + '/' + zero.currentBuild.total);
+- async getZeroBuilds({ limit, kind } = {}) | scopes: content:read
+  - Returns: { builds: [{ id, kind: 'helper'|'workshop', title, status, placed, total, requester, world, bounds, createdAt }], stale }
+  - Zero's recent builds, newest first: builds for players (helper) and his own workshop projects (workshop).
+  - limit is 1-50 (default 10). kind filters to helper or workshop builds.
+  - Example: const { builds } = await Twinkle.minecraft.getZeroBuilds({ limit: 10, kind: 'workshop' });
+- async getPeople() | scopes: content:read
+  - Returns: { canManage, people: [{ uuid, name, role: 'visitor'|'member'|'builder'|'moderator', groups, op, online, banned, protected, firstSeenAt, lastSeenAt, isZero, twinkle: { userId, username } | null }], roles }
+  - Everyone who has joined the server with their in-game role, for the server owner's role management screen.
+  - Only the server owner, in an app they own, gets the list; everyone else gets { canManage: false, people: [] } without an error, so hide the feature when canManage is false.
+  - Roles: visitor (play and chat), member (/tpa, /home, /back, may ask Zero to build), builder (member + /fly and creative/survival), moderator (builder + teleport others, CoreProtect rollback, /kick). op: true players are server operators and have every power regardless of role.
+  - protected: true players (the owner and Zero's account) can't be changed from the app. Sorted online first, then most recently seen.
+  - Not cached; call on screen open or after a change, not on a timer.
+  - twinkle is the Twinkle account linked to that player with /link, or null.
+  - Example: const { canManage, people } = await Twinkle.minecraft.getPeople(); if (!canManage) hidePeopleTab();
+- async setPlayerRole({ uuid, role }) | scopes: content:write
+  - Returns: { player: { uuid, name, role, op } }
+  - Change a player's in-game role; it applies immediately, even while they are online.
+  - Server owner only, in an app they own; others get 403 with code minecraft_roles_forbidden.
+  - role is visitor, member, builder or moderator. 400 codes: minecraft_bad_uuid, minecraft_bad_role, minecraft_protected_player, minecraft_unknown_player. 503 minecraft_unavailable while the server restarts.
+  - Every change is logged on the server and emailed to the owner; the player is told in game.
+  - Example: await Twinkle.minecraft.setPlayerRole({ uuid: person.uuid, role: 'builder' });
+- async getChat({ since } = {}) | scopes: content:read
+  - Returns: { events: [{ seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death', name, text, userId, archived }], latestSeq, online, archiveReady, viewer: { canSend, muted, canModerate }, mutedUserIds }
+  - Live server chat after a sequence number: player chat, Zero, messages sent from the web, joins, leaves and deaths.
+  - Without since (or 0) it returns the newest 50 events, oldest first. Pass since = latestSeq from the previous response to get only new events. Poll every 2-3 seconds while the chat is visible; stop when hidden.
+  - kind: chat (a player), zero (Zero, the AI builder), web (someone chatting from the Twinkle app; userId is their Twinkle user id), join, leave, death. Private messages are never included.
+  - name is a Minecraft username for chat/join/leave/death, and a Twinkle username for web.
+  - viewer.canModerate is true only for the server owner; mutedUserIds is filled only for them.
+  - Example: let since = 0; async function poll() { const { events, latestSeq } = await Twinkle.minecraft.getChat({ since }); since = latestSeq; render(events); } setInterval(poll, 2500);
+- async getChatHistory({ before, limit, query, includeArchived } = {}) | scopes: content:read
+  - Returns: { events: [{ seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death', name, text, userId, archived }], hasMore, nextBefore: { at, seq } | null, includesArchived }
+  - Older server chat, newest first, for scrolling back or searching past days.
+  - before is the nextBefore cursor from the previous page; omit it to start from the newest. limit 1-100 (default 50). query searches message text and names (60 chars).
+  - Chat from before the web chat bridge existed (imported from server logs) is archived: only the server owner can include it with includeArchived: true; others never receive it.
+  - Example: const page = await Twinkle.minecraft.getChatHistory({ limit: 50 }); const older = await Twinkle.minecraft.getChatHistory({ before: page.nextBefore });
+- async sendChat({ text }) | scopes: content:write
+  - Returns: { event: { seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death', name, text, userId, archived } }
+  - Send a chat message from the app into the Minecraft server; players see it as [Web] <your Twinkle username>.
+  - Signed-in viewers only. text is trimmed to 200 characters. About one message per 2.5 seconds and 10 per minute per person: 429 with code minecraft_chat_rate_limited and retryAfterMs.
+  - 403 minecraft_chat_forbidden for accounts banned from chat; 400 minecraft_muted when the server owner muted them from web chat.
+  - Send only on a user action (Enter or Send); never automatically.
+  - Example: await Twinkle.minecraft.sendChat({ text: 'Hi from the website!' });
+- async muteChatUser({ userId, muted }) | scopes: content:write
+  - Returns: { userId, muted }
+  - Server owner only: stop (or allow again) a Twinkle user sending web chat into the server.
+  - Server owner only, in an app they own; others get 403 with code minecraft_roles_forbidden. muted defaults to true.
+  - Example: await Twinkle.minecraft.muteChatUser({ userId: event.userId, muted: true });
+- async getMyLink() | scopes: content:read
+  - Returns: { links: [{ uuid, name, linkedAt }], pending: { code, expiresAt } | null }
+  - The Minecraft accounts linked to the signed-in viewer's Twinkle account, and any unused link code.
+  - Always the caller's own account. A viewer may link several Minecraft accounts (e.g. Java and Bedrock); each Minecraft account belongs to one Twinkle user.
+  - Poll every few seconds only while showing a code and waiting for the player to type /link in game.
+  - Example: const { links } = await Twinkle.minecraft.getMyLink(); const myMinecraftName = links[0]?.name;
+- async createLinkCode() | scopes: content:write
+  - Returns: { code, expiresAt, command }
+  - Get a one-time code the viewer types in game as /link CODE to connect that Minecraft account to their Twinkle account.
+  - Signed-in viewers only. Codes last 10 minutes, work once, and a new code replaces the old one. About 5 codes per 10 minutes: 429 minecraft_link_rate_limited.
+  - The player sees a confirmation in game; getMyLink() then lists the account.
+  - Example: const { command } = await Twinkle.minecraft.createLinkCode(); showText(`Type ${command} in Minecraft`);
+- async unlinkMinecraft({ uuid }) | scopes: content:write
+  - Returns: { removed }
+  - Remove one of the viewer's own linked Minecraft accounts.
+  - Only the viewer's own links; removed is false when there was nothing to remove.
+  - Example: await Twinkle.minecraft.unlinkMinecraft({ uuid: link.uuid });
+
 ### Twinkle.leaderboards
 - async get({ boardKey = 'default', limit, cursor } = {}) | scopes: none
   - Returns: { entries: [{ rank, id, buildId, boardKey, viewerKind, userId, displayName, score, meta, achievedAt, createdAt, updatedAt }], scores, cursor, hasMore, personalBest: { id, buildId, boardKey, viewerKind, userId, displayName, score, meta, achievedAt, createdAt, updatedAt } | null }

package/sdk/LUMINE_ADMIN.md

@@ -3008,7 +3008,10 @@ disagreements and the `jev_reply_gate_audit`, `jev_chat_routing_audit` and
 missing evidence. Report fallback rates and reasons instead. Auto rows served
 without a comparison carry `baselineStatus: not_run`; its fallback LLM spend is
 `lumine_model_fallback`. The eight comparison-only routing families below are
-unchanged. The rest of this section describes the pre-September-23 pilot.
+unchanged. Chat routing is also off since September 23
+(`JEV_CHAT_ROUTING_ENABLED`, default off; Jev served ~1% of chats and could not
+judge when a reply needs older history), so zero chat serving rows is expected.
+The rest of this section describes the pre-September-23 pilot.
 
 Read `data.jevPilot` from `lumine admin brief --json` and carry it into
 the full report for Mikey. The active `daily-run report --json` also includes