@bongos/core 1.23.21 → 1.24.1

package/modules/ai-studio/module.json

@@ -0,0 +1,26 @@
+{
+  "key": "ai-studio",
+  "title": "AI studio (artists' generation)",
+  "description": "An artist submits a sketch or image set with a prompt in the Studio and gets a Gemini reply plus generated images, with project context added on the server (task 1004916, goal 1000136, ADR 0392). Runs on our provider key against a processor-held balance (provider cost times one named multiplier, funds held before the run, released on failure) or on the builder's own key at no charge. Keys are entered only in Settings and never leave the server. default:false: enabled where billing is wanted, the hub first.",
+  "version": "1.0.0",
+  "coreVersion": "^1.19.0",
+  "category": {
+    "parent": "money"
+  },
+  "author": "Cloud Bongos LLC",
+  "origin": "Cloud Bongos (cloudbongos.com)",
+  "license": "AGPL-3.0",
+  "maintainer": "Cloud Bongos maintainers",
+  "default": false,
+  "maintenance": {
+    "status": "maintained"
+  },
+  "migrations": true,
+  "contributes": {
+    "routes": [
+      "ai-studio"
+    ]
+  },
+  "provides": [],
+  "consumes": []
+}

package/modules/ai-studio/openrouter.js

@@ -0,0 +1,90 @@
+// modules/ai-studio/openrouter.js — the two OpenRouter calls a generation makes
+// (task 1004917, goal 1000136, ADR 0392): a Gemini REPLY to the artist's
+// submission, then IMAGES drawn from the prompt, the reply and the sketch.
+//
+// Why OpenRouter for both: one account, one key, and every response reports
+// what the call really cost (`usage.cost`, in dollars), which is exactly the
+// number the builder is billed on (cost x the multiplier). A call that does not
+// report its cost is treated as a failure, so the hold is released and nobody
+// is charged a guess.
+//
+// `fetch` is handed in, so tests never touch the network.
+
+'use strict';
+
+const ENDPOINT = 'https://openrouter.ai/api/v1/chat/completions';
+const REPLY_MODEL = 'google/gemini-2.5-pro';
+const IMAGE_MODEL = 'google/gemini-2.5-flash-image';
+const TIMEOUT_MS = 120000;
+
+class ProviderError extends Error {
+  constructor(code, message) { super(message); this.code = code; }
+}
+
+// The artist's files as chat content parts: images inline, PDFs as files.
+function fileParts(files) {
+  return (files || []).map((f) => (f.content_type === 'application/pdf'
+    ? { type: 'file', file: { filename: f.name || 'document.pdf', file_data: `data:application/pdf;base64,${f.base64}` } }
+    : { type: 'image_url', image_url: { url: `data:${f.content_type};base64,${f.base64}` } }));
+}
+
+async function post(fetchImpl, key, body) {
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), TIMEOUT_MS);
+  let res;
+  try {
+    res = await fetchImpl(ENDPOINT, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json', 'x-title': 'Cloud Bongos AI studio' },
+      body: JSON.stringify({ ...body, usage: { include: true } }),
+      signal: ctl.signal,
+    });
+  } catch (err) {
+    throw new ProviderError(err.name === 'AbortError' ? 'provider_timeout' : 'provider_unreachable', 'The AI provider could not be reached.');
+  } finally {
+    clearTimeout(timer);
+  }
+  let json = null;
+  try { json = await res.json(); } catch (_) { /* fall through */ }
+  if (!res.ok || !json || json.error) {
+    throw new ProviderError('provider_error', `The AI provider refused the request (HTTP ${res.status}).`);
+  }
+  const cost = json.usage && Number(json.usage.cost);
+  if (!Number.isFinite(cost) || cost < 0) throw new ProviderError('provider_cost_unknown', 'The AI provider did not report what the call cost.');
+  const msg = (json.choices && json.choices[0] && json.choices[0].message) || {};
+  return { message: msg, costMicro: Math.ceil(cost * 1000000) };
+}
+
+// Gemini's reply to the submission. Returns { text, costMicro }.
+async function reply({ fetchImpl, key, system, prompt, files }) {
+  const out = await post(fetchImpl, key, {
+    model: REPLY_MODEL,
+    messages: [
+      { role: 'system', content: system },
+      { role: 'user', content: [{ type: 'text', text: prompt }, ...fileParts(files)] },
+    ],
+  });
+  const text = typeof out.message.content === 'string' ? out.message.content.trim() : '';
+  if (!text) throw new ProviderError('provider_empty', 'The AI provider returned no reply.');
+  return { text, costMicro: out.costMicro };
+}
+
+// Images drawn from the brief. Returns { images: [{ content_type, base64 }], costMicro }.
+async function images({ fetchImpl, key, system, brief, files }) {
+  const out = await post(fetchImpl, key, {
+    model: IMAGE_MODEL,
+    modalities: ['image', 'text'],
+    messages: [
+      { role: 'system', content: system },
+      { role: 'user', content: [{ type: 'text', text: brief }, ...fileParts((files || []).filter((f) => f.content_type !== 'application/pdf'))] },
+    ],
+  });
+  const list = (out.message.images || [])
+    .map((i) => /^data:(image\/(?:png|jpeg|webp));base64,(.+)$/.exec((i.image_url && i.image_url.url) || ''))
+    .filter(Boolean)
+    .map((m) => ({ content_type: m[1], base64: m[2] }));
+  if (!list.length) throw new ProviderError('provider_no_images', 'The AI provider returned no images.');
+  return { images: list, costMicro: out.costMicro };
+}
+
+module.exports = { ENDPOINT, ProviderError, reply, images };

package/modules/ai-studio/payments.js

@@ -0,0 +1,105 @@
+// modules/ai-studio/payments.js — the payments port: where a builder's AI
+// balance actually lives (task 1004920, goal 1000136, ADR 0392 decisions 2 and 7).
+//
+// Bongos holds no user money (ADR 0385). The balance is the PROCESSOR's; this
+// port is how we read it and instruct holds against it. Two backends:
+//
+//   'none'  (the default)  payments are not set up: no balance, no top-up, and a
+//                          paid generation is refused. A builder's own key still works.
+//   'fake'  (test mode)    an in-memory stand-in for the processor, chosen only by
+//                          AI_STUDIO_PAYMENTS=fake. Deterministic, so tests and the
+//                          hall preview can exercise every path with no card.
+//
+// A real processor adapter joins this table once the owner supplies its keys in
+// Settings; nothing outside this file changes when it does.
+//
+// Every amount is integer micro-dollars (pricing.js).
+
+'use strict';
+
+const crypto = require('node:crypto');
+
+// ---- the 'fake' backend -------------------------------------------------------
+
+function createFakeBackend() {
+  const accounts = new Map(); // builderId -> { available, held }
+  const holds = new Map();    // holdId -> { builderId, amount, state }
+  const acct = (id) => {
+    const k = String(id);
+    if (!accounts.has(k)) accounts.set(k, { available: 0, held: 0 });
+    return accounts.get(k);
+  };
+  const ref = (p) => `fake_${p}_${crypto.randomBytes(6).toString('hex')}`;
+
+  return {
+    name: 'fake',
+    testMode: true,
+    async balance(builderId) {
+      const a = acct(builderId);
+      return { available_micro: a.available, held_micro: a.held };
+    },
+    // A card payment of chargeMicro that credits creditedMicro to the balance.
+    async topUp(builderId, { chargeMicro, creditedMicro }) {
+      if (!(chargeMicro >= creditedMicro)) throw new Error('a top-up charge must cover what it credits');
+      acct(builderId).available += creditedMicro;
+      return { ref: ref('pay') };
+    },
+    async hold(builderId, amountMicro) {
+      const a = acct(builderId);
+      if (a.available < amountMicro) return { ok: false, reason: 'insufficient_funds', available_micro: a.available };
+      a.available -= amountMicro;
+      a.held += amountMicro;
+      const holdId = ref('hold');
+      holds.set(holdId, { builderId: String(builderId), amount: amountMicro, state: 'held' });
+      return { ok: true, holdId };
+    },
+    // Take amountMicro (at most the hold) and return the rest to the balance.
+    async capture(holdId, amountMicro) {
+      const h = holds.get(holdId);
+      if (!h || h.state !== 'held') throw new Error('no open hold');
+      if (amountMicro > h.amount) throw new Error('cannot capture more than was held');
+      const a = acct(h.builderId);
+      a.held -= h.amount;
+      a.available += h.amount - amountMicro;
+      h.state = 'captured';
+      return { captured_micro: amountMicro, released_micro: h.amount - amountMicro };
+    },
+    async release(holdId) {
+      const h = holds.get(holdId);
+      if (!h || h.state !== 'held') return { released_micro: 0 };
+      const a = acct(h.builderId);
+      a.held -= h.amount;
+      a.available += h.amount;
+      h.state = 'released';
+      return { released_micro: h.amount };
+    },
+  };
+}
+
+// ---- the 'none' backend -------------------------------------------------------
+
+const NONE = Object.freeze({
+  name: 'none',
+  testMode: false,
+  async balance() { return null; },
+  async topUp() { throw Object.assign(new Error('payments are not set up'), { code: 'payments_not_configured' }); },
+  async hold() { return { ok: false, reason: 'payments_not_configured' }; },
+  async capture() { throw new Error('payments are not set up'); },
+  async release() { return { released_micro: 0 }; },
+});
+
+let current = null;
+
+// The backend this instance runs on. AI_STUDIO_PAYMENTS names it; anything
+// unrecognised is 'none', so a typo never opens a free balance.
+function backend() {
+  if (current) return current;
+  const want = String(process.env.AI_STUDIO_PAYMENTS || '').trim().toLowerCase();
+  current = want === 'fake' ? createFakeBackend() : NONE;
+  return current;
+}
+
+// Tests swap in a fresh backend.
+function _setBackend(b) { current = b; }
+
+module.exports = { backend, createFakeBackend, NONE, _setBackend };

package/modules/ai-studio/pricing.js

@@ -0,0 +1,92 @@
+// modules/ai-studio/pricing.js — what an AI generation costs a builder, and what
+// a top-up charges their card (task 1004920, goal 1000136, ADR 0392).
+//
+// Every amount is an integer number of MICRO-DOLLARS (millionths of a dollar):
+// a generation can cost a fraction of a cent, and floats lose money in rounding.
+// The three numbers that set prices are named here and spelled nowhere else:
+//
+//   AI_PRICE_MULTIPLIER    provider cost x this = what the builder pays (owner,
+//                          2026-10-28: 1.08, an 8% markup on every call's real cost)
+//   PROCESSOR_PERCENT_BPS  the card processor's percentage fee, in basis points
+//   PROCESSOR_FIXED_MICRO  the card processor's fixed fee per payment
+//
+// The processor's fee is never taken out of the markup: a top-up is grossed up
+// so the balance the builder asked for arrives whole (ADR 0392 decision 4).
+//
+// Pure: no DB, no network.
+
+'use strict';
+
+const MICRO_PER_USD = 1000000;
+const MICRO_PER_CENT = 10000;
+
+const AI_PRICE_MULTIPLIER = 1.08;
+const PROCESSOR_PERCENT_BPS = 290;      // 2.9%
+const PROCESSOR_FIXED_MICRO = 300000;   // $0.30
+
+// Smallest and largest top-up a builder may ask for, so the fixed fee never
+// dwarfs the balance and a typo cannot charge a fortune.
+const MIN_TOPUP_MICRO = 5 * MICRO_PER_USD;
+const MAX_TOPUP_MICRO = 500 * MICRO_PER_USD;
+
+// The multiplier as an exact integer ratio (1.08 -> 10800 / 10000), so the
+// arithmetic below never multiplies money by a float.
+const MULTIPLIER_BPS = Math.round(AI_PRICE_MULTIPLIER * 10000);
+
+function isMicro(n) { return Number.isSafeInteger(n) && n >= 0; }
+
+// What a call that cost the provider `costMicro` costs the builder: the price,
+// split into the provider's cost and our markup. Rounded UP to the micro-dollar,
+// so the markup is never shaved below the multiplier.
+function priceFor(costMicro) {
+  if (!isMicro(costMicro)) throw new TypeError('costMicro must be a non-negative integer');
+  const price = Math.ceil((costMicro * MULTIPLIER_BPS) / 10000);
+  return { provider_cost_micro: costMicro, markup_micro: price - costMicro, price_micro: price };
+}
+
+// The processor's fee on a card payment of `grossCents` (whole cents, as a card
+// is charged), rounded to the cent the way processors round it.
+function processorFeeCents(grossCents) {
+  return Math.round((grossCents * PROCESSOR_PERCENT_BPS) / 10000) + PROCESSOR_FIXED_MICRO / MICRO_PER_CENT;
+}
+
+// What to charge a card so that, after the processor's fee, `netMicro` reaches
+// the builder's balance. Returns the charge, the fee and the credited amount
+// (the net, rounded up to a whole cent). The smallest such charge is found by
+// solving, then stepping a cent at a time past any rounding edge.
+function topUpCharge(netMicro) {
+  if (!isMicro(netMicro)) throw new TypeError('netMicro must be a non-negative integer');
+  if (netMicro < MIN_TOPUP_MICRO) throw new RangeError(`a top-up is at least $${MIN_TOPUP_MICRO / MICRO_PER_USD}`);
+  if (netMicro > MAX_TOPUP_MICRO) throw new RangeError(`a top-up is at most $${MAX_TOPUP_MICRO / MICRO_PER_USD}`);
+  const netCents = Math.ceil(netMicro / MICRO_PER_CENT);
+  const fixedCents = PROCESSOR_FIXED_MICRO / MICRO_PER_CENT;
+  let gross = Math.ceil(((netCents + fixedCents) * 10000) / (10000 - PROCESSOR_PERCENT_BPS));
+  while (gross - processorFeeCents(gross) < netCents) gross += 1;
+  while ((gross - 1) - processorFeeCents(gross - 1) >= netCents) gross -= 1;
+  return {
+    charge_micro: gross * MICRO_PER_CENT,
+    processor_fee_micro: processorFeeCents(gross) * MICRO_PER_CENT,
+    credited_micro: netCents * MICRO_PER_CENT,
+  };
+}
+
+// "$0.0432" for a sub-cent amount, "$12.50" otherwise: a builder sees what a
+// generation really cost, not a rounded zero.
+function formatUsd(micro) {
+  const usd = micro / MICRO_PER_USD;
+  if (micro !== 0 && Math.abs(micro) < MICRO_PER_CENT) return `$${usd.toFixed(4)}`;
+  return `$${usd.toFixed(2)}`;
+}
+
+module.exports = {
+  AI_PRICE_MULTIPLIER,
+  PROCESSOR_PERCENT_BPS,
+  PROCESSOR_FIXED_MICRO,
+  MIN_TOPUP_MICRO,
+  MAX_TOPUP_MICRO,
+  MICRO_PER_USD,
+  priceFor,
+  processorFeeCents,
+  topUpCharge,
+  formatUsd,
+};

package/modules/ai-studio/routes/ai-studio.js

@@ -0,0 +1,252 @@
+// modules/ai-studio/routes/ai-studio.js — the AI studio's HTTP surface (goal
+// 1000136, ADR 0392).
+//
+//   GET    /ai-studio/status            is the module on
+//   GET    /ai-studio/keys              my provider keys: set or not, last four, when
+//   PUT    /ai-studio/keys/:provider    save or replace my key   { key }
+//   DELETE /ai-studio/keys/:provider    remove my key
+//   GET    /ai-studio/balance           my balance (read from the processor) + my recent ledger
+//   GET    /ai-studio/topup/quote       what a top-up would charge the card  ?amount_usd=
+//   POST   /ai-studio/topup             add to my balance           { amount_usd }
+//   POST   /ai-studio/uploads           upload one sketch / image / PDF  { name, content_type, data }
+//   POST   /ai-studio/requests          send a request on my uploads     { prompt, file_ids }
+//   GET    /ai-studio/requests          my recent requests
+//   GET    /ai-studio/requests/:id      one request: reply, images, price
+//   GET    /ai-studio/files/:id         one of my files (upload or output)
+//
+// A request answers 202 at once and runs in the background; the page polls
+// GET /ai-studio/requests/:id until it is done, failed or refused.
+//
+// rank: builder — every route needs a signed-in builder, and a builder only
+// ever touches their own keys. A key arrives here only from the Settings page;
+// no route returns it, and no log line carries it or the request body.
+
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const K = require('../keys');
+const db = require('../db');
+const P = require('../pricing');
+const payments = require('../payments');
+const S = require('../studio');
+const openrouter = require('../openrouter');
+const gemini = require('../gemini');
+const { runOnOurKey, runOnOwnKey } = require('../generate');
+const { projectContext } = require('../context');
+
+const log = api.logger('ai-studio');
+
+const ID_RE = /^\d{1,18}$/;
+const FILE_URL_PREFIX = '/api/bongos/ai-studio/files/';
+const CLIENTS = { openrouter, gemini };
+
+// Runs one request in the background, on the key `choice` names. Our key is
+// the server's own OPENROUTER_API_KEY; without it a request is refused with a
+// pointer to Settings. A builder's own key is decrypted here, inside the run,
+// and handed only to the provider call: it is never logged or stored again.
+function runInBackground(request, choice) {
+  (async () => {
+    const files = (await db.requestUploads(request.id)).map(S.forProvider);
+    const context = await projectContext();
+    if (choice.source === 'own') {
+      let key;
+      try { key = api.secretBox.decrypt(await db.getKeyEnc(request.builder_id, choice.provider)); } catch (_) { key = null; }
+      if (!key) {
+        await db.finishRequest(request.id, { status: 'failed', error: 'Your saved key could not be read. Enter it again in Settings. Nothing was charged.' });
+        return;
+      }
+      await runOnOwnKey(request, files, { db, providers: CLIENTS[choice.provider], fetchImpl: fetch, key, provider: choice.provider, context, log });
+      return;
+    }
+    await runOnOurKey(request, files, {
+      db, payments: payments.backend(), providers: openrouter, fetchImpl: fetch,
+      ourKey: process.env.OPENROUTER_API_KEY || '', context, log,
+    });
+  })().catch((err) => {
+    log.error({ request_id: request.id, err: err.message }, 'ai-studio: request run crashed');
+    db.finishRequest(request.id, { status: 'failed', error: 'The generation could not run. You were not charged.' }).catch(() => {});
+  });
+}
+
+module.exports = function buildAiStudioRouter() {
+  const router = express.Router();
+
+  router.get('/ai-studio/status', api.requireBuilder, api.asyncHandler('GET /ai-studio/status', async (req, res) => {
+    res.json({ ok: true, module: 'ai-studio' });
+  }));
+
+  router.get('/ai-studio/keys', api.requireBuilder, api.asyncHandler('GET /ai-studio/keys', async (req, res) => {
+    const rows = await db.listKeyMeta(req.builder.id);
+    res.json({ storage_configured: api.secretBox.isConfigured(), keys: K.listPublic(rows) });
+  }));
+
+  router.put('/ai-studio/keys/:provider', api.requireBuilder, api.asyncHandler('PUT /ai-studio/keys/:provider', async (req, res) => {
+    const { provider } = req.params;
+    if (api.validateOrRespond(req, res, { key: { required: true, type: 'string', maxLength: K.MAX_KEY } })) return;
+    if (!K.isProvider(provider)) return res.fail('unknown_provider', { status: 404, message: 'No such AI provider.' });
+    if (!api.secretBox.isConfigured()) {
+      return res.fail('storage_not_configured', { status: 409, message: 'Key storage is not set up on this project yet.' });
+    }
+    const cleaned = K.cleanKey(req.body && req.body.key);
+    if (cleaned.error) return res.fail(cleaned.error, { status: 400, message: 'That does not look like a key. Paste the whole key, with no spaces.' });
+    const row = await db.setKey(req.builder.id, provider, api.secretBox.encrypt(cleaned.key), K.last4(cleaned.key));
+    log.info({ builder_id: req.builder.id, provider }, 'provider key saved');
+    res.json({ key: K.publicKey(provider, row) });
+  }));
+
+  router.delete('/ai-studio/keys/:provider', api.requireBuilder, api.asyncHandler('DELETE /ai-studio/keys/:provider', async (req, res) => {
+    const { provider } = req.params;
+    if (!K.isProvider(provider)) return res.fail('unknown_provider', { status: 404, message: 'No such AI provider.' });
+    const removed = await db.clearKey(req.builder.id, provider);
+    log.info({ builder_id: req.builder.id, provider, removed }, 'provider key removed');
+    res.json({ key: K.publicKey(provider, null), removed });
+  }));
+
+  router.get('/ai-studio/balance', api.requireBuilder, api.asyncHandler('GET /ai-studio/balance', async (req, res) => {
+    const b = payments.backend();
+    const [balance, ledger] = await Promise.all([b.balance(req.builder.id), db.recentLedger(req.builder.id, { limit: 50 })]);
+    res.json({
+      payments: b.name,
+      test_mode: !!b.testMode,
+      price_multiplier: P.AI_PRICE_MULTIPLIER,
+      // What one generation may cost, so the Studio can say how much is set
+      // aside before a run without spelling the number itself (task 1004921).
+      max_cost_micro: S.MAX_COST_MICRO,
+      balance,
+      ledger: ledger.map(publicLedgerRow),
+    });
+  }));
+
+  // What a top-up of amount_usd would charge the card, before anything is paid
+  // (task 1004921): the Studio shows "your card is charged $20.91" from this, so
+  // the processor's fee stays spelled only in pricing.js. Writes nothing.
+  router.get('/ai-studio/topup/quote', api.requireBuilder, api.asyncHandler('GET /ai-studio/topup/quote', async (req, res) => {
+    const raw = String(req.query.amount_usd || '');
+    if (!/^\d{1,4}(\.\d{1,2})?$/.test(raw)) {
+      return res.fail('bad_amount', { status: 400, message: `Top up between ${P.MIN_TOPUP_MICRO / P.MICRO_PER_USD} and ${P.MAX_TOPUP_MICRO / P.MICRO_PER_USD}.` });
+    }
+    const usd = Number(raw);
+    let quote;
+    try { quote = P.topUpCharge(Math.round(usd * P.MICRO_PER_USD)); } catch (err) {
+      return res.fail('bad_amount', { status: 400, message: `Top up between ${P.MIN_TOPUP_MICRO / P.MICRO_PER_USD} and ${P.MAX_TOPUP_MICRO / P.MICRO_PER_USD}.` });
+    }
+    res.json({ quote, min_micro: P.MIN_TOPUP_MICRO, max_micro: P.MAX_TOPUP_MICRO });
+  }));
+
+  // Top up the processor-held balance. The card is charged enough that the
+  // amount asked for arrives whole after the processor's fee (ADR 0392 d.4).
+  router.post('/ai-studio/topup', api.requireBuilder, api.asyncHandler('POST /ai-studio/topup', async (req, res) => {
+    if (api.validateOrRespond(req, res, { amount_usd: { required: true, type: 'number' } })) return;
+    const b = payments.backend();
+    if (b.name === 'none') return res.fail('payments_not_configured', { status: 409, message: 'Paying for generations is not set up here yet.' });
+    let quote;
+    try { quote = P.topUpCharge(Math.round(req.body.amount_usd * P.MICRO_PER_USD)); } catch (err) {
+      return res.fail('bad_amount', { status: 400, message: `Top up between ${P.MIN_TOPUP_MICRO / P.MICRO_PER_USD} and ${P.MAX_TOPUP_MICRO / P.MICRO_PER_USD}.` });
+    }
+    const paid = await b.topUp(req.builder.id, { chargeMicro: quote.charge_micro, creditedMicro: quote.credited_micro });
+    await db.appendLedger({ builderId: req.builder.id, kind: 'topup', amountMicro: quote.credited_micro, processorFeeMicro: quote.processor_fee_micro, backend: b.name, ref: paid.ref, note: `card charged ${P.formatUsd(quote.charge_micro)}` });
+    log.info({ builder_id: req.builder.id, credited_micro: quote.credited_micro, backend: b.name }, 'ai balance topped up');
+    res.status(201).json({ topup: quote, balance: await b.balance(req.builder.id) });
+  }));
+
+  // One file per call, so a request body stays small; the global 64 KB parser
+  // skips this path (src/bongos/routes.js) and this parser takes it.
+  router.post('/ai-studio/uploads', api.requireBuilder, express.json({ limit: S.UPLOAD_BODY_LIMIT }), api.asyncHandler('POST /ai-studio/uploads', async (req, res) => {
+    if (api.validateOrRespond(req, res, {
+      content_type: { required: true, type: 'string', maxLength: 40 },
+      data: { required: true, type: 'string', maxLength: 12 * 1024 * 1024 },
+      name: { type: 'string', maxLength: 400 },
+    })) return;
+    const checked = S.checkFile(req.body);
+    if (checked.error) return res.fail(checked.error, { status: 400, message: S.MESSAGES[checked.error] });
+    const row = await db.addUpload(req.builder.id, checked.file);
+    res.status(201).json({ file: publicFile(row) });
+  }));
+
+  router.post('/ai-studio/requests', api.requireBuilder, api.asyncHandler('POST /ai-studio/requests', async (req, res) => {
+    if (api.validateOrRespond(req, res, {
+      prompt: { required: true, type: 'string', maxLength: S.MAX_PROMPT + 200 },
+      file_ids: { required: true, type: 'array', maxItems: S.MAX_FILES },
+      pay_with: { type: 'string', enum: ['own', 'ours'] },
+    })) return;
+    const checked = S.checkRequest(req.body);
+    if (checked.error) return res.fail(checked.error, { status: 400, message: S.MESSAGES[checked.error] });
+    const stored = (await db.listKeyMeta(req.builder.id)).map((k) => k.provider);
+    const choice = K.chooseKey(stored, req.body.pay_with);
+    if (choice.error) return res.fail(choice.error, { status: 409, message: 'You have no key of your own saved. Add one in Settings, or pay with your balance.' });
+    if (await db.countActiveRequests(req.builder.id) >= S.MAX_ACTIVE_REQUESTS) {
+      return res.fail('too_many_running', { status: 429, message: `You have ${S.MAX_ACTIVE_REQUESTS} requests running already. Wait for one to finish.` });
+    }
+    const request = await db.createRequest(req.builder.id, checked.prompt, checked.fileIds);
+    if (!request) return res.fail('file_not_found', { status: 404, message: 'One of those files is not yours, or was already sent with another request.' });
+    if (Number(request.attached) !== checked.fileIds.length) {
+      await db.finishRequest(request.id, { status: 'refused', error: 'One of those files was sent with another request at the same moment.' });
+      return res.fail('file_not_found', { status: 409, message: 'One of those files was already sent with another request.' });
+    }
+    log.info({ builder_id: req.builder.id, request_id: request.id, files: checked.fileIds.length, key_source: choice.source }, 'ai request queued');
+    runInBackground(request, choice);
+    res.status(202).json({ request: publicRequest({ ...request, files: [] }) });
+  }));
+
+  router.get('/ai-studio/requests', api.requireBuilder, api.asyncHandler('GET /ai-studio/requests', async (req, res) => {
+    const rows = await db.listRequests(req.builder.id, { limit: 30 });
+    res.json({ requests: rows.map((r) => publicRequest(r)) });
+  }));
+
+  router.get('/ai-studio/requests/:id', api.requireBuilder, api.asyncHandler('GET /ai-studio/requests/:id', async (req, res) => {
+    const id = String(req.params.id || '');
+    if (!ID_RE.test(id)) return res.fail('invalid_request_id', 400);
+    const row = await db.getRequest(req.builder.id, id);
+    if (!row) return res.fail('request_not_found', 404);
+    res.json({ request: publicRequest(row) });
+  }));
+
+  router.get('/ai-studio/files/:id', api.requireBuilder, api.asyncHandler('GET /ai-studio/files/:id', async (req, res) => {
+    const id = String(req.params.id || '');
+    if (!ID_RE.test(id)) return res.fail('invalid_file_id', 400);
+    const file = await db.getFile(req.builder.id, id);
+    if (!file) return res.fail('file_not_found', 404);
+    res.set('Content-Type', file.content_type);
+    res.set('X-Content-Type-Options', 'nosniff');
+    res.set('Content-Security-Policy', "default-src 'none'");
+    // Images show in the page; anything else (a PDF) downloads, so a document
+    // an artist uploaded never renders inside the hall's own origin.
+    const disposition = file.content_type.startsWith('image/') ? 'inline' : 'attachment';
+    res.set('Content-Disposition', `${disposition}; filename="${file.name}"`);
+    res.set('Cache-Control', 'private, max-age=3600');
+    res.send(file.bytes);
+  }));
+
+  return router;
+};
+
+function publicFile(f) {
+  return {
+    id: String(f.id), role: f.role, name: f.name, content_type: f.content_type,
+    size_bytes: Number(f.size_bytes) || 0, url: FILE_URL_PREFIX + f.id,
+  };
+}
+
+// The request a builder sees: its status, the reply, the files, and the price
+// with the provider's cost and our markup apart.
+function publicRequest(r) {
+  const n = (v) => (v === null || v === undefined ? null : Number(v));
+  return {
+    id: String(r.id), prompt: r.prompt, status: r.status, key_source: r.key_source,
+    reply_md: r.reply_md || null, error: r.error || null,
+    provider_cost_micro: n(r.provider_cost_micro), markup_micro: n(r.markup_micro), price_micro: n(r.price_micro),
+    created_at: r.created_at, finished_at: r.finished_at || null,
+    files: (r.files || []).map(publicFile),
+  };
+}
+
+// The ledger row a builder sees: every amount apart, nothing internal (no ref).
+function publicLedgerRow(r) {
+  return {
+    id: String(r.id), kind: r.kind, request_id: r.request_id,
+    amount_micro: Number(r.amount_micro), provider_cost_micro: Number(r.provider_cost_micro),
+    markup_micro: Number(r.markup_micro), processor_fee_micro: Number(r.processor_fee_micro),
+    backend: r.backend, note: r.note, created_at: r.created_at,
+  };
+}