Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

feat(chat): charge Chat's model calls to the one AI budget (#1788)

Cihan2ca91b0243cd
diff --git a/server/src/lib/chat-budget.js b/server/src/lib/chat-budget.js
new file mode 100644
index 000000000..21f2895ba
--- /dev/null
+++ b/server/src/lib/chat-budget.js
@@ -0,0 +1,147 @@
+/**
+ * Chat's model steps on the workspace's one AI budget (CHAT-04 §C items
+ * 11–14, CHAT-16 items 22, 26, 29–30; DECISIONS P), behind CHAT_AGENTIC. The
+ * web's Chat engine runs the models; before each model step it asks for a
+ * hold here, and once the step ends it charges it, lets it go or keeps it,
+ * through /api/internal/chat/budget (routes/internal-chat-budget.js).
+ *
+ * Every step writes one prompt_improve_usage row, named by its run and step
+ * (00405):
+ * - On Ansvisor's key, the row is a hold of the step's worst case, taken
+ * by reserve_chat_ai_usage under the organization's lock only while the
+ * period's spend, holds in flight included, plus that worst case stays
+ * within the budget: runs at once can't pass it (item 13). Stricter than
+ * reserveAiBudget's, which lets a call start while anything is left.
+ * - On the workspace's own key (ownKey), the row is written without a
+ * check and never counts: the provider bills the workspace (item 26).
+ * - With no budget to hold against (self-hosted), it is written unchecked.
+ * The charge then turns the row into the step's real cost: 1x, what the
+ * model costs at the price in effect (generationCostUsd: the synced catalog
+ * price first, for Chat's steps only, and never a $0 one for a paid model).
+ * The margin on purchased AI credits (CHAT-16 30a) is never here.
+ *
+ * The trial's budget is the plan's in its trial (applyTrialAiBudget), over a
+ * period that runs the whole trial (aiBudgetOf): it never resets.
+ */
+
+import supabaseAdmin from '../config/supabase.js';
+import { chatAgenticEnabled } from './chat-flag.js';
+import { generationCostUsd } from './improve-cost.js';
+import { CHAT_AI_FEATURES, aiBudgetOf, aiBudgetUsedUp } from './plan-guard.js';
+
+/** What a Chat step can be metered as: a run's model step, then agents, scheduled runs, images. */
+export const CHAT_BUDGET_FEATURES = CHAT_AI_FEATURES;
+
+/** A request about a step the server can't take (Chat off, a run not the workspace's). */
+export class ChatBudgetError extends Error {
+ /**
+ * @param {'chat_off' | 'not_found'} code
+ * @param {number} statusCode
+ */
+ constructor(code, statusCode, message) {
+ super(message);
+ this.name = 'ChatBudgetError';
+ this.code = code;
+ this.statusCode = statusCode;
+ }
+}
+
+/**
+ * A step's worst case (item 13): its prompt at the input price in effect and
+ * every token it may write at the output price. The pre-step estimate
+ * assumes no prompt-cache hit (§D item 29), so a cache miss can't pass it.
+ */
+export function stepWorstCaseUsd(modelId, { inputTokens, maxOutputTokens }) {
+ return generationCostUsd(
+ modelId,
+ { inputTokens, outputTokens: maxOutputTokens },
+ { synced: true },
+ );
+}
+
+function assertChatOn(orgId) {
+ if (!chatAgenticEnabled(orgId)) {
+ throw new ChatBudgetError('chat_off', 403, 'Chat is off for this workspace.');
+ }
+}
+
+/**
+ * Holds a step's worst case on the budget and writes its row; returns the
+ * row's id, for the charge or the release. PlanLimitError 429 when the
+ * budget can't cover the step (the step doesn't start), 402 without an
+ * active plan; ChatBudgetError 404 when the run isn't the workspace's, or the
+ * step the run's.
+ */
+export async function reserveChatStep(
+ orgId,
+ { feature = 'chat', modelId, inputTokens, maxOutputTokens, runId, stepId = null, ownKey = false },
+) {
+ assertChatOn(orgId);
+ const { plan, budgetUsd, since } = await aiBudgetOf(orgId);
+ const { data, error } = await supabaseAdmin.rpc('reserve_chat_ai_usage', {
+ p_organization_id: orgId,
+ p_chat_run_id: runId,
+ p_chat_run_step_id: stepId,
+ p_feature: feature,
+ p_model: modelId,
+ p_cost: stepWorstCaseUsd(modelId, { inputTokens, maxOutputTokens }),
+ p_own_key: ownKey,
+ p_since: since,
+ p_budget: budgetUsd,
+ });
+ if (error) {
+ if (error.code === 'P0002') {
+ throw new ChatBudgetError('not_found', 404, 'Chat run not found.');
+ }
+ throw new Error(error.message);
+ }
+ if (!data) throw aiBudgetUsedUp(plan);
+ return data;
+}
+
+/**
+ * The step's real cost in place of its hold: what its model used, priced 1x
+ * (generationCostUsd). Only the workspace's own Chat rows: ChatBudgetError
+ * 404 when the row is gone (released) or isn't one. A step that called the
+ * model more than once (a retry) is charged its total usage. A provider
+ * that reported no usage leaves the hold as the step's cost: over, never
+ * under.
+ */
+export async function chargeChatStep(orgId, usageId, { modelId, usage }) {
+ const reported = usage?.inputTokens != null || usage?.outputTokens != null;
+ const { data, error } = await supabaseAdmin
+ .from('prompt_improve_usage')
+ .update(
+ reported
+ ? {
+ model: modelId,
+ input_tokens: usage.inputTokens ?? null,
+ output_tokens: usage.outputTokens ?? null,
+ cost_usd: generationCostUsd(modelId, usage, { synced: true }),
+ }
+ : { model: modelId },
+ )
+ .eq('id', usageId)
+ .eq('organization_id', orgId)
+ .in('feature', CHAT_BUDGET_FEATURES)
+ .select('id');
+ if (error) throw new Error(error.message);
+ if (!data?.length) throw new ChatBudgetError('not_found', 404, 'Chat step usage not found.');
+}
+
+/**
+ * A step that billed nothing (it failed before an answer): its hold goes.
+ * Safe to ask more than once. A step a Stop aborted isn't released: the
+ * provider bills it all the same, so its hold stays as its cost (the web's
+ * keep()). Charging and releasing settle a hold already taken, so they work
+ * whether or not Chat is still on.
+ */
+export async function releaseChatStep(orgId, usageId) {
+ const { error } = await supabaseAdmin
+ .from('prompt_improve_usage')
+ .delete()
+ .eq('id', usageId)
+ .eq('organization_id', orgId)
+ .in('feature', CHAT_BUDGET_FEATURES);
+ if (error) throw new Error(error.message);
+}
diff --git a/server/src/lib/chat-budget.test.js b/server/src/lib/chat-budget.test.js
new file mode 100644
index 000000000..e749f2d97
--- /dev/null
+++ b/server/src/lib/chat-budget.test.js
@@ -0,0 +1,382 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { TRIAL_AI_BUDGET_USD } from '../config/plans.js';
+
+/**
+ * Chat's model steps on the workspace's one AI budget (CHAT-04 §C, CHAT-16
+ * §H): one usage row per step, held at its worst case before it starts and
+ * turned into its real cost (1x) after; own-key steps written, never
+ * counted; the trial's budget kept over the whole trial.
+ *
+ * The database is a ledger in memory. reserve_chat_ai_usage and
+ * ai_usage_by_feature do what 00405's do (checked against the database in a
+ * rolled-back transaction when 00405 was written): one hold at a time per
+ * organization, and a step only while spend + holds + its worst case stays
+ * within the budget; own-key rows left out of every sum.
+ */
+
+const RUN = '0b6c2f2e-6a43-4c55-9f0e-3f4f1d2a7c01';
+const STEP = '0b6c2f2e-6a43-4c55-9f0e-3f4f1d2a7c02';
+// Priced from improve-cost's own table: $1 / $5 per million tokens.
+const MODEL = 'anthropic/claude-haiku-4-5';
+
+let org;
+let ledger;
+let rpcCalls;
+let runs;
+let nextId;
+// The per-organization lock: each hold waits for the one before.
+let lock;
+
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+/** 00405's reserve_chat_ai_usage, on the ledger. */
+async function reserveChatAiUsage(args) {
+ if (!runs.has(args.p_chat_run_id)) {
+ return { data: null, error: { code: 'P0002', message: 'chat run not found' } };
+ }
+ const held = lock.then(async () => {
+ if (!args.p_own_key && args.p_budget !== null) {
+ const spent = ledger
+ .filter((r) => !r.own_key && r.used_at >= args.p_since)
+ .reduce((sum, r) => sum + r.cost_usd, 0);
+ // The database's time between reading the spend and writing the hold.
+ await tick();
+ if (spent >= args.p_budget || spent + args.p_cost > args.p_budget + 1e-12) return null;
+ }
+ const id = `u${nextId++}`;
+ ledger.push({
+ id,
+ organization_id: args.p_organization_id,
+ feature: args.p_feature,
+ model: args.p_model,
+ cost_usd: args.p_cost,
+ own_key: args.p_own_key,
+ chat_run_id: args.p_chat_run_id,
+ chat_run_step_id: args.p_chat_run_step_id,
+ used_at: new Date().toISOString(),
+ });
+ return id;
+ });
+ lock = held.catch(() => {});
+ return { data: await held, error: null };
+}
+
+/** 00405's ai_usage_by_feature, on the ledger. */
+function aiUsageByFeature(args) {
+ const by = new Map();
+ for (const r of ledger) {
+ if (r.own_key || r.used_at < args.p_since) continue;
+ by.set(r.feature ?? 'other', (by.get(r.feature ?? 'other') ?? 0) + r.cost_usd);
+ }
+ return { data: [...by].map(([feature, cost_usd]) => ({ feature, cost_usd })), error: null };
+}
+
+function query(table) {
+ const op = { kind: 'select', filters: [] };
+ const matches = (r) =>
+ op.filters.every(([kind, col, val]) => (kind === 'in' ? val.includes(r[col]) : r[col] === val));
+ const run = () => {
+ if (table === 'organizations') return { data: org, error: null };
+ if (op.kind === 'update') {
+ const hit = ledger.filter(matches);
+ hit.forEach((r) => Object.assign(r, op.value));
+ return { data: hit.map((r) => ({ id: r.id })), error: null };
+ }
+ if (op.kind === 'delete') {
+ ledger = ledger.filter((r) => !matches(r));
+ return { data: null, error: null };
+ }
+ return { data: null, error: null };
+ };
+ const builder = {
+ select: () => builder,
+ eq: (col, val) => (op.filters.push(['eq', col, val]), builder),
+ in: (col, val) => (op.filters.push(['in', col, val]), builder),
+ update: (value) => (Object.assign(op, { kind: 'update', value }), builder),
+ delete: () => (Object.assign(op, { kind: 'delete' }), builder),
+ maybeSingle: () => builder,
+ single: () => builder,
+ then: (resolve, reject) => Promise.resolve(run()).then(resolve, reject),
+ };
+ return builder;
+}
+
+let budget;
+let guard;
+
+beforeEach(async () => {
+ vi.resetModules();
+ vi.stubEnv('IS_CLOUD', 'true');
+ vi.stubEnv('CHAT_AGENTIC', 'true');
+ vi.stubEnv('CHAT_AGENTIC_ORGS', '');
+ // Renews on the 20th: the period runs from the 20th of last month.
+ org = {
+ plan: 'starter',
+ subscription_status: 'active',
+ subscription_ends_at: '2026-11-20T09:00:00Z',
+ };
+ ledger = [];
+ rpcCalls = [];
+ runs = new Set([RUN]);
+ nextId = 1;
+ lock = Promise.resolve();
+ vi.doMock('../config/supabase.js', () => ({
+ default: {
+ from: (t) => query(t),
+ rpc: async (fn, args) => {
+ rpcCalls.push({ fn, args });
+ if (fn === 'reserve_chat_ai_usage') return reserveChatAiUsage(args);
+ if (fn === 'ai_usage_by_feature') return aiUsageByFeature(args);
+ return { data: null, error: { message: `no ${fn}` } };
+ },
+ },
+ }));
+ vi.doMock('./logger.js', () => ({ logger: { error: vi.fn(), info: vi.fn(), warn: vi.fn() } }));
+ vi.useFakeTimers({ toFake: ['Date'] });
+ vi.setSystemTime(new Date('2026-10-29T12:00:00Z'));
+ budget = await import('./chat-budget.js');
+ guard = await import('./plan-guard.js');
+});
+
+afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllEnvs();
+ vi.doUnmock('../config/supabase.js');
+ vi.doUnmock('./logger.js');
+});
+
+/** Spend already this period, on another feature. */
+const spent = (usd) =>
+ ledger.push({
+ id: 'prior',
+ feature: 'content',
+ cost_usd: usd,
+ own_key: false,
+ used_at: '2026-10-21T00:00:00.000Z',
+ });
+
+const nonOwnSpend = () => ledger.filter((r) => !r.own_key).reduce((s, r) => s + r.cost_usd, 0);
+
+const step = (over = {}) => ({
+ modelId: MODEL,
+ inputTokens: 2000,
+ maxOutputTokens: 1000,
+ runId: RUN,
+ ...over,
+});
+
+describe('a Chat step on the AI budget', () => {
+ it('holds its worst case, then writes its real cost on the same row: one row a step', async () => {
+ const id = await budget.reserveChatStep('o1', step({ stepId: STEP }));
+ expect(rpcCalls[0]).toEqual({
+ fn: 'reserve_chat_ai_usage',
+ args: {
+ p_organization_id: 'o1',
+ p_chat_run_id: RUN,
+ p_chat_run_step_id: STEP,
+ p_feature: 'chat',
+ p_model: MODEL,
+ // 2,000 tokens in at $1/M and 1,000 out at $5/M: every token it may write.
+ p_cost: 0.007,
+ p_own_key: false,
+ // From the period's start, against Starter's $5.
+ p_since: '2026-10-20T09:00:00.000Z',
+ p_budget: 5,
+ },
+ });
+ expect(ledger).toEqual([
+ expect.objectContaining({ id, feature: 'chat', cost_usd: 0.007, chat_run_step_id: STEP }),
+ ]);
+
+ await budget.chargeChatStep('o1', id, {
+ modelId: MODEL,
+ usage: { inputTokens: 1800, outputTokens: 400 },
+ });
+ // 1x: what the model cost, no margin.
+ expect(ledger).toEqual([
+ expect.objectContaining({
+ id,
+ input_tokens: 1800,
+ output_tokens: 400,
+ cost_usd: 0.0038,
+ chat_run_id: RUN,
+ }),
+ ]);
+
+ // A second step writes its own row.
+ const second = await budget.reserveChatStep('o1', step({ stepId: null }));
+ await budget.chargeChatStep('o1', second, {
+ modelId: MODEL,
+ usage: { inputTokens: 100, outputTokens: 100 },
+ });
+ expect(ledger.map((r) => r.id)).toEqual([id, second]);
+ expect(ledger.every((r) => r.chat_run_id === RUN && r.feature === 'chat')).toBe(true);
+ });
+
+ it('never lets 20 steps at once pass the cap with 1% of it left', async () => {
+ // Starter's $5 with $0.05 left; each step may cost $0.007.
+ spent(4.95);
+ const results = await Promise.allSettled(
+ Array.from({ length: 20 }, () => budget.reserveChatStep('o1', step())),
+ );
+ const held = results.filter((r) => r.status === 'fulfilled').map((r) => r.value);
+ const refused = results.filter((r) => r.status === 'rejected').map((r) => r.reason);
+ // 7 × $0.007 = $0.049 fits; an 8th would pass $5.
+ expect(held).toHaveLength(7);
+ expect(refused).toHaveLength(13);
+ expect(refused.every((e) => e.statusCode === 429)).toBe(true);
+ expect(nonOwnSpend()).toBeLessThanOrEqual(5);
+
+ // Each charged at what it used (never more than its worst case): still within.
+ await Promise.all(
+ held.map((id) =>
+ budget.chargeChatStep('o1', id, {
+ modelId: MODEL,
+ usage: { inputTokens: 2000, outputTokens: 1000 },
+ }),
+ ),
+ );
+ expect(nonOwnSpend()).toBeLessThanOrEqual(5);
+ // Once spent, the next step doesn't start.
+ await expect(budget.reserveChatStep('o1', step())).rejects.toMatchObject({ statusCode: 429 });
+ });
+
+ it('writes a step on the workspace’s own key, and the meter’s percent doesn’t move', async () => {
+ spent(1);
+ const before = await guard.getAiUsage('o1');
+ expect(before.percentUsed).toBe(20);
+
+ const id = await budget.reserveChatStep('o1', step({ ownKey: true }));
+ await budget.chargeChatStep('o1', id, {
+ modelId: MODEL,
+ usage: { inputTokens: 500_000, outputTokens: 100_000 },
+ });
+ // The row is there, marked, at its cost…
+ expect(ledger).toContainEqual(
+ expect.objectContaining({ id, own_key: true, feature: 'chat', cost_usd: 1 }),
+ );
+ // …and the meter reads as it did, with no Chat row.
+ const after = await guard.getAiUsage('o1');
+ expect(after.percentUsed).toBe(20);
+ expect(after.features).toEqual([{ feature: 'content', percent: 20 }]);
+
+ // Even with the budget spent, an own-key step runs.
+ spent(4);
+ await expect(budget.reserveChatStep('o1', step({ ownKey: true }))).resolves.toEqual(
+ expect.any(String),
+ );
+ });
+
+ it('shows Ansvisor-key steps in their own Chat row, and says Chat is metered', async () => {
+ spent(1);
+ const id = await budget.reserveChatStep('o1', step());
+ await budget.chargeChatStep('o1', id, {
+ modelId: MODEL,
+ usage: { inputTokens: 250_000, outputTokens: 50_000 },
+ });
+ const usage = await guard.getAiUsage('o1');
+ expect(usage.chatMetered).toBe(true);
+ expect(usage.percentUsed).toBe(30);
+ expect(usage.features).toEqual([
+ { feature: 'content', percent: 20 },
+ { feature: 'chat', percent: 10 },
+ ]);
+ });
+
+ it('keeps the free trial’s budget over the whole trial: the 1st of the month doesn’t reset it', async () => {
+ // A trial that ends on 8 November, read on 2 November.
+ org = {
+ plan: 'growth',
+ subscription_status: 'trialing',
+ subscription_ends_at: '2026-11-08T10:00:00Z',
+ };
+ vi.setSystemTime(new Date('2026-11-02T12:00:00Z'));
+ ledger.push({
+ id: 'october',
+ feature: 'improve',
+ cost_usd: TRIAL_AI_BUDGET_USD - 0.001,
+ own_key: false,
+ used_at: '2026-10-25T00:00:00.000Z',
+ });
+
+ await expect(budget.reserveChatStep('o1', step())).rejects.toMatchObject({
+ statusCode: 429,
+ trial: true,
+ });
+ expect(rpcCalls[0].args).toMatchObject({
+ p_budget: TRIAL_AI_BUDGET_USD,
+ // From the trial's start, not 1 November: October's spend still counts.
+ p_since: '2026-10-08T10:00:00.000Z',
+ });
+ });
+
+ it('keeps the hold as the cost when the provider reported no usage: over, never under', async () => {
+ const id = await budget.reserveChatStep('o1', step());
+ await budget.chargeChatStep('o1', id, { modelId: MODEL, usage: {} });
+ expect(ledger).toEqual([expect.objectContaining({ id, cost_usd: 0.007 })]);
+ });
+
+ it('lets a hold go when the step billed nothing, and never another feature’s row', async () => {
+ const id = await budget.reserveChatStep('o1', step());
+ ledger.push({
+ id: 'other',
+ feature: 'content',
+ cost_usd: 0.1,
+ own_key: false,
+ used_at: '2026-10-21',
+ });
+ await budget.releaseChatStep('o1', id);
+ await budget.releaseChatStep('o1', id);
+ await budget.releaseChatStep('o1', 'other');
+ expect(ledger.map((r) => r.id)).toEqual(['other']);
+ // A released row can't be charged.
+ await expect(
+ budget.chargeChatStep('o1', id, { modelId: MODEL, usage: { inputTokens: 1 } }),
+ ).rejects.toMatchObject({ statusCode: 404, code: 'not_found' });
+ });
+
+ it('refuses a run that isn’t the workspace’s', async () => {
+ await expect(
+ budget.reserveChatStep('o1', step({ runId: '0b6c2f2e-6a43-4c55-9f0e-3f4f1d2a7cff' })),
+ ).rejects.toMatchObject({ statusCode: 404, code: 'not_found' });
+ expect(ledger).toEqual([]);
+ });
+
+ it('holds nothing, and meters nothing, while Chat is off for the workspace', async () => {
+ vi.stubEnv('CHAT_AGENTIC', 'false');
+ await expect(budget.reserveChatStep('o1', step())).rejects.toMatchObject({
+ statusCode: 403,
+ code: 'chat_off',
+ });
+ expect(rpcCalls).toEqual([]);
+ expect(ledger).toEqual([]);
+ expect((await guard.getAiUsage('o1')).chatMetered).toBe(false);
+ });
+
+ it('prices a step from the synced catalog, but never at a $0 rate for a paid model', async () => {
+ const cache = await import('./model-price-cache.js');
+ const SONNET = 'anthropic/claude-sonnet-5.5';
+ // The synced price is used: $3 / $15 per million tokens.
+ cache.setSyncedPrices([{ model_id: SONNET, input_per_m: 3, output_per_m: 15, overrides: [] }]);
+ await budget.reserveChatStep('o1', step({ modelId: SONNET }));
+ expect(rpcCalls[0].args.p_cost).toBeCloseTo(0.021, 9);
+ // Listed at $0: the server's table prices it ($2 / $10), hold and charge alike.
+ cache.setSyncedPrices([{ model_id: SONNET, input_per_m: 0, output_per_m: 0, overrides: [] }]);
+ const id = await budget.reserveChatStep('o1', step({ modelId: SONNET }));
+ expect(rpcCalls[1].args.p_cost).toBeCloseTo(0.014, 9);
+ await budget.chargeChatStep('o1', id, {
+ modelId: SONNET,
+ usage: { inputTokens: 1000, outputTokens: 100 },
+ });
+ expect(ledger.find((r) => r.id === id).cost_usd).toBeCloseTo(0.003, 9);
+ cache.setSyncedPrices([]);
+ });
+
+ it('writes each step without a hold where nothing is metered (self-hosted)', async () => {
+ vi.stubEnv('IS_CLOUD', 'false');
+ spent(100);
+ const id = await budget.reserveChatStep('o1', step());
+ expect(rpcCalls[0].args).toMatchObject({ p_budget: null, p_since: null });
+ expect(ledger).toContainEqual(expect.objectContaining({ id, feature: 'chat' }));
+ });
+});
diff --git a/server/src/lib/improve-cost.js b/server/src/lib/improve-cost.js
index 16b2bf813..017bdac38 100644
--- a/server/src/lib/improve-cost.js
+++ b/server/src/lib/improve-cost.js
@@ -3,10 +3,11 @@
* quota can be a dollar budget — a share of what the customer pays — and stay
* there whichever model IMPROVE_SUGGESTION_MODEL points at.
*
- * List prices in USD per million tokens. While CHAT_AGENTIC is on, the
- * prices synced daily from OpenRouter's catalog come first (model-prices.js,
- * CHAT-16 §A), at the price in effect; this table prices a model the sync
- * doesn't have, or every model with the flag off. Update it when a provider
+ * List prices in USD per million tokens. Chat's own steps (chat-budget.js,
+ * only for workspaces Chat is on for) read the prices synced daily from
+ * OpenRouter's catalog first (model-prices.js, CHAT-16 §A), at the price in
+ * effect; every other call, and a Chat step whose model isn't synced or is
+ * synced at $0, is priced from this table. Update it when a provider
* changes its prices or a new model is configured; a model missing from both
* is charged at FALLBACK_PRICE, deliberately expensive, so an unknown model
* can only use the budget up faster, never overspend it. A model here priced
@@ -40,23 +41,51 @@ export const FALLBACK_PRICE = { input: 5, output: 25 };
const TYPICAL_TOKENS = { input: 7000, output: 2000 };
/**
- * A model's price: the synced one in effect now (for a call of
- * `promptTokens`, which may cross a prompt-size price), else this table's.
- * OpenRouter ids carry the provider id after an `openrouter/` prefix
- * (`openrouter/google/gemini-3-flash-preview`); they're priced as that model.
+ * This table's price for a model: under its id, or with OpenRouter's dotted
+ * version written as ours ("anthropic/claude-haiku-5.5" is
+ * "anthropic/claude-haiku-5-5"). OpenRouter ids carry the provider id after
+ * an `openrouter/` prefix (`openrouter/google/gemini-3-flash-preview`);
+ * they're priced as that model. Null when the table hasn't the model.
*/
-export function priceFor(modelId, { promptTokens = 0 } = {}) {
- const synced = syncedPriceFor(modelId, { promptTokens });
- if (synced) return synced;
+function tablePriceFor(modelId) {
const id = String(modelId ?? '').replace(/^openrouter\//, '');
- const price = MODEL_PRICES[id] ?? FALLBACK_PRICE;
+ return MODEL_PRICES[id] ?? MODEL_PRICES[id.replace(/-(\d+)\.(\d+)$/, '-$1-$2')] ?? null;
+}
+
+/**
+ * A synced price the budget may use: both rates above $0, unless the model
+ * is a `:free` one. A $0 rate for a paid model (a catalog mistake or a
+ * promotion) would let its calls cost the budget nothing, so the table (or
+ * FALLBACK_PRICE) prices it instead.
+ */
+function usableSynced(modelId, price) {
+ if (!price) return false;
+ if (String(modelId ?? '').endsWith(':free')) return true;
+ return price.input > 0 && price.output > 0;
+}
+
+/**
+ * A model's price, for a call of `promptTokens` (which may cross a
+ * prompt-size price). With `synced` (Chat's own steps only), the synced one
+ * in effect now comes first; otherwise, and when it's missing or $0, this
+ * table's, and FALLBACK_PRICE for a model the table hasn't.
+ */
+export function priceFor(modelId, { promptTokens = 0, synced = false } = {}) {
+ if (synced) {
+ const price = syncedPriceFor(modelId, { promptTokens });
+ if (usableSynced(modelId, price)) return price;
+ }
+ const price = tablePriceFor(modelId) ?? FALLBACK_PRICE;
return price.long && promptTokens > price.long.over ? price.long : price;
}
-/** USD cost of one call from the AI SDK's `usage`. */
-export function generationCostUsd(modelId, usage) {
+/**
+ * USD cost of one call from the AI SDK's `usage`. `synced`: a Chat step,
+ * priced from the synced catalog first (priceFor).
+ */
+export function generationCostUsd(modelId, usage, { synced = false } = {}) {
const input = Number(usage?.inputTokens) || 0;
- const price = priceFor(modelId, { promptTokens: input });
+ const price = priceFor(modelId, { promptTokens: input, synced });
const output = Number(usage?.outputTokens) || 0;
return (input * price.input + output * price.output) / 1_000_000;
}
diff --git a/server/src/lib/improve-cost.test.js b/server/src/lib/improve-cost.test.js
index bbffc182c..6eebde208 100644
--- a/server/src/lib/improve-cost.test.js
+++ b/server/src/lib/improve-cost.test.js
@@ -81,34 +81,90 @@ describe('priceFor with synced prices (CHAT-16 §A)', () => {
overrides: [{ min_prompt_tokens: 100000, prompt: '0.0000005', completion: '0.0000025' }],
};
- it('reads the synced price first, under its hyphened or OpenRouter id too', () => {
+ const SYNCED = { synced: true };
+
+ it('reads the synced price first for a Chat step, under its hyphened or OpenRouter id too', () => {
setSyncedPrices([HAIKU]);
for (const id of [
'anthropic/claude-haiku-5.5',
'anthropic/claude-haiku-5-5',
'openrouter/anthropic/claude-haiku-5.5',
]) {
- expect(priceFor(id)).toEqual({ input: 0.1, output: 0.5 });
+ expect(priceFor(id, SYNCED)).toEqual({ input: 0.1, output: 0.5 });
}
});
it("falls back to the server's own table for a model that isn't synced", () => {
setSyncedPrices([HAIKU]);
- expect(priceFor('google/gemini-3-flash-preview')).toBe(
+ expect(priceFor('google/gemini-3-flash-preview', SYNCED)).toBe(
MODEL_PRICES['google/gemini-3-flash-preview'],
);
- expect(priceFor('someone/new-model')).toBe(FALLBACK_PRICE);
+ expect(priceFor('someone/new-model', SYNCED)).toBe(FALLBACK_PRICE);
});
it('prices a call at the prompt-size override once its input is that large', () => {
setSyncedPrices([HAIKU]);
expect(
- generationCostUsd('anthropic/claude-haiku-5.5', { inputTokens: 10_000, outputTokens: 1000 }),
+ generationCostUsd(
+ 'anthropic/claude-haiku-5.5',
+ { inputTokens: 10_000, outputTokens: 1000 },
+ SYNCED,
+ ),
).toBeCloseTo(0.0015, 8);
expect(
- generationCostUsd('anthropic/claude-haiku-5.5', { inputTokens: 100_000, outputTokens: 1000 }),
+ generationCostUsd(
+ 'anthropic/claude-haiku-5.5',
+ { inputTokens: 100_000, outputTokens: 1000 },
+ SYNCED,
+ ),
).toBeCloseTo(0.0525, 8);
});
+
+ it("leaves every other call on the table: the synced catalog prices Chat's steps only", () => {
+ setSyncedPrices([
+ { model_id: 'google/gemini-3-flash-preview', input_per_m: 9, output_per_m: 9, overrides: [] },
+ ]);
+ expect(priceFor('google/gemini-3-flash-preview')).toBe(
+ MODEL_PRICES['google/gemini-3-flash-preview'],
+ );
+ expect(
+ generationCostUsd('google/gemini-3-flash-preview', { inputTokens: 7000, outputTokens: 2000 }),
+ ).toBeCloseTo(0.0095, 6);
+ });
+
+ it('never meters a paid model at a synced $0: the table, or the fallback, prices it', () => {
+ setSyncedPrices([
+ { model_id: 'anthropic/claude-sonnet-5.5', input_per_m: 0, output_per_m: 0, overrides: [] },
+ { model_id: 'anthropic/claude-haiku-5.5', input_per_m: 0.1, output_per_m: 0, overrides: [] },
+ { model_id: 'someone/new-model', input_per_m: 0, output_per_m: 0, overrides: [] },
+ { model_id: 'someone/free-model:free', input_per_m: 0, output_per_m: 0, overrides: [] },
+ ]);
+ expect(priceFor('anthropic/claude-sonnet-5.5', SYNCED)).toBe(
+ MODEL_PRICES['anthropic/claude-sonnet-5-5'],
+ );
+ expect(priceFor('anthropic/claude-haiku-5.5', SYNCED)).toBe(
+ MODEL_PRICES['anthropic/claude-haiku-5-5'],
+ );
+ expect(priceFor('someone/new-model', SYNCED)).toBe(FALLBACK_PRICE);
+ expect(
+ generationCostUsd(
+ 'anthropic/claude-sonnet-5.5',
+ { inputTokens: 7000, outputTokens: 2000 },
+ SYNCED,
+ ),
+ ).toBeCloseTo(0.034, 6);
+ // A `:free` model is free by name: its $0 is its price.
+ expect(priceFor('someone/free-model:free', SYNCED)).toEqual({ input: 0, output: 0 });
+ });
+
+ it("prices OpenRouter's dotted id from the table when nothing is synced", () => {
+ expect(priceFor('anthropic/claude-haiku-5.5', SYNCED)).toBe(
+ MODEL_PRICES['anthropic/claude-haiku-5-5'],
+ );
+ expect(priceFor('anthropic/claude-sonnet-5.5')).toBe(
+ MODEL_PRICES['anthropic/claude-sonnet-5-5'],
+ );
+ });
});
describe('the same 1% budget buys more on a cheaper model', () => {
diff --git a/server/src/lib/model-prices.js b/server/src/lib/model-prices.js
index 42fd2cee0..34b99e980 100644
--- a/server/src/lib/model-prices.js
+++ b/server/src/lib/model-prices.js
@@ -16,7 +16,8 @@ import {
* The catalog needs no key. A sync upserts every model it lists and removes
* none: a failed or short read keeps the last good prices. After a sync, and
* when the server starts, the rows are loaded into model-price-cache.js, where
- * a call's cost (improve-cost.js) and the multipliers below read them.
+ * a Chat step's cost (improve-cost.js, for chat-budget.js only) and the
+ * multipliers below read them.
*
* Multipliers (CHAT-16 §B): a model's blended cost is 3 × its input price +
* its output price, at the price in effect; its multiplier is that over
diff --git a/server/src/lib/plan-guard-ai-budget.test.js b/server/src/lib/plan-guard-ai-budget.test.js
index f20ab5156..af8b6752a 100644
--- a/server/src/lib/plan-guard-ai-budget.test.js
+++ b/server/src/lib/plan-guard-ai-budget.test.js
@@ -15,12 +15,18 @@ let ops;
let recent;
// The `or` filters its reads ask for.
let ors;
+// The `eq` filters its prompt_improve_usage reads ask for.
+let filters;
function query(table) {
const op = { table, kind: 'select', filters: [] };
const builder = {
select: () => builder,
- eq: (col, val) => (op.filters.push([col, val]), builder),
+ eq: (col, val) => {
+ op.filters.push([col, val]);
+ if (table === 'prompt_improve_usage') filters.push([col, val]);
+ return builder;
+ },
gte: (col, val) => (op.filters.push([col, val]), builder),
or: (val) => (ors.push(val), builder),
order: () => builder,
@@ -51,6 +57,7 @@ beforeEach(async () => {
rpcCalls = [];
ops = [];
ors = [];
+ filters = [];
vi.doMock('../config/supabase.js', () => ({
default: {
from: (t) => query(t),
@@ -111,7 +118,15 @@ describe('reserveAiBudget', () => {
feature: 'content',
modelId: 'google/gemini-3-flash-preview',
});
- expect(ors).toEqual(['feature.is.null,feature.neq.quality']);
+ expect(ors).toEqual(['feature.is.null,feature.not.in.(quality,chat,agent,schedule,image)']);
+ });
+
+ it('leaves steps on a workspace’s own key out of the median a hold is sized on', async () => {
+ await guard.reserveAiBudget('o1', {
+ feature: 'content',
+ modelId: 'google/gemini-3-flash-preview',
+ });
+ expect(filters).toContainEqual(['own_key', false]);
});
it('holds the estimate on the period’s budget, then turns it into the real cost', async () => {
@@ -235,6 +250,21 @@ describe('reserveAiBudget', () => {
});
describe('getImproveQuotaStatus', () => {
+ it('counts Chat’s steps as spent, but sizes a call on the others, and leaves own-key rows out', async () => {
+ recent = {
+ data: [
+ ...Array.from({ length: 10 }, () => ({ cost_usd: 0.001, feature: 'chat' })),
+ ...Array.from({ length: 5 }, () => ({ cost_usd: 0.02, feature: 'improve' })),
+ ],
+ error: null,
+ };
+ const status = await guard.getImproveQuotaStatus('o1', 'google/gemini-3-flash-preview');
+ expect(status.spentUsd).toBeCloseTo(0.11);
+ // $4.89 left at $0.02 a call: Chat's $0.001 steps don't pull the estimate down.
+ expect(status.generationsLeft).toBe(244);
+ expect(filters).toContainEqual(['own_key', false]);
+ });
+
it('counts Quality’s small checks as spent, but sizes a call on the others', async () => {
recent = {
data: [
diff --git a/server/src/lib/plan-guard-ai-usage.test.js b/server/src/lib/plan-guard-ai-usage.test.js
index fa0a4ad9d..edde7676c 100644
--- a/server/src/lib/plan-guard-ai-usage.test.js
+++ b/server/src/lib/plan-guard-ai-usage.test.js
@@ -227,6 +227,8 @@ describe('getDraftAiUsage', () => {
expect(pageFilters).toEqual([
['eq', 'organization_id', 'o1'],
['eq', 'content_draft_id', 'd1'],
+ // Calls on the workspace's own key never count (00405).
+ ['eq', 'own_key', false],
// The same period as the month's figure: it renews on the 20th.
['gte', 'used_at', '2026-10-20T09:00:00.000Z'],
]);
diff --git a/server/src/lib/plan-guard.js b/server/src/lib/plan-guard.js
index 3bf0bada5..51e3da0d2 100644
--- a/server/src/lib/plan-guard.js
+++ b/server/src/lib/plan-guard.js
@@ -15,6 +15,7 @@ import {
typicalCostUsd,
} from './improve-cost.js';
import { logger } from './logger.js';
+import { chatAgenticEnabled } from './chat-flag.js';
import { RELEVANCE_BUDGET_SHARE } from './suggestion-relevance.js';
import { AUDIT_RUN_TIMEOUT_MS } from './audit/history.js';
import {
@@ -360,19 +361,33 @@ export async function getBriefQuotaStatus(orgId, { readOnly = false } = {}) {
/** How many of the org's latest calls its typical cost is the median of. */
const RECENT_CALLS = 20;
+/**
+ * Chat's model steps on the budget (00405): a Chat run's ('chat'), and the
+ * room its agents, scheduled runs and images take. They count in what's
+ * spent, but not in what an Improve or Content Editor call typically costs:
+ * a step is sized on its own worst case (chat-budget.js).
+ */
+export const CHAT_AI_FEATURES = ['chat', 'agent', 'schedule', 'image'];
+
+/** Features whose calls aren't sized like an Improve or Content Editor call. */
+const NOT_TYPICAL = new Set(['quality', ...CHAT_AI_FEATURES]);
+
async function improveSpendThisPeriod(orgId) {
const periodStart = await quotaPeriodStart(orgId);
const { data } = await supabaseAdmin
.from('prompt_improve_usage')
.select('cost_usd, feature')
.eq('organization_id', orgId)
+ // A step on the workspace's own key is billed to it, not to the budget.
+ .eq('own_key', false)
.gte('used_at', periodStart.toISOString())
.order('used_at', { ascending: false })
.limit(5000);
const rows = data ?? [];
const spent = rows.reduce((sum, r) => sum + (Number(r.cost_usd) || 0), 0);
- // Quality's small checks count in what's spent, not in what a call costs.
- const calls = rows.filter((r) => r.feature !== 'quality').slice(0, RECENT_CALLS);
+ // Quality's small checks and Chat's steps count in what's spent, not in
+ // what a call costs.
+ const calls = rows.filter((r) => !NOT_TYPICAL.has(r.feature)).slice(0, RECENT_CALLS);
return { spent, typical: medianCost(calls.map((r) => Number(r.cost_usd) || 0)) };
}
@@ -446,14 +461,7 @@ export async function reserveAiBudget(
p_content_draft_id: draftId,
});
if (error) throw new Error(error.message);
- if (!data) {
- throw new PlanLimitError(
- plan.trial
- ? "The free trial's AI usage is used up. Starting the plan gives its full monthly allowance."
- : `This month's suggestion budget on the ${plan.name} plan is used up. It resets when your subscription renews.`,
- 429,
- );
- }
+ if (!data) throw aiBudgetUsedUp(plan);
reservedId = data;
}
@@ -514,6 +522,35 @@ export async function reserveAiBudget(
};
}
+/**
+ * The workspace's AI budget is spent (429): in the free trial (`trial`),
+ * more comes with starting the plan.
+ */
+export function aiBudgetUsedUp(plan) {
+ const err = new PlanLimitError(
+ plan.trial
+ ? "The free trial's AI usage is used up. Starting the plan gives its full monthly allowance."
+ : `This month's suggestion budget on the ${plan.name} plan is used up. It resets when your subscription renews.`,
+ 429,
+ );
+ err.trial = plan.trial === true;
+ return err;
+}
+
+/**
+ * The workspace's AI budget as a hold is taken on it: the plan (402 without
+ * an active one, as reserveAiBudget), its budget in USD and the period's
+ * start, from which the spend counts; both null when the budget is
+ * unlimited (self-hosted). In the free trial the period runs over the whole
+ * trial (quotaPeriodStart, from the trial's end): its budget never resets.
+ */
+export async function aiBudgetOf(orgId) {
+ const plan = await resolveOrgPlanByOrgId(orgId);
+ const budget = plan.limits.improveMonthlyBudgetUsd ?? -1;
+ if (budget === -1) return { plan, budgetUsd: null, since: null };
+ return { plan, budgetUsd: budget, since: (await quotaPeriodStart(orgId)).toISOString() };
+}
+
/**
* What a call holds before it runs: the org's median cost over its last
* RECENT_CALLS calls this period, never less than the model's typical one.
@@ -525,13 +562,15 @@ export async function reserveAiBudget(
*/
async function holdCostUsd(orgId, modelId, since) {
const typical = typicalCostUsd(modelId);
- // Quality's small checks hold their own (holdUsd): left out, they don't
- // pull the median under what the larger calls cost.
+ // Quality's small checks hold their own (holdUsd), and Chat's steps their
+ // worst case: left out, they don't pull the median under what the larger
+ // calls cost. Steps on a workspace's own key never count.
const { data, error } = await supabaseAdmin
.from('prompt_improve_usage')
.select('cost_usd')
.eq('organization_id', orgId)
- .or('feature.is.null,feature.neq.quality')
+ .eq('own_key', false)
+ .or(`feature.is.null,feature.not.in.(${[...NOT_TYPICAL].join(',')})`)
.gte('used_at', since)
.order('used_at', { ascending: false })
.limit(RECENT_CALLS);
@@ -547,12 +586,18 @@ async function holdCostUsd(orgId, modelId, since) {
* The meter's rows, in order, and what the workspace's AI budget spent on
* each, as prompt_improve_usage.feature says (00242): the Content Editor's
* quality checks ('quality', 00264) are its AI too, so they count in its
- * row. 'other' is spend whose feature isn't known.
+ * row. Chat's model steps have theirs (00405), with Chat on: Chat's runs,
+ * then its agents, scheduled runs and images, as they come. 'other' is spend
+ * whose feature isn't known.
*/
export const AI_USAGE_FEATURES = {
improve: ['improve'],
content: ['content', 'quality'],
action_center: ['action_center'],
+ chat: ['chat'],
+ agent: ['agent'],
+ schedule: ['schedule'],
+ image: ['image'],
other: ['other'],
};
@@ -570,6 +615,9 @@ const tenths = (n) => Math.round(n * 10) / 10;
* listed (an Action Center whose task writer is off has no row), so a row
* can read 0 when its share is under a twentieth of a percent: the page
* reads that as "<0.1%". Unlimited plans (self-hosted) show no meter.
+ * `chatMetered`: Chat draws on the budget too (CHAT_AGENTIC on for the
+ * workspace); off, it runs on the workspace's own key only, as the page says.
+ * Steps on a workspace's own key never count (ai_usage_by_feature, 00405).
*/
export async function getAiUsage(orgId) {
const plan = await resolveOrgPlanByOrgId(orgId);
@@ -581,6 +629,7 @@ export async function getAiUsage(orgId) {
trial: plan.trial === true,
periodStart: periodStart.toISOString(),
periodEnd: shiftMonthClamped(periodStart, 1).toISOString(),
+ chatMetered: chatAgenticEnabled(orgId),
};
const budget = plan.limits.improveMonthlyBudgetUsd ?? -1;
if (budget === -1) return { ...base, unlimited: true, percentUsed: null, features: [] };
@@ -632,6 +681,7 @@ export async function getDraftAiUsage(orgId, draftId) {
.select('cost_usd')
.eq('organization_id', orgId)
.eq('content_draft_id', draftId)
+ .eq('own_key', false)
.gte('used_at', since),
supabaseAdmin.rpc('ai_usage_by_feature', { p_organization_id: orgId, p_since: since }),
]);
diff --git a/server/src/middleware/demo-brand.test.js b/server/src/middleware/demo-brand.test.js
index 9bb7611cb..f91af3f3f 100644
--- a/server/src/middleware/demo-brand.test.js
+++ b/server/src/middleware/demo-brand.test.js
@@ -425,6 +425,8 @@ describe('coverage of the write routes', () => {
expect(outside.sort()).toEqual([
'bot-ingest.js',
'cloro-callback.js',
+ // Chat's budget holds (CRON_SECRET, called by the web's engine): keyed by run, no brand.
+ 'internal-chat-budget.js',
// The first run after a payment (CRON_SECRET): refuses a demo brand itself.
'internal-trigger-tracking.js',
'traffic.js',
diff --git a/server/src/middleware/rate-limiter.js b/server/src/middleware/rate-limiter.js
index bd04023cb..d1ecddcf3 100644
--- a/server/src/middleware/rate-limiter.js
+++ b/server/src/middleware/rate-limiter.js
@@ -1,5 +1,6 @@
import { createHash } from 'node:crypto';
import rateLimit from 'express-rate-limit';
+import { webhookSecretsMatch } from '../lib/webhook-secret.js';
import { verifiedBotConnection, verifiedUserId } from './verified-tokens.js';
/**
@@ -40,8 +41,28 @@ export function apiLimiterKey(req) {
return anonymousIpKey(req.ip);
}
-// General API rate limit, per verified user (per IP otherwise)
+/** The web's Chat engine's budget calls (routes/internal-chat-budget.js). */
+const CHAT_BUDGET_PATH = /^\/api\/internal\/chat\/budget(\/|$)/;
+
+/**
+ * Whether a request is the web's Chat engine holding or settling a model
+ * step on the AI budget, with the internal secret (CRON_SECRET, compared in
+ * constant time). Every Chat step makes two of them, and on Vercel the web's
+ * calls come from a few shared addresses, so the API's per-IP bucket would
+ * stop Chat for every workspace at once. Only this path, and only with the
+ * secret: any other request, or this path without it, is counted as before.
+ */
+export function isInternalChatBudgetCall(req) {
+ if (!CHAT_BUDGET_PATH.test(`${req.baseUrl ?? ''}${req.path ?? ''}`)) return false;
+ const auth = req.headers?.authorization;
+ if (typeof auth !== 'string' || !auth.startsWith('Bearer ')) return false;
+ return webhookSecretsMatch(process.env.CRON_SECRET, auth.slice('Bearer '.length));
+}
+
+// General API rate limit, per verified user (per IP otherwise). The Chat
+// engine's budget calls, with the internal secret, aren't counted.
export const apiLimiter = rateLimit({
+ skip: isInternalChatBudgetCall,
windowMs: 15 * 60 * 1000,
// A verified user's bucket only needs to absorb their own burst (several
// tabs polling tracking status every 15s plus normal navigation).
diff --git a/server/src/middleware/rate-limiter.test.js b/server/src/middleware/rate-limiter.test.js
index 92d083485..69cbf58df 100644
--- a/server/src/middleware/rate-limiter.test.js
+++ b/server/src/middleware/rate-limiter.test.js
@@ -1,12 +1,14 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import express from 'express';
import {
+ apiLimiter,
apiLimiterKey,
botIngestKey,
catalogCategoryLimiter,
catalogLimiter,
cmsLimiter,
cmsStatusLimiter,
+ isInternalChatBudgetCall,
isJourneyBeacon,
journeyEventKey,
shoppingPathLimiter,
@@ -228,3 +230,76 @@ describe('rate-limiter – shopping path builds', () => {
}
});
});
+
+describe('rate-limiter – the Chat engine’s budget calls', () => {
+ beforeEach(() => vi.stubEnv('CRON_SECRET', 'chat-secret'));
+ afterEach(() => vi.unstubAllEnvs());
+
+ const req = (path, authorization) => ({
+ baseUrl: '/api',
+ path,
+ headers: authorization ? { authorization } : {},
+ });
+
+ it('exempts only the budget path, and only with the internal secret', () => {
+ expect(
+ isInternalChatBudgetCall(req('/internal/chat/budget/reserve', 'Bearer chat-secret')),
+ ).toBe(true);
+ expect(
+ isInternalChatBudgetCall(req('/internal/chat/budget/charge', 'Bearer chat-secret')),
+ ).toBe(true);
+ // Without it, with another, or with the secret on any other path: counted.
+ expect(isInternalChatBudgetCall(req('/internal/chat/budget/reserve'))).toBe(false);
+ expect(isInternalChatBudgetCall(req('/internal/chat/budget/reserve', 'Bearer nope'))).toBe(
+ false,
+ );
+ expect(isInternalChatBudgetCall(req('/internal/chat/budget/reserve', 'chat-secret'))).toBe(
+ false,
+ );
+ expect(isInternalChatBudgetCall(req('/internal/ai-usage', 'Bearer chat-secret'))).toBe(false);
+ expect(isInternalChatBudgetCall(req('/internal/chat/budgetx', 'Bearer chat-secret'))).toBe(
+ false,
+ );
+ // No secret configured: nothing is exempt.
+ vi.stubEnv('CRON_SECRET', '');
+ expect(isInternalChatBudgetCall(req('/internal/chat/budget/reserve', 'Bearer '))).toBe(false);
+ });
+
+ it('never stops the secret’s budget calls, and still limits everything else from that address', async () => {
+ const app = express();
+ app.use('/api', apiLimiter);
+ app.post('/api/internal/chat/budget/reserve', (_req, res) => res.json({}));
+ app.get('/api/internal/ai-usage', (_req, res) => res.json({}));
+ const server = await new Promise((resolve) => {
+ const listening = app.listen(0, '127.0.0.1', () => resolve(listening));
+ });
+ const base = `http://127.0.0.1:${server.address().port}/api`;
+ const call = (method, path, secret) =>
+ fetch(base + path, {
+ method,
+ headers: secret ? { Authorization: `Bearer ${secret}` } : {},
+ }).then((r) => r.status);
+ try {
+ // Past the address's 250 a quarter-hour: none counted, none stopped.
+ const budget = [];
+ for (let i = 0; i < 260; i += 1) {
+ budget.push(await call('POST', '/internal/chat/budget/reserve', 'chat-secret'));
+ }
+ expect(new Set(budget)).toEqual(new Set([200]));
+
+ // The same address without the secret still gets its 250…
+ const plain = [];
+ for (let i = 0; i < 250; i += 1) plain.push(await call('GET', '/internal/ai-usage'));
+ expect(new Set(plain)).toEqual(new Set([200]));
+ // …then is stopped, on the budget path without the secret, with a wrong
+ // one, and on another internal path with the right one.
+ expect(await call('POST', '/internal/chat/budget/reserve')).toBe(429);
+ expect(await call('POST', '/internal/chat/budget/reserve', 'nope')).toBe(429);
+ expect(await call('GET', '/internal/ai-usage', 'chat-secret')).toBe(429);
+ // The secret's budget calls go on.
+ expect(await call('POST', '/internal/chat/budget/reserve', 'chat-secret')).toBe(200);
+ } finally {
+ await new Promise((resolve) => server.close(resolve));
+ }
+ });
+});
diff --git a/server/src/routes/internal-chat-budget.js b/server/src/routes/internal-chat-budget.js
new file mode 100644
index 000000000..1bc95430a
--- /dev/null
+++ b/server/src/routes/internal-chat-budget.js
@@ -0,0 +1,142 @@
+/**
+ * Chat's model steps on the AI budget (lib/chat-budget.js), for the web's
+ * Chat engine (web/src/lib/chat/budget.ts). Server to server: CRON_SECRET
+ * auth, as the other internal endpoints; the web passes the workspace it
+ * checked the person against.
+ *
+ * POST /api/internal/chat/budget/reserve
+ * { orgId, runId, stepId?, feature?, model, inputTokens, maxOutputTokens, ownKey? }
+ * → 201 { usageId }: the step's row, its worst case held (on Ansvisor's key).
+ * → 429 ai_limit { trial }: the budget can't cover the step; it doesn't start.
+ * → 402 plan_limit: no active plan. 404 not_found: the run isn't the
+ * workspace's. 403 chat_off: Chat is off for the workspace.
+ * POST /api/internal/chat/budget/charge { orgId, usageId, model, usage }
+ * → 200: the row holds the step's real cost. 404 when it is gone.
+ * POST /api/internal/chat/budget/release { orgId, usageId }
+ * → 200: the hold went (nothing was billed). Safe to repeat.
+ * A step a Stop aborted calls neither: its hold stays as its cost.
+ *
+ * Dollars never leave the server: no answer carries one. Calls with the
+ * secret aren't counted by the API's per-IP limiter (isInternalChatBudgetCall
+ * in middleware/rate-limiter.js): each step makes two, from the web's few
+ * shared addresses.
+ */
+
+import { Router } from 'express';
+import { z } from 'zod';
+import {
+ CHAT_BUDGET_FEATURES,
+ ChatBudgetError,
+ chargeChatStep,
+ releaseChatStep,
+ reserveChatStep,
+} from '../lib/chat-budget.js';
+import { PlanLimitError } from '../lib/plan-guard.js';
+
+const router = Router();
+
+router.use((req, res, next) => {
+ const secret = req.headers.authorization?.replace('Bearer ', '');
+ if (!process.env.CRON_SECRET || secret !== process.env.CRON_SECRET) {
+ return res.status(401).json({ success: false, message: 'Unauthorized' });
+ }
+ return next();
+});
+
+/** Token counts as the AI SDK reports them, capped well past any model's window. */
+const tokens = z.number().int().min(0).max(10_000_000);
+const model = z.string().trim().min(1).max(200);
+
+const reserveSchema = z.strictObject({
+ orgId: z.guid(),
+ runId: z.guid(),
+ stepId: z.guid().nullish(),
+ feature: z.enum(CHAT_BUDGET_FEATURES).default('chat'),
+ model,
+ inputTokens: tokens,
+ maxOutputTokens: tokens.min(1),
+ ownKey: z.boolean().default(false),
+});
+
+const chargeSchema = z.strictObject({
+ orgId: z.guid(),
+ usageId: z.guid(),
+ model,
+ usage: z.strictObject({ inputTokens: tokens.optional(), outputTokens: tokens.optional() }),
+});
+
+const releaseSchema = z.strictObject({ orgId: z.guid(), usageId: z.guid() });
+
+/** The body as `schema` reads it, or null once a 400 is sent. */
+function parse(schema, req, res) {
+ const parsed = schema.safeParse(req.body ?? {});
+ if (parsed.success) return parsed.data;
+ res.status(400).json({ success: false, error: 'invalid_request', message: 'Invalid request' });
+ return null;
+}
+
+function fail(err, req, res, what) {
+ if (err instanceof ChatBudgetError) {
+ return res
+ .status(err.statusCode)
+ .json({ success: false, error: err.code, message: err.message });
+ }
+ if (err instanceof PlanLimitError) {
+ // 429: the budget is used up (in the free trial, the trial's); 402: no active plan.
+ return err.statusCode === 429
+ ? res.status(429).json({
+ success: false,
+ error: 'ai_limit',
+ trial: err.trial === true,
+ message: err.message,
+ })
+ : res
+ .status(err.statusCode)
+ .json({ success: false, error: 'plan_limit', message: err.message });
+ }
+ req.log.error({ err }, `internal chat budget ${what} error`);
+ return res.status(500).json({ success: false, message: 'Internal error' });
+}
+
+router.post('/reserve', async (req, res) => {
+ const body = parse(reserveSchema, req, res);
+ if (!body) return undefined;
+ try {
+ const usageId = await reserveChatStep(body.orgId, {
+ feature: body.feature,
+ modelId: body.model,
+ inputTokens: body.inputTokens,
+ maxOutputTokens: body.maxOutputTokens,
+ runId: body.runId,
+ stepId: body.stepId ?? null,
+ ownKey: body.ownKey,
+ });
+ return res.status(201).json({ success: true, usageId });
+ } catch (err) {
+ return fail(err, req, res, 'reserve');
+ }
+});
+
+router.post('/charge', async (req, res) => {
+ const body = parse(chargeSchema, req, res);
+ if (!body) return undefined;
+ try {
+ await chargeChatStep(body.orgId, body.usageId, { modelId: body.model, usage: body.usage });
+ return res.json({ success: true });
+ } catch (err) {
+ return fail(err, req, res, 'charge');
+ }
+});
+
+router.post('/release', async (req, res) => {
+ const body = parse(releaseSchema, req, res);
+ if (!body) return undefined;
+ try {
+ await releaseChatStep(body.orgId, body.usageId);
+ return res.json({ success: true });
+ } catch (err) {
+ return fail(err, req, res, 'release');
+ }
+});
+
+export default router;
diff --git a/server/src/routes/internal-chat-budget.test.js b/server/src/routes/internal-chat-budget.test.js
new file mode 100644
index 000000000..b08850627
--- /dev/null
+++ b/server/src/routes/internal-chat-budget.test.js
@@ -0,0 +1,203 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import express from 'express';
+
+/**
+ * The web's Chat engine asks for a step's hold, then charges it or lets it
+ * go, server to server with CRON_SECRET; bodies are checked before anything
+ * runs, and answers carry no dollars.
+ */
+
+const ORG = '22222222-2222-4222-8222-222222222222';
+const RUN = '0b6c2f2e-6a43-4c55-9f0e-3f4f1d2a7c01';
+const STEP = '0b6c2f2e-6a43-4c55-9f0e-3f4f1d2a7c02';
+const USAGE = '0b6c2f2e-6a43-4c55-9f0e-3f4f1d2a7c03';
+
+class PlanLimitError extends Error {
+ constructor(message, statusCode = 403) {
+ super(message);
+ this.statusCode = statusCode;
+ }
+}
+class ChatBudgetError extends Error {
+ constructor(code, statusCode, message) {
+ super(message);
+ this.code = code;
+ this.statusCode = statusCode;
+ }
+}
+
+const reserveChatStep = vi.fn();
+const chargeChatStep = vi.fn();
+const releaseChatStep = vi.fn();
+vi.mock('../lib/plan-guard.js', () => ({ PlanLimitError }));
+vi.mock('../lib/chat-budget.js', () => ({
+ CHAT_BUDGET_FEATURES: ['chat', 'agent', 'schedule', 'image'],
+ ChatBudgetError,
+ reserveChatStep: (...args) => reserveChatStep(...args),
+ chargeChatStep: (...args) => chargeChatStep(...args),
+ releaseChatStep: (...args) => releaseChatStep(...args),
+}));
+
+const { default: router } = await import('./internal-chat-budget.js');
+
+let server;
+let baseUrl;
+
+beforeEach(async () => {
+ vi.stubEnv('CRON_SECRET', 'shh');
+ reserveChatStep.mockReset().mockResolvedValue(USAGE);
+ chargeChatStep.mockReset().mockResolvedValue(undefined);
+ releaseChatStep.mockReset().mockResolvedValue(undefined);
+ const app = express();
+ app.use(express.json());
+ app.use((req, _res, next) => {
+ req.log = { error: vi.fn() };
+ next();
+ });
+ app.use('/api/internal/chat/budget', router);
+ await new Promise((resolve) => {
+ server = app.listen(0, resolve);
+ });
+ baseUrl = `http://127.0.0.1:${server.address().port}/api/internal/chat/budget`;
+});
+
+afterEach(async () => {
+ vi.unstubAllEnvs();
+ await new Promise((resolve) => server.close(resolve));
+});
+
+const post = (path, body, secret = 'shh') =>
+ fetch(`${baseUrl}/${path}`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${secret}` },
+ body: JSON.stringify(body),
+ });
+
+const reserveBody = (over = {}) => ({
+ orgId: ORG,
+ runId: RUN,
+ stepId: STEP,
+ model: 'anthropic/claude-sonnet-5.5',
+ inputTokens: 4200,
+ maxOutputTokens: 2000,
+ ...over,
+});
+
+describe('POST /api/internal/chat/budget/*', () => {
+ it('answers only the web, with its secret', async () => {
+ for (const path of ['reserve', 'charge', 'release']) {
+ expect((await post(path, reserveBody(), 'nope')).status).toBe(401);
+ }
+ vi.stubEnv('CRON_SECRET', '');
+ expect((await post('reserve', reserveBody(), '')).status).toBe(401);
+ expect(reserveChatStep).not.toHaveBeenCalled();
+ });
+
+ it('holds a step and answers its row, a Chat step on Ansvisor’s key unless it says otherwise', async () => {
+ const res = await post('reserve', reserveBody());
+ expect(res.status).toBe(201);
+ expect(await res.json()).toEqual({ success: true, usageId: USAGE });
+ expect(reserveChatStep).toHaveBeenCalledWith(ORG, {
+ feature: 'chat',
+ modelId: 'anthropic/claude-sonnet-5.5',
+ inputTokens: 4200,
+ maxOutputTokens: 2000,
+ runId: RUN,
+ stepId: STEP,
+ ownKey: false,
+ });
+
+ await post('reserve', reserveBody({ stepId: undefined, feature: 'image', ownKey: true }));
+ expect(reserveChatStep).toHaveBeenLastCalledWith(
+ ORG,
+ expect.objectContaining({ feature: 'image', stepId: null, ownKey: true }),
+ );
+ });
+
+ it('refuses a body it can’t read before holding anything', async () => {
+ for (const body of [
+ reserveBody({ orgId: 'o1' }),
+ reserveBody({ runId: undefined }),
+ reserveBody({ feature: 'content' }),
+ reserveBody({ maxOutputTokens: 0 }),
+ reserveBody({ inputTokens: -1 }),
+ reserveBody({ model: '' }),
+ // A cost the web works out is never taken: the server prices the step.
+ reserveBody({ costUsd: 0 }),
+ ]) {
+ const res = await post('reserve', body);
+ expect(res.status).toBe(400);
+ expect(await res.json()).toMatchObject({ error: 'invalid_request' });
+ }
+ expect(reserveChatStep).not.toHaveBeenCalled();
+ });
+
+ it('says the budget is used up, and whether it is the free trial’s', async () => {
+ const used = new PlanLimitError("The free trial's AI usage is used up.", 429);
+ used.trial = true;
+ reserveChatStep.mockRejectedValueOnce(used);
+ let res = await post('reserve', reserveBody());
+ expect(res.status).toBe(429);
+ expect(await res.json()).toMatchObject({ error: 'ai_limit', trial: true });
+
+ reserveChatStep.mockRejectedValueOnce(new PlanLimitError('used up', 429));
+ res = await post('reserve', reserveBody());
+ expect(await res.json()).toMatchObject({ error: 'ai_limit', trial: false });
+
+ reserveChatStep.mockRejectedValueOnce(new PlanLimitError('no plan', 402));
+ res = await post('reserve', reserveBody());
+ expect(res.status).toBe(402);
+ expect(await res.json()).toMatchObject({ error: 'plan_limit' });
+
+ reserveChatStep.mockRejectedValueOnce(
+ new ChatBudgetError('not_found', 404, 'Chat run not found.'),
+ );
+ res = await post('reserve', reserveBody());
+ expect(res.status).toBe(404);
+ expect(await res.json()).toMatchObject({ error: 'not_found' });
+
+ reserveChatStep.mockRejectedValueOnce(new ChatBudgetError('chat_off', 403, 'Chat is off.'));
+ res = await post('reserve', reserveBody());
+ expect(res.status).toBe(403);
+ expect(await res.json()).toMatchObject({ error: 'chat_off' });
+ });
+
+ it('charges a step its usage, and lets a hold go', async () => {
+ let res = await post('charge', {
+ orgId: ORG,
+ usageId: USAGE,
+ model: 'anthropic/claude-sonnet-5.5',
+ usage: { inputTokens: 4000, outputTokens: 800 },
+ });
+ expect(res.status).toBe(200);
+ expect(chargeChatStep).toHaveBeenCalledWith(ORG, USAGE, {
+ modelId: 'anthropic/claude-sonnet-5.5',
+ usage: { inputTokens: 4000, outputTokens: 800 },
+ });
+ // A cost from the web is never taken.
+ res = await post('charge', {
+ orgId: ORG,
+ usageId: USAGE,
+ model: 'm',
+ usage: { inputTokens: 1, costUsd: 0 },
+ });
+ expect(res.status).toBe(400);
+
+ res = await post('release', { orgId: ORG, usageId: USAGE });
+ expect(res.status).toBe(200);
+ expect(releaseChatStep).toHaveBeenCalledWith(ORG, USAGE);
+ expect((await post('release', { orgId: ORG })).status).toBe(400);
+ });
+
+ it('hides what went wrong inside', async () => {
+ chargeChatStep.mockRejectedValueOnce(new Error('relation does not exist'));
+ const res = await post('charge', {
+ orgId: ORG,
+ usageId: USAGE,
+ model: 'm',
+ usage: {},
+ });
+ expect(res.status).toBe(500);
+ expect(await res.json()).toEqual({ success: false, message: 'Internal error' });
+ });
+});
diff --git a/server/src/server.js b/server/src/server.js
index fac563443..a85b984ff 100644
--- a/server/src/server.js
+++ b/server/src/server.js
@@ -25,6 +25,7 @@ import trafficRoutes from './routes/traffic.js';
import botIngestRoutes from './routes/bot-ingest.js';
import cloroCallbackRoutes from './routes/cloro-callback.js';
import internalTriggerTrackingRoutes from './routes/internal-trigger-tracking.js';
+import internalChatBudgetRoutes from './routes/internal-chat-budget.js';
import { pruneBotEvents } from './lib/bot-ingest.js';
import { pruneContentVersions } from './lib/content-history.js';
import {
@@ -614,6 +615,12 @@ app.get('/api/internal/integrations-config', (req, res) => {
return res.json({ success: true, config: integrationsConfig() });
});
+// --- Internal Chat budget endpoints (CRON_SECRET auth, called by the web's Chat engine) ---
+// Each model step of a Chat run is held on the workspace's AI budget before it
+// starts, then charged at its real cost or let go (routes/internal-chat-budget.js).
+// With the secret, the /api limiter above doesn't count them (rate-limiter.js).
+app.use('/api/internal/chat/budget', internalChatBudgetRoutes);
+
// --- Internal Improve send endpoint (CRON_SECRET auth, called by web MCP layer) ---
// The web MCP layer verifies the caller's `ans_` API key org owns the prompt
// before reaching here and passes the key's user, so this endpoint trusts the
diff --git a/supabase/migrations/00405_chat_ai_budget.sql b/supabase/migrations/00405_chat_ai_budget.sql
new file mode 100644
index 000000000..d1d30a813
--- /dev/null
+++ b/supabase/migrations/00405_chat_ai_budget.sql
@@ -0,0 +1,286 @@
+-- ============================================================================
+-- 00405: Chat's model steps on the workspace's one AI budget
+-- ============================================================================
+-- Chat (CHAT-04 §C items 11–14, CHAT-16 items 22, 26, 28–30; DECISIONS P),
+-- behind CHAT_AGENTIC: with the flag on, a Chat run calls models on
+-- Ansvisor's key and each model step draws on the workspace's monthly AI
+-- budget (plan.limits.improveMonthlyBudgetUsd), the one Improve, the Content
+-- Editor's AI and the Action Center's task writer already share
+-- (prompt_improve_usage, 00120 / 00242 / 00243). A step costs what the model
+-- costs (1x); the margin on purchased AI credits (CHAT-16 30a) is not here.
+--
+-- * feature: 'chat' (a Chat run's model step), and the room the next ones
+-- need: 'agent' (CHAT-21), 'schedule' (CHAT-12) and 'image' (CHAT-15).
+-- * own_key: the step ran on the workspace's own provider key (CHAT-16
+-- item 26). Its row is written, with its cost, so every step has one,
+-- but the provider bills the workspace: it never counts toward the
+-- budget. Every sum of the budget leaves it out (the two functions
+-- below, and the server's reads in plan-guard.js).
+-- * chat_run_id, chat_run_step_id: the run, and the step when it has one,
+-- the row was for (00400). A deleted run or step leaves its rows, named
+-- by neither: what was spent stays spent.
+-- * reserve_chat_ai_usage: a step's hold before it starts. Stricter than
+-- reserve_ai_usage (00243), which lets a call start while anything is
+-- left: a Chat step starts only when the period's spend, holds in flight
+-- included, plus the step's worst case stays within the budget (CHAT-04
+-- item 13), so runs at once can't pass it. The same per-organization
+-- lock as reserve_ai_usage, so Chat and the other features queue on one
+-- budget.
+-- * organizations.legacy_key_grandfathered: a Starter workspace (or one
+-- in its free trial) that saved its own key before Chat drew on the
+-- budget keeps using it (CHAT-16 item 28): own keys are otherwise
+-- Growth's and Enterprise's. Set here for those with a key now; the web
+-- sets it for one that saves a key while Chat is still off for it. Only
+-- the server writes it (the guard below).
+
+-- ─── What a row was for ─────────────────────────────────────────────────────
+
+alter table public.prompt_improve_usage
+ drop constraint if exists prompt_improve_usage_feature_check;
+alter table public.prompt_improve_usage
+ add constraint prompt_improve_usage_feature_check
+ check (
+ feature is null
+ or feature in (
+ 'improve', 'content', 'action_center', 'quality', 'chat', 'agent', 'schedule', 'image'
+ )
+ );
+
+comment on column public.prompt_improve_usage.feature is
+ 'What the AI call was for: improve (the Improve tab), content (the Content Editor''s AI), action_center (the task writer), quality (the Content Editor''s Quality checks, 00264), chat (a Chat run''s model step, 00405), agent, schedule or image (Chat''s agents, scheduled runs and images). Null on rows from before 00242 whose prompt, draft or action was deleted.';
+
+alter table public.prompt_improve_usage
+ add column if not exists own_key boolean not null default false;
+
+comment on column public.prompt_improve_usage.own_key is
+ 'The call ran on the workspace''s own provider key (CHAT-16 item 26): the provider bills the workspace, so the row never counts toward the AI budget.';
+
+alter table public.prompt_improve_usage
+ add column if not exists chat_run_id uuid
+ references public.chat_runs(id) on delete set null;
+alter table public.prompt_improve_usage
+ add column if not exists chat_run_step_id uuid
+ references public.chat_run_steps(id) on delete set null;
+
+comment on column public.prompt_improve_usage.chat_run_id is
+ 'The Chat run whose model step this row is (00405). Null for other features, and once the run is deleted.';
+comment on column public.prompt_improve_usage.chat_run_step_id is
+ 'The run''s step the model call was for, when it had one. Null otherwise, and once the step is deleted.';
+
+-- A run's rows, for its cost; and what a deleted run or step looks up.
+create index if not exists prompt_improve_usage_chat_run_idx
+ on public.prompt_improve_usage (chat_run_id)
+ where chat_run_id is not null;
+create index if not exists prompt_improve_usage_chat_run_step_idx
+ on public.prompt_improve_usage (chat_run_step_id)
+ where chat_run_step_id is not null;
+
+-- ─── The budget's sums leave own-key rows out ───────────────────────────────
+
+-- 00243's, with own-key rows left out of the spend.
+create or replace function public.reserve_ai_usage(
+ p_organization_id uuid,
+ p_since timestamptz,
+ p_budget numeric,
+ p_cost numeric,
+ p_feature text,
+ p_model text,
+ p_prompt_id uuid default null,
+ p_action_id uuid default null,
+ p_content_draft_id uuid default null
+)
+returns uuid
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+ v_spent numeric;
+ v_id uuid;
+begin
+ -- One reservation at a time per organization: the next waits and sees this one.
+ perform pg_advisory_xact_lock(hashtext('ai_usage:' || p_organization_id::text));
+
+ select coalesce(sum(cost_usd), 0) into v_spent
+ from public.prompt_improve_usage
+ where organization_id = p_organization_id
+ and used_at >= p_since
+ and not own_key;
+
+ if v_spent >= p_budget then
+ return null;
+ end if;
+
+ insert into public.prompt_improve_usage (
+ organization_id, feature, model, prompt_id, action_id, content_draft_id, cost_usd)
+ values (
+ p_organization_id, p_feature, p_model, p_prompt_id, p_action_id, p_content_draft_id,
+ greatest(p_cost, 0))
+ returning id into v_id;
+ return v_id;
+end;
+$$;
+
+-- 00242's, with own-key rows left out: they never move the meter.
+create or replace function public.ai_usage_by_feature(
+ p_organization_id uuid,
+ p_since timestamptz
+)
+returns table (feature text, cost_usd numeric)
+language sql
+stable
+security definer
+set search_path = public
+as $$
+ select coalesce(u.feature, 'other') as feature, sum(u.cost_usd) as cost_usd
+ from public.prompt_improve_usage u
+ where u.organization_id = p_organization_id
+ and u.used_at >= p_since
+ and not u.own_key
+ group by 1;
+$$;
+
+-- ─── A Chat step's hold ─────────────────────────────────────────────────────
+
+-- Writes the step's row and returns its id; the server turns it into the
+-- step's real cost once the model answers, or deletes it when nothing was
+-- billed. Null when the budget can't cover the step's worst case (p_cost).
+-- On the workspace's own key (p_own_key), or with no budget to hold against
+-- (p_budget null: self-hosted), the row is written without a check. The run
+-- must be the organization's, and the step, when named, the run's.
+create or replace function public.reserve_chat_ai_usage(
+ p_organization_id uuid,
+ p_chat_run_id uuid,
+ p_chat_run_step_id uuid,
+ p_feature text,
+ p_model text,
+ p_cost numeric,
+ p_own_key boolean,
+ p_since timestamptz,
+ p_budget numeric
+)
+returns uuid
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+ v_spent numeric;
+ v_id uuid;
+begin
+ if p_feature is null or p_feature not in ('chat', 'agent', 'schedule', 'image') then
+ raise exception 'not a Chat feature: %', p_feature using errcode = '22023';
+ end if;
+
+ if not exists (
+ select 1
+ from public.chat_runs r
+ join public.chat_conversations c on c.id = r.conversation_id
+ where r.id = p_chat_run_id
+ and c.organization_id = p_organization_id
+ ) or (
+ p_chat_run_step_id is not null
+ and not exists (
+ select 1 from public.chat_run_steps s
+ where s.id = p_chat_run_step_id and s.run_id = p_chat_run_id
+ )
+ ) then
+ raise exception 'chat run not found' using errcode = 'P0002';
+ end if;
+
+ if not coalesce(p_own_key, false) and p_budget is not null then
+ -- The lock reserve_ai_usage takes: one hold at a time per organization.
+ perform pg_advisory_xact_lock(hashtext('ai_usage:' || p_organization_id::text));
+
+ select coalesce(sum(cost_usd), 0) into v_spent
+ from public.prompt_improve_usage
+ where organization_id = p_organization_id
+ and used_at >= p_since
+ and not own_key;
+
+ if v_spent >= p_budget or v_spent + greatest(p_cost, 0) > p_budget then
+ return null;
+ end if;
+ end if;
+
+ insert into public.prompt_improve_usage (
+ organization_id, feature, model, cost_usd, own_key, chat_run_id, chat_run_step_id)
+ values (
+ p_organization_id, p_feature, p_model, greatest(p_cost, 0), coalesce(p_own_key, false),
+ p_chat_run_id, p_chat_run_step_id)
+ returning id into v_id;
+ return v_id;
+end;
+$$;
+
+comment on function public.reserve_chat_ai_usage(uuid, uuid, uuid, text, text, numeric, boolean, timestamptz, numeric) is
+ 'Holds a Chat step''s worst-case cost (p_cost) on its organization''s AI budget under the per-organization lock, only while the period''s spend since p_since (own-key rows left out, holds in flight in) plus p_cost stays within p_budget; returns the row to settle, or null. Own-key steps and an unlimited budget (null) write the row unchecked.';
+
+revoke all on function public.reserve_chat_ai_usage(uuid, uuid, uuid, text, text, numeric, boolean, timestamptz, numeric)
+ from public, anon, authenticated;
+grant execute on function public.reserve_chat_ai_usage(uuid, uuid, uuid, text, text, numeric, boolean, timestamptz, numeric)
+ to service_role;
+
+-- ─── Starter keys saved before Chat drew on the budget ──────────────────────
+
+alter table public.organizations
+ add column if not exists legacy_key_grandfathered boolean not null default false;
+
+comment on column public.organizations.legacy_key_grandfathered is
+ 'CHAT-16 item 28: a Starter workspace (or a Growth one in its free trial) that saved its own AI key before Chat drew on the AI budget keeps using that key for Chat. Set by 00405 and, while Chat is off for the workspace, when it saves a key; server only.';
+
+update public.organizations o
+set legacy_key_grandfathered = true
+where (o.plan = 'starter' or (o.plan = 'growth' and o.subscription_status = 'trialing'))
+ and exists (select 1 from public.organization_ai_keys k where k.organization_id = o.id);
+
+-- 00276's guard, with the new column the server's too: a member can't mark
+-- their own workspace.
+create or replace function public.guard_organization_server_columns()
+returns trigger
+language plpgsql
+set search_path = ''
+as $$
+begin
+ if (select rolbypassrls from pg_catalog.pg_roles where rolname = current_user) then
+ return new;
+ end if;
+
+ if tg_op = 'INSERT' then
+ if new.plan is distinct from 'free'
+ or new.plan_overrides is not null
+ or new.subscription_status is distinct from 'incomplete'
+ or new.subscription_ends_at is not null
+ or new.stripe_customer_id is not null
+ or new.stripe_subscription_id is not null
+ or new.anthropic_api_key_encrypted is not null
+ or new.anthropic_api_key_last4 is not null
+ or new.anthropic_api_key_set_at is not null
+ or new.anthropic_api_key_set_by is not null
+ or new.legacy_key_grandfathered is distinct from false
+ then
+ raise exception 'organization column is managed server-side and cannot be set from the client'
+ using errcode = '42501';
+ end if;
+ return new;
+ end if;
+
+ if new.plan is distinct from old.plan
+ or new.plan_overrides is distinct from old.plan_overrides
+ or new.subscription_status is distinct from old.subscription_status
+ or new.subscription_ends_at is distinct from old.subscription_ends_at
+ or new.stripe_customer_id is distinct from old.stripe_customer_id
+ or new.stripe_subscription_id is distinct from old.stripe_subscription_id
+ or new.anthropic_api_key_encrypted is distinct from old.anthropic_api_key_encrypted
+ or new.anthropic_api_key_last4 is distinct from old.anthropic_api_key_last4
+ or new.anthropic_api_key_set_at is distinct from old.anthropic_api_key_set_at
+ or new.anthropic_api_key_set_by is distinct from old.anthropic_api_key_set_by
+ or new.legacy_key_grandfathered is distinct from old.legacy_key_grandfathered
+ then
+ raise exception 'organization column is managed server-side and cannot be set from the client'
+ using errcode = '42501';
+ end if;
+
+ return new;
+end;
+$$;
diff --git a/supabase/schema.sql b/supabase/schema.sql
index 1f69c6c90..7aaf12a2e 100644
--- a/supabase/schema.sql
+++ b/supabase/schema.sql
@@ -45336,3 +45336,293 @@ alter table public.chat_model_prices enable row level security;
revoke all on table public.chat_model_prices from anon, authenticated;
grant all on table public.chat_model_prices to service_role;
+-- ─────────────────────────────────────────────────────────────────────────
+-- migrations/00405_chat_ai_budget.sql
+-- ─────────────────────────────────────────────────────────────────────────
+-- ============================================================================
+-- 00405: Chat's model steps on the workspace's one AI budget
+-- ============================================================================
+-- Chat (CHAT-04 §C items 11–14, CHAT-16 items 22, 26, 28–30; DECISIONS P),
+-- behind CHAT_AGENTIC: with the flag on, a Chat run calls models on
+-- Ansvisor's key and each model step draws on the workspace's monthly AI
+-- budget (plan.limits.improveMonthlyBudgetUsd), the one Improve, the Content
+-- Editor's AI and the Action Center's task writer already share
+-- (prompt_improve_usage, 00120 / 00242 / 00243). A step costs what the model
+-- costs (1x); the margin on purchased AI credits (CHAT-16 30a) is not here.
+--
+-- * feature: 'chat' (a Chat run's model step), and the room the next ones
+-- need: 'agent' (CHAT-21), 'schedule' (CHAT-12) and 'image' (CHAT-15).
+-- * own_key: the step ran on the workspace's own provider key (CHAT-16
+-- item 26). Its row is written, with its cost, so every step has one,
+-- but the provider bills the workspace: it never counts toward the
+-- budget. Every sum of the budget leaves it out (the two functions
+-- below, and the server's reads in plan-guard.js).
+-- * chat_run_id, chat_run_step_id: the run, and the step when it has one,
+-- the row was for (00400). A deleted run or step leaves its rows, named
+-- by neither: what was spent stays spent.
+-- * reserve_chat_ai_usage: a step's hold before it starts. Stricter than
+-- reserve_ai_usage (00243), which lets a call start while anything is
+-- left: a Chat step starts only when the period's spend, holds in flight
+-- included, plus the step's worst case stays within the budget (CHAT-04
+-- item 13), so runs at once can't pass it. The same per-organization
+-- lock as reserve_ai_usage, so Chat and the other features queue on one
+-- budget.
+-- * organizations.legacy_key_grandfathered: a Starter workspace (or one
+-- in its free trial) that saved its own key before Chat drew on the
+-- budget keeps using it (CHAT-16 item 28): own keys are otherwise
+-- Growth's and Enterprise's. Set here for those with a key now; the web
+-- sets it for one that saves a key while Chat is still off for it. Only
+-- the server writes it (the guard below).
+
+-- ─── What a row was for ─────────────────────────────────────────────────────
+
+alter table public.prompt_improve_usage
+ drop constraint if exists prompt_improve_usage_feature_check;
+alter table public.prompt_improve_usage
+ add constraint prompt_improve_usage_feature_check
+ check (
+ feature is null
+ or feature in (
+ 'improve', 'content', 'action_center', 'quality', 'chat', 'agent', 'schedule', 'image'
+ )
+ );
+
+comment on column public.prompt_improve_usage.feature is
+ 'What the AI call was for: improve (the Improve tab), content (the Content Editor''s AI), action_center (the task writer), quality (the Content Editor''s Quality checks, 00264), chat (a Chat run''s model step, 00405), agent, schedule or image (Chat''s agents, scheduled runs and images). Null on rows from before 00242 whose prompt, draft or action was deleted.';
+
+alter table public.prompt_improve_usage
+ add column if not exists own_key boolean not null default false;
+
+comment on column public.prompt_improve_usage.own_key is
+ 'The call ran on the workspace''s own provider key (CHAT-16 item 26): the provider bills the workspace, so the row never counts toward the AI budget.';
+
+alter table public.prompt_improve_usage
+ add column if not exists chat_run_id uuid
+ references public.chat_runs(id) on delete set null;
+alter table public.prompt_improve_usage
+ add column if not exists chat_run_step_id uuid
+ references public.chat_run_steps(id) on delete set null;
+
+comment on column public.prompt_improve_usage.chat_run_id is
+ 'The Chat run whose model step this row is (00405). Null for other features, and once the run is deleted.';
+comment on column public.prompt_improve_usage.chat_run_step_id is
+ 'The run''s step the model call was for, when it had one. Null otherwise, and once the step is deleted.';
+
+-- A run's rows, for its cost; and what a deleted run or step looks up.
+create index if not exists prompt_improve_usage_chat_run_idx
+ on public.prompt_improve_usage (chat_run_id)
+ where chat_run_id is not null;
+create index if not exists prompt_improve_usage_chat_run_step_idx
+ on public.prompt_improve_usage (chat_run_step_id)
+ where chat_run_step_id is not null;
+
+-- ─── The budget's sums leave own-key rows out ───────────────────────────────
+
+-- 00243's, with own-key rows left out of the spend.
+create or replace function public.reserve_ai_usage(
+ p_organization_id uuid,
+ p_since timestamptz,
+ p_budget numeric,
+ p_cost numeric,
+ p_feature text,
+ p_model text,
+ p_prompt_id uuid default null,
+ p_action_id uuid default null,
+ p_content_draft_id uuid default null
+)
+returns uuid
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+ v_spent numeric;
+ v_id uuid;
+begin
+ -- One reservation at a time per organization: the next waits and sees this one.
+ perform pg_advisory_xact_lock(hashtext('ai_usage:' || p_organization_id::text));
+
+ select coalesce(sum(cost_usd), 0) into v_spent
+ from public.prompt_improve_usage
+ where organization_id = p_organization_id
+ and used_at >= p_since
+ and not own_key;
+
+ if v_spent >= p_budget then
+ return null;
+ end if;
+
+ insert into public.prompt_improve_usage (
+ organization_id, feature, model, prompt_id, action_id, content_draft_id, cost_usd)
+ values (
+ p_organization_id, p_feature, p_model, p_prompt_id, p_action_id, p_content_draft_id,
+ greatest(p_cost, 0))
+ returning id into v_id;
+ return v_id;
+end;
+$$;
+
+-- 00242's, with own-key rows left out: they never move the meter.
+create or replace function public.ai_usage_by_feature(
+ p_organization_id uuid,
+ p_since timestamptz
+)
+returns table (feature text, cost_usd numeric)
+language sql
+stable
+security definer
+set search_path = public
+as $$
+ select coalesce(u.feature, 'other') as feature, sum(u.cost_usd) as cost_usd
+ from public.prompt_improve_usage u
+ where u.organization_id = p_organization_id
+ and u.used_at >= p_since
+ and not u.own_key
+ group by 1;
+$$;
+
+-- ─── A Chat step's hold ─────────────────────────────────────────────────────
+
+-- Writes the step's row and returns its id; the server turns it into the
+-- step's real cost once the model answers, or deletes it when nothing was
+-- billed. Null when the budget can't cover the step's worst case (p_cost).
+-- On the workspace's own key (p_own_key), or with no budget to hold against
+-- (p_budget null: self-hosted), the row is written without a check. The run
+-- must be the organization's, and the step, when named, the run's.
+create or replace function public.reserve_chat_ai_usage(
+ p_organization_id uuid,
+ p_chat_run_id uuid,
+ p_chat_run_step_id uuid,
+ p_feature text,
+ p_model text,
+ p_cost numeric,
+ p_own_key boolean,
+ p_since timestamptz,
+ p_budget numeric
+)
+returns uuid
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+ v_spent numeric;
+ v_id uuid;
+begin
+ if p_feature is null or p_feature not in ('chat', 'agent', 'schedule', 'image') then
+ raise exception 'not a Chat feature: %', p_feature using errcode = '22023';
+ end if;
+
+ if not exists (
+ select 1
+ from public.chat_runs r
+ join public.chat_conversations c on c.id = r.conversation_id
+ where r.id = p_chat_run_id
+ and c.organization_id = p_organization_id
+ ) or (
+ p_chat_run_step_id is not null
+ and not exists (
+ select 1 from public.chat_run_steps s
+ where s.id = p_chat_run_step_id and s.run_id = p_chat_run_id
+ )
+ ) then
+ raise exception 'chat run not found' using errcode = 'P0002';
+ end if;
+
+ if not coalesce(p_own_key, false) and p_budget is not null then
+ -- The lock reserve_ai_usage takes: one hold at a time per organization.
+ perform pg_advisory_xact_lock(hashtext('ai_usage:' || p_organization_id::text));
+
+ select coalesce(sum(cost_usd), 0) into v_spent
+ from public.prompt_improve_usage
+ where organization_id = p_organization_id
+ and used_at >= p_since
+ and not own_key;
+
+ if v_spent >= p_budget or v_spent + greatest(p_cost, 0) > p_budget then
+ return null;
+ end if;
+ end if;
+
+ insert into public.prompt_improve_usage (
+ organization_id, feature, model, cost_usd, own_key, chat_run_id, chat_run_step_id)
+ values (
+ p_organization_id, p_feature, p_model, greatest(p_cost, 0), coalesce(p_own_key, false),
+ p_chat_run_id, p_chat_run_step_id)
+ returning id into v_id;
+ return v_id;
+end;
+$$;
+
+comment on function public.reserve_chat_ai_usage(uuid, uuid, uuid, text, text, numeric, boolean, timestamptz, numeric) is
+ 'Holds a Chat step''s worst-case cost (p_cost) on its organization''s AI budget under the per-organization lock, only while the period''s spend since p_since (own-key rows left out, holds in flight in) plus p_cost stays within p_budget; returns the row to settle, or null. Own-key steps and an unlimited budget (null) write the row unchecked.';
+
+revoke all on function public.reserve_chat_ai_usage(uuid, uuid, uuid, text, text, numeric, boolean, timestamptz, numeric)
+ from public, anon, authenticated;
+grant execute on function public.reserve_chat_ai_usage(uuid, uuid, uuid, text, text, numeric, boolean, timestamptz, numeric)
+ to service_role;
+
+-- ─── Starter keys saved before Chat drew on the budget ──────────────────────
+
+alter table public.organizations
+ add column if not exists legacy_key_grandfathered boolean not null default false;
+
+comment on column public.organizations.legacy_key_grandfathered is
+ 'CHAT-16 item 28: a Starter workspace (or a Growth one in its free trial) that saved its own AI key before Chat drew on the AI budget keeps using that key for Chat. Set by 00405 and, while Chat is off for the workspace, when it saves a key; server only.';
+
+update public.organizations o
+set legacy_key_grandfathered = true
+where (o.plan = 'starter' or (o.plan = 'growth' and o.subscription_status = 'trialing'))
+ and exists (select 1 from public.organization_ai_keys k where k.organization_id = o.id);
+
+-- 00276's guard, with the new column the server's too: a member can't mark
+-- their own workspace.
+create or replace function public.guard_organization_server_columns()
+returns trigger
+language plpgsql
+set search_path = ''
+as $$
+begin
+ if (select rolbypassrls from pg_catalog.pg_roles where rolname = current_user) then
+ return new;
+ end if;
+
+ if tg_op = 'INSERT' then
+ if new.plan is distinct from 'free'
+ or new.plan_overrides is not null
+ or new.subscription_status is distinct from 'incomplete'
+ or new.subscription_ends_at is not null
+ or new.stripe_customer_id is not null
+ or new.stripe_subscription_id is not null
+ or new.anthropic_api_key_encrypted is not null
+ or new.anthropic_api_key_last4 is not null
+ or new.anthropic_api_key_set_at is not null
+ or new.anthropic_api_key_set_by is not null
+ or new.legacy_key_grandfathered is distinct from false
+ then
+ raise exception 'organization column is managed server-side and cannot be set from the client'
+ using errcode = '42501';
+ end if;
+ return new;
+ end if;
+
+ if new.plan is distinct from old.plan
+ or new.plan_overrides is distinct from old.plan_overrides
+ or new.subscription_status is distinct from old.subscription_status
+ or new.subscription_ends_at is distinct from old.subscription_ends_at
+ or new.stripe_customer_id is distinct from old.stripe_customer_id
+ or new.stripe_subscription_id is distinct from old.stripe_subscription_id
+ or new.anthropic_api_key_encrypted is distinct from old.anthropic_api_key_encrypted
+ or new.anthropic_api_key_last4 is distinct from old.anthropic_api_key_last4
+ or new.anthropic_api_key_set_at is distinct from old.anthropic_api_key_set_at
+ or new.anthropic_api_key_set_by is distinct from old.anthropic_api_key_set_by
+ or new.legacy_key_grandfathered is distinct from old.legacy_key_grandfathered
+ then
+ raise exception 'organization column is managed server-side and cannot be set from the client'
+ using errcode = '42501';
+ end if;
+
+ return new;
+end;
+$$;
+
diff --git a/web/.env.example b/web/.env.example
index b79bbf904..55cdc2c12 100644
--- a/web/.env.example
+++ b/web/.env.example
@@ -78,6 +78,10 @@ NEXT_PUBLIC_CONTENT_QUALITY_PHASE=
# to the same values.
# CHAT_AGENTIC_ORGS: with Chat on, only these organizations (ids,
# comma-separated); empty = every organization.
+# With Chat on, a workspace without its own key (own keys: Growth and
+# Enterprise, or a Starter key saved before) runs Chat on ANTHROPIC_API_KEY
+# above, and each model step draws on its monthly AI budget through the
+# server's internal endpoints (CRON_SECRET below).
# -----------------------------------------------------------------------------
CHAT_AGENTIC=
CHAT_AGENTIC_ORGS=
diff --git a/web/messages/en.json b/web/messages/en.json
index e5d56575b..209a1f650 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -55,6 +55,14 @@
"exhaustedTrial": "You've used the free trial's AI usage. Starting the plan gives its full monthly allowance; Agent Chat on your own AI key keeps working."
}
},
+ "chatBudget": {
+ "ai_limit": "You've used this month's AI limit, so Chat stopped here. What's done so far is kept.",
+ "ai_limit_trial": "Your trial AI limit is used up, so Chat stopped here. What's done so far is kept.",
+ "plan_limit": "This workspace's plan isn't active, so Chat can't run. Choose a plan to use it again.",
+ "not_found": "This chat's work is gone. Ask your question again.",
+ "chat_off": "Chat isn't on for this workspace.",
+ "unavailable": "Chat couldn't check your AI usage just now, so it didn't start this step. Try again in a moment."
+ },
"readOnly": {
"banner": {
"ended": "Your workspace is read-only. You can look around; adding, running and AI need a plan.",
@@ -10031,6 +10039,7 @@
"aiUsageMeter": {
"title": "This period's AI usage",
"description": "Improve suggestions, the Content Editor's AI and the Action Center's task writing share your plan's monthly AI allowance.",
+ "descriptionChat": "Chat, Improve suggestions, the Content Editor's AI and the Action Center's task writing share your plan's monthly AI allowance.",
"used": "{percent} used",
"resets": "Resets on {date}",
"exhausted": "This period's AI usage is used up. AI features resume on {date}.",
@@ -10041,10 +10050,15 @@
"improve": "Improve suggestions",
"content": "Content Editor (briefs, Content Agent, quality checks)",
"action_center": "Action Center task writing",
+ "chat": "Chat",
+ "agent": "Agents",
+ "schedule": "Scheduled runs",
+ "image": "Images",
"other": "Other"
},
"none": "No AI usage yet this period.",
"chat": "Agent Chat runs on your own AI key, so it doesn't use this allowance.",
+ "chatMetered": "Chat uses this allowance too. Chat on your own AI key isn't counted.",
"failed": "Couldn't read this period's AI usage. Try again later."
},
"cancelsOn": "Subscription ends on {date}",
diff --git a/web/src/app/api/settings/ai-providers/route.test.ts b/web/src/app/api/settings/ai-providers/route.test.ts
index 4afa7dbaf..c349c5cc1 100644
--- a/web/src/app/api/settings/ai-providers/route.test.ts
+++ b/web/src/app/api/settings/ai-providers/route.test.ts
@@ -41,7 +41,7 @@ vi.mock('@/lib/supabase/admin', () => ({
queries.push(query);
const settle = () => Promise.resolve(results.shift() ?? { data: null, error: null });
const chain: Record<string, unknown> = {};
- for (const op of ['select', 'eq', 'upsert', 'update', 'delete', 'order', 'limit']) {
+ for (const op of ['select', 'eq', 'or', 'upsert', 'update', 'delete', 'order', 'limit']) {
chain[op] = (...args: unknown[]) => {
query.calls.push([op, ...args]);
return chain;
@@ -82,6 +82,12 @@ beforeEach(() => {
queries.length = 0;
results = [];
rpc.mockReset().mockResolvedValue({ data: true, error: null });
+ // Chat off, as today: a saved key is marked to keep working once it is on.
+ vi.stubEnv('CHAT_AGENTIC', 'false');
+});
+
+afterEach(() => {
+ vi.unstubAllEnvs();
});
describe('GET', () => {
@@ -193,7 +199,27 @@ describe('PUT', () => {
p_provider: 'azure',
p_only_if_none: true,
});
- // Only an Anthropic key has an old copy to clear.
+ // Only an Anthropic key has an old copy to clear; the workspace is marked
+ // to keep its key for Chat (below).
+ expect(queries.map((q) => q.table)).toEqual(['organization_ai_keys', 'organizations']);
+ });
+
+ it('marks a Starter or trial workspace to keep its key for Chat while Chat is off', async () => {
+ expect((await PUT(send('PUT', { provider: 'openai', apiKey: KEY }))).status).toBe(200);
+ const mark = queries[queries.length - 1];
+ expect(mark.table).toBe('organizations');
+ expect(mark.calls).toEqual([
+ ['update', { legacy_key_grandfathered: true }],
+ ['eq', 'id', 'org1'],
+ // Only where its plan wouldn't include own keys (CHAT-16 item 28).
+ ['or', 'plan.eq.starter,and(plan.eq.growth,subscription_status.eq.trialing)'],
+ ]);
+ });
+
+ it('marks nothing once Chat is on: own keys are then Growth’s and Enterprise’s', async () => {
+ vi.stubEnv('CHAT_AGENTIC', 'true');
+ vi.stubEnv('CHAT_AGENTIC_ORGS', '');
+ expect((await PUT(send('PUT', { provider: 'openai', apiKey: KEY }))).status).toBe(200);
expect(queries.map((q) => q.table)).toEqual(['organization_ai_keys']);
});
diff --git a/web/src/app/api/settings/ai-providers/route.ts b/web/src/app/api/settings/ai-providers/route.ts
index 18573423e..f93680c6c 100644
--- a/web/src/app/api/settings/ai-providers/route.ts
+++ b/web/src/app/api/settings/ai-providers/route.ts
@@ -4,6 +4,7 @@ import { supabaseAdmin } from '@/lib/supabase/admin';
import { writeRefusal } from '@/lib/subscription-guard';
import { encryptApiKey, last4 } from '@/lib/agent/key-encryption';
import { isAiProvider, parseProviderSettings, type AiProvider } from '@/lib/agent/providers';
+import { chatAgenticEnabled } from '@/lib/chat/flag';
/**
* GET / PUT / PATCH / DELETE /api/settings/ai-providers
@@ -95,6 +96,21 @@ async function clearLegacyAnthropicKey(organizationId: string) {
.eq('id', organizationId);
}
+/**
+ * A key saved while Chat is still off for the workspace keeps working for
+ * Chat once it is on, on Starter or in a Growth free trial too (CHAT-16 item
+ * 28; 00405 marked the workspaces that had one then). With Chat on, own
+ * keys are Growth's and Enterprise's (lib/chat/key.ts), so nothing is marked.
+ */
+async function markLegacyKey(organizationId: string) {
+ if (chatAgenticEnabled(organizationId)) return { error: null };
+ return supabaseAdmin
+ .from('organizations')
+ .update({ legacy_key_grandfathered: true })
+ .eq('id', organizationId)
+ .or('plan.eq.starter,and(plan.eq.growth,subscription_status.eq.trialing)');
+}
+
export async function GET() {
const ctx = await getCallerAndOrg();
if ('error' in ctx) {
@@ -213,6 +229,10 @@ export async function PUT(req: Request) {
return NextResponse.json({ error: legacyError.message }, { status: 500 });
}
}
+ const { error: markError } = await markLegacyKey(organizationId);
+ if (markError) {
+ return NextResponse.json({ error: markError.message }, { status: 500 });
+ }
return NextResponse.json({ ok: true });
}
diff --git a/web/src/components/settings/ai-usage-card.test.tsx b/web/src/components/settings/ai-usage-card.test.tsx
index 323068912..a3819d53f 100644
--- a/web/src/components/settings/ai-usage-card.test.tsx
+++ b/web/src/components/settings/ai-usage-card.test.tsx
@@ -102,6 +102,41 @@ describe('AiUsageCard', () => {
expect(container.textContent).not.toContain('No AI usage yet');
});
+ it('gives Chat its row in percent, and says it uses the allowance, once Chat is on', async () => {
+ vi.mocked(getAiUsage).mockResolvedValue(
+ usage({
+ chatMetered: true,
+ percentUsed: 20.5,
+ features: [
+ { feature: 'content', percent: 12.5 },
+ { feature: 'chat', percent: 8 },
+ ],
+ }),
+ );
+ await render();
+ const text = container.textContent ?? '';
+ expect([...container.querySelectorAll('li')].map((li) => li.textContent)).toEqual([
+ 'Content Editor (briefs, Content Agent, quality checks)12.5%',
+ 'Chat8%',
+ ]);
+ expect(text).toContain("Chat, Improve suggestions, the Content Editor's AI");
+ expect(text).toContain("Chat uses this allowance too. Chat on your own AI key isn't counted.");
+ expect(text).not.toContain('Agent Chat runs on your own AI key');
+ // Shares only: no dollar figure reaches the page.
+ expect(text).not.toContain('$');
+ });
+
+ it('keeps today’s line on Agent Chat while Chat is off', async () => {
+ vi.mocked(getAiUsage).mockResolvedValue(usage({ chatMetered: false }));
+ await render();
+ const text = container.textContent ?? '';
+ expect(text).toContain("Agent Chat runs on your own AI key, so it doesn't use this allowance.");
+ expect(text).toContain(
+ "Improve suggestions, the Content Editor's AI and the Action Center's task writing share",
+ );
+ expect(text).not.toContain('Chat uses this allowance too');
+ });
+
it('says nothing has used it yet, in place of the list', async () => {
vi.mocked(getAiUsage).mockResolvedValue(usage({ percentUsed: 0, features: [] }));
await render();
diff --git a/web/src/components/settings/ai-usage-card.tsx b/web/src/components/settings/ai-usage-card.tsx
index e035ff471..03b45957f 100644
--- a/web/src/components/settings/ai-usage-card.tsx
+++ b/web/src/components/settings/ai-usage-card.tsx
@@ -24,9 +24,10 @@ const BAR_CLASS: Record<UsageTone, string> = {
/**
* This period's AI usage on the Billing page: how much of the plan's
* monthly AI allowance the workspace has used, what used it, and when it
- * renews. Agent Chat runs on the workspace's own AI key, so it is a line
- * of text, not a share. Renders nothing for a plan without an allowance,
- * or a workspace without an active plan.
+ * renews. With Chat on for the workspace (`chatMetered`), Chat draws on it
+ * too and has its row; off, Agent Chat runs on the workspace's own AI key,
+ * so it is a line of text, not a share. Renders nothing for a plan without
+ * an allowance, or a workspace without an active plan.
*/
export function AiUsageCard() {
const t = useTranslations('settings.aiUsageMeter');
@@ -75,7 +76,9 @@ export function AiUsageCard() {
<Card id="ai-usage" ref={card} className="scroll-mt-6">
<CardHeader>
<CardTitle>{t('title')}</CardTitle>
- <CardDescription>{t('description')}</CardDescription>
+ <CardDescription>
+ {t(usage?.chatMetered ? 'descriptionChat' : 'description')}
+ </CardDescription>
</CardHeader>
<CardContent className="space-y-4">
{failed ? (
@@ -137,7 +140,9 @@ export function AiUsageCard() {
) : (
<p className="text-sm text-muted-foreground">{t('none')}</p>
)}
- <p className="text-xs text-muted-foreground">{t('chat')}</p>
+ <p className="text-xs text-muted-foreground">
+ {t(usage.chatMetered ? 'chatMetered' : 'chat')}
+ </p>
</>
)}
</CardContent>
diff --git a/web/src/lib/billing/ai-usage.ts b/web/src/lib/billing/ai-usage.ts
index 9f835ab0b..0c4e0f979 100644
--- a/web/src/lib/billing/ai-usage.ts
+++ b/web/src/lib/billing/ai-usage.ts
@@ -10,7 +10,20 @@ import { USAGE_WARNING_RATIO, type UsageTone } from '@/lib/content-usage';
* only decides how they read.
*/
-export const AI_USAGE_FEATURES = ['improve', 'content', 'action_center', 'other'] as const;
+/**
+ * The meter's rows, in order: Chat's (00405) only with Chat on for the
+ * workspace, its agents, scheduled runs and images as they come.
+ */
+export const AI_USAGE_FEATURES = [
+ 'improve',
+ 'content',
+ 'action_center',
+ 'chat',
+ 'agent',
+ 'schedule',
+ 'image',
+ 'other',
+] as const;
export type AiUsageFeature = (typeof AI_USAGE_FEATURES)[number];
export interface AiUsage {
@@ -30,6 +43,11 @@ export interface AiUsage {
* percent comes as 0, read with featurePercentLabel.
*/
features: { feature: AiUsageFeature; percent: number }[];
+ /**
+ * Chat draws on the allowance too (CHAT_AGENTIC on for the workspace;
+ * missing from an older API: off). Off, it runs on the workspace's own key.
+ */
+ chatMetered?: boolean;
}
/** A count against its plan's limit this period. */
diff --git a/web/src/lib/chat/budget.test.ts b/web/src/lib/chat/budget.test.ts
new file mode 100644
index 000000000..dd8559340
--- /dev/null
+++ b/web/src/lib/chat/budget.test.ts
@@ -0,0 +1,241 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+ RESERVE_TIMEOUT_MS,
+ reserveChatStep,
+ type ChatBudgetStep,
+ type ChatStepBudget,
+ type ChatStepReservation,
+} from './budget';
+
+/**
+ * The Chat engine's side of the AI budget: a hold before each model step,
+ * then exactly one of charge, release or keep, through the API's internal
+ * endpoints. Nothing throws; a step that can't be held doesn't start, and
+ * says why. With Chat off nothing is asked.
+ */
+
+const ORG = '22222222-2222-4222-8222-222222222222';
+const RUN = '0b6c2f2e-6a43-4c55-9f0e-3f4f1d2a7c01';
+const STEP = '0b6c2f2e-6a43-4c55-9f0e-3f4f1d2a7c02';
+const USAGE = '0b6c2f2e-6a43-4c55-9f0e-3f4f1d2a7c03';
+
+type Call = { path: string; body: Record<string, unknown>; auth: string | null; timed: boolean };
+let calls: Call[];
+/** What each call answers, in order; a function throws (no answer). */
+let answers: ({ status: number; body: unknown } | (() => never))[];
+
+beforeEach(() => {
+ vi.stubEnv('CHAT_AGENTIC', 'true');
+ vi.stubEnv('CHAT_AGENTIC_ORGS', '');
+ vi.stubEnv('CRON_SECRET', 'shh');
+ calls = [];
+ answers = [];
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async (url: string, init: RequestInit) => {
+ calls.push({
+ path: url.replace(/^.*\/api\/internal\/chat\/budget\//, ''),
+ body: JSON.parse(String(init.body)),
+ auth: (init.headers as Record<string, string>).Authorization ?? null,
+ timed: init.signal instanceof AbortSignal,
+ });
+ const next = answers.shift() ?? { status: 200, body: { success: true } };
+ if (typeof next === 'function') next();
+ const { status, body } = next as { status: number; body: unknown };
+ return new Response(JSON.stringify(body), { status });
+ }),
+ );
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+});
+
+afterEach(() => {
+ vi.unstubAllEnvs();
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ vi.useRealTimers();
+});
+
+const step = (over: Partial<ChatBudgetStep> = {}): ChatBudgetStep => ({
+ organizationId: ORG,
+ runId: RUN,
+ stepId: STEP,
+ model: 'anthropic/claude-sonnet-5.5',
+ inputTokens: 4199.2,
+ maxOutputTokens: 2000,
+ source: 'ansvisor',
+ ...over,
+});
+
+const held = () => {
+ answers.push({ status: 201, body: { success: true, usageId: USAGE } });
+};
+
+function budgetOf(r: ChatStepReservation): ChatStepBudget {
+ if (!r.ok) throw new Error(`refused: ${r.refusal}`);
+ return r.budget;
+}
+
+describe('reserveChatStep', () => {
+ it('holds the step, then charges the same row with its usage: one row a step', async () => {
+ held();
+ const budget = budgetOf(await reserveChatStep(step()));
+ expect(calls[0]).toEqual({
+ path: 'reserve',
+ auth: 'Bearer shh',
+ timed: true,
+ body: {
+ orgId: ORG,
+ runId: RUN,
+ stepId: STEP,
+ feature: 'chat',
+ model: 'anthropic/claude-sonnet-5.5',
+ // Counted up, never down.
+ inputTokens: 4200,
+ maxOutputTokens: 2000,
+ ownKey: false,
+ },
+ });
+ // No cost goes from here: the server prices the step.
+ expect(JSON.stringify(calls[0].body)).not.toMatch(/cost|usd/i);
+
+ await budget.charge({ inputTokens: 4000, outputTokens: 700 });
+ await budget.release();
+ expect(calls.slice(1)).toEqual([
+ {
+ path: 'charge',
+ auth: 'Bearer shh',
+ timed: true,
+ body: {
+ orgId: ORG,
+ usageId: USAGE,
+ model: 'anthropic/claude-sonnet-5.5',
+ usage: { inputTokens: 4000, outputTokens: 700 },
+ },
+ },
+ ]);
+ });
+
+ it('charges a step that called the model again with what it used in all', async () => {
+ held();
+ const budget = budgetOf(await reserveChatStep(step()));
+ await budget.charge({ inputTokens: 1000, outputTokens: 100 });
+ await budget.charge({ inputTokens: 1200, outputTokens: 300 });
+ expect(calls[2].body.usage).toEqual({ inputTokens: 2200, outputTokens: 400 });
+ });
+
+ it('sends no counts the provider didn’t report, so the hold stays as the cost', async () => {
+ held();
+ const budget = budgetOf(await reserveChatStep(step()));
+ await budget.charge({});
+ expect(calls[1].body.usage).toEqual({});
+ });
+
+ it('lets the hold go when the step failed before the model billed anything', async () => {
+ held();
+ const budget = budgetOf(await reserveChatStep(step()));
+ await budget.release();
+ await budget.release();
+ expect(calls.map((c) => c.path)).toEqual(['reserve', 'release']);
+ expect(calls[1].body).toEqual({ orgId: ORG, usageId: USAGE });
+ });
+
+ it('keeps the hold as the cost of a call a Stop aborted: nothing is let go', async () => {
+ held();
+ const budget = budgetOf(await reserveChatStep(step()));
+ budget.keep();
+ await budget.release();
+ expect(calls.map((c) => c.path)).toEqual(['reserve']);
+ });
+
+ it('marks a step on the workspace’s own key, still writing its row', async () => {
+ held();
+ budgetOf(await reserveChatStep(step({ source: 'own', feature: 'image', stepId: null })));
+ expect(calls[0].body).toMatchObject({ ownKey: true, feature: 'image', stepId: null });
+ });
+
+ it('says the AI limit is used up, in the trial’s words in the free trial, and starts nothing', async () => {
+ answers.push({ status: 429, body: { success: false, error: 'ai_limit', trial: false } });
+ expect(await reserveChatStep(step())).toEqual({
+ ok: false,
+ refusal: 'ai_limit',
+ trial: false,
+ retryable: false,
+ message:
+ "You've used this month's AI limit, so Chat stopped here. What's done so far is kept.",
+ });
+ answers.push({ status: 429, body: { success: false, error: 'ai_limit', trial: true } });
+ expect(await reserveChatStep(step())).toMatchObject({
+ refusal: 'ai_limit',
+ trial: true,
+ message: "Your trial AI limit is used up, so Chat stopped here. What's done so far is kept.",
+ });
+ answers.push({ status: 402, body: { success: false, error: 'plan_limit' } });
+ expect(await reserveChatStep(step())).toMatchObject({ ok: false, refusal: 'plan_limit' });
+ });
+
+ it('starts nothing when the API doesn’t answer in time or answers 502, and says to try again', async () => {
+ answers.push(() => {
+ throw new DOMException('The operation timed out.', 'TimeoutError');
+ });
+ const timedOut = await reserveChatStep(step());
+ expect(timedOut).toEqual({
+ ok: false,
+ refusal: 'unavailable',
+ trial: false,
+ retryable: true,
+ message:
+ "Chat couldn't check your AI usage just now, so it didn't start this step. Try again in a moment.",
+ });
+ // Asked once: a hold whose answer was lost would hold twice.
+ expect(calls).toHaveLength(1);
+
+ answers.push({ status: 502, body: null });
+ expect(await reserveChatStep(step())).toMatchObject({
+ ok: false,
+ refusal: 'unavailable',
+ retryable: true,
+ });
+ answers.push({ status: 500, body: { success: false, message: 'Internal error' } });
+ expect(await reserveChatStep(step())).toMatchObject({
+ refusal: 'unavailable',
+ retryable: false,
+ });
+ expect(RESERVE_TIMEOUT_MS).toBeLessThanOrEqual(5_000);
+ });
+
+ it('starts nothing, and doesn’t throw, without CRON_SECRET', async () => {
+ vi.stubEnv('CRON_SECRET', '');
+ expect(await reserveChatStep(step())).toMatchObject({ ok: false, refusal: 'unavailable' });
+ expect(calls).toEqual([]);
+ });
+
+ it('settles once more after a 502, and never throws when it can’t', async () => {
+ held();
+ const budget = budgetOf(await reserveChatStep(step()));
+ answers.push({ status: 502, body: null }, { status: 200, body: { success: true } });
+ await budget.charge({ inputTokens: 10, outputTokens: 10 });
+ expect(calls.map((c) => c.path)).toEqual(['reserve', 'charge', 'charge']);
+
+ held();
+ const other = budgetOf(await reserveChatStep(step()));
+ answers.push(
+ () => {
+ throw new TypeError('fetch failed');
+ },
+ () => {
+ throw new TypeError('fetch failed');
+ },
+ );
+ await expect(other.release()).resolves.toBeUndefined();
+ expect(calls.map((c) => c.path).slice(3)).toEqual(['reserve', 'release', 'release']);
+ });
+
+ it('holds nothing and writes nothing while Chat is off: today’s Agent Chat', async () => {
+ vi.stubEnv('CHAT_AGENTIC', 'false');
+ const budget = budgetOf(await reserveChatStep(step()));
+ await budget.charge({ inputTokens: 10, outputTokens: 10 });
+ budget.keep();
+ await budget.release();
+ expect(calls).toEqual([]);
+ });
+});
diff --git a/web/src/lib/chat/budget.ts b/web/src/lib/chat/budget.ts
new file mode 100644
index 000000000..5fcfe5c6c
--- /dev/null
+++ b/web/src/lib/chat/budget.ts
@@ -0,0 +1,249 @@
+import { createTranslator } from 'next-intl';
+import messages from '../../../messages/en.json';
+import { API_BASE_URL } from '@/config/api';
+import { chatAgenticEnabled } from './flag';
+import type { ChatKeySource } from './key';
+
+/**
+ * A Chat model step on the workspace's one AI budget (CHAT-04 §C items
+ * 11–14, CHAT-16 items 26, 29–30), for the Chat engine: before each model
+ * step, reserveChatStep holds the step's worst case on the budget, and the
+ * step then ends with exactly one of
+ * - charge(usage): it answered; the hold becomes its real cost (1x);
+ * - release(): it failed before the model billed anything; the hold goes;
+ * - keep(): it was sent and then aborted (the run's Stop); the provider
+ * bills it all the same, so the hold stays as its cost.
+ * The server keeps the ledger and prices every step (server/src/lib/
+ * chat-budget.js, through /api/internal/chat/budget): dollars never pass
+ * through here, and none goes to a browser.
+ *
+ * Every step writes one usage row, on either key (lib/chat/key.ts): on
+ * Ansvisor's it counts toward the budget, on the workspace's own it is
+ * marked and never counts. With CHAT_AGENTIC off for the workspace nothing is
+ * held or written: today's Agent Chat runs on the workspace's own key only.
+ *
+ * Nothing here throws: a step that can't be held comes back as a refusal,
+ * with the words to show, and doesn't start; settling one that fails is
+ * logged and leaves the hold at the step's worst case (over, never under).
+ * Every call to the API has a short time limit, so an API that doesn't
+ * answer (a 502 while it restarts) can't hang a run. Server code only
+ * (CRON_SECRET).
+ */
+
+export const CHAT_BUDGET_FEATURES = ['chat', 'agent', 'schedule', 'image'] as const;
+export type ChatBudgetFeature = (typeof CHAT_BUDGET_FEATURES)[number];
+
+/** What a model step used, as the AI SDK reports it. */
+export interface ChatStepUsage {
+ inputTokens?: number;
+ outputTokens?: number;
+}
+
+export interface ChatBudgetStep {
+ organizationId: string;
+ runId: string;
+ /** The run's step the call is for, when it has one. */
+ stepId?: string | null;
+ /** 'chat' unless the step is an agent's, a scheduled run's or an image. */
+ feature?: ChatBudgetFeature;
+ /** The model's catalog id ("anthropic/claude-sonnet-5.5"), as the server prices it. */
+ model: string;
+ /**
+ * The step's prompt in tokens, counted up rather than down: the hold
+ * assumes no prompt-cache hit, so a miss can't pass the budget.
+ */
+ inputTokens: number;
+ /** The step's max output tokens: the most it may write. */
+ maxOutputTokens: number;
+ /** Whose key the step runs on (resolveChatModelKey). */
+ source: ChatKeySource;
+}
+
+/**
+ * Why a step can't start: the budget can't cover it (ai_limit; CHAT-04 item
+ * 17's card, the trial's own words in the free trial), no active plan
+ * (plan_limit), a run that isn't the workspace's (not_found), Chat off on
+ * the server (chat_off), or the API didn't answer in time (unavailable).
+ */
+export const CHAT_BUDGET_REFUSALS = [
+ 'ai_limit',
+ 'plan_limit',
+ 'not_found',
+ 'chat_off',
+ 'unavailable',
+] as const;
+export type ChatBudgetRefusal = (typeof CHAT_BUDGET_REFUSALS)[number];
+
+/** A held step, settled once by charge, release or keep. */
+export interface ChatStepBudget {
+ /** The step answered: its usage, priced on the server. */
+ charge(usage: ChatStepUsage): Promise<void>;
+ /** Nothing was billed: the hold goes. A no-op once charged or kept; call it in a finally. */
+ release(): Promise<void>;
+ /** A Stop aborted the call the provider still bills: the hold stays as its cost. */
+ keep(): void;
+}
+
+export type ChatStepReservation =
+ | { ok: true; budget: ChatStepBudget }
+ | {
+ ok: false;
+ refusal: ChatBudgetRefusal;
+ /** The free trial's budget is the one used up. */
+ trial: boolean;
+ /** Asking again may help: the API didn't answer, or said it was down. */
+ retryable: boolean;
+ /** What to tell the person, from messages/en.json (chatBudget). */
+ message: string;
+ };
+
+/** How long a hold may take before the step is given up: a run waits on it. */
+export const RESERVE_TIMEOUT_MS = 5_000;
+/** How long settling a step may take, each try. */
+export const SETTLE_TIMEOUT_MS = 5_000;
+/** The wait before settling once more, after no answer or a 502–504. */
+export const SETTLE_RETRY_DELAY_MS = 500;
+
+const t = createTranslator({ locale: 'en', messages, namespace: 'chatBudget' });
+
+/** A refusal, with its words. */
+function refused(
+ refusal: ChatBudgetRefusal,
+ { trial = false, retryable = false }: { trial?: boolean; retryable?: boolean } = {},
+): Extract<ChatStepReservation, { ok: false }> {
+ const message = refusal === 'ai_limit' && trial ? t('ai_limit_trial') : t(refusal);
+ return { ok: false, refusal, trial, retryable, message };
+}
+
+/** With Chat off: nothing held, nothing written. */
+const UNMETERED: ChatStepBudget = {
+ async charge() {},
+ async release() {},
+ keep() {},
+};
+
+type BudgetPath = 'reserve' | 'charge' | 'release';
+
+/** The proxy's answers while the API is down or restarting. */
+const isTransient = (status: number) => status === 502 || status === 503 || status === 504;
+
+/**
+ * One call to the API's budget endpoint. Null when it didn't answer within
+ * `timeoutMs` (a dropped connection, the time limit) or CRON_SECRET isn't
+ * set; never throws.
+ */
+async function post(
+ path: BudgetPath,
+ body: Record<string, unknown>,
+ timeoutMs: number,
+): Promise<{ status: number; body: Record<string, unknown> | null } | null> {
+ const secret = process.env.CRON_SECRET;
+ if (!secret) {
+ console.error('[chat/budget] CRON_SECRET must be configured for Chat');
+ return null;
+ }
+ try {
+ const res = await fetch(`${API_BASE_URL}/api/internal/chat/budget/${path}`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${secret}` },
+ body: JSON.stringify(body),
+ cache: 'no-store',
+ signal: AbortSignal.timeout(timeoutMs),
+ });
+ return {
+ status: res.status,
+ body: (await res.json().catch(() => null)) as Record<string, unknown> | null,
+ };
+ } catch (err) {
+ console.error(`[chat/budget] ${path} got no answer:`, (err as Error)?.name ?? err);
+ return null;
+ }
+}
+
+/**
+ * Settles a held step: once more after a short wait when the API didn't
+ * answer or said it was down (both are safe to repeat: a charge sets the
+ * row, a release deletes it). A failure is logged and leaves the hold.
+ */
+async function settle(path: 'charge' | 'release', body: Record<string, unknown>) {
+ let res = await post(path, body, SETTLE_TIMEOUT_MS);
+ if (!res || isTransient(res.status)) {
+ await new Promise((resolve) => setTimeout(resolve, SETTLE_RETRY_DELAY_MS));
+ res = await post(path, body, SETTLE_TIMEOUT_MS);
+ }
+ if (res?.status !== 200) {
+ console.error(
+ `[chat/budget] ${path} failed`,
+ res?.status ?? 'no answer',
+ res?.body?.error ?? '',
+ );
+ }
+}
+
+/**
+ * Holds a model step on the workspace's AI budget before it starts. The step
+ * runs only on `ok: true`; a refusal says why, in words to show (the run
+ * then pauses at the cap, CHAT-04 item 17, or stops). Asked once, within
+ * RESERVE_TIMEOUT_MS: a hold isn't safe to repeat blindly (one taken whose
+ * answer was lost would hold twice), so an API that doesn't answer is a
+ * refusal marked retryable, and the step doesn't run unheld.
+ */
+export async function reserveChatStep(step: ChatBudgetStep): Promise<ChatStepReservation> {
+ if (!chatAgenticEnabled(step.organizationId)) return { ok: true, budget: UNMETERED };
+
+ const reserved = await post(
+ 'reserve',
+ {
+ orgId: step.organizationId,
+ runId: step.runId,
+ stepId: step.stepId ?? null,
+ feature: step.feature ?? 'chat',
+ model: step.model,
+ inputTokens: Math.max(0, Math.ceil(step.inputTokens)),
+ maxOutputTokens: Math.max(1, Math.ceil(step.maxOutputTokens)),
+ ownKey: step.source === 'own',
+ },
+ RESERVE_TIMEOUT_MS,
+ );
+ if (!reserved) return refused('unavailable', { retryable: true });
+ const usageId = reserved.body?.usageId;
+ if (reserved.status !== 201 || typeof usageId !== 'string') {
+ const code = reserved.body?.error;
+ if (typeof code === 'string' && (CHAT_BUDGET_REFUSALS as readonly string[]).includes(code)) {
+ return refused(code as ChatBudgetRefusal, { trial: reserved.body?.trial === true });
+ }
+ // A 502 while the API restarts, or an answer it shouldn't give.
+ return refused('unavailable', { retryable: isTransient(reserved.status) });
+ }
+
+ // A step that called the model again (a retry) is charged what it used in
+ // all. Counts the provider didn't report stay out: with none, the server
+ // keeps the hold as the step's cost.
+ const used: ChatStepUsage = {};
+ const add = (key: keyof ChatStepUsage, n: number | undefined) => {
+ if (typeof n === 'number' && Number.isFinite(n)) used[key] = (used[key] ?? 0) + Math.max(0, n);
+ };
+ let settled = false;
+ const budget: ChatStepBudget = {
+ async charge(usage) {
+ settled = true;
+ add('inputTokens', usage?.inputTokens);
+ add('outputTokens', usage?.outputTokens);
+ await settle('charge', {
+ orgId: step.organizationId,
+ usageId,
+ model: step.model,
+ usage: { ...used },
+ });
+ },
+ async release() {
+ if (settled) return;
+ settled = true;
+ await settle('release', { orgId: step.organizationId, usageId });
+ },
+ keep() {
+ settled = true;
+ },
+ };
+ return { ok: true, budget };
+}
diff --git a/web/src/lib/chat/key.test.ts b/web/src/lib/chat/key.test.ts
new file mode 100644
index 000000000..d0aaa320c
--- /dev/null
+++ b/web/src/lib/chat/key.test.ts
@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+/**
+ * Whose key a Chat step runs on: with Chat on, the workspace's own when its
+ * plan allows it (Growth+, or a Starter key kept from before), else
+ * Ansvisor's, which draws on the AI budget. With Chat off, today's Agent
+ * Chat: the workspace's own key or nothing on the cloud.
+ */
+
+const ORG = '22222222-2222-4222-8222-222222222222';
+
+let org: Record<string, unknown> | null;
+let ownKey: Record<string, unknown> | null;
+const reads: string[] = [];
+
+vi.mock('@/lib/supabase/admin', () => ({
+ supabaseAdmin: {
+ from: (table: string) => {
+ reads.push(table);
+ const chain = {
+ select: () => chain,
+ eq: () => chain,
+ maybeSingle: async () => ({
+ data: table === 'organizations' ? org : ownKey,
+ error: null,
+ }),
+ };
+ return chain;
+ },
+ },
+}));
+
+vi.mock('@/lib/agent/key-encryption', () => ({
+ decryptApiKey: (envelope: string) => `plain(${envelope})`,
+}));
+
+const { ownKeyAllowed, resolveChatModelKey } = await import('./key');
+
+const CUSTOMER = {
+ provider: 'openai',
+ key_encrypted: 'env1',
+ settings: { model: 'gpt-5.5' },
+};
+
+beforeEach(() => {
+ vi.stubEnv('NEXT_PUBLIC_IS_CLOUD', 'true');
+ vi.stubEnv('ANTHROPIC_API_KEY', 'ansvisor-key');
+ vi.stubEnv('CHAT_AGENTIC', 'true');
+ vi.stubEnv('CHAT_AGENTIC_ORGS', '');
+ org = { plan: 'starter', subscription_status: 'active', legacy_key_grandfathered: false };
+ ownKey = null;
+ reads.length = 0;
+});
+
+afterEach(() => {
+ vi.unstubAllEnvs();
+});
+
+const ANSVISOR = {
+ source: 'ansvisor',
+ config: { provider: 'anthropic', apiKey: 'ansvisor-key', settings: {} },
+};
+const OWN = {
+ source: 'own',
+ config: { provider: 'openai', apiKey: 'plain(env1)', settings: { model: 'gpt-5.5' } },
+};
+
+describe('ownKeyAllowed', () => {
+ it('opens own keys to Growth and Enterprise, not to Starter or a Growth trial', () => {
+ const at = (plan: string, subscription_status = 'active', legacy = false) =>
+ ownKeyAllowed({ plan, subscription_status, legacy_key_grandfathered: legacy });
+ expect(at('growth')).toBe(true);
+ expect(at('enterprise')).toBe(true);
+ expect(at('enterprise', 'trialing')).toBe(true);
+ expect(at('starter')).toBe(false);
+ expect(at('growth', 'trialing')).toBe(false);
+ // A key kept from before Chat drew on the budget (CHAT-16 item 28).
+ expect(at('starter', 'active', true)).toBe(true);
+ expect(at('growth', 'trialing', true)).toBe(true);
+ expect(ownKeyAllowed(null)).toBe(false);
+ });
+});
+
+describe('resolveChatModelKey, Chat on', () => {
+ it('runs a Growth workspace on its own key: its provider bills it', async () => {
+ org = { plan: 'growth', subscription_status: 'active', legacy_key_grandfathered: false };
+ ownKey = CUSTOMER;
+ expect(await resolveChatModelKey(ORG)).toEqual(OWN);
+ });
+
+ it('runs Starter on Ansvisor’s key, its own key saved since left aside', async () => {
+ ownKey = CUSTOMER;
+ expect(await resolveChatModelKey(ORG)).toEqual(ANSVISOR);
+ // Not even read: the plan doesn't include it.
+ expect(reads).toEqual(['organizations']);
+ });
+
+ it('keeps a Starter workspace’s key from before on its own key', async () => {
+ org = { plan: 'starter', subscription_status: 'active', legacy_key_grandfathered: true };
+ ownKey = CUSTOMER;
+ expect(await resolveChatModelKey(ORG)).toEqual(OWN);
+ });
+
+ it('falls back to Ansvisor’s key when a Growth workspace has none', async () => {
+ org = { plan: 'growth', subscription_status: 'active', legacy_key_grandfathered: false };
+ expect(await resolveChatModelKey(ORG)).toEqual(ANSVISOR);
+ });
+
+ it('runs a Growth free trial on Ansvisor’s key, as Starter', async () => {
+ org = { plan: 'growth', subscription_status: 'trialing', legacy_key_grandfathered: false };
+ ownKey = CUSTOMER;
+ expect(await resolveChatModelKey(ORG)).toEqual(ANSVISOR);
+ });
+
+ it('is null with neither key', async () => {
+ vi.stubEnv('ANTHROPIC_API_KEY', '');
+ expect(await resolveChatModelKey(ORG)).toBeNull();
+ });
+
+ it('uses the operator’s key self-hosted, where nothing is metered', async () => {
+ vi.stubEnv('NEXT_PUBLIC_IS_CLOUD', 'false');
+ expect(await resolveChatModelKey(ORG)).toEqual(ANSVISOR);
+ expect(reads).toEqual([]);
+ });
+});
+
+describe('resolveChatModelKey, Chat off', () => {
+ beforeEach(() => {
+ vi.stubEnv('CHAT_AGENTIC', 'false');
+ });
+
+ it('keeps today’s Agent Chat: the workspace’s own key, on any plan', async () => {
+ ownKey = CUSTOMER;
+ expect(await resolveChatModelKey(ORG)).toEqual(OWN);
+ // The plan isn't read: Agent Chat never looked at it.
+ expect(reads).toEqual(['organization_ai_keys']);
+ });
+
+ it('never falls back to Ansvisor’s key on the cloud', async () => {
+ org = { plan: 'growth', subscription_status: 'active', legacy_key_grandfathered: false };
+ expect(await resolveChatModelKey(ORG)).toBeNull();
+ });
+
+ it('is on for the listed workspaces only', async () => {
+ vi.stubEnv('CHAT_AGENTIC', 'true');
+ vi.stubEnv('CHAT_AGENTIC_ORGS', '33333333-3333-4333-8333-333333333333');
+ expect(await resolveChatModelKey(ORG)).toBeNull();
+ });
+});
diff --git a/web/src/lib/chat/key.ts b/web/src/lib/chat/key.ts
new file mode 100644
index 000000000..4ec7724b4
--- /dev/null
+++ b/web/src/lib/chat/key.ts
@@ -0,0 +1,86 @@
+import { supabaseAdmin } from '@/lib/supabase/admin';
+import { isCloud } from '@/config/plans';
+import { resolveAgentModelConfig } from '@/lib/agent/key';
+import type { AgentModelConfig } from '@/lib/agent/model';
+import { chatAgenticEnabled } from './flag';
+
+/**
+ * Whose key a Chat step runs on (CHAT-16 item 22, owner decision 11 of the
+ * Chat P0 plan): the workspace's own, which its provider bills, or
+ * Ansvisor's, which draws on the workspace's monthly AI budget (CHAT-04 §C,
+ * lib/chat/budget.ts). Both write the step's usage row; only Ansvisor's
+ * counts.
+ */
+export type ChatKeySource = 'own' | 'ansvisor';
+
+export interface ChatModelKey {
+ source: ChatKeySource;
+ config: AgentModelConfig;
+}
+
+/** What decides whether a workspace's own key may run Chat. */
+export interface OwnKeyOrg {
+ plan: string | null;
+ subscription_status: string | null;
+ legacy_key_grandfathered: boolean | null;
+}
+
+/**
+ * Own keys come with Growth and Enterprise (CHAT-16 item 19); not in a
+ * Growth free trial, which is locked as Starter is. Enterprise trials are a
+ * deal's, with its terms.
+ */
+export function ownKeyInPlan(org: Pick<OwnKeyOrg, 'plan' | 'subscription_status'>): boolean {
+ return (
+ org.plan === 'enterprise' || (org.plan === 'growth' && org.subscription_status !== 'trialing')
+ );
+}
+
+/**
+ * Whether Chat may run on the workspace's own key: its plan includes them,
+ * or it saved one on Starter (or in a free trial) before Chat drew on the AI
+ * budget, and keeps it (CHAT-16 item 28, organizations.legacy_key_grandfathered).
+ */
+export function ownKeyAllowed(org: OwnKeyOrg | null | undefined): boolean {
+ if (!org) return false;
+ return ownKeyInPlan(org) || org.legacy_key_grandfathered === true;
+}
+
+/**
+ * The key a Chat step runs on, in order:
+ * 1. The workspace's own (its active key in Settings › AI Providers), when
+ * its plan allows it (ownKeyAllowed): the provider bills the workspace,
+ * and the usage percent doesn't move.
+ * 2. Ansvisor's (ANTHROPIC_API_KEY; Auto is Anthropic first-party): the
+ * step draws on the workspace's AI budget.
+ * Null when neither is there. Self-hosted, the operator's own key is
+ * Ansvisor's here, with no budget to draw on (the server meters nothing).
+ *
+ * Only with CHAT_AGENTIC on for the workspace. Off, it is today's Agent
+ * Chat: on the cloud the workspace's own key or nothing, never Ansvisor's
+ * (resolveAgentModelConfig), and nothing is metered; it reads as 'own'.
+ */
+export async function resolveChatModelKey(organizationId: string): Promise<ChatModelKey | null> {
+ if (!chatAgenticEnabled(organizationId)) {
+ const config = await resolveAgentModelConfig(organizationId);
+ return config ? { source: 'own', config } : null;
+ }
+
+ if (isCloud()) {
+ const { data: org, error } = await supabaseAdmin
+ .from('organizations')
+ .select('plan, subscription_status, legacy_key_grandfathered')
+ .eq('id', organizationId)
+ .maybeSingle();
+ if (error) throw new Error(error.message);
+ if (ownKeyAllowed(org)) {
+ const own = await resolveAgentModelConfig(organizationId);
+ if (own) return { source: 'own', config: own };
+ }
+ }
+
+ const apiKey = process.env.ANTHROPIC_API_KEY;
+ return apiKey
+ ? { source: 'ansvisor', config: { provider: 'anthropic', apiKey, settings: {} } }
+ : null;
+}
diff --git a/web/src/lib/mcp/server.ts b/web/src/lib/mcp/server.ts
index 578584fe5..bf05a9a4f 100644
--- a/web/src/lib/mcp/server.ts
+++ b/web/src/lib/mcp/server.ts
@@ -2001,7 +2001,7 @@ export function createMcpServer(auth: McpAuthContext): McpServer {
{
title: 'AI usage this period',
description:
- "How much of the workspace's monthly AI allowance is used this period, as the Billing page's meter shows it: percent_used (0–100, to a tenth; the allowance is one budget that Improve suggestions, the Content Editor's AI and quality checks, and the Action Center's task writing all draw on), each feature's share (features: improve, content, action_center, other — only those that used some), the plan, whether it is the free trial's smaller allowance, and when the period started and renews. unlimited is true where nothing is metered (self-hosted); active_plan is false when the workspace has no active plan, so there is no allowance. Dollars are not shown. Use it before suggesting AI-heavy work (many Improve runs or drafts), or when asked how much AI is left.",
+ "How much of the workspace's monthly AI allowance is used this period, as the Billing page's meter shows it: percent_used (0–100, to a tenth; the allowance is one budget that Improve suggestions, the Content Editor's AI and quality checks, and the Action Center's task writing all draw on), each feature's share (features: improve, content, action_center, chat, agent, schedule, image, other — only those that used some; chat and the rest with Chat on), the plan, whether it is the free trial's smaller allowance, and when the period started and renews. unlimited is true where nothing is metered (self-hosted); active_plan is false when the workspace has no active plan, so there is no allowance. Dollars are not shown. Use it before suggesting AI-heavy work (many Improve runs or drafts), or when asked how much AI is left.",
inputSchema: {},
annotations: { readOnlyHint: true, openWorldHint: false },
},
diff --git a/web/src/types/supabase.ts b/web/src/types/supabase.ts
index a6a212ad2..7c642aec6 100644
--- a/web/src/types/supabase.ts
+++ b/web/src/types/supabase.ts
@@ -3982,6 +3982,7 @@ export type Database = {
anthropic_api_key_set_by: string | null
created_at: string
id: string
+ legacy_key_grandfathered: boolean
name: string
plan: string
plan_overrides: Json | null
@@ -3999,6 +4000,7 @@ export type Database = {
anthropic_api_key_set_by?: string | null
created_at?: string
id?: string
+ legacy_key_grandfathered?: boolean
name: string
plan?: string
plan_overrides?: Json | null
@@ -4016,6 +4018,7 @@ export type Database = {
anthropic_api_key_set_by?: string | null
created_at?: string
id?: string
+ legacy_key_grandfathered?: boolean
name?: string
plan?: string
plan_overrides?: Json | null