@wipcomputer/wip-ldm-os 0.4.85-alpha.30 → 0.4.85-alpha.32

package/src/hosted-mcp/server.mjs

@@ -5,7 +5,7 @@
 // WebAuthn: Passkey-based signup/login (replaces agent name text form).
 
 import { randomUUID, randomBytes, createHash } from "node:crypto";
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, accessSync, constants as fsConstants } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createServer } from "node:http";
@@ -1706,7 +1706,7 @@ function handleAgentAuthApprove(req, res) {
 
 // ---------- QR Login (Chrome fallback) ----------
 
-// `next` whitelist for the QR login flow. Two shapes are allowed; both
+// `next` whitelist for the QR login flow. Three shapes are allowed; each
 // land the user on a known phone-side surface after successful sign-in.
 // Anything else is silently dropped. `next` is NOT a general redirect
 // primitive.
@@ -1722,8 +1722,12 @@ function handleAgentAuthApprove(req, res) {
 //    Kaleidoscope phone-side remote-control thread surface. Standard
 //    ?next semantics; allowed on both desktop and mobile (this is
 //    navigation continuation, not authority transfer).
+//
+// 3. DEMO_NEXT_REGEX: /demo for the homepage CTA. Standard post-login
+//    continuation; allowed on both desktop and mobile.
 const PAIR_NEXT_REGEX = /^\/pair\/[ABCDEFGHJKLMNPQRSTUVWXYZ23456789]{6}$/;
 const REMOTE_CONTROL_NEXT_REGEX = /^\/codex-remote-control\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DEMO_NEXT_REGEX = /^\/demo$/;
 
 function sanitizeCrcPairNext(raw) {
   if (typeof raw !== "string") return null;
@@ -1732,7 +1736,7 @@ function sanitizeCrcPairNext(raw) {
   try { decoded = decodeURIComponent(raw); } catch { return null; }
   // Catch double-encoded payloads.
   if (decoded !== raw && /%/.test(decoded)) return null;
-  if (!PAIR_NEXT_REGEX.test(decoded) && !REMOTE_CONTROL_NEXT_REGEX.test(decoded)) return null;
+  if (!PAIR_NEXT_REGEX.test(decoded) && !REMOTE_CONTROL_NEXT_REGEX.test(decoded) && !DEMO_NEXT_REGEX.test(decoded)) return null;
   return decoded;
 }
 
@@ -1747,10 +1751,11 @@ async function handleQrLoginStart(req, res) {
   //
   // Only /pair/<CODE> next triggers pair-mode (C6 strip on desktop
   // status, C8 desktop-no-redirect, the "phone is the actor" model).
-  // /codex-remote-control/<UUID> is a normal post-login continuation:
-  // desktop status returns the full login response (apiKey, handle,
-  // next) so the desktop poll can authenticate and redirect on its
-  // own. The phone also gets next via approve, so both ends can act.
+  // /codex-remote-control/<UUID> and /demo are normal post-login
+  // continuations: desktop status returns the full login response
+  // (apiKey, handle, next) so the desktop poll can authenticate and
+  // redirect on its own. The phone also gets next via approve, so both
+  // ends can act.
   const next = sanitizeCrcPairNext(body && body.next);
   const purpose = (next && PAIR_NEXT_REGEX.test(next)) ? "pair" : null;
   const sessionId = randomUUID();
@@ -1764,7 +1769,7 @@ async function handleQrLoginStart(req, res) {
     handle: handle || null,
     expires: Date.now() + QR_LOGIN_EXPIRY_MS,
     purpose,           // "pair" | null
-    next: next || null, // sanitized `/pair/<CODE>` or null
+    next: next || null, // sanitized `/pair/<CODE>`, `/codex-remote-control/<UUID>`, `/demo`, or null
   };
   console.log("QR login: created session " + sessionId.slice(0, 8) + "..." + (purpose === "pair" ? " (pair-mode)" : ""));
   json(res, 200, { sessionId, qrUrl: "/api/qr-login/qr?s=" + sessionId });
@@ -1805,17 +1810,18 @@ function handleQrLoginStatus(req, res) {
       // C6 round 4. Desktop never becomes the pairing authority.
       json(res, 200, { status: "approved", agentId: entry.agentId });
     } else {
-      // Legacy login mode OR codex-remote-control continuation
+      // Legacy login mode OR standard login continuation
       // (purpose === null). Desktop gets full identity to render the
       // welcome view OR redirect to next on its own poll.
       // credentialLabel matches the saved-passkey label (see
       // register-verify / auth-verify). next is included only if a
       // sanitized non-pair-mode next was set on the session
-      // (currently /codex-remote-control/<UUID>); legacy login
-      // sessions without next get next === null.
+      // (/codex-remote-control/<UUID> or /demo); legacy login sessions
+      // without next get next === null.
       json(res, 200, {
         status: "approved",
         agentId: entry.agentId,
+        tenantId: entry.tenantId || null,
         apiKey: entry.apiKey,
         credentialLabel: entry.credentialLabel || null,
         next: entry.next || null,
@@ -1834,7 +1840,7 @@ function handleQrLoginStatus(req, res) {
 // {ok: true} unchanged.
 function handleQrLoginApprove(req, res) {
   readBody(req).then(function(body) {
-    const { sessionId, agentId, apiKey, credentialLabel } = body || {};
+    const { sessionId, agentId, apiKey, tenantId, credentialLabel } = body || {};
     const entry = qrLoginSessions[sessionId];
     if (!entry || Date.now() > entry.expires) {
       json(res, 404, { error: "Session not found or expired" });
@@ -1847,16 +1853,19 @@ function handleQrLoginApprove(req, res) {
     entry.status = "approved";
     entry.agentId = agentId;
     entry.apiKey = apiKey;
+    const verifiedIdentity = identityForApiKey(apiKey);
+    entry.tenantId = verifiedIdentity?.tenantId || (isInternalTenantId(tenantId) ? tenantId : null);
     // Phone-side passes the label it received from register-verify /
     // auth-verify so the desktop can show the same string the user
     // just saved on their phone. Optional for back-compat.
     entry.credentialLabel = (typeof credentialLabel === "string" && credentialLabel.length <= 64) ? credentialLabel : null;
     console.log("QR login: approved session " + sessionId.slice(0, 8) + "... for '" + agentId + "'" + (entry.purpose === "pair" ? " (pair-mode)" : (entry.next ? " (next=" + entry.next + ")" : "")));
     // Phone receives next on approve regardless of purpose, so the
-    // phone can redirect to either /pair/<CODE> (pair-mode, phone is
-    // the actor) or /codex-remote-control/<UUID> (continuation, phone
-    // can act). Desktop's separate behavior (strip vs full response)
-    // is handled in handleQrLoginStatus.
+    // phone can redirect to /pair/<CODE> (pair-mode, phone is the
+    // actor) or a standard continuation such as
+    // /codex-remote-control/<UUID> or /demo. Desktop's separate
+    // behavior (strip vs full response) is handled in
+    // handleQrLoginStatus.
     if (entry.next) {
       json(res, 200, { ok: true, next: entry.next });
     } else {
@@ -1870,32 +1879,77 @@ function handleQrLoginApprove(req, res) {
 // ---------- Demo API handlers ----------
 
 // ── Wallet tracking (per agent) ──
-const IMAGE_COST_CENTS = 1; // $0.01
-const INITIAL_BALANCE_CENTS = 500; // $5.00
+const IMAGE_COST_CENTS = 1; // $0.01, launch onboarding image-generation step
+const INITIAL_BALANCE_CENTS = 1000; // $10.00
 
 // JSON fallback for wallets
 const WALLET_FILE = join(dirname(fileURLToPath(import.meta.url)), "wallets.json");
+const DEMO_WALLET_RESET_MARKER_FILE = join(dirname(fileURLToPath(import.meta.url)), ".demo-wallet-reset-v0-4-87.json");
 function loadWalletsFromFile() { try { return JSON.parse(readFileSync(WALLET_FILE, "utf8")); } catch { return {}; } }
 function saveWalletsToFile(w) { try { writeFileSync(WALLET_FILE, JSON.stringify(w, null, 2) + "\n"); } catch {} }
 
+function walletUserIdForAgent(agentId) {
+  return typeof agentId === "string" && agentId.startsWith("acct:") ? agentId.slice("acct:".length) : agentId;
+}
+
+function resetAndNormalizeWalletFileEntries(wallets) {
+  const normalizedWallets = {};
+  let resetCount = 0;
+  for (const agentId of Object.keys(wallets)) {
+    normalizedWallets[walletUserIdForAgent(agentId)] = INITIAL_BALANCE_CENTS;
+    resetCount += 1;
+  }
+  return { wallets: normalizedWallets, count: resetCount };
+}
+
+async function resetExistingDemoWalletsToStarterBalanceOnce() {
+  if (existsSync(DEMO_WALLET_RESET_MARKER_FILE)) return;
+  let prismaResetCount = 0;
+  let jsonResetCount = 0;
+  if (usePrisma) {
+    try {
+      const result = await prisma.wallet.updateMany({ data: { balance: INITIAL_BALANCE_CENTS } });
+      prismaResetCount = result.count || 0;
+    } catch (err) {
+      console.error("Demo wallet reset migration error:", err.message);
+    }
+  }
+  const normalizedWalletFile = resetAndNormalizeWalletFileEntries(loadWalletsFromFile());
+  jsonResetCount = normalizedWalletFile.count;
+  saveWalletsToFile(normalizedWalletFile.wallets);
+  try {
+    writeFileSync(DEMO_WALLET_RESET_MARKER_FILE, JSON.stringify({
+      resetAt: new Date().toISOString(),
+      balance: INITIAL_BALANCE_CENTS,
+      prismaCount: prismaResetCount,
+      jsonCount: jsonResetCount,
+    }, null, 2) + "\n");
+  } catch (err) {
+    console.error("Demo wallet reset marker write error:", err.message);
+  }
+  console.log("Demo wallet reset migration: set " + (prismaResetCount + jsonResetCount) + " existing wallet balance(s) to " + formatCents(INITIAL_BALANCE_CENTS));
+}
+
 async function getBalance(agentId) {
+  const walletUserId = walletUserIdForAgent(agentId);
   if (usePrisma) {
     try {
-      const wallet = await prisma.wallet.findFirst({ where: { userId: agentId } });
+      const wallet = await prisma.wallet.findFirst({ where: { userId: walletUserId } });
       return wallet ? wallet.balance : INITIAL_BALANCE_CENTS;
     } catch {}
   }
   const w = loadWalletsFromFile();
-  return w[agentId] !== undefined ? w[agentId] : INITIAL_BALANCE_CENTS;
+  return w[walletUserId] !== undefined ? w[walletUserId] : INITIAL_BALANCE_CENTS;
 }
 
 async function deductBalance(agentId, cents) {
+  const walletUserId = walletUserIdForAgent(agentId);
   if (usePrisma) {
     try {
-      let wallet = await prisma.wallet.findFirst({ where: { userId: agentId } });
+      let wallet = await prisma.wallet.findFirst({ where: { userId: walletUserId } });
       if (!wallet) {
         wallet = await prisma.wallet.create({
-          data: { userId: agentId, balance: INITIAL_BALANCE_CENTS },
+          data: { userId: walletUserId, balance: INITIAL_BALANCE_CENTS },
         });
       }
       const newBalance = Math.max(0, wallet.balance - cents);
@@ -1907,13 +1961,515 @@ async function deductBalance(agentId, cents) {
   }
   // JSON fallback
   const w = loadWalletsFromFile();
-  if (w[agentId] === undefined) w[agentId] = INITIAL_BALANCE_CENTS;
-  w[agentId] = Math.max(0, w[agentId] - cents);
+  if (w[walletUserId] === undefined) w[walletUserId] = INITIAL_BALANCE_CENTS;
+  w[walletUserId] = Math.max(0, w[walletUserId] - cents);
   saveWalletsToFile(w);
-  return w[agentId];
+  return w[walletUserId];
 }
 function formatCents(c) { return "$" + (c / 100).toFixed(2); }
 
+await resetExistingDemoWalletsToStarterBalanceOnce();
+
+const LIVE_WALL_FILE = process.env.KALEIDOSCOPE_LIVE_WALL_FILE || join(__dirname, "kaleidoscope-live-wall.json");
+const LIVE_WALL_MEDIA_ROUTE = "/media/kaleidoscope/generated/";
+const LIVE_WALL_DEFAULT_MEDIA_DIR = DEV_MODE
+  ? join(__dirname, "media", "kaleidoscope", "generated")
+  : "/var/www/wip.computer/public_html/media/kaleidoscope/generated";
+const LIVE_WALL_MEDIA_DIR = process.env.KALEIDOSCOPE_LIVE_WALL_MEDIA_DIR || LIVE_WALL_DEFAULT_MEDIA_DIR;
+const LIVE_WALL_MAX_IMAGE_BYTES = Math.max(1, parseInt(process.env.KALEIDOSCOPE_LIVE_WALL_MAX_IMAGE_BYTES || String(10 * 1024 * 1024), 10));
+const LIVE_WALL_FETCH_TIMEOUT_MS = Math.max(1_000, parseInt(process.env.KALEIDOSCOPE_LIVE_WALL_FETCH_TIMEOUT_MS || "15000", 10));
+const LIVE_WALL_LIMIT = 240;
+const KALEIDOSCOPE_PUBLIC_STATS_BASELINE = Object.freeze({
+  timezone: "America/Los_Angeles",
+  date: "2026-05-21",
+  startsAt: "2026-05-21T07:00:00.000Z",
+  counts: Object.freeze({
+    keysCreated: 3,
+    genericKaleidoscopes: 11,
+    imageKaleidoscopes: 3,
+  }),
+});
+const LIVE_WALL_SEED_SOURCES = [
+  {
+    sourceUrl: "https://imgen.x.ai/xai-imgen/xai-tmp-imgen-bd814982-276f-438d-bc3c-2ca817982aae.jpeg",
+    createdAt: "2026-05-20T00:00:00.000Z",
+    kind: "generic",
+  },
+  {
+    sourceUrl: "https://imgen.x.ai/xai-imgen/xai-tmp-imgen-226e18a9-7721-4f6c-9ef2-3c26c0ff1293.jpeg",
+    createdAt: "2026-05-20T00:00:01.000Z",
+    kind: "generic",
+  },
+  {
+    sourceUrl: "https://imgen.x.ai/xai-imgen/xai-tmp-imgen-b1b398b5-4982-4ed8-b583-170a4ae4e811.jpeg",
+    createdAt: "2026-05-20T00:00:02.000Z",
+    kind: "generic",
+  },
+  {
+    sourceUrl: "https://imgen.x.ai/xai-imgen/xai-tmp-imgen-5505496e-c436-4047-ab81-630a22ec75ea.jpeg",
+    createdAt: "2026-05-20T00:00:03.000Z",
+    kind: "generic",
+  },
+];
+let liveWallSeedBackfillAttempted = false;
+
+function ensureLiveWallRuntimeStorage() {
+  try {
+    mkdirSync(dirname(LIVE_WALL_FILE), { recursive: true });
+    mkdirSync(LIVE_WALL_MEDIA_DIR, { recursive: true });
+    accessSync(dirname(LIVE_WALL_FILE), fsConstants.W_OK);
+    accessSync(LIVE_WALL_MEDIA_DIR, fsConstants.W_OK);
+  } catch (err) {
+    console.error("FATAL: Kaleidoscope live wall storage is not writable:", err.message);
+    process.exit(1);
+  }
+}
+
+ensureLiveWallRuntimeStorage();
+
+const LIVE_WALL_GENERIC_PROMPT = "Create an abstract kaleidoscope image with mirrored radial symmetry, analog film grain, warm color bleed, soft exposure, organic imperfections, and no text.";
+const LIVE_WALL_PHOTO_PROMPT = "Create an abstract kaleidoscope image from the colors, light, and shapes in the user's photo. Use mirrored radial symmetry, analog film grain, warm color bleed, soft exposure, organic imperfections, and no text.";
+const LIVE_WALL_IMAGE_PROMPT_PREFIX = "Create an abstract kaleidoscope image from these visual details in the user's photo: ";
+const LIVE_WALL_IMAGE_PROMPT_SUFFIX = ". Use mirrored radial symmetry, analog film grain, warm color bleed, soft exposure, organic imperfections, and no text.";
+
+function classifyLiveWallPrompt(prompt) {
+  if (prompt === LIVE_WALL_GENERIC_PROMPT) return "generic";
+  if (prompt === LIVE_WALL_PHOTO_PROMPT) return "image";
+  if (typeof prompt === "string"
+    && prompt.startsWith(LIVE_WALL_IMAGE_PROMPT_PREFIX)
+    && prompt.endsWith(LIVE_WALL_IMAGE_PROMPT_SUFFIX)) {
+    return "image";
+  }
+  return null;
+}
+
+function parseTimestampMs(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function createdAtSinceBaseline(item) {
+  const baselineMs = Date.parse(KALEIDOSCOPE_PUBLIC_STATS_BASELINE.startsAt);
+  const createdAtMs = parseTimestampMs(item?.createdAt);
+  return createdAtMs !== null && createdAtMs >= baselineMs;
+}
+
+function isWipTestHandle(handle) {
+  return typeof handle === "string" && handle.trim().toLowerCase().startsWith("wiptest-");
+}
+
+function publicKeyCreatedSinceBaseline(entry) {
+  return createdAtSinceBaseline(entry) && !isWipTestHandle(entry?.handle);
+}
+
+function latestCreatedAt(items) {
+  let latestMs = null;
+  let latest = null;
+  for (const item of Array.isArray(items) ? items : []) {
+    const ms = parseTimestampMs(item?.createdAt);
+    if (ms === null) continue;
+    if (latestMs === null || ms > latestMs) {
+      latestMs = ms;
+      latest = new Date(ms).toISOString();
+    }
+  }
+  return latest;
+}
+
+function countCreatedInLast24Hours(items, now = new Date()) {
+  const nowMs = now.getTime();
+  const windowStartMs = nowMs - (24 * 60 * 60 * 1000);
+  return (Array.isArray(items) ? items : []).filter(item => {
+    const ms = parseTimestampMs(item?.createdAt);
+    return ms !== null && ms >= windowStartMs && ms <= nowMs;
+  }).length;
+}
+
+function deriveKaleidoscopePublicStats({ images, passkeyEntries, now = new Date() }) {
+  const safeImages = Array.isArray(images) ? images : [];
+  const safePasskeys = Array.isArray(passkeyEntries) ? passkeyEntries : [];
+  const postBaselineGeneric = safeImages
+    .filter(item => item && isPublicWallImageUrl(item.url) && item.kind !== "image" && createdAtSinceBaseline(item))
+    .length;
+  const postBaselineImage = safeImages
+    .filter(item => item && isPublicWallImageUrl(item.url) && item.kind === "image" && createdAtSinceBaseline(item))
+    .length;
+  const publicPasskeys = safePasskeys.filter(item => !isWipTestHandle(item?.handle));
+  const postBaselineKeys = publicPasskeys.filter(createdAtSinceBaseline).length;
+  const newestCreatedAt = latestCreatedAt([...safeImages, ...publicPasskeys]);
+
+  return {
+    genericKaleidoscopes: KALEIDOSCOPE_PUBLIC_STATS_BASELINE.counts.genericKaleidoscopes + postBaselineGeneric,
+    imageKaleidoscopes: KALEIDOSCOPE_PUBLIC_STATS_BASELINE.counts.imageKaleidoscopes + postBaselineImage,
+    keysCreated: KALEIDOSCOPE_PUBLIC_STATS_BASELINE.counts.keysCreated + postBaselineKeys,
+    publicWallImages: safeImages.filter(item => item && isPublicWallImageUrl(item.url)).length,
+    baseline: KALEIDOSCOPE_PUBLIC_STATS_BASELINE,
+    newSinceBaseline: {
+      genericKaleidoscopes: postBaselineGeneric,
+      imageKaleidoscopes: postBaselineImage,
+      keysCreated: postBaselineKeys,
+      total: postBaselineGeneric + postBaselineImage + postBaselineKeys,
+    },
+    last24Hours: {
+      wallImages: countCreatedInLast24Hours(safeImages, now),
+      keysCreated: countCreatedInLast24Hours(publicPasskeys, now),
+    },
+    lastCreated: newestCreatedAt,
+  };
+}
+
+function loadLiveWallState() {
+  try {
+    const parsed = JSON.parse(readFileSync(LIVE_WALL_FILE, "utf8"));
+    const saved = Array.isArray(parsed?.images) ? parsed.images : [];
+    return {
+      images: saved,
+    };
+  } catch {
+    return {
+      images: [],
+    };
+  }
+}
+
+function saveLiveWallState(state) {
+  try {
+    mkdirSync(dirname(LIVE_WALL_FILE), { recursive: true });
+    writeFileSync(LIVE_WALL_FILE, JSON.stringify({
+      images: Array.isArray(state?.images) ? state.images : [],
+    }, null, 2) + "\n");
+  } catch (err) {
+    console.error("Kaleidoscope live wall save error:", err.message);
+  }
+}
+
+function liveWallSourceHash(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function publicLiveWallMediaUrl(filename) {
+  return ISSUER_URL + LIVE_WALL_MEDIA_ROUTE + filename;
+}
+
+function liveWallMediaFilenameFromUrl(value) {
+  try {
+    const url = new URL(value, ISSUER_URL);
+    if (url.origin !== ISSUER_URL || !url.pathname.startsWith(LIVE_WALL_MEDIA_ROUTE)) return null;
+    const filename = url.pathname.slice(LIVE_WALL_MEDIA_ROUTE.length);
+    return /^[a-f0-9]{64}\.(jpg|png|webp)$/.test(filename) ? filename : null;
+  } catch {
+    return null;
+  }
+}
+
+function liveWallMediaFileExists(value) {
+  const filename = liveWallMediaFilenameFromUrl(value);
+  return Boolean(filename && existsSync(join(LIVE_WALL_MEDIA_DIR, filename)));
+}
+
+function liveWallContentTypeForFilename(filename) {
+  if (filename.endsWith(".jpg")) return "image/jpeg";
+  if (filename.endsWith(".png")) return "image/png";
+  if (filename.endsWith(".webp")) return "image/webp";
+  return null;
+}
+
+function serveKaleidoscopeGeneratedMedia(path, res) {
+  const filename = path.slice(LIVE_WALL_MEDIA_ROUTE.length);
+  if (!/^[a-f0-9]{64}\.(jpg|png|webp)$/.test(filename)) {
+    json(res, 404, { error: "Not found" });
+    return;
+  }
+  try {
+    const content = readFileSync(join(LIVE_WALL_MEDIA_DIR, filename));
+    const contentType = liveWallContentTypeForFilename(filename) || "application/octet-stream";
+    res.writeHead(200, {
+      "Content-Type": contentType,
+      "Content-Length": content.length,
+      "Cache-Control": "public, max-age=31536000, immutable",
+    });
+    res.end(content);
+  } catch {
+    json(res, 404, { error: "Not found" });
+  }
+}
+
+function isLiveWallMediaUrl(value) {
+  if (typeof value !== "string" || value.length > 2048) return false;
+  try {
+    const url = new URL(value, ISSUER_URL);
+    return url.origin === ISSUER_URL && url.pathname.startsWith(LIVE_WALL_MEDIA_ROUTE);
+  } catch {
+    return false;
+  }
+}
+
+function isAllowedLiveWallSourceUrl(value) {
+  if (typeof value !== "string" || value.length > 2048) return false;
+  if (value.startsWith("data:")) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && url.hostname === "imgen.x.ai" && url.pathname.startsWith("/xai-imgen/");
+  } catch {
+    return false;
+  }
+}
+
+function isPublicWallImageUrl(value) {
+  return isLiveWallMediaUrl(value) || isAllowedLiveWallSourceUrl(value);
+}
+
+function normalizeLiveWallContentType(value) {
+  const type = String(value || "").split(";")[0].trim().toLowerCase();
+  if (type === "image/jpg") return "image/jpeg";
+  return type;
+}
+
+function liveWallExtensionForContentType(contentType) {
+  if (contentType === "image/jpeg") return "jpg";
+  if (contentType === "image/png") return "png";
+  if (contentType === "image/webp") return "webp";
+  return null;
+}
+
+function liveWallBufferMatchesContentType(buffer, contentType) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 12) return false;
+  if (contentType === "image/jpeg") {
+    return buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff;
+  }
+  if (contentType === "image/png") {
+    return buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47
+      && buffer[4] === 0x0d && buffer[5] === 0x0a && buffer[6] === 0x1a && buffer[7] === 0x0a;
+  }
+  if (contentType === "image/webp") {
+    return buffer.subarray(0, 4).toString("ascii") === "RIFF"
+      && buffer.subarray(8, 12).toString("ascii") === "WEBP";
+  }
+  return false;
+}
+
+async function readLiveWallImageResponseBody(response) {
+  if (!response.body || typeof response.body.getReader !== "function") {
+    throw new Error("source image response body is not readable");
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      total += value.byteLength;
+      if (total > LIVE_WALL_MAX_IMAGE_BYTES) {
+        throw new Error("source image exceeds max byte size");
+      }
+      chunks.push(Buffer.from(value));
+    }
+  } finally {
+    try { reader.releaseLock(); } catch {}
+  }
+
+  if (total < 1) throw new Error("source image byte size is invalid");
+  return Buffer.concat(chunks, total);
+}
+
+async function archiveKaleidoscopeGeneratedImage(sourceUrl) {
+  if (!isAllowedLiveWallSourceUrl(sourceUrl)) throw new Error("source image URL is not an allowed HTTPS image source");
+  const source = new URL(sourceUrl);
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), LIVE_WALL_FETCH_TIMEOUT_MS);
+  if (typeof timeout.unref === "function") timeout.unref();
+  let imageRes;
+  try {
+    imageRes = await fetch(source.href, { redirect: "follow", signal: controller.signal });
+    if (!imageRes.ok) throw new Error("source image fetch failed with HTTP " + imageRes.status);
+    const finalUrl = new URL(imageRes.url || source.href);
+    if (!isAllowedLiveWallSourceUrl(finalUrl.href)) throw new Error("source image redirected away from allowed image source");
+
+    const contentType = normalizeLiveWallContentType(imageRes.headers.get("content-type"));
+    const ext = liveWallExtensionForContentType(contentType);
+    if (!ext) throw new Error("source image content type is not an allowed raster image");
+
+    const contentLength = Number.parseInt(imageRes.headers.get("content-length") || "0", 10);
+    if (Number.isFinite(contentLength) && contentLength > LIVE_WALL_MAX_IMAGE_BYTES) {
+      throw new Error("source image exceeds max byte size");
+    }
+
+    const buffer = await readLiveWallImageResponseBody(imageRes);
+    if (!liveWallBufferMatchesContentType(buffer, contentType)) {
+      throw new Error("source image bytes do not match content type");
+    }
+
+    const contentHash = createHash("sha256").update(buffer).digest("hex");
+    const sourceUrlHash = liveWallSourceHash(source.href);
+    const filename = contentHash + "." + ext;
+    mkdirSync(LIVE_WALL_MEDIA_DIR, { recursive: true });
+    const filePath = join(LIVE_WALL_MEDIA_DIR, filename);
+    if (!existsSync(filePath)) writeFileSync(filePath, buffer);
+
+    return {
+      url: publicLiveWallMediaUrl(filename),
+      sourceProvider: "xai",
+      sourceUrlHash,
+      contentHash,
+      contentType,
+      byteLength: buffer.length,
+      archivedAt: new Date().toISOString(),
+    };
+  } catch (err) {
+    if (err?.name === "AbortError") throw new Error("source image fetch timed out");
+    throw err;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function liveWallEntryFromArchived({ archived, createdAt, kind, id }) {
+  return {
+    id: id || randomUUID(),
+    url: archived.url,
+    createdAt: createdAt || new Date().toISOString(),
+    kind: kind === "image" ? "image" : "generic",
+    sourceProvider: archived.sourceProvider,
+    sourceUrlHash: archived.sourceUrlHash,
+    contentHash: archived.contentHash,
+    contentType: archived.contentType,
+    byteLength: archived.byteLength,
+    archivedAt: archived.archivedAt,
+  };
+}
+
+function liveWallEntrySourceHash(item) {
+  if (!item || typeof item !== "object") return null;
+  if (typeof item.sourceUrlHash === "string" && item.sourceUrlHash) return item.sourceUrlHash;
+  if (isAllowedLiveWallSourceUrl(item.url)) return liveWallSourceHash(item.url);
+  return null;
+}
+
+async function ensureLiveWallSeedImages() {
+  if (liveWallSeedBackfillAttempted) return;
+  liveWallSeedBackfillAttempted = true;
+
+  const state = loadLiveWallState();
+  const images = [];
+  const existingSourceHashes = new Set();
+  const existingUrls = new Set(images.map(item => item.url).filter(Boolean));
+  let changed = false;
+
+  for (const item of state.images) {
+    if (!item || typeof item.url !== "string") {
+      changed = true;
+      continue;
+    }
+    if (isLiveWallMediaUrl(item.url) && liveWallMediaFileExists(item.url)) {
+      images.push(item);
+      if (item.sourceUrlHash) existingSourceHashes.add(item.sourceUrlHash);
+      existingUrls.add(item.url);
+      continue;
+    }
+    if (isAllowedLiveWallSourceUrl(item.url)) {
+      try {
+        const archived = await archiveKaleidoscopeGeneratedImage(item.url);
+        if (!existingUrls.has(archived.url)) {
+          images.push(liveWallEntryFromArchived({
+            archived,
+            createdAt: item.createdAt,
+            kind: item.kind,
+            id: item.id,
+          }));
+          existingUrls.add(archived.url);
+        }
+        existingSourceHashes.add(archived.sourceUrlHash);
+        changed = true;
+      } catch (err) {
+        images.push(item);
+        console.error("Kaleidoscope live wall registry image migration failed:", JSON.stringify({
+          sourceUrlHash: liveWallSourceHash(item.url),
+          message: err.message,
+        }));
+      }
+      continue;
+    }
+    changed = true;
+  }
+
+  for (const seed of LIVE_WALL_SEED_SOURCES) {
+    const sourceUrlHash = liveWallSourceHash(seed.sourceUrl);
+    if (existingSourceHashes.has(sourceUrlHash)) continue;
+    try {
+      const archived = await archiveKaleidoscopeGeneratedImage(seed.sourceUrl);
+      if (existingUrls.has(archived.url)) continue;
+      images.push(liveWallEntryFromArchived({
+        archived,
+        createdAt: seed.createdAt,
+        kind: seed.kind,
+      }));
+      existingSourceHashes.add(sourceUrlHash);
+      existingUrls.add(archived.url);
+      changed = true;
+    } catch (err) {
+      console.error("Kaleidoscope live wall seed archive failed:", JSON.stringify({
+        sourceUrlHash,
+        message: err.message,
+      }));
+    }
+  }
+
+  if (changed) saveLiveWallState({ images: images.slice(0, LIVE_WALL_LIMIT) });
+}
+
+async function registerKaleidoscopeLiveWallEvent({ kind, imageUrl }) {
+  if (kind !== "generic" && kind !== "image") return;
+  let archived;
+  try {
+    archived = await archiveKaleidoscopeGeneratedImage(imageUrl);
+  } catch (err) {
+    console.error("Kaleidoscope live wall archive failed:", JSON.stringify({
+      kind,
+      message: err.message,
+    }));
+    return;
+  }
+
+  const state = loadLiveWallState();
+  const mediaImages = state.images
+    .filter(item => item && isLiveWallMediaUrl(item.url) && liveWallMediaFileExists(item.url))
+    .filter(item => item.url !== archived.url && item.sourceUrlHash !== archived.sourceUrlHash);
+  const rawImages = state.images
+    .filter(item => item && isAllowedLiveWallSourceUrl(item.url))
+    .filter(item => liveWallEntrySourceHash(item) !== archived.sourceUrlHash);
+  const images = [
+    liveWallEntryFromArchived({
+      archived,
+      createdAt: new Date().toISOString(),
+      kind,
+    }),
+    ...mediaImages,
+    ...rawImages,
+  ];
+  saveLiveWallState({ images: images.slice(0, LIVE_WALL_LIMIT) });
+  return archived.url;
+}
+
+async function handleKaleidoscopeLiveWall(req, res) {
+  await ensureLiveWallSeedImages();
+  const state = loadLiveWallState();
+  const images = state.images
+    .filter(item => item && isLiveWallMediaUrl(item.url) && liveWallMediaFileExists(item.url))
+    .slice(0, LIVE_WALL_LIMIT);
+  const stats = deriveKaleidoscopePublicStats({ images, passkeyEntries: passkeys });
+  res.setHeader("Cache-Control", "no-store");
+  json(res, 200, {
+    count: images.length,
+    stats,
+    images: images.map(item => ({ url: item.url, createdAt: item.createdAt || null })),
+  });
+}
+
 // POST /demo/api/analyze-photo
 // Sends a base64 image to OpenAI GPT-4o vision to extract colors/mood.
 async function handleDemoAnalyzePhoto(req, res) {
@@ -1986,6 +2542,7 @@ async function handleDemoImagine(req, res) {
   try {
     const body = await readBody(req);
     const prompt = body?.prompt || "kaleidoscope";
+    const liveWallKind = classifyLiveWallPrompt(prompt);
 
     const XAI_KEY = process.env.XAI_API_KEY || "";
     if (!XAI_KEY) {
@@ -1993,34 +2550,57 @@ async function handleDemoImagine(req, res) {
       return;
     }
 
+    const imageModel = process.env.XAI_IMAGE_MODEL || "grok-imagine-image-quality";
+    const imageRequestBody = {
+      model: imageModel,
+      prompt: prompt,
+    };
     const grokRes = await fetch("https://api.x.ai/v1/images/generations", {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         "Authorization": "Bearer " + XAI_KEY,
       },
-      body: JSON.stringify({
-        model: "grok-imagine-image",
-        prompt: prompt,
-        n: 1,
-      }),
+      body: JSON.stringify(imageRequestBody),
     });
 
-    const grokData = await grokRes.json();
-    if (grokData.error) {
-      json(res, 502, { error: grokData.error.message || "Image generation failed" });
+    const grokText = await grokRes.text();
+    let grokData;
+    try {
+      grokData = grokText ? JSON.parse(grokText) : {};
+    } catch {
+      grokData = { error: { message: "Non-JSON image API response" } };
+    }
+
+    if (!grokRes.ok || grokData.error) {
+      const message = grokData.error?.message || grokRes.statusText || "Image generation failed";
+      console.error("Demo imagine upstream error:", JSON.stringify({
+        status: grokRes.status,
+        model: imageModel,
+        message,
+        type: grokData.error?.type || null,
+        code: grokData.error?.code || null,
+        param: grokData.error?.param || null,
+      }));
+      json(res, 502, { error: message });
       return;
     }
 
     const imageUrl = grokData.data?.[0]?.url;
     if (!imageUrl) {
+      console.error("Demo imagine upstream returned no image URL:", JSON.stringify({
+        status: grokRes.status,
+        model: imageModel,
+        responseKeys: Object.keys(grokData || {}),
+      }));
       json(res, 502, { error: "No image returned" });
       return;
     }
 
     const newBalance = await deductBalance(identity.agentId, IMAGE_COST_CENTS);
-    console.log("Demo: generated image for agent '" + identity.agentId + "' (balance: " + formatCents(newBalance) + ")");
-    json(res, 200, { url: imageUrl, prompt: prompt, cost: formatCents(IMAGE_COST_CENTS), balance: formatCents(newBalance) });
+    const archivedImageUrl = await registerKaleidoscopeLiveWallEvent({ kind: liveWallKind, imageUrl });
+    console.log("Demo: generated image for agent '" + identity.agentId + "' using " + imageModel + " (balance: " + formatCents(newBalance) + ")");
+    json(res, 200, { url: archivedImageUrl || imageUrl, prompt: prompt, cost: formatCents(IMAGE_COST_CENTS), balance: formatCents(newBalance) });
   } catch (err) {
     console.error("Demo imagine error:", err.message);
     json(res, 500, { error: "Internal error" });
@@ -2266,6 +2846,11 @@ const httpServer = createServer(async (req, res) => {
 
   // --- Shared assets (Kaleidoscope template system) ---
 
+  if (req.method === "GET" && path.startsWith(LIVE_WALL_MEDIA_ROUTE)) {
+    serveKaleidoscopeGeneratedMedia(path, res);
+    return;
+  }
+
   if (req.method === "GET" && path.startsWith("/shared/")) {
     const filePath = join(__dirname, path);
     try {
@@ -2337,6 +2922,33 @@ const httpServer = createServer(async (req, res) => {
 
   // --- Legal pages ---
 
+  if (req.method === "GET" && path === "/legal/legal.css") {
+    try {
+      const css = readFileSync(join(__dirname, "legal", "legal.css"), "utf8");
+      res.writeHead(200, { "Content-Type": "text/css; charset=utf-8" });
+      res.end(css);
+    } catch { json(res, 404, { error: "Not found" }); }
+    return;
+  }
+
+  if (req.method === "GET" && path === "/legal/legal-footer.js") {
+    try {
+      const js = readFileSync(join(__dirname, "legal", "legal-footer.js"), "utf8");
+      res.writeHead(200, { "Content-Type": "text/javascript; charset=utf-8" });
+      res.end(js);
+    } catch { json(res, 404, { error: "Not found" }); }
+    return;
+  }
+
+  if (req.method === "GET" && (path === "/legal/privacy/" || path === "/legal/privacy")) {
+    try {
+      const html = readFileSync(join(__dirname, "legal", "privacy", "index.html"), "utf8");
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(html);
+    } catch { json(res, 404, { error: "Not found" }); }
+    return;
+  }
+
   if (req.method === "GET" && (path === "/legal/privacy/en-ww/" || path === "/legal/privacy/en-ww")) {
     try {
       const html = readFileSync(join(__dirname, "legal", "privacy", "en-ww", "index.html"), "utf8");
@@ -2355,6 +2967,15 @@ const httpServer = createServer(async (req, res) => {
     return;
   }
 
+  if (req.method === "GET" && (path === "/legal/internet-services/kaleidoscope/" || path === "/legal/internet-services/kaleidoscope")) {
+    try {
+      const html = readFileSync(join(__dirname, "legal", "internet-services", "kaleidoscope", "index.html"), "utf8");
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(html);
+    } catch { json(res, 404, { error: "Not found" }); }
+    return;
+  }
+
   // --- WebAuthn API ---
 
   if (req.method === "POST" && path === "/webauthn/register-options") {
@@ -2501,6 +3122,12 @@ const httpServer = createServer(async (req, res) => {
     return;
   }
 
+  if (req.method === "GET" && path === "/demo/api/kaleidoscope-live-wall") {
+    if (!applyRateLimit(req, res, "status")) return;
+    await handleKaleidoscopeLiveWall(req, res);
+    return;
+  }
+
   if (req.method === "POST" && path === "/demo/api/analyze-photo") {
     await handleDemoAnalyzePhoto(req, res);
     return;