Events: AI use in tokens, not rand (for 2.3.0); contracts: token fields on the AI status

Site settings → AI, the usage tables and the 80% email show input/output
tokens and the percentage; the rand amounts from the Hub are dropped on
arrival. AiCall stores each call's tokens (migration ai_tokens). v2
/ai/status and /ai/usage carry tokens instead of cents. Needs Hub 2.0.1
for the token figures; older Hubs show the percentage only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-17 10:59:36 +02:00
co-authored by Claude Opus 5.5
parent e8853cf0c8
commit 38ebce24ab
17 changed files with 725 additions and 169 deletions
+61 -21
View File
@@ -1,7 +1,8 @@
/**
* AI helpers (2.0, roadmap §15). The site never holds a Claude API key: every call goes through
* the Cross Events Hub (docs/hub-protocol.md §3b), which checks the licence's monthly cap in rand,
* calls Claude and meters the call. This module:
* the Cross Events Hub (docs/hub-protocol.md §3b), which checks the licence's monthly cap, calls
* Claude and meters the call. The site shows that use as tokens and a percentage (2.3.0); the cap's
* rand amount stays on the Hub. This module:
* - works out what the AI buttons do (`aiStatus`): hidden, working, or disabled until the
* allowance renews — from the licence token first, then the Hub (cached for a minute);
* - runs one helper call (`runHelper`), with this site's own switches per helper and an optional
@@ -32,8 +33,16 @@ const { logAdminAction } = require('../utils/adminAudit') as { logAdminAction(en
export const HELPERS = ['draft_event', 'summarise_report', 'draft_message', 'summarise_feedback', 'improve_text'] as const;
export type HelperName = (typeof HELPERS)[number];
/** What the Hub says (§3b). Cents are charged rand, with fractions. */
export type HubAiStatus = { enabled: boolean; capReached: boolean; capCents: number; usedCents: number; usedPercent: number; renewsOn: string | null };
/**
* What the Hub says (§3b), as the site keeps it. The Hub also sends the allowance in rand
* (`capCents`, `usedCents`); the site drops those (2.3.0): people see tokens and a percentage,
* and only the Hub shows rand. The token fields are null from a Hub before 2.0.1.
*/
export type HubAiStatus = {
enabled: boolean; capReached: boolean; usedPercent: number; renewsOn: string | null;
usedInputTokens: number | null; usedOutputTokens: number | null;
capInputTokens: number | null; capOutputTokens: number | null;
};
/** What the buttons need: the Hub's answer, whether it could be reached, and this site's switches. */
export type AiStatus = HubAiStatus & { available: boolean; helpers: Record<HelperName, boolean> };
@@ -44,7 +53,28 @@ const STATUS_TTL_MS = 60 * 1000;
const CALL_TIMEOUT_MS = 90 * 1000;
const KEEP_CALLS_DAYS = 400;
const OFF: HubAiStatus = { enabled: false, capReached: false, capCents: 0, usedCents: 0, usedPercent: 0, renewsOn: null };
const OFF: HubAiStatus = { enabled: false, capReached: false, usedPercent: 0, renewsOn: null, usedInputTokens: null, usedOutputTokens: null, capInputTokens: null, capOutputTokens: null };
const tokens = (n: unknown): number | null => (typeof n === 'number' && Number.isFinite(n) && n >= 0 ? Math.round(n) : null);
/** The Hub's status without its rand amounts. */
function fromHub(v: Record<string, unknown>): HubAiStatus {
return {
enabled: v.enabled === true,
capReached: v.capReached === true,
usedPercent: typeof v.usedPercent === 'number' ? v.usedPercent : 0,
renewsOn: typeof v.renewsOn === 'string' ? v.renewsOn : null,
usedInputTokens: tokens(v.usedInputTokens), usedOutputTokens: tokens(v.usedOutputTokens),
capInputTokens: tokens(v.capInputTokens), capOutputTokens: tokens(v.capOutputTokens),
};
}
/** "1.2M", "450K", "800": tokens for people. */
export function tokenText(n: number): string {
if (n >= 1e6) return `${(n / 1e6).toFixed(n >= 1e7 ? 0 : 1).replace(/\.0$/, '')}M`;
if (n >= 1e3) return `${Math.round(n / 1e3)}K`;
return String(n);
}
// ─── This site's settings ─────────────────────────────────────────────────────
@@ -78,8 +108,8 @@ let cached: { at: number; value: HubAiStatus; available: boolean } | null = null
/** Keep what the Hub just said (every AI reply and error carries it). */
function remember(value: unknown, available = true): void {
const v = value as Partial<HubAiStatus> | null;
if (v && typeof v.enabled === 'boolean') cached = { at: Date.now(), value: { ...OFF, ...v } as HubAiStatus, available };
const v = value as Record<string, unknown> | null;
if (v && typeof v.enabled === 'boolean') cached = { at: Date.now(), value: fromHub(v), available };
}
export function clearAiStatusCache(): void {
@@ -185,7 +215,10 @@ async function warnAt80(status: HubAiStatus): Promise<void> {
if (!email.isSmtpConfigured()) return;
const admins = await prisma.user.findMany({ where: { role: 'admin', isActive: true }, select: { email: true } });
const when = renewsText(status.renewsOn);
const text = `This site has used ${status.usedPercent}% of this month's AI allowance (R${(status.usedCents / 100).toFixed(2)} of R${(status.capCents / 100).toFixed(2)}). The AI buttons stop working when it runs out, until it renews on ${when}. Site settings → AI shows who used it and for what.`;
const used = status.usedInputTokens != null && status.usedOutputTokens != null
? ` (${tokenText(status.usedInputTokens)} input and ${tokenText(status.usedOutputTokens)} output tokens)`
: '';
const text = `This site has used ${status.usedPercent}% of this month's AI allowance${used}. The AI buttons stop working when it runs out, until it renews on ${when}. Site settings → AI shows who used it and for what.`;
for (const a of admins) {
await email.sendMail({ to: a.email, subject: `AI allowance ${status.usedPercent}% used`, text, html: email.emailWrapper(`<p>${text}</p>`) })
.catch(e => console.warn('[ai] 80% warning email failed:', (e as Error).message));
@@ -210,9 +243,13 @@ export async function runHelper(helper: HelperName, userId: string, req: HelperR
let outcome = 'ok';
let chargedCents = 0;
let inputTokens = 0;
let outputTokens = 0;
try {
const reply = await hub.signedPost('/api/installs/ai/complete', { protocolVersion: hub.PROTOCOL_VERSION, helper, ...req }, { timeoutMs: CALL_TIMEOUT_MS });
chargedCents = Number(reply.chargedCents) || 0;
inputTokens = tokens(reply.usage?.inputTokens) ?? 0;
outputTokens = tokens(reply.usage?.outputTokens) ?? 0;
remember(reply.status);
await warnAt80(reply.status).catch(e => console.warn('[ai] 80% check failed:', (e as Error).message));
return { output: reply.output, status: { ...(cached?.value || OFF), available: true, helpers: status.helpers } };
@@ -223,7 +260,7 @@ export async function runHelper(helper: HelperName, userId: string, req: HelperR
if ((e as { code?: string }).code === 'HUB_UNREACHABLE') remember(cached?.value || { ...OFF, enabled: true }, false);
throw mapped.error;
} finally {
await prisma.aiCall.create({ data: { userId, helper, outcome, chargedCents } }).catch(err => console.warn('[ai] could not log the call:', (err as Error).message));
await prisma.aiCall.create({ data: { userId, helper, outcome, chargedCents, inputTokens, outputTokens } }).catch(err => console.warn('[ai] could not log the call:', (err as Error).message));
await pruneOldCalls();
}
}
@@ -234,27 +271,30 @@ export async function runHelper(helper: HelperName, userId: string, req: HelperR
export async function usageThisMonth(now = new Date()) {
const sast = new Date(now.getTime() + 2 * 3600 * 1000);
const from = new Date(Date.UTC(sast.getUTCFullYear(), sast.getUTCMonth(), 1) - 2 * 3600 * 1000);
const calls = await prisma.aiCall.findMany({ where: { createdAt: { gte: from } }, select: { userId: true, helper: true, outcome: true, chargedCents: true, createdAt: true } });
const add = (m: Map<string, { uses: number; chargedCents: number }>, key: string, cents: number) => {
const v = m.get(key) || { uses: 0, chargedCents: 0 };
const calls = await prisma.aiCall.findMany({ where: { createdAt: { gte: from } }, select: { userId: true, helper: true, outcome: true, inputTokens: true, outputTokens: true, createdAt: true } });
type Use = { uses: number; inputTokens: number; outputTokens: number };
const add = (m: Map<string, Use>, key: string, c: { inputTokens: number; outputTokens: number }) => {
const v = m.get(key) || { uses: 0, inputTokens: 0, outputTokens: 0 };
v.uses++;
v.chargedCents += cents;
v.inputTokens += c.inputTokens;
v.outputTokens += c.outputTokens;
m.set(key, v);
};
const byPerson = new Map<string, { uses: number; chargedCents: number }>();
const byHelper = new Map<string, { uses: number; chargedCents: number }>();
const byDay = new Map<string, { uses: number; chargedCents: number }>();
const byPerson = new Map<string, Use>();
const byHelper = new Map<string, Use>();
const byDay = new Map<string, Use>();
for (const c of calls) {
if (c.outcome === 'cap_reached' || c.outcome === 'unavailable') continue;
add(byPerson, c.userId || '', c.chargedCents);
add(byHelper, c.helper, c.chargedCents);
add(byDay, new Date(c.createdAt.getTime() + 2 * 3600 * 1000).toISOString().slice(0, 10), c.chargedCents);
add(byPerson, c.userId || '', c);
add(byHelper, c.helper, c);
add(byDay, new Date(c.createdAt.getTime() + 2 * 3600 * 1000).toISOString().slice(0, 10), c);
}
const people = await prisma.user.findMany({ where: { id: { in: [...byPerson.keys()].filter(Boolean) } }, select: { id: true, name: true } });
const names = new Map(people.map(p => [p.id, p.name]));
const most = (a: Use, b: Use) => (b.inputTokens + b.outputTokens) - (a.inputTokens + a.outputTokens) || b.uses - a.uses;
return {
people: [...byPerson.entries()].map(([id, v]) => ({ userId: id || null, name: id ? names.get(id) || 'Unknown' : 'Removed account', ...v })).sort((a, b) => b.chargedCents - a.chargedCents),
helpers: [...byHelper.entries()].map(([helper, v]) => ({ helper, ...v })).sort((a, b) => b.chargedCents - a.chargedCents),
people: [...byPerson.entries()].map(([id, v]) => ({ userId: id || null, name: id ? names.get(id) || 'Unknown' : 'Removed account', ...v })).sort(most),
helpers: [...byHelper.entries()].map(([helper, v]) => ({ helper, ...v })).sort(most),
days: [...byDay.entries()].map(([day, v]) => ({ day, ...v })).sort((a, b) => a.day.localeCompare(b.day)),
};
}
+6 -4
View File
@@ -21,9 +21,11 @@ const status = z.object({
enabled: z.boolean().describe('false: hide the AI buttons (the licence has no AI, or the site isn\'t connected to the Hub)'),
capReached: z.boolean().describe('true: show the buttons disabled until `renewsOn`'),
available: z.boolean().describe('false: the Hub couldn\'t be reached just now'),
capCents: z.number().describe('The monthly allowance, in cents'),
usedCents: z.number().describe('Used this month, in cents (fractions of a cent)'),
usedPercent: z.number(),
usedPercent: z.number().describe('How much of this month\'s allowance is used (0–100)'),
usedInputTokens: z.number().int().nullable().describe('Input tokens used this month by all the church\'s products (null from a Hub before 2.0.1)'),
usedOutputTokens: z.number().int().nullable().describe('Output tokens used this month'),
capInputTokens: z.number().int().nullable().describe('About how many input tokens the monthly allowance holds, if half of it went on input (an estimate: cached prompts cost less)'),
capOutputTokens: z.number().int().nullable().describe('About how many output tokens the allowance holds, if half of it went on output'),
renewsOn: z.string().nullable().describe('YYYY-MM-DD'),
helpers: helperFlags.describe('Each helper switched on or off in Site settings → AI'),
});
@@ -33,7 +35,7 @@ const settings = z.object({
dailyLimitPerPerson: z.number().int().min(0).max(1000).describe('0 = no limit'),
});
const use = z.object({ uses: z.number().int(), chargedCents: z.number() });
const use = z.object({ uses: z.number().int(), inputTokens: z.number().int(), outputTokens: z.number().int() });
export const getAiStatus = defineRoute({
method: 'get',