@bongos/core 1.23.22 → 1.24.1

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

@@ -1,15 +1,73 @@
-// modules/ai-studio/routes/ai-studio.js — the AI studio's HTTP surface (task
-// 1004916, goal 1000136, ADR 0392). A skeleton for now: later tasks add the
-// provider-key, balance, submit and result routes beside this one.
+// 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, and is a provider key stored
+//   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)
 //
-// rank: builder — every route needs a signed-in builder.
+// 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();
@@ -18,5 +76,177 @@ module.exports = function buildAiStudioRouter() {
     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,
+  };
+}

package/modules/ai-studio/studio.js

@@ -0,0 +1,121 @@
+// modules/ai-studio/studio.js — the pure half of a generation (task 1004917,
+// goal 1000136, ADR 0392 decision 9): checking what the artist uploaded, and
+// assembling the project context the AI is given on the SERVER, never from the
+// browser.
+//
+// Uploads follow the page-notes rules (PNG, JPG, GIF, WebP, the declared type
+// must match the file's own first bytes, SVG refused because it is executable),
+// plus PDF for a documentation set. Video is not accepted yet: one clip costs
+// more to send than a whole generation.
+
+'use strict';
+
+const MAX_FILES = 6;
+const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
+const MAX_PDF_BYTES = 8 * 1024 * 1024;
+const MAX_PROMPT = 4000;
+const MIN_PROMPT = 3;
+
+// The most one generation may cost the provider. The full price of this is held
+// before the calls run; the real cost is captured after.
+const MAX_COST_MICRO = 500000; // $0.50
+
+// How many requests one builder may have queued or running at once, so a burst
+// of clicks cannot pile up provider calls on any key.
+const MAX_ACTIVE_REQUESTS = 2;
+
+// How much of each context source the AI is given, so a long doc cannot crowd
+// out the artist's own prompt.
+const CONTEXT_BUDGET = { project: 4000, design: 6000 };
+
+const SIGNATURES = {
+  'image/png': (b) => b.length > 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47,
+  'image/jpeg': (b) => b.length > 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff,
+  'image/gif': (b) => b.length > 6 && b.slice(0, 6).toString('latin1').startsWith('GIF8'),
+  'image/webp': (b) => b.length > 12 && b.slice(0, 4).toString('latin1') === 'RIFF' && b.slice(8, 12).toString('latin1') === 'WEBP',
+  'application/pdf': (b) => b.length > 5 && b.slice(0, 5).toString('latin1') === '%PDF-',
+};
+
+// The base64 a PDF at the size cap encodes to, plus headroom: the upload
+// route's body parser limit.
+const UPLOAD_BODY_LIMIT = '12mb';
+
+// What each refusal says to the artist.
+const MESSAGES = {
+  bad_file: 'That file could not be read. Try saving it again.',
+  unsupported_type: 'Send a PNG, JPG, GIF or WebP image, or a PDF.',
+  file_too_large: 'That file is too big: images up to 4 MB, PDFs up to 8 MB.',
+  type_mismatch: 'That file is not the kind of file its name says it is.',
+  prompt_required: 'Say what you would like, in a few words at least.',
+  prompt_too_long: `Keep the request under ${MAX_PROMPT} characters.`,
+  file_required: 'Add a sketch or an image to work from.',
+  too_many_files: `Send up to ${MAX_FILES} files at a time.`,
+};
+
+// Checks one uploaded file ({ name, content_type, data } with data in base64).
+// Returns { file: { name, content_type, bytes } } or { error }.
+function checkFile(f) {
+  if (!f || typeof f !== 'object') return { error: 'bad_file' };
+  const type = String(f.content_type || '').toLowerCase();
+  if (!SIGNATURES[type]) return { error: 'unsupported_type' };
+  if (typeof f.data !== 'string' || !f.data) return { error: 'bad_file' };
+  const bytes = Buffer.from(f.data, 'base64');
+  const max = type === 'application/pdf' ? MAX_PDF_BYTES : MAX_IMAGE_BYTES;
+  if (!bytes.length) return { error: 'bad_file' };
+  if (bytes.length > max) return { error: 'file_too_large' };
+  if (!SIGNATURES[type](bytes)) return { error: 'type_mismatch' };
+  const name = String(f.name || 'upload').replace(/[^\w.\- ]+/g, '_').slice(0, 120) || 'upload';
+  return { file: { name, content_type: type, bytes } };
+}
+
+// Checks a request ({ prompt, file_ids }) once its files are uploaded.
+// Returns { prompt, fileIds } or { error }.
+function checkRequest(body) {
+  const prompt = typeof (body && body.prompt) === 'string' ? body.prompt.trim() : '';
+  if (prompt.length < MIN_PROMPT) return { error: 'prompt_required' };
+  if (prompt.length > MAX_PROMPT) return { error: 'prompt_too_long' };
+  const raw = Array.isArray(body.file_ids) ? body.file_ids : [];
+  if (!raw.length) return { error: 'file_required' };
+  if (raw.length > MAX_FILES) return { error: 'too_many_files' };
+  const fileIds = [...new Set(raw.map((x) => String(x)))];
+  if (!fileIds.every((x) => /^\d{1,18}$/.test(x))) return { error: 'bad_file' };
+  return { prompt, fileIds };
+}
+
+// A stored file as the provider calls want it.
+function forProvider(row) {
+  return { name: row.name, content_type: row.content_type, base64: Buffer.from(row.bytes).toString('base64') };
+}
+
+function clip(text, n) {
+  const s = String(text || '').trim();
+  return s.length > n ? `${s.slice(0, n)}\n[…cut for length]` : s;
+}
+
+// The system prompt both calls share: who the project is, how it looks, and
+// what the artist is asking for. Sources are read by the caller (so this stays
+// pure): branding, the project context doc, and DESIGN.md.
+function buildContext({ branding, projectDoc, designDoc }) {
+  const id = (branding && branding.identity) || {};
+  const palette = branding && branding.theme && branding.theme.colors ? JSON.stringify(branding.theme.colors).slice(0, 800) : '';
+  const parts = [
+    `You are the art director's assistant for ${id.productName || 'this project'}${id.worldName && id.worldName !== id.productName ? `, set in the world of ${id.worldName}` : ''}.`,
+    'An artist on the project has sent a sketch or reference images with a request. Answer as a thoughtful collaborator: say what you see, what works, and how to take it further, in plain words.',
+    'Keep everything you suggest consistent with the project as described below.',
+  ];
+  if (palette) parts.push(`## Brand colours\n${palette}`);
+  if (projectDoc) parts.push(`## The project\n${clip(projectDoc, CONTEXT_BUDGET.project)}`);
+  if (designDoc) parts.push(`## The design system\n${clip(designDoc, CONTEXT_BUDGET.design)}`);
+  return parts.join('\n\n');
+}
+
+// What the image model is asked to draw: the artist's words first, then the
+// reply's direction.
+function imageBrief(prompt, replyText) {
+  return `Create finished artwork for this request from the project's artist. Follow the attached sketch's composition.\n\nThe artist asked:\n${prompt}\n\nArt direction:\n${clip(replyText, 1500)}`;
+}
+
+module.exports = {
+  MAX_FILES, MAX_IMAGE_BYTES, MAX_PROMPT, MAX_COST_MICRO, MAX_ACTIVE_REQUESTS, CONTEXT_BUDGET, UPLOAD_BODY_LIMIT, MESSAGES,
+  checkFile, checkRequest, forProvider, buildContext, imageBrief,
+};