@bongos/core 1.25.11 → 1.25.12

package/tests/front_door_guide.mjs

@@ -0,0 +1,410 @@
+// tests/front_door_guide.mjs — the start-a-project guide's server (task 1005272): a
+// signed-out visitor starts a chat, talks, and every wall holds — the message cap, the
+// length limit, the per-visitor spend cap, the daily and monthly budget cut-off to the
+// form, the missing-key fallback, a refused reply, and a scripted abuse run.
+//
+// Drives the REAL router over an in-memory db and a mocked Claude client, so it needs no
+// Postgres, no network and no key, and spends no money. Settings come from the
+// environment, re-read per request, so each test sets the knobs it is about.
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const db = require('../modules/front-door-guide/db.js');
+const claude = require('../modules/front-door-guide/claude.js');
+const G = require('../modules/front-door-guide/guide.js');
+
+const KEY = 'sk-ant-api03-TEST-ONLY-NOT-A-REAL-KEY-0123456789';
+const ENV = 'BONGOS_FRONT_DOOR_GUIDE_';
+
+// ---- an in-memory db with the same rules as the SQL ----------------------------------
+
+const convs = new Map();
+let callRows = [];
+let seq = 0;
+let baselineDay = 0;   // spend already on the books today, outside these tests
+let baselineMonth = 0;
+const copy = (c) => c && { ...c, messages: JSON.parse(JSON.stringify(c.messages)) };
+Object.assign(db, {
+  createConversation: async (tokenHash, visitorHash) => {
+    const c = { id: String(++seq), token_hash: tokenHash, visitor_hash: visitorHash, messages: [], visitor_messages: 0, spend_micro: 0, status: 'open', end_reason: null, created_at: new Date(Date.now() - 10_000).toISOString() };
+    convs.set(c.id, c);
+    return copy(c);
+  },
+  getConversation: async (id, tokenHash) => { const c = convs.get(String(id)); return c && c.token_hash === tokenHash ? copy(c) : null; },
+  siteSpendMicro: async (period) => callRows.reduce((s, r) => s + r.cost_micro, period === 'day' ? baselineDay : baselineMonth),
+  visitorUsage: async (visitorHash) => {
+    const mine = callRows.filter((r) => r.visitor_hash === visitorHash);
+    return { messages: mine.length, spendMicro: mine.reduce((s, r) => s + r.cost_micro, 0) };
+  },
+  recordTurn: async (convId, { messages, status, endReason }, call) => {
+    callRows.push({ conversation_id: String(convId), visitor_hash: call.visitorHash, cost_micro: call.costMicro, model: call.model, input_tokens: call.inputTokens, output_tokens: call.outputTokens, stop_reason: call.stopReason });
+    const c = convs.get(String(convId));
+    Object.assign(c, { messages, status, end_reason: endReason, visitor_messages: c.visitor_messages + 1, spend_micro: c.spend_micro + call.costMicro });
+    return copy(c);
+  },
+  endConversation: async (convId, reason) => Object.assign(convs.get(String(convId)), { status: 'ended', end_reason: reason }),
+});
+
+// ---- the mocked Claude client: records every request, answers from a script ----------
+
+let requests = [];
+let respond = null;
+let delayMs = 0;
+let clientKeys = [];
+const normalReply = () => ({
+  model: 'claude-opus-5-5', stop_reason: 'end_turn',
+  content: [{ type: 'thinking', thinking: '' }, { type: 'text', text: 'Sounds useful. Who will use it first?' }],
+  usage: { input_tokens: 800, output_tokens: 200 },
+});
+claude.createClient = (apiKey) => {
+  clientKeys.push(apiKey);
+  return { messages: { create: async (req) => {
+    requests.push(req);
+    if (delayMs) await new Promise((r) => setTimeout(r, delayMs));
+    return respond ? respond(req) : normalReply();
+  } } };
+};
+
+// ---- the real router over http ----------------------------------------------------------
+
+const express = require('express');
+const app = express();
+app.set('trust proxy', true); // so each test can be a different visitor via X-Forwarded-For
+app.use(express.json({ limit: '64kb' }));
+app.use('/api/bongos', require('../modules/front-door-guide/routes/front-door-guide.js')());
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const PORT = server.address().port;
+
+const UA = 'Mozilla/5.0 (test browser)';
+function call(method, path, { body, ip = '10.0.0.1', ua = UA, headers = {} } = {}) {
+  return new Promise((resolve, reject) => {
+    const data = body === undefined ? null : JSON.stringify(body);
+    const h = { 'content-type': 'application/json', 'x-forwarded-for': ip, ...headers };
+    if (ua) h['user-agent'] = ua;
+    const req = http.request({ host: '127.0.0.1', port: PORT, method, path: `/api/bongos${path}`, headers: h }, (res) => {
+      let buf = '';
+      res.on('data', (c) => { buf += c; });
+      res.on('end', () => resolve({ status: res.statusCode, body: buf ? JSON.parse(buf) : null, raw: buf }));
+    });
+    req.on('error', reject);
+    if (data) req.write(data);
+    req.end();
+  });
+}
+
+let ipSeq = 0;
+const freshIp = () => `10.1.${Math.floor(++ipSeq / 250)}.${ipSeq % 250}`;
+
+function setEnv(over = {}) {
+  for (const k of Object.keys(process.env)) if (k.startsWith(ENV)) delete process.env[k];
+  const all = {
+    ANTHROPIC_API_KEY: KEY, MIN_FIRST_MESSAGE_MS: '1', STARTS_PER_HOUR: '1000', MESSAGES_PER_MINUTE: '1000',
+    ...over,
+  };
+  for (const [k, v] of Object.entries(all)) if (v !== null) process.env[ENV + k] = String(v);
+}
+
+function reset(over) {
+  setEnv(over);
+  convs.clear(); callRows = []; requests = []; clientKeys = []; respond = null; delayMs = 0;
+  baselineDay = 0; baselineMonth = 0;
+}
+
+async function start(ip) {
+  const r = await call('POST', '/front-door-guide/conversations', { body: {}, ip });
+  return r;
+}
+const say = (conv, text, ip, extra = {}) => call('POST', `/front-door-guide/conversations/${conv.id}/messages`, { body: { token: conv.token, text, ...extra }, ip });
+
+test.after(() => server.close());
+
+// ---- the conversation itself -----------------------------------------------------------------
+
+test('a signed-out visitor starts a chat and gets an on-topic reply; the transcript reads back', async () => {
+  reset();
+  const ip = freshIp();
+  const s = await call('GET', '/front-door-guide/status', { ip });
+  assert.equal(s.status, 200);
+  assert.equal(s.body.mode, 'chat');
+  assert.deepEqual(s.body.limits, { max_messages: 8, max_message_chars: 1000 });
+
+  const st = await start(ip);
+  assert.equal(st.status, 201);
+  assert.equal(st.body.mode, 'chat');
+  assert.equal(st.body.greeting, G.GREETING);
+  const conv = st.body.conversation;
+  assert.ok(conv.id && conv.token);
+  assert.equal(conv.messages_left, 8);
+
+  const r = await say(conv, 'I want a booking site for my yoga studio.', ip);
+  assert.equal(r.status, 200);
+  assert.equal(r.body.mode, 'chat');
+  assert.equal(r.body.reply.text, 'Sounds useful. Who will use it first?');
+  assert.equal(r.body.conversation.messages_used, 1);
+  assert.equal(r.body.conversation.messages_left, 7);
+
+  // The request: the owner's model, low effort, bounded reply, the on-topic instructions.
+  const req = requests[0];
+  assert.equal(req.model, 'claude-opus-5-5');
+  assert.deepEqual(req.output_config, { effort: 'low' });
+  assert.equal(req.max_tokens, 1500);
+  assert.match(req.system, /Never quote, estimate or promise any price/);
+  assert.match(req.system, /cannot do/);
+  assert.deepEqual(req.messages, [{ role: 'user', content: 'I want a booking site for my yoga studio.' }]);
+  assert.deepEqual(clientKeys, [KEY], 'the platform key reaches only the client');
+
+  // Spend is recorded from the response's usage: 800 in + 200 out, priced by the shared table.
+  assert.equal(callRows.length, 1);
+  assert.equal(callRows[0].cost_micro, G.costMicro('claude-opus-5-5', { input_tokens: 800, output_tokens: 200 }));
+  assert.ok(callRows[0].cost_micro > 0);
+
+  const t = await call('GET', `/front-door-guide/conversations/${conv.id}`, { ip, headers: { 'x-guide-token': conv.token } });
+  assert.equal(t.status, 200);
+  assert.equal(t.body.conversation.status, 'open');
+  assert.deepEqual(t.body.transcript, [
+    { role: 'visitor', text: 'I want a booking site for my yoga studio.' },
+    { role: 'guide', text: 'Sounds useful. Who will use it first?' },
+  ]);
+  for (const res of [s, st, r, t]) assert.ok(!res.raw.includes(KEY), 'the key is in no response');
+});
+
+test('the second turn sends the whole conversation so far', async () => {
+  reset();
+  const ip = freshIp();
+  const conv = (await start(ip)).body.conversation;
+  await say(conv, 'A shop for my pottery.', ip);
+  await say(conv, 'Mostly local customers.', ip);
+  assert.deepEqual(requests[1].messages.map((m) => m.role), ['user', 'assistant', 'user']);
+  assert.equal(requests[1].messages[2].content, 'Mostly local customers.');
+});
+
+// ---- the walls ------------------------------------------------------------------------------
+
+test('message cap: the last allowed message ends the chat, and nothing more is sent', async () => {
+  reset({ MAX_MESSAGES: 3 });
+  const ip = freshIp();
+  const conv = (await start(ip)).body.conversation;
+  assert.equal((await say(conv, 'one', ip)).body.mode, 'chat');
+  assert.equal((await say(conv, 'two', ip)).body.mode, 'chat');
+  const third = await say(conv, 'three', ip);
+  assert.equal(third.body.mode, 'ended');
+  assert.equal(third.body.reason, 'message_cap');
+  assert.ok(third.body.reply.text, 'the last message still gets its reply');
+  assert.equal(third.body.conversation.messages_left, 0);
+
+  const fourth = await say(conv, 'four', ip);
+  assert.equal(fourth.status, 200);
+  assert.equal(fourth.body.mode, 'ended');
+  assert.equal(requests.length, 3, 'no call past the cap');
+
+  // A new chat does not reset the visitor's cap.
+  const again = await start(ip);
+  assert.equal(again.body.mode, 'form');
+  assert.equal(again.body.reason, 'visitor_limit');
+});
+
+test('length limit: one character over is refused before any call; exactly the limit is fine', async () => {
+  reset({ MAX_MESSAGE_CHARS: 40 });
+  const ip = freshIp();
+  const conv = (await start(ip)).body.conversation;
+  const over = await say(conv, 'x'.repeat(41), ip);
+  assert.equal(over.status, 400);
+  assert.equal(over.body.error, 'too_long');
+  assert.equal(over.body.max_message_chars, 40);
+  assert.equal(requests.length, 0);
+  assert.equal((await say(conv, 'x'.repeat(40), ip)).body.mode, 'chat');
+  assert.equal((await say(conv, '   ', ip)).body.error, 'empty');
+  assert.equal(requests.length, 1);
+});
+
+test('per-visitor spend cap: the visitor stops before passing it, and never passes it', async () => {
+  reset({ VISITOR_CAP_CENTS: 6 }); // 60,000 micro-dollars
+  const ip = freshIp();
+  const conv = (await start(ip)).body.conversation;
+  let last;
+  for (let i = 0; i < 8; i++) {
+    last = await say(conv, `message ${i}`, ip);
+    if (last.body.mode !== 'chat') break;
+  }
+  assert.equal(last.body.mode, 'ended');
+  assert.equal(last.body.reason, 'visitor_budget');
+  const spent = callRows.reduce((s, r) => s + r.cost_micro, 0);
+  assert.ok(spent <= 60_000, `spent ${spent} within the cap`);
+  assert.ok(callRows.length >= 1 && callRows.length < 8);
+  const after = await say(conv, 'one more', ip);
+  assert.equal(after.body.mode, 'ended');
+  assert.equal(requests.length, callRows.length, 'no call after the cap');
+});
+
+test('daily budget cut-off: the guide answers the form, never an error, and makes no call', async () => {
+  reset({ DAILY_BUDGET_CENTS: 200 });
+  const ip = freshIp();
+  const conv = (await start(ip)).body.conversation;
+  baselineDay = 2_000_000 - 1_000; // a tenth of a cent left today: less than one reply could cost
+  const r = await say(conv, 'Hello there', ip);
+  assert.equal(r.status, 200);
+  assert.deepEqual(r.body, G.formAnswer('daily_budget'));
+  assert.equal(requests.length, 0);
+  const s = await call('GET', '/front-door-guide/status', { ip });
+  assert.equal(s.body.mode, 'chat', 'status still offers the chat while a cent is left');
+  baselineDay = 2_000_000;
+  assert.equal((await call('GET', '/front-door-guide/status', { ip })).body.reason, 'daily_budget');
+  const st = await start(freshIp());
+  assert.equal(st.status, 200);
+  assert.equal(st.body.mode, 'form');
+  assert.equal(st.body.reason, 'daily_budget');
+});
+
+test('monthly budget cut-off: the form too', async () => {
+  reset({ MONTHLY_BUDGET_CENTS: 2500 });
+  baselineMonth = 25_000_000;
+  const st = await start(freshIp());
+  assert.deepEqual(st.body, G.formAnswer('monthly_budget'));
+});
+
+test('no key configured: every route answers the form, never an error, and no client is made', async () => {
+  reset({ ANTHROPIC_API_KEY: null });
+  const ip = freshIp();
+  const s = await call('GET', '/front-door-guide/status', { ip });
+  assert.equal(s.status, 200);
+  assert.equal(s.body.mode, 'form');
+  assert.equal(s.body.reason, 'no_key');
+  const st = await start(ip);
+  assert.equal(st.status, 200);
+  assert.deepEqual(st.body, G.formAnswer('no_key'));
+
+  // A chat started while the key was set, then the key removed: the form, not a 500.
+  setEnv();
+  const conv = (await start(ip)).body.conversation;
+  setEnv({ ANTHROPIC_API_KEY: null });
+  const r = await say(conv, 'hello', ip);
+  assert.equal(r.status, 200);
+  assert.equal(r.body.reason, 'no_key');
+  assert.equal(clientKeys.length, 0);
+});
+
+test('a refusal stop reason gets a graceful reply, and the refused words are not sent again', async () => {
+  reset();
+  const ip = freshIp();
+  const conv = (await start(ip)).body.conversation;
+  respond = () => ({ model: 'claude-opus-5-5', stop_reason: 'refusal', stop_details: { type: 'refusal', category: null }, content: [], usage: { input_tokens: 500, output_tokens: 3 } });
+  const r = await say(conv, 'something off topic', ip);
+  assert.equal(r.status, 200);
+  assert.equal(r.body.mode, 'chat');
+  assert.equal(r.body.declined, true);
+  assert.equal(r.body.reply.text, G.REFUSAL_REPLY);
+  assert.equal(callRows[0].stop_reason, 'refusal');
+  assert.ok(callRows[0].cost_micro > 0, 'a refused call is still recorded');
+
+  respond = null;
+  await say(conv, 'OK, a recipe website.', ip);
+  const sent = JSON.stringify(requests[1].messages);
+  assert.ok(!sent.includes('something off topic'));
+});
+
+test('a failed API call answers the form and records no spend', async () => {
+  reset();
+  const ip = freshIp();
+  const conv = (await start(ip)).body.conversation;
+  respond = () => { const e = new Error('overloaded'); e.status = 529; throw e; };
+  const r = await say(conv, 'hello', ip);
+  assert.equal(r.status, 200);
+  assert.deepEqual(r.body, G.formAnswer('unavailable'));
+  assert.equal(callRows.length, 0);
+});
+
+// ---- a scripted abuse run -------------------------------------------------------------------
+
+test('scripted abuse run: bots, stolen ids, floods and a budget stampede all hold', async () => {
+  reset({ DAILY_BUDGET_CENTS: 10, STARTS_PER_HOUR: 3, MESSAGES_PER_MINUTE: 4 });
+
+  // 1. The bot check: honeypot filled, no user agent, a first message faster than typing.
+  const botIp = freshIp();
+  assert.equal((await call('POST', '/front-door-guide/conversations', { body: { website: 'http://spam' }, ip: botIp })).body.reason, 'check_failed');
+  assert.equal((await call('POST', '/front-door-guide/conversations', { body: {}, ip: freshIp(), ua: null })).body.reason, 'check_failed');
+  const ip1 = freshIp();
+  const conv = (await start(ip1)).body.conversation;
+  assert.equal((await say(conv, 'hi', ip1, { website: 'x' })).body.reason, 'check_failed');
+  setEnv({ DAILY_BUDGET_CENTS: 10, STARTS_PER_HOUR: 3, MESSAGES_PER_MINUTE: 4, MIN_FIRST_MESSAGE_MS: 60_000 });
+  assert.equal((await say(conv, 'instant', ip1)).body.reason, 'check_failed');
+  setEnv({ DAILY_BUDGET_CENTS: 10, STARTS_PER_HOUR: 3, MESSAGES_PER_MINUTE: 4 });
+  assert.equal(requests.length, 0, 'no bot reached the API');
+
+  // 2. Someone else's chat: a wrong token or a made-up id is a 404; garbage is a 400.
+  assert.equal((await say({ id: conv.id, token: 'A'.repeat(32) }, 'hijack', freshIp())).status, 404);
+  assert.equal((await say({ id: '999999', token: conv.token }, 'hijack', freshIp())).status, 404);
+  assert.equal((await say({ id: 'abc', token: conv.token }, 'x', freshIp())).status, 400);
+  assert.equal((await call('GET', `/front-door-guide/conversations/${conv.id}`, { headers: { 'x-guide-token': 'B'.repeat(32) } })).status, 404);
+
+  // 3. Firing five messages at once: one call runs, the rest are told to wait.
+  delayMs = 60;
+  const burst = await Promise.all([0, 1, 2, 3].map((i) => say(conv, `parallel ${i}`, ip1)));
+  delayMs = 0;
+  const answered = burst.filter((b) => b.status === 200);
+  assert.equal(answered.length, 1, 'exactly one parallel message was answered');
+  assert.ok(burst.filter((b) => b.status === 429).every((b) => ['busy', 'rate_limited'].includes(b.body.error)));
+  assert.equal(requests.length, 1);
+
+  // 4. A message flood from one address hits the per-minute limit with Retry-After.
+  let flooded = null;
+  for (let i = 0; i < 6 && !flooded; i++) {
+    const r = await say(conv, `flood ${i}`, ip1);
+    if (r.status === 429 && r.body.error === 'rate_limited') flooded = r;
+  }
+  assert.ok(flooded, 'the per-minute limiter tripped');
+  assert.ok(flooded.body.retry_after_seconds >= 1);
+
+  // 5. A start flood from one address hits the per-hour limit.
+  const ip2 = freshIp();
+  const starts = [];
+  for (let i = 0; i < 5; i++) starts.push((await start(ip2)).status);
+  assert.deepEqual(starts.slice(0, 3), [201, 201, 201]);
+  assert.equal(starts[3], 429);
+
+  // 6. A stampede of fresh visitors cannot spend past the daily budget: once it is
+  //    near, everyone gets the form, and the books never pass ten cents.
+  let forms = 0;
+  for (let v = 0; v < 25; v++) {
+    const ip = freshIp();
+    const st = await start(ip);
+    if (st.body.mode === 'form') { forms++; continue; }
+    for (let m = 0; m < 3; m++) {
+      const r = await say(st.body.conversation, `visitor ${v} message ${m}`, ip);
+      if (r.body.mode === 'form') { forms++; break; }
+    }
+  }
+  const spent = callRows.reduce((s, r) => s + r.cost_micro, 0);
+  assert.ok(spent <= 100_000, `site spend ${spent} stays within the daily budget`);
+  assert.ok(forms > 0, 'the budget cut-off was reached and answered with the form');
+  const s = await call('GET', '/front-door-guide/status', { ip: freshIp() });
+  assert.equal(s.status, 200);
+});
+
+// ---- pure pieces --------------------------------------------------------------------------
+
+test('settings: env knobs override, bad values fall back to the defaults, money in micro-dollars', () => {
+  const { readSettings, DEFAULTS } = require('../modules/front-door-guide/settings.js');
+  const s = readSettings({ resolve: (k) => ({ FRONT_DOOR_GUIDE_MAX_MESSAGES: '3', FRONT_DOOR_GUIDE_DAILY_BUDGET_CENTS: '-5', FRONT_DOOR_GUIDE_MODEL: 'gpt-4', FRONT_DOOR_GUIDE_EFFORT: 'max' })[k] });
+  assert.equal(s.maxMessages, 3);
+  assert.equal(s.dailyBudgetMicro, DEFAULTS.DAILY_BUDGET_CENTS * 10_000, 'a negative budget is not a budget');
+  assert.equal(s.model, 'claude-opus-5-5', 'only a Claude model id is accepted');
+  assert.equal(s.effort, 'max');
+  assert.equal(s.apiKey, null);
+  const d = readSettings({ resolve: () => undefined });
+  assert.equal(d.visitorCapMicro, 500_000);
+  assert.equal(d.monthlyBudgetMicro, 25_000_000);
+  assert.equal(d.maxMessageChars, 1000);
+});
+
+test('the reservation covers a full-length reply, so it is never below the recorded cost', () => {
+  const system = G.systemPrompt('Cloud Bongos');
+  const messages = [{ role: 'user', content: 'x'.repeat(1000) }];
+  const est = G.estimateMicro({ model: 'claude-opus-5-5', system, messages, maxReplyTokens: 1500 });
+  const real = G.costMicro('claude-opus-5-5', { input_tokens: Math.ceil((system.length + 1000) / 4), output_tokens: 1500 });
+  assert.ok(est >= real);
+});

package/tests/module_loader.mjs

@@ -278,7 +278,7 @@ test('the live tree discovers the extracted modules cleanly (BV1.R43/R48/R47/R49
   // That is precisely how the agents regression reached an open PR (task 1002485).
   loader._reset();
   const snap = loader.loaderSnapshot();
-  assert.deepEqual(snap.loaded, ['agents', 'ai-studio', 'autonomy', 'builder-settings', 'copy-desk', 'design-styles', 'discord', 'economy', 'government', 'grading', 'hall-ui', 'ideas', 'lifecycle', 'market-watch', 'memory', 'npm-release', 'onboarding', 'page-notes', 'pixel-art', 'platform-identity', 'provisioning', 'public-landing', 'raise', 'render-deploy', 'security', 'sessions', 'specialities', 'status-ui', 'ui-design']);
+  assert.deepEqual(snap.loaded, ['agents', 'ai-studio', 'autonomy', 'builder-settings', 'copy-desk', 'design-styles', 'discord', 'economy', 'front-door-guide', 'government', 'grading', 'hall-ui', 'ideas', 'lifecycle', 'market-watch', 'memory', 'npm-release', 'onboarding', 'page-notes', 'pixel-art', 'platform-identity', 'provisioning', 'public-landing', 'raise', 'render-deploy', 'security', 'sessions', 'specialities', 'status-ui', 'ui-design']);
   assert.deepEqual(snap.errors, []);
   assert.deepEqual(snap.skipped, []);
   loader._reset();