Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

45.6 KB
Raw Blame
// Tests for /api/llm/anthropic — we-pay LLM proxy.
// Focus: monthly token budgeting (input+output), embed-policy enforcement
// (origin, surface, brain mode), upstream error sanitization, model allowlist.

import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { Readable } from 'node:stream';

process.env.PUBLIC_APP_ORIGIN ||= 'https://app.test';
process.env.JWT_SECRET ||= 'test-secret-llm';
process.env.ANTHROPIC_API_KEY ||= 'sk-ant-test-key';
process.env.UPSTASH_REDIS_REST_URL ||= 'https://redis.test';
process.env.UPSTASH_REDIS_REST_TOKEN ||= 'redis-token';

// ── Mocks ─────────────────────────────────────────────────────────────────

const policyState = { policy: null };
const avatarPolicyState = { policy: null };
const avatarState = { avatar: null };

vi.mock('../../api/_lib/embed-policy.js', () => ({
	readEmbedPolicy: vi.fn(async () => policyState.policy),
	readEmbedPolicyByAvatarId: vi.fn(async () => avatarPolicyState.policy),
	defaultEmbedPolicy: () => JSON.parse(JSON.stringify(DEFAULT_POLICY)),
}));

vi.mock('../../api/_lib/avatars.js', () => ({
	getAvatar: vi.fn(async () => avatarState.avatar),
}));

const rlState = {
	ip: { success: true },
	agent: { success: true },
	hostKeyGlobal: { success: true },
};

vi.mock('../../api/_lib/rate-limit.js', () => ({
	limits: {
		embedLlmIp: vi.fn(async () => rlState.ip),
		embedLlmAgent: vi.fn(async () => rlState.agent),
		chatHostKeyGlobal: vi.fn(async () => rlState.hostKeyGlobal),
	},
	clientIp: () => '203.0.113.1',
}));

// Identity for the header-less (non-browser) lane. Null means anonymous, which
// is what every browser-shaped test wants.
const authState = { user: null };

vi.mock('../../api/_lib/auth.js', () => ({
	getRequestUser: vi.fn(async () => authState.user),
}));

const usageEvents = [];
vi.mock('../../api/_lib/usage.js', () => ({
	recordEvent: (evt) => usageEvents.push(evt),
	logger: () => ({ info: () => {}, warn: () => {}, error: () => {} }),
}));

// In-memory Redis stub backing the @upstash/redis client. Token + quota
// counters are kept here so tests can prime initial usage and assert deltas.
const redisStore = new Map();
const redisCalls = [];
class FakeRedis {
	constructor(_opts) {}
	async incr(key) {
		const next = (redisStore.get(key) ?? 0) + 1;
		redisStore.set(key, next);
		redisCalls.push({ op: 'incr', key, value: next });
		return next;
	}
	async incrby(key, delta) {
		const next = (redisStore.get(key) ?? 0) + delta;
		redisStore.set(key, next);
		redisCalls.push({ op: 'incrby', key, delta, value: next });
		return next;
	}
	async get(key) {
		return redisStore.get(key) ?? null;
	}
	async expire(key, ttl) {
		redisCalls.push({ op: 'expire', key, ttl });
		return 1;
	}
}

vi.mock('@upstash/redis', () => ({ Redis: FakeRedis }));

// The Vertex Gemini credits anchor mints a GCP OAuth token per request; stub
// the token exchange so anchor-lane tests need no real GCP credentials.
vi.mock('../../api/_lib/gcp-auth.js', () => ({
	getGcpAccessToken: vi.fn(async () => 'gcp-test-token'),
	gcpAuthConfigured: () => true,
	parseServiceAccount: vi.fn(),
}));

// Default upstream mock — overridden per-test as needed.
const fetchState = {
	response: () => upstreamOk({ ok: true, usage: { input_tokens: 10, output_tokens: 20 } }),
	calls: [],
};

function upstreamOk(json) {
	return {
		ok: true,
		status: 200,
		headers: new Map([['content-type', 'application/json']]),
		text: async () => JSON.stringify(json),
	};
}

function upstreamErr(status, body) {
	return {
		ok: false,
		status,
		headers: new Map([['content-type', 'application/json']]),
		text: async () => (typeof body === 'string' ? body : JSON.stringify(body)),
	};
}

// Map.get is case-sensitive but the handler reads via headers.get('content-type')
// — patch Headers-like objects to mimic native fetch Headers behavior.
function patchHeaders(map) {
	return { get: (k) => map.get(k.toLowerCase()) ?? map.get(k) ?? null };
}

globalThis.fetch = vi.fn(async (url, init) => {
	fetchState.calls.push({ url, init });
	const r = await fetchState.response();
	r.headers = patchHeaders(
		r.headers instanceof Map ? r.headers : new Map(Object.entries(r.headers || {})),
	);
	return r;
});

const {
	default: handler,
	modelFallbackChain,
	resolveModelRoute,
} = await import('../../api/llm/anthropic.js');

// Upstream that answers with an SSE body, the shape both streaming lanes read
// (`upstream.body.getReader()`); one reader chunk per array entry.
function upstreamSse(chunks) {
	const encoder = new TextEncoder();
	let i = 0;
	return {
		ok: true,
		status: 200,
		headers: new Map([['content-type', 'text/event-stream']]),
		body: {
			getReader: () => ({
				read: async () =>
					i < chunks.length
						? { done: false, value: encoder.encode(chunks[i++]) }
						: { done: true, value: undefined },
			}),
		},
		text: async () => chunks.join(''),
	};
}

// ── Helpers ───────────────────────────────────────────────────────────────

// Requests default to a first-party localhost Origin, the shape a real browser
// embed sends, so tests that aren't about the origin gate exercise the lane a
// browser actually takes. Pass `noOrigin: true` for the header-less machine lane.
function makeReq({
	url = '/api/llm/anthropic?agent=agent-1',
	headers = {},
	body = null,
	noOrigin = false,
} = {}) {
	const base = body ? Readable.from([Buffer.from(JSON.stringify(body))]) : Readable.from([]);
	const hasOrigin = 'origin' in headers || 'referer' in headers;
	base.method = 'POST';
	base.url = url;
	base.headers = {
		host: 'app.test',
		'content-type': 'application/json',
		...(hasOrigin || noOrigin ? {} : { origin: 'http://localhost:3000' }),
		...headers,
	};
	return base;
}

function makeRes() {
	return {
		statusCode: 200,
		headers: {},
		body: '',
		writableEnded: false,
		setHeader(k, v) {
			this.headers[k.toLowerCase()] = v;
		},
		getHeader(k) {
			return this.headers[k.toLowerCase()];
		},
		write(chunk) {
			this.body += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
			return true;
		},
		end(chunk) {
			if (chunk !== undefined) this.body += chunk;
			this.writableEnded = true;
		},
	};
}

async function invoke(opts = {}) {
	const req = makeReq(opts);
	const res = makeRes();
	await handler(req, res);
	const json = res.body ? safeJson(res.body) : null;
	return { res, status: res.statusCode, body: json };
}

function safeJson(s) {
	try {
		return JSON.parse(s);
	} catch {
		return s;
	}
}

const VALID_BODY = {
	messages: [{ role: 'user', content: 'hello' }],
	max_tokens: 100,
};

const WE_PAY_POLICY = {
	version: 1,
	origins: { mode: 'allowlist', hosts: ['client.test'] },
	surfaces: { script: true, iframe: true, widget: true, mcp: false },
	brain: {
		mode: 'we-pay',
		proxy_url: null,
		monthly_quota: null,
		rate_limit_per_min: null,
		model: 'claude-opus-4-6',
		cost_limit_cents: null,
	},
	storage: { primary: 'r2', pinned_ipfs: false, onchain_attested: false },
};

// Mirrors embed-policy.js defaultEmbedPolicy() — the we-pay free-model policy
// granted to bare public-avatar embeds that have no agent_identity row.
const DEFAULT_POLICY = {
	version: 1,
	origins: { mode: 'allowlist', hosts: [] },
	surfaces: { script: true, iframe: true, widget: true, mcp: false },
	brain: {
		mode: 'we-pay',
		proxy_url: null,
		monthly_quota: 1000,
		rate_limit_per_min: 10,
		model: 'google/gemma-4-31b-it:free',
	},
	storage: { primary: 'r2', pinned_ipfs: false, onchain_attested: false },
};

// ── Reset between tests ───────────────────────────────────────────────────

beforeEach(() => {
	// The Vertex Gemini credits anchor joins the fallback chain whenever
	// GOOGLE_CLOUD_PROJECT is set; clear it so chain-shape assertions here are
	// deterministic on GCP-configured machines. The anchor's own coverage lives
	// in tests/api/llm-vertex-anchor-surfaces.test.js.
	delete process.env.GOOGLE_CLOUD_PROJECT;
	policyState.policy = JSON.parse(JSON.stringify(WE_PAY_POLICY));
	avatarPolicyState.policy = null;
	avatarState.avatar = null;
	rlState.ip = { success: true };
	rlState.agent = { success: true };
	rlState.hostKeyGlobal = { success: true };
	authState.user = null;
	usageEvents.length = 0;
	redisStore.clear();
	redisCalls.length = 0;
	fetchState.calls.length = 0;
	fetchState.response = () =>
		upstreamOk({ ok: true, usage: { input_tokens: 10, output_tokens: 20 } });
});

// ── agent + policy gating ─────────────────────────────────────────────────

describe('/api/llm/anthropic — agent + policy gating', () => {
	it('rejects when no agent query param supplied', async () => {
		const { status, body } = await invoke({ url: '/api/llm/anthropic', body: VALID_BODY });
		expect(status).toBe(400);
		expect(body.error).toBe('validation_error');
	});

	it('returns 404 when no agent, avatar-agent, or public avatar matches', async () => {
		policyState.policy = null;
		avatarPolicyState.policy = null;
		avatarState.avatar = null;
		const { status, body } = await invoke({ body: VALID_BODY });
		expect(status).toBe(404);
		expect(body.error).toBe('not_found');
	});

	it('falls back to the agent_identity linked by avatar_id', async () => {
		policyState.policy = null;
		avatarPolicyState.policy = JSON.parse(JSON.stringify(WE_PAY_POLICY));
		const { status } = await invoke({ body: VALID_BODY });
		expect(status).toBe(200);
	});

	it('grants the default we-pay policy to a bare public avatar embed', async () => {
		policyState.policy = null;
		avatarPolicyState.policy = null;
		avatarState.avatar = { id: 'avatar-uuid', visibility: 'public' };
		// The default policy serves the free OpenRouter model.
		process.env.OPENROUTER_API_KEY = 'sk-or-test';
		try {
			const { status } = await invoke({ body: VALID_BODY });
			expect(status).toBe(200);
		} finally {
			delete process.env.OPENROUTER_API_KEY;
		}
	});

	it('does not grant a policy to a private avatar', async () => {
		policyState.policy = null;
		avatarPolicyState.policy = null;
		avatarState.avatar = { id: 'avatar-uuid', visibility: 'private' };
		const { status, body } = await invoke({ body: VALID_BODY });
		expect(status).toBe(404);
		expect(body.error).toBe('not_found');
	});

	it('returns 402 payment_required when brain.mode is not we-pay', async () => {
		policyState.policy.brain.mode = 'wallet-gated';
		const { status, body } = await invoke({ body: VALID_BODY });
		expect(status).toBe(402);
		expect(body.error).toBe('payment_required');
	});

	it('returns 403 embed_denied_surface when script surface is disabled', async () => {
		policyState.policy.surfaces.script = false;
		const { status, body } = await invoke({ body: VALID_BODY });
		expect(status).toBe(403);
		expect(body.error).toBe('embed_denied_surface');
	});
});

// ── origin enforcement ───────────────────────────────────────────────────

describe('/api/llm/anthropic — origin / referer policy', () => {
	it('rejects an origin not on the allowlist', async () => {
		const { status, body } = await invoke({
			body: VALID_BODY,
			headers: { origin: 'https://attacker.test' },
		});
		expect(status).toBe(403);
		expect(body.error).toBe('embed_denied_origin');
	});

	// The header's absence used to mean "allowed", which made the allowlist
	// advisory: any script could strip Origin and spend the host's provider keys
	// against a public agent id. Anonymous header-less callers are now denied.
	it('rejects an anonymous request that sends no Origin header', async () => {
		authState.user = null;
		const { status, body } = await invoke({ body: VALID_BODY, noOrigin: true });
		expect(status).toBe(403);
		expect(body.error).toBe('embed_denied_origin');
		expect(body.error_description).toMatch(/authenticate/i);
	});

	it('allows a server-to-server request that authenticates', async () => {
		authState.user = { id: 'user-1', source: 'bearer' };
		const { status } = await invoke({
			body: VALID_BODY,
			noOrigin: true,
			headers: { authorization: 'Bearer platform-key' },
		});
		expect(status).toBe(200);
	});

	// An authenticated caller still cannot launder a denied browser origin: the
	// escape hatch is only for requests that carry no Origin at all.
	it('does not let a signed-in caller override a denied Origin', async () => {
		authState.user = { id: 'user-1', source: 'bearer' };
		const { status, body } = await invoke({
			body: VALID_BODY,
			headers: { origin: 'https://attacker.test', authorization: 'Bearer platform-key' },
		});
		expect(status).toBe(403);
		expect(body.error).toBe('embed_denied_origin');
	});

	it('allows first-party localhost origin without policy entry', async () => {
		policyState.policy.origins.hosts = []; // explicitly empty
		const { status } = await invoke({
			body: VALID_BODY,
			headers: { origin: 'http://localhost:3000' },
		});
		expect(status).toBe(200);
	});
});

// ── rate limiting ────────────────────────────────────────────────────────

describe('/api/llm/anthropic — rate limiting', () => {
	it('returns 429 on per-IP rate limit', async () => {
		rlState.ip = { success: false };
		const { status, body } = await invoke({ body: VALID_BODY });
		expect(status).toBe(429);
		expect(body.error_description).toMatch(/IP/);
	});

	it('returns 429 on per-agent rate limit when policy declares one', async () => {
		policyState.policy.brain.rate_limit_per_min = 5;
		rlState.agent = { success: false };
		const { status, body } = await invoke({ body: VALID_BODY });
		expect(status).toBe(429);
		expect(body.error_description).toMatch(/agent rate limit/);
	});
});

// ── monthly call-count quota ─────────────────────────────────────────────

describe('/api/llm/anthropic — monthly call quota', () => {
	it('returns 429 quota_exceeded once monthly_quota is reached', async () => {
		policyState.policy.brain.monthly_quota = 2;
		// Pre-seed the call counter so the next incr crosses the quota.
		const monthKey = new Date().toISOString().slice(0, 7);
		redisStore.set(`llm:quota:agent-1:${monthKey}`, 2);
		const { status, body } = await invoke({ body: VALID_BODY });
		expect(status).toBe(429);
		expect(body.error).toBe('quota_exceeded');
		expect(body.error_description).toMatch(/monthly quota of 2/);
	});

	it('passes through when under monthly_quota', async () => {
		policyState.policy.brain.monthly_quota = 100;
		const { status } = await invoke({ body: VALID_BODY });
		expect(status).toBe(200);
	});
});

// ── monthly token budget ────────────────────────────────────────────────

describe('/api/llm/anthropic — monthly token budget', () => {
	it('returns 429 quota_exceeded when token budget already met (default budget)', async () => {
		const monthKey = new Date().toISOString().slice(0, 7);
		// Default budget is 1_000_000 — pre-seed at the cap.
		redisStore.set(`llm:tokens:agent-1:${monthKey}`, 1_000_000);
		const { status, body } = await invoke({ body: VALID_BODY });
		expect(status).toBe(429);
		expect(body.error).toBe('quota_exceeded');
		expect(body.error_description).toMatch(/monthly token budget/);
	});

	it('derives a smaller token budget from policy.brain.cost_limit_cents', async () => {
		// 15 cents @ 1.5¢/1k tokens = 10_000-token budget.
		policyState.policy.brain.cost_limit_cents = 15;
		const monthKey = new Date().toISOString().slice(0, 7);
		redisStore.set(`llm:tokens:agent-1:${monthKey}`, 10_000);
		const { status, body } = await invoke({ body: VALID_BODY });
		expect(status).toBe(429);
		expect(body.error_description).toMatch(/10000/);
	});

	it('debits actual token usage to the per-agent counter on success', async () => {
		fetchState.response = () =>
			upstreamOk({ ok: true, usage: { input_tokens: 123, output_tokens: 456 } });
		const { status } = await invoke({ body: VALID_BODY });
		expect(status).toBe(200);
		const monthKey = new Date().toISOString().slice(0, 7);
		expect(redisStore.get(`llm:tokens:agent-1:${monthKey}`)).toBe(579);
	});

	it('does NOT debit tokens when upstream fails', async () => {
		fetchState.response = () => upstreamErr(500, { error: 'overloaded' });
		await invoke({ body: VALID_BODY });
		const monthKey = new Date().toISOString().slice(0, 7);
		expect(redisStore.get(`llm:tokens:agent-1:${monthKey}`)).toBeUndefined();
	});
});

// ── request body validation + model allowlist ───────────────────────────

describe('/api/llm/anthropic — request body + model', () => {
	it('rejects empty messages array', async () => {
		const { status, body } = await invoke({ body: { messages: [] } });
		expect(status).toBe(400);
		expect(body.error).toBe('validation_error');
	});

	it('rejects model not on allowlist', async () => {
		const { status, body } = await invoke({
			body: { ...VALID_BODY, model: 'gpt-4' },
		});
		expect(status).toBe(400);
		expect(body.error_description).toMatch(/not in allowlist/);
	});

	it('uses the model from the policy when caller omits one', async () => {
		policyState.policy.brain.model = 'claude-sonnet-4-6';
		await invoke({ body: VALID_BODY });
		const sentBody = JSON.parse(fetchState.calls[0].init.body);
		expect(sentBody.model).toBe('claude-sonnet-4-6');
	});

	it('honours a paid model the owner configured on the policy', async () => {
		policyState.policy.brain.model = 'claude-opus-4-6';
		await invoke({ body: { ...VALID_BODY, model: 'claude-opus-4-6' } });
		const sentBody = JSON.parse(fetchState.calls[0].init.body);
		expect(sentBody.model).toBe('claude-opus-4-6');
	});
});

// ── caller-chosen model vs. the owner's policy ──────────────────────────
//
// Which host-billed model an embed runs is the agent owner's decision, taken in
// the dashboard and stored on the policy. A visitor may switch between free
// lanes; asking for a pricier host-keyed model returns the configured one.
// The free lanes need their provider keys present, or the fallback chain
// degrades past them and the assertion reads the wrong upstream call.

describe('/api/llm/anthropic: paid-model clamp', () => {
	beforeEach(() => {
		process.env.OPENROUTER_API_KEY = 'sk-or-test';
		process.env.GROQ_API_KEY = 'gsk-test';
	});

	afterEach(() => {
		delete process.env.OPENROUTER_API_KEY;
		delete process.env.GROQ_API_KEY;
	});

	it('caller-supplied free model overrides the policy default', async () => {
		policyState.policy.brain.model = 'google/gemma-4-31b-it:free';
		await invoke({ body: { ...VALID_BODY, model: 'llama-3.3-70b-versatile' } });
		const sentBody = JSON.parse(fetchState.calls[0].init.body);
		expect(sentBody.model).toBe('llama-3.3-70b-versatile');
	});

	it('clamps a caller-requested paid model back to the policy model', async () => {
		policyState.policy.brain.model = 'google/gemma-4-31b-it:free';
		await invoke({ body: { ...VALID_BODY, model: 'claude-opus-5' } });
		const sentBody = JSON.parse(fetchState.calls[0].init.body);
		expect(sentBody.model).toBe('google/gemma-4-31b-it:free');
	});

	it('clamps a paid model on the free default policy too', async () => {
		delete policyState.policy.brain.model;
		await invoke({ body: { ...VALID_BODY, model: 'grok-4.5' } });
		const sentBody = JSON.parse(fetchState.calls[0].init.body);
		expect(sentBody.model).toBe('google/gemma-4-31b-it:free');
	});
});

// ── platform-wide host-key ceiling ──────────────────────────────────────

describe('/api/llm/anthropic: host-key global ceiling', () => {
	it('returns 429 when the shared host-key budget is saturated', async () => {
		rlState.hostKeyGlobal = { success: false, reset: Date.now() + 1000 };
		const { status, body } = await invoke({ body: VALID_BODY });
		expect(status).toBe(429);
		expect(body.error_description).toMatch(/capacity/i);
	});
});

// ── upstream response handling ──────────────────────────────────────────

describe('/api/llm/anthropic — upstream behaviour', () => {
	it('proxies a successful upstream response unchanged', async () => {
		const upstreamPayload = {
			ok: true,
			id: 'msg_123',
			content: [{ type: 'text', text: 'hi' }],
			usage: { input_tokens: 5, output_tokens: 7 },
		};
		fetchState.response = () => upstreamOk(upstreamPayload);
		const { res, status, body } = await invoke({ body: VALID_BODY });
		expect(status).toBe(200);
		expect(body).toEqual(upstreamPayload);
		expect(res.headers['content-type']).toMatch(/application\/json/);
	});

	it('sanitizes upstream errors into a generic 502 envelope (no leaking)', async () => {
		fetchState.response = () =>
			upstreamErr(429, {
				error: { type: 'rate_limit', message: 'slow down', secret: 'leaked' },
			});
		const { status, body } = await invoke({ body: VALID_BODY });
		expect(status).toBe(502);
		expect(body.error).toBe('upstream_error');
		// The original Anthropic body must NOT be forwarded.
		expect(JSON.stringify(body)).not.toContain('leaked');
		expect(JSON.stringify(body)).not.toContain('rate_limit');
	});

	it('records a usage event with input/output token counts', async () => {
		fetchState.response = () =>
			upstreamOk({ ok: true, usage: { input_tokens: 11, output_tokens: 22 } });
		await invoke({ body: VALID_BODY });
		// recordEvent runs synchronously (queueMicrotask in production code is in
		// usage.js; the mock here pushes immediately).
		expect(usageEvents).toHaveLength(1);
		expect(usageEvents[0]).toMatchObject({
			kind: 'llm',
			tool: 'anthropic.messages',
			agentId: 'agent-1',
			status: 'ok',
		});
		expect(usageEvents[0].meta.input_tokens).toBe(11);
		expect(usageEvents[0].meta.output_tokens).toBe(22);
	});
});

// ── free-provider routing (Groq / OpenRouter) ──────────────────────────
//
// The browser sends Anthropic-shape bodies for every model; the proxy
// inspects `model`, picks the upstream URL + key, and translates request
// + response shapes both ways. These tests pin that translation contract.

describe('/api/llm/anthropic — free-provider routing', () => {
	const SYSTEM = 'you are a helpful agent';

	beforeEach(() => {
		process.env.OPENROUTER_API_KEY = 'sk-or-test';
		process.env.GROQ_API_KEY = 'gsk-test';
		// OpenAI-shape response by default; individual tests can override.
		fetchState.response = () =>
			upstreamOk({
				id: 'gen-1',
				choices: [
					{
						message: { role: 'assistant', content: 'hi from free model' },
						finish_reason: 'stop',
					},
				],
				usage: { prompt_tokens: 7, completion_tokens: 9 },
			});
	});

	it('routes free OpenRouter models to OpenRouter with bearer auth', async () => {
		await invoke({
			body: {
				...VALID_BODY,
				system: SYSTEM,
				model: 'google/gemma-4-31b-it:free',
			},
		});
		const call = fetchState.calls[0];
		expect(call.url).toBe('https://openrouter.ai/api/v1/chat/completions');
		expect(call.init.headers.authorization).toBe('Bearer sk-or-test');
		expect(call.init.headers['HTTP-Referer']).toBe('https://three.ws');
	});

	it('routes Groq model ids to api.groq.com', async () => {
		await invoke({
			body: { ...VALID_BODY, model: 'llama-3.3-70b-versatile' },
		});
		const call = fetchState.calls[0];
		expect(call.url).toBe('https://api.groq.com/openai/v1/chat/completions');
		expect(call.init.headers.authorization).toBe('Bearer gsk-test');
	});

	it('degrades through the fallback chain when the requested model has no key', async () => {
		// The requested OpenRouter lane is unkeyed; the request must NOT 503 —
		// it walks the chain and serves from the next configured lane.
		delete process.env.OPENROUTER_API_KEY;
		const { status } = await invoke({
			body: { ...VALID_BODY, model: 'google/gemma-4-31b-it:free' },
		});
		expect(status).toBe(200);
		// Every attempted call skipped the unkeyed OpenRouter lane.
		expect(fetchState.calls.every((c) => !c.url.includes('openrouter.ai'))).toBe(true);
	});

	it('degrades to a free lane when the keyed upstream rejects with 401 (dead key)', async () => {
		// Account-level 4xx (dead/revoked key) must fall through to the next
		// lane, not surface as a terminal error.
		let first = true;
		fetchState.response = () => {
			if (first) {
				first = false;
				return upstreamErr(401, 'invalid x-api-key');
			}
			return upstreamOk({
				id: 'gen-2',
				choices: [
					{ message: { role: 'assistant', content: 'rescued by free lane' }, finish_reason: 'stop' },
				],
				usage: { prompt_tokens: 3, completion_tokens: 4 },
			});
		};
		const { status } = await invoke({
			body: { ...VALID_BODY, model: 'google/gemma-4-31b-it:free' },
		});
		expect(status).toBe(200);
		expect(fetchState.calls.length).toBeGreaterThan(1);
	});

	it('returns 503 only when no lane in the chain is configured', async () => {
		delete process.env.OPENROUTER_API_KEY;
		delete process.env.GROQ_API_KEY;
		delete process.env.NVIDIA_API_KEY;
		const savedAnthropic = process.env.ANTHROPIC_API_KEY;
		delete process.env.ANTHROPIC_API_KEY;
		try {
			const { status, body } = await invoke({
				body: { ...VALID_BODY, model: 'google/gemma-4-31b-it:free' },
			});
			expect(status).toBe(503);
			expect(body.error).toBe('provider_unavailable');
			expect(fetchState.calls).toHaveLength(0);
		} finally {
			process.env.ANTHROPIC_API_KEY = savedAnthropic;
		}
	});

	it('serves from the Vertex Gemini credits anchor when every keyed lane is unconfigured', async () => {
		// Prod repro of the 2026-07-21 diagnosis: free keys dead/absent, paid keys
		// dead/absent; the keyless GCP-credits anchor must answer instead of 503.
		delete process.env.OPENROUTER_API_KEY;
		delete process.env.GROQ_API_KEY;
		delete process.env.NVIDIA_API_KEY;
		const savedAnthropic = process.env.ANTHROPIC_API_KEY;
		delete process.env.ANTHROPIC_API_KEY;
		process.env.GOOGLE_CLOUD_PROJECT = 'test-project';
		try {
			const { status, body } = await invoke({
				body: { ...VALID_BODY, model: 'google/gemma-4-31b-it:free' },
			});
			expect(status).toBe(200);
			const call = fetchState.calls[0];
			expect(call.url).toContain('aiplatform.googleapis.com');
			expect(call.url).toContain('test-project');
			expect(call.init.headers.authorization).toBe('Bearer gcp-test-token');
			// OpenAI-shape upstream translated back to the Anthropic shape the
			// embed client parses.
			expect(body.role).toBe('assistant');
			expect(body.content?.[0]?.text).toBe('hi from free model');
		} finally {
			process.env.ANTHROPIC_API_KEY = savedAnthropic;
			delete process.env.GOOGLE_CLOUD_PROJECT;
		}
	});

	it('translates Anthropic body shape → OpenAI body shape', async () => {
		await invoke({
			body: {
				system: SYSTEM,
				model: 'google/gemma-4-31b-it:free',
				max_tokens: 256,
				temperature: 0.4,
				messages: [
					{ role: 'user', content: 'how are you?' },
					{
						role: 'assistant',
						content: [
							{ type: 'text', text: 'let me check' },
							{
								type: 'tool_use',
								id: 'toolu_01',
								name: 'getTime',
								input: { tz: 'UTC' },
							},
						],
					},
					{
						role: 'user',
						content: [
							{ type: 'tool_result', tool_use_id: 'toolu_01', content: '12:00' },
						],
					},
				],
				tools: [
					{
						name: 'getTime',
						description: 'returns the current time',
						input_schema: {
							type: 'object',
							properties: { tz: { type: 'string' } },
							required: ['tz'],
						},
					},
				],
			},
		});
		const sent = JSON.parse(fetchState.calls[0].init.body);
		expect(sent.model).toBe('google/gemma-4-31b-it:free');
		expect(sent.max_tokens).toBe(256);
		expect(sent.temperature).toBe(0.4);
		// System collapses into the first message.
		expect(sent.messages[0]).toEqual({ role: 'system', content: SYSTEM });
		expect(sent.messages[1]).toEqual({ role: 'user', content: 'how are you?' });
		// Assistant turn with a tool_use → OpenAI tool_calls array.
		expect(sent.messages[2]).toMatchObject({
			role: 'assistant',
			content: 'let me check',
			tool_calls: [
				{
					id: 'toolu_01',
					type: 'function',
					function: { name: 'getTime', arguments: JSON.stringify({ tz: 'UTC' }) },
				},
			],
		});
		// tool_result block → role:"tool" message.
		expect(sent.messages[3]).toEqual({
			role: 'tool',
			tool_call_id: 'toolu_01',
			content: '12:00',
		});
		// Tool schema converted to OpenAI function-tool shape.
		expect(sent.tools[0]).toEqual({
			type: 'function',
			function: {
				name: 'getTime',
				description: 'returns the current time',
				parameters: {
					type: 'object',
					properties: { tz: { type: 'string' } },
					required: ['tz'],
				},
			},
		});
		expect(sent.tool_choice).toBe('auto');
	});

	it('translates OpenAI-shape upstream response → Anthropic-shape body', async () => {
		const { status, body } = await invoke({
			body: { ...VALID_BODY, model: 'llama-3.3-70b-versatile' },
		});
		expect(status).toBe(200);
		expect(body).toMatchObject({
			type: 'message',
			role: 'assistant',
			model: 'llama-3.3-70b-versatile',
			content: [{ type: 'text', text: 'hi from free model' }],
			stop_reason: 'end_turn',
			usage: { input_tokens: 7, output_tokens: 9 },
		});
	});

	it('translates upstream tool_calls into Anthropic tool_use blocks', async () => {
		fetchState.response = () =>
			upstreamOk({
				id: 'gen-2',
				choices: [
					{
						message: {
							role: 'assistant',
							content: '',
							tool_calls: [
								{
									id: 'call_1',
									type: 'function',
									function: { name: 'getTime', arguments: '{"tz":"UTC"}' },
								},
							],
						},
						finish_reason: 'tool_calls',
					},
				],
				usage: { prompt_tokens: 4, completion_tokens: 5 },
			});
		const { body } = await invoke({
			body: { ...VALID_BODY, model: 'google/gemma-4-31b-it:free' },
		});
		expect(body.content).toEqual([
			{ type: 'tool_use', id: 'call_1', name: 'getTime', input: { tz: 'UTC' } },
		]);
		expect(body.stop_reason).toBe('tool_use');
	});

	it('debits OpenAI-shape token usage (prompt + completion) onto the agent', async () => {
		await invoke({
			body: { ...VALID_BODY, model: 'google/gemma-4-31b-it:free' },
		});
		const monthKey = new Date().toISOString().slice(0, 7);
		expect(redisStore.get(`llm:tokens:agent-1:${monthKey}`)).toBe(16);
	});

	it('records usage with the upstream provider tag', async () => {
		await invoke({
			body: { ...VALID_BODY, model: 'google/gemma-4-31b-it:free' },
		});
		expect(usageEvents[0]).toMatchObject({
			kind: 'llm',
			tool: 'openrouter.chat',
			agentId: 'agent-1',
		});
	});
});

// ── fallback-chain integrity ───────────────────────────────────────────────
//
// A rung the attempt loop cannot resolve is skipped in silence: the chain looks
// four deep in the comments and runs three deep in production. Pin every rung
// to the allowlist so the next edit cannot reintroduce a phantom step.

describe('/api/llm/anthropic: fallback chain integrity', () => {
	it('resolves every rung it lists to a real upstream route', () => {
		process.env.OPENROUTER_API_KEY = 'sk-or-test';
		process.env.GROQ_API_KEY = 'gsk-test';
		process.env.NVIDIA_API_KEY = 'nv-test';
		process.env.SAMBANOVA_API_KEY = 'sn-test';
		const chain = modelFallbackChain('google/gemma-4-31b-it:free');
		expect(chain.length).toBeGreaterThan(1);
		for (const rung of chain) {
			expect(resolveModelRoute(rung), `rung "${rung}" is not routable`).toBeTruthy();
		}
	});

	it('keeps the paid Anthropic rung last among the keyed lanes', () => {
		const chain = modelFallbackChain('google/gemma-4-31b-it:free');
		expect(chain[chain.length - 1]).toBe('claude-haiku-4-5-20251001');
	});
});

// ── Anthropic request shaping ──────────────────────────────────────────────

describe('/api/llm/anthropic: Anthropic request shaping', () => {
	it('supplies max_tokens when the caller omits it (the Messages API requires it)', async () => {
		await invoke({ body: { messages: [{ role: 'user', content: 'hello' }] } });
		const sent = JSON.parse(fetchState.calls[0].init.body);
		expect(sent.max_tokens).toBe(4096);
	});

	it('keeps a caller-supplied max_tokens', async () => {
		await invoke({ body: { ...VALID_BODY, max_tokens: 512 } });
		const sent = JSON.parse(fetchState.calls[0].init.body);
		expect(sent.max_tokens).toBe(512);
	});
});

// ── streaming ──────────────────────────────────────────────────────────────
//
// Streaming is the lane every browser embed takes, and it was the untested one.
// The OpenAI-shape upstreams are rewritten into Anthropic SSE on the fly, and
// the token counters that enforce the monthly budget are fed from that stream.

describe('/api/llm/anthropic: streaming, OpenAI-shape lanes', () => {
	const monthKey = () => new Date().toISOString().slice(0, 7);

	beforeEach(() => {
		process.env.OPENROUTER_API_KEY = 'sk-or-test';
		process.env.GROQ_API_KEY = 'gsk-test';
	});

	it('asks OpenAI-compatible providers for streaming usage', async () => {
		fetchState.response = () => upstreamSse(['data: [DONE]\n\n']);
		await invoke({ body: { ...VALID_BODY, model: 'google/gemma-4-31b-it:free', stream: true } });
		const sent = JSON.parse(fetchState.calls[0].init.body);
		expect(sent.stream).toBe(true);
		expect(sent.stream_options).toEqual({ include_usage: true });
	});

	it('does not send stream_options on a non-streaming request', async () => {
		await invoke({ body: { ...VALID_BODY, model: 'google/gemma-4-31b-it:free' } });
		const sent = JSON.parse(fetchState.calls[0].init.body);
		expect(sent.stream_options).toBeUndefined();
	});

	it('rewrites OpenAI deltas into Anthropic SSE and debits the usage chunk', async () => {
		fetchState.response = () =>
			upstreamSse([
				'data: {"choices":[{"delta":{"content":"Hel"}}]}\n\n',
				'data: {"choices":[{"delta":{"content":"lo"}}]}\n\n',
				'data: {"choices":[{"delta":{},"finish_reason":"stop"}]}\n\n',
				'data: {"choices":[],"usage":{"prompt_tokens":12,"completion_tokens":5}}\n\n',
				'data: [DONE]\n\n',
			]);
		const { res } = await invoke({
			body: { ...VALID_BODY, model: 'google/gemma-4-31b-it:free', stream: true },
		});
		expect(res.headers['content-type']).toBe('text/event-stream');
		expect(res.headers['x-llm-transport']).toBe('openrouter');
		expect(res.body).toContain('event: message_start');
		expect(res.body).toContain('"text_delta","text":"Hel"');
		expect(res.body).toContain('"text_delta","text":"lo"');
		expect(res.body).toContain('event: message_stop');
		expect(res.writableEnded).toBe(true);
		// The budget the handler enforces is fed from that usage chunk.
		expect(redisStore.get(`llm:tokens:agent-1:${monthKey()}`)).toBe(17);
		expect(usageEvents[0]).toMatchObject({ provider: 'openrouter', outputTokens: 5 });
	});

	it("reads Groq's x_groq.usage, which sits outside the OpenAI usage field", async () => {
		fetchState.response = () =>
			upstreamSse([
				'data: {"choices":[{"delta":{"content":"hi"}}]}\n\n',
				'data: {"choices":[{"delta":{},"finish_reason":"stop"}],"x_groq":{"usage":{"prompt_tokens":8,"completion_tokens":3}}}\n\n',
				'data: [DONE]\n\n',
			]);
		await invoke({ body: { ...VALID_BODY, model: 'llama-3.3-70b-versatile', stream: true } });
		expect(redisStore.get(`llm:tokens:agent-1:${monthKey()}`)).toBe(11);
	});

	it('converts a streamed tool call into an Anthropic tool_use block', async () => {
		fetchState.response = () =>
			upstreamSse([
				'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call_1","function":{"name":"getTime","arguments":""}}]}}]}\n\n',
				'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\\"tz\\":"}}]}}]}\n\n',
				'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\\"UTC\\"}"}}]}}]}\n\n',
				'data: {"choices":[{"delta":{},"finish_reason":"tool_calls"}]}\n\n',
				'data: [DONE]\n\n',
			]);
		const { res } = await invoke({
			body: { ...VALID_BODY, model: 'google/gemma-4-31b-it:free', stream: true },
		});
		expect(res.body).toContain('"type":"tool_use","id":"call_1","name":"getTime"');
		expect(res.body).toContain('"input_json_delta","partial_json":"{\\"tz\\":"');
		expect(res.body).toContain('"input_json_delta","partial_json":"\\"UTC\\"}"');
		expect(res.body).toContain('event: content_block_stop');
		expect(res.body).toContain('"stop_reason":"tool_use"');
	});

	it('keeps a tool name that streams in fragments ahead of its id', async () => {
		fetchState.response = () =>
			upstreamSse([
				'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"name":"get"}}]}}]}\n\n',
				'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"name":"Time"}}]}}]}\n\n',
				'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{}"}}]}}]}\n\n',
				'data: {"choices":[{"delta":{},"finish_reason":"tool_calls"}]}\n\n',
				'data: [DONE]\n\n',
			]);
		const { res } = await invoke({
			body: { ...VALID_BODY, model: 'google/gemma-4-31b-it:free', stream: true },
		});
		expect(res.body).toContain('"name":"getTime"');
		expect(res.body).not.toContain('"name":"get"');
		expect(res.body).toContain('"input_json_delta","partial_json":"{}"');
	});

	it('emits a tool call whose id never arrived instead of dropping it', async () => {
		fetchState.response = () =>
			upstreamSse([
				'data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"name":"getTime"}}]}}]}\n\n',
				'data: {"choices":[{"delta":{},"finish_reason":"tool_calls"}]}\n\n',
				'data: [DONE]\n\n',
			]);
		const { res } = await invoke({
			body: { ...VALID_BODY, model: 'google/gemma-4-31b-it:free', stream: true },
		});
		expect(res.body).toContain('"type":"tool_use"');
		expect(res.body).toContain('"name":"getTime"');
		expect(res.body).toContain('event: content_block_stop');
	});
});

describe('/api/llm/anthropic: streaming, Anthropic lane', () => {
	it('passes upstream Anthropic SSE through byte for byte and debits cache tokens', async () => {
		const chunks = [
			'event: message_start\ndata: {"type":"message_start","message":{"usage":{"input_tokens":30,"cache_creation_input_tokens":100,"cache_read_input_tokens":200}}}\n\n',
			'event: content_block_delta\ndata: {"type":"content_block_delta","delta":{"type":"text_delta","text":"hi"}}\n\n',
			'event: message_delta\ndata: {"type":"message_delta","usage":{"output_tokens":9}}\n\n',
		];
		fetchState.response = () => upstreamSse(chunks);
		const { res } = await invoke({ body: { ...VALID_BODY, stream: true } });
		expect(res.body).toBe(chunks.join(''));
		expect(res.headers['x-llm-transport']).toBe('anthropic');
		const monthKey = new Date().toISOString().slice(0, 7);
		// 30 uncached + 100 cache-write + 200 cache-read prompt tokens, 9 output.
		expect(redisStore.get(`llm:tokens:agent-1:${monthKey}`)).toBe(339);
		expect(usageEvents[0].meta).toMatchObject({
			input_tokens: 330,
			output_tokens: 9,
			cache_write_tokens: 100,
			cache_read_tokens: 200,
		});
	});
});

// ── Anthropic SDK clients (base-URL path, block system, large max_tokens) ──
//
// An SDK client is configured with a base URL and appends /v1/messages to it,
// so the agent travels in the path. These pin that such a client, sending what
// the official SDKs send by default, is served rather than turned away on a
// field it does not choose.

describe('/api/llm/anthropic: Anthropic SDK clients', () => {
	const SDK_URL = '/api/llm/anthropic/agents/agent-1/v1/messages?beta=true';

	beforeEach(() => {
		process.env.OPENROUTER_API_KEY = 'sk-or-test';
		authState.user = { id: 'platform-user', source: 'bearer' };
		fetchState.response = () =>
			upstreamOk({
				id: 'gen-sdk',
				choices: [{ message: { role: 'assistant', content: 'ok' }, finish_reason: 'stop' }],
				usage: { prompt_tokens: 3, completion_tokens: 1 },
			});
	});

	async function invokeSdk(body, { query = { agent: 'agent-1' } } = {}) {
		const req = makeReq({ url: SDK_URL, body, noOrigin: true, headers: { authorization: 'Bearer sk_live_test' } });
		req.query = query;
		const res = makeRes();
		await handler(req, res);
		return { status: res.statusCode, body: res.body ? safeJson(res.body) : null };
	}

	it('meters against the agent the router bound from the path segment', async () => {
		const { status } = await invokeSdk({ ...VALID_BODY, model: 'google/gemma-4-31b-it:free' });
		expect(status).toBe(200);
		expect(usageEvents[0]).toMatchObject({ agentId: 'agent-1', status: 'ok' });
	});

	it('still requires an agent when neither the query nor the path names one', async () => {
		const { status, body } = await invokeSdk(VALID_BODY, { query: {} });
		expect(status).toBe(400);
		expect(body.error).toBe('validation_error');
	});

	it('still refuses a header-less caller that does not authenticate', async () => {
		authState.user = null;
		const { status, body } = await invokeSdk(VALID_BODY);
		expect(status).toBe(403);
		expect(body.error).toBe('embed_denied_origin');
	});

	it('accepts a block-array system prompt and hands OpenAI-shape lanes one string', async () => {
		const { status } = await invokeSdk({
			...VALID_BODY,
			model: 'google/gemma-4-31b-it:free',
			system: [
				{ type: 'text', text: 'first block' },
				{ type: 'text', text: 'second block', cache_control: { type: 'ephemeral' } },
			],
		});
		expect(status).toBe(200);
		const sent = JSON.parse(fetchState.calls[0].init.body);
		expect(sent.messages[0]).toEqual({ role: 'system', content: 'first block\n\nsecond block' });
	});

	it('passes a block-array system prompt to an Anthropic lane unchanged', async () => {
		const system = [{ type: 'text', text: 'keep my cache marker', cache_control: { type: 'ephemeral' } }];
		fetchState.response = () => upstreamOk({ ok: true, usage: { input_tokens: 1, output_tokens: 1 } });
		const { status } = await invokeSdk({ ...VALID_BODY, system });
		expect(status).toBe(200);
		expect(fetchState.calls[0].url).toBe('https://api.anthropic.com/v1/messages');
		expect(JSON.parse(fetchState.calls[0].init.body).system).toEqual(system);
	});

	it('bounds a block-array system prompt by the same total length as a string one', async () => {
		const { status, body } = await invokeSdk({
			...VALID_BODY,
			system: [
				{ type: 'text', text: 'a'.repeat(40_000) },
				{ type: 'text', text: 'b'.repeat(40_000) },
			],
		});
		expect(status).toBe(400);
		expect(body.error).toBe('validation_error');
		expect(fetchState.calls).toHaveLength(0);
	});

	it('accepts an in-thread system turn and folds it into the system prompt for OpenAI-shape lanes', async () => {
		const { status } = await invokeSdk({
			model: 'google/gemma-4-31b-it:free',
			system: [{ type: 'text', text: 'base prompt' }],
			messages: [
				{ role: 'user', content: [{ type: 'text', text: 'hi' }] },
				{ role: 'system', content: [{ type: 'text', text: '# Environment' }] },
			],
		});
		expect(status).toBe(200);
		const sent = JSON.parse(fetchState.calls[0].init.body);
		expect(sent.messages).toEqual([
			{ role: 'system', content: 'base prompt\n\n# Environment' },
			{ role: 'user', content: 'hi' },
		]);
	});

	it('passes an in-thread system turn to an Anthropic lane unchanged', async () => {
		fetchState.response = () => upstreamOk({ ok: true, usage: { input_tokens: 1, output_tokens: 1 } });
		const messages = [
			{ role: 'user', content: 'hi' },
			{ role: 'system', content: [{ type: 'text', text: '# Environment' }] },
		];
		const { status } = await invokeSdk({ max_tokens: 10, messages });
		expect(status).toBe(200);
		expect(JSON.parse(fetchState.calls[0].init.body).messages).toEqual(messages);
	});

	it('clamps an oversized max_tokens instead of rejecting the request', async () => {
		const { status } = await invokeSdk({ ...VALID_BODY, model: 'google/gemma-4-31b-it:free', max_tokens: 32_000 });
		expect(status).toBe(200);
		const sent = JSON.parse(fetchState.calls[0].init.body);
		expect(sent.max_tokens).toBe(16_000);
	});

	it('hands a text-block tool_result to an OpenAI-shape model as plain text', async () => {
		await invokeSdk({
			...VALID_BODY,
			model: 'google/gemma-4-31b-it:free',
			messages: [
				{ role: 'user', content: 'run it' },
				{ role: 'assistant', content: [{ type: 'tool_use', id: 'toolu_1', name: 'Bash', input: { command: 'ls' } }] },
				{
					role: 'user',
					content: [
						{
							type: 'tool_result',
							tool_use_id: 'toolu_1',
							content: [
								{ type: 'text', text: 'a.txt' },
								{ type: 'text', text: 'b.txt' },
							],
						},
					],
				},
			],
		});
		const sent = JSON.parse(fetchState.calls[0].init.body);
		expect(sent.messages.find((m) => m.role === 'tool')).toEqual({
			role: 'tool',
			tool_call_id: 'toolu_1',
			content: 'a.txt\nb.txt',
		});
	});
});

describe('/api/llm/anthropic: SDK base-URL route', () => {
	it('resolves the SDK path to the proxy alias and binds the agent segment', async () => {
		const path = await import('node:path');
		const { resolveApiHandler } = await import('../../server/route-resolve.mjs');
		const apiRoot = path.resolve('api');
		const sdk = resolveApiHandler(apiRoot, '/api/llm/anthropic/agents/4c0e4d18-0544-4c95-a0db-a16896b029be/v1/messages');
		expect(sdk.file).toBe(path.join(apiRoot, 'llm/anthropic/agents/[agent]/v1/messages.js'));
		expect(sdk.params).toEqual({ agent: '4c0e4d18-0544-4c95-a0db-a16896b029be' });
		const alias = await import('../../api/llm/anthropic/agents/[agent]/v1/messages.js');
		expect(alias.default).toBe(handler);
		// The canonical path still reaches the proxy file itself.
		expect(resolveApiHandler(apiRoot, '/api/llm/anthropic').file).toBe(path.join(apiRoot, 'llm/anthropic.js'));
	});
});