Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. π₯
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat(api): spend an MCP credits balance first on hosted MCP calls (#5455)
Rakshith Ramprakash180db64023c9
diff --git a/apps/api/src/__tests__/routes/check-credits-middleware.test.ts b/apps/api/src/__tests__/routes/check-credits-middleware.test.tsindex ed9b425f5..fd8a7bfbd 100644--- a/apps/api/src/__tests__/routes/check-credits-middleware.test.ts+++ b/apps/api/src/__tests__/routes/check-credits-middleware.test.ts@@ -15,6 +15,7 @@ vi.mock("../../lib/logger", () => ({vi.mock("../../services/autumn/autumn.service", () => ({autumnService: {checkCredits: vi.fn(),+ mcpCreditsAvailable: vi.fn(),},CREDITS_FEATURE_ID: "CREDITS",}));@@ -49,6 +50,10 @@ import { getTeamBalance } from "../../services/autumn/usage";const checkCreditsMock = autumnService.checkCredits as MockedFunction<typeof autumnService.checkCredits>;+const mcpCreditsAvailableMock =+ autumnService.mcpCreditsAvailable as MockedFunction<+ typeof autumnService.mcpCreditsAvailable+ >;const getTeamBalanceMock = getTeamBalance as MockedFunction<typeof getTeamBalance>;@@ -65,6 +70,7 @@ function buildReq(overrides: any = {}): any {function runMiddleware(req: any,+ middleware = checkCreditsMiddleware(),): Promise<{ res: any; nextErr?: any; nextCalled: boolean }> {return new Promise(resolve => {let settled = false;@@ -90,7 +96,7 @@ function runMiddleware(nextCalled = true;settle({ res, nextErr: err });};- checkCreditsMiddleware()(req, res, next);+ middleware(req, res, next);});}@@ -371,3 +377,134 @@ describe("checkCreditsMiddleware β unverified agent-key 50-credit cap", () =>expect(res.status).not.toHaveBeenCalled();});});++describe("checkCreditsMiddleware β MCP credits", () => {+ const hostedMcpAuth = {+ team_id: "team_test",+ org_id: "org_test",+ hostedMcp: true,+ };++ const spendsMcpCredits = checkCreditsMiddleware(undefined, undefined, {+ mcpCredits: true,+ });++ beforeEach(() => {+ vi.clearAllMocks();+ });++ it("runs a hosted MCP call the team's credits can't cover when its MCP credits can", async () => {+ checkCreditsMock.mockResolvedValue({ allowed: false, remaining: 0 });+ mcpCreditsAvailableMock.mockResolvedValue(1);++ const req = buildReq({+ path: "/v2/scrape",+ body: {},+ auth: hostedMcpAuth,+ acuc: { api_key_id: 7 },+ });+ const { res, nextCalled } = await runMiddleware(req, spendsMcpCredits);++ expect(res.status).not.toHaveBeenCalled();+ expect(nextCalled).toBe(true);+ expect(req.account.remainingCredits).toBe(Infinity);+ expect(mcpCreditsAvailableMock).toHaveBeenCalledExactlyOnceWith({+ teamId: "team_test",+ orgId: "org_test",+ value: 1,+ properties: {+ source: "checkCreditsMiddleware:mcp",+ path: "/v2/scrape",+ apiKeyId: 7,+ },+ });+ });++ it("keeps the full crawl limit when MCP credits cover it", async () => {+ checkCreditsMock.mockResolvedValue({ allowed: false, remaining: 5 });+ mcpCreditsAvailableMock.mockResolvedValue(100);++ const req = buildReq({ auth: hostedMcpAuth, body: { limit: 100 } });+ const { res } = await runMiddleware(req, spendsMcpCredits);++ expect(res.status).not.toHaveBeenCalled();+ expect(req.body.limit).toBe(100);+ expect(mcpCreditsAvailableMock).toHaveBeenCalledWith(+ expect.objectContaining({ value: 100 }),+ );+ });++ it("clamps the crawl limit as today when MCP credits cover only part of it", async () => {+ checkCreditsMock+ .mockResolvedValueOnce({ allowed: false, remaining: 5 })+ .mockResolvedValueOnce({ allowed: true, remaining: 5 });+ mcpCreditsAvailableMock.mockResolvedValue(40);++ const req = buildReq({ auth: hostedMcpAuth, body: { limit: 100 } });+ const { res } = await runMiddleware(req, spendsMcpCredits);++ expect(res.status).not.toHaveBeenCalled();+ expect(req.body.limit).toBe(5);+ });++ // Per-key spend caps limit regular credits only.+ it("runs a hosted MCP call on MCP credits when its key is over its spend cap", async () => {+ // A per-key cap denies while the team balance stays healthy.+ checkCreditsMock.mockResolvedValue({ allowed: false, remaining: 5000 });+ mcpCreditsAvailableMock.mockResolvedValue(1);++ const req = buildReq({+ path: "/v2/scrape",+ body: {},+ auth: hostedMcpAuth,+ acuc: { api_key_id: 7 },+ });+ const { res, nextCalled } = await runMiddleware(req, spendsMcpCredits);++ expect(res.status).not.toHaveBeenCalled();+ expect(nextCalled).toBe(true);+ });++ it("falls back to the existing gate once MCP credits can't cover the call", async () => {+ checkCreditsMock.mockResolvedValue({ allowed: false, remaining: 0 });+ mcpCreditsAvailableMock.mockResolvedValue(0);++ const req = buildReq({ auth: hostedMcpAuth });+ const { res, nextCalled } = await runMiddleware(req, spendsMcpCredits);++ expect(res.status).toHaveBeenCalledWith(402);+ expect(nextCalled).toBe(false);+ });++ it("never looks at MCP credits when the team's own credits allow the call", async () => {+ checkCreditsMock.mockResolvedValue({ allowed: true, remaining: 100 });++ const req = buildReq({ auth: hostedMcpAuth });+ const { res } = await runMiddleware(req, spendsMcpCredits);++ expect(res.status).not.toHaveBeenCalled();+ expect(mcpCreditsAvailableMock).not.toHaveBeenCalled();+ });++ it("never looks at MCP credits for a call the hosted MCP did not make", async () => {+ checkCreditsMock.mockResolvedValue({ allowed: false, remaining: 0 });++ const req = buildReq({ body: { limit: 100, origin: "mcp-fastmcp" } });+ const { res } = await runMiddleware(req, spendsMcpCredits);++ expect(res.status).toHaveBeenCalledWith(402);+ expect(mcpCreditsAvailableMock).not.toHaveBeenCalled();+ });++ it("never looks at MCP credits on a route whose billing doesn't spend them", async () => {+ checkCreditsMock.mockResolvedValue({ allowed: false, remaining: 0 });+ mcpCreditsAvailableMock.mockResolvedValue(100);++ const req = buildReq({ path: "/v2/extract", auth: hostedMcpAuth });+ const { res, nextCalled } = await runMiddleware(req);++ expect(res.status).toHaveBeenCalledWith(402);+ expect(nextCalled).toBe(false);+ expect(mcpCreditsAvailableMock).not.toHaveBeenCalled();+ });+});diff --git a/apps/api/src/__tests__/routes/research-credit-gate.routes.test.ts b/apps/api/src/__tests__/routes/research-credit-gate.routes.test.tsindex 141c644b4..6a0ec8dcb 100644--- a/apps/api/src/__tests__/routes/research-credit-gate.routes.test.ts+++ b/apps/api/src/__tests__/routes/research-credit-gate.routes.test.ts@@ -34,18 +34,24 @@ vi.mock("../../services/billing/credit_billing", () => ({}));vi.mock("../../services/autumn/autumn.service", () => ({- autumnService: { checkCredits: vi.fn() },+ autumnService: { checkCredits: vi.fn(), mcpCreditsAvailable: vi.fn() },CREDITS_FEATURE_ID: "CREDITS",SEARCH_CREDITS_FEATURE_ID: "SEARCH_CREDITS",}));const checkCredits = vi.mocked(autumnService.checkCredits);+const mcpCreditsAvailable = vi.mocked(autumnService.mcpCreditsAvailable);-function appWith(orgId: string | undefined) {+function appWith(orgId: string | undefined, hostedMcp = false) {const app = express();app.use(express.json());app.use((req: any, _res, next) => {- req.auth = { team_id: "team-test", org_id: orgId, plan: "standard" };+ req.auth = {+ team_id: "team-test",+ org_id: orgId,+ plan: "standard",+ ...(hostedMcp ? { hostedMcp: true } : {}),+ };req.acuc = { api_key_id: 4 };next();});@@ -109,6 +115,19 @@ describe.each([expect(res.statusCode).toBe(200);expect(checkCredits).not.toHaveBeenCalled();});++ it("serves a hosted MCP search the team's MCP credits can cover", async () => {+ checkCredits.mockResolvedValue({ allowed: false, remaining: 0 });+ mcpCreditsAvailable.mockResolvedValue(2);++ const res = await request(appWith("org-test", true)).get(path);++ expect(res.statusCode).toBe(200);+ expect(upstreamCalls).toHaveLength(1);+ expect(mcpCreditsAvailable).toHaveBeenCalledWith(+ expect.objectContaining({ teamId: "team-test", value: 2 }),+ );+ });});it("leaves free paper search ungated", async () => {diff --git a/apps/api/src/config.ts b/apps/api/src/config.tsindex e42e46c14..2837f0c07 100644--- a/apps/api/src/config.ts+++ b/apps/api/src/config.ts@@ -305,6 +305,11 @@ const configSchema = z.object({MCP_ACTION_LOG_SECRET: z.string().optional(),MCP_ACTION_LOG_STORAGE_ENABLED: z.stringbool().default(false),MCP_ACTION_LOG_WRITES_ENABLED: z.stringbool().default(false),+ // Autumn feature id of the balance hosted MCP calls spend first (see+ // AutumnService.trackHostedMcpCredits).+ MCP_CREDITS_FEATURE_ID: emptyStringAsDefault(+ z.string().trim().min(1).default("MCP_CREDITS"),+ ),// Agent auth discovery (RFC 9728 WWW-Authenticate on 401)AGENT_AUTH_RESOURCE_METADATA_URL: zdiff --git a/apps/api/src/controllers/__tests__/auth.test.ts b/apps/api/src/controllers/__tests__/auth.test.tsindex 4f51d1d5b..44c7b65df 100644--- a/apps/api/src/controllers/__tests__/auth.test.ts+++ b/apps/api/src/controllers/__tests__/auth.test.ts@@ -1245,6 +1245,71 @@ describe("authenticateUser", () => {expect(planConsume).toHaveBeenCalledExactlyOnceWith("team-1");});+ it("marks the verified hosted MCP calls on the auth result, and no others", async () => {+ const delegated = await authenticateUser(+ requestWith("Bearer " + signDelegation()),+ {},+ RateLimiterMode.Scrape,+ );+ const relayed = await authenticateUser(+ requestWith(API_KEY, {+ headers: { "x-firecrawl-keyless-secret": "hosted-mcp-proxy-secret" },+ }),+ {},+ RateLimiterMode.Crawl,+ );+ const selfDeclared = await authenticateUser(+ requestWith(API_KEY, {+ body: { origin: "mcp-fastmcp" },+ headers: {+ "x-origin": "mcp-fastmcp",+ "x-firecrawl-keyless-secret": "not-the-secret",+ },+ }),+ {},+ RateLimiterMode.Scrape,+ );++ expect(delegated).toMatchObject({ success: true, hostedMcp: true });+ expect(relayed).toMatchObject({ success: true, hostedMcp: true });+ expect(selfDeclared.success).toBe(true);+ expect(selfDeclared).not.toHaveProperty("hostedMcp");+ });++ it("never marks an OAuth access token as a hosted MCP call, even with the proxy secret", async () => {+ config.OAUTH_INTROSPECT_URL = "https://example.test/introspect";+ config.OAUTH_INTROSPECT_SECRET = "secret";+ vi.stubGlobal(+ "fetch",+ vi.fn().mockResolvedValue(+ new Response(+ JSON.stringify({+ active: true,+ api_key: "fc-00000000000000004000800000000000",+ scope: "firecrawl:global",+ client_id: "client-1",+ team_id: "team-1",+ exp: Math.floor(Date.now() / 1000) + 60,+ aud: "https://api.firecrawl.dev/",+ credential_purpose: "hosted_mcp_oauth",+ }),+ { status: 200, headers: { "Content-Type": "application/json" } },+ ),+ ),+ );++ const auth = await authenticateUser(+ requestWith("Bearer fco_rest_grant_token", {+ headers: { "x-firecrawl-keyless-secret": "hosted-mcp-proxy-secret" },+ }),+ {},+ RateLimiterMode.Crawl,+ );++ expect(auth.success).toBe(true);+ expect(auth).not.toHaveProperty("hostedMcp");+ });+it.each([["", {}],[diff --git a/apps/api/src/controllers/auth.ts b/apps/api/src/controllers/auth.tsindex ae0171aaa..a615fc005 100644--- a/apps/api/src/controllers/auth.ts+++ b/apps/api/src/controllers/auth.ts@@ -1139,6 +1139,7 @@ async function supaAuthenticateUser(}}+ let hostedMcpCall = false;if (chunk !== null) {// Calls the hosted MCP makes on routes that opt in (every v2 route) get a// raised per-minute minimum, and scrape calls a raised concurrency@@ -1148,14 +1149,15 @@ async function supaAuthenticateUser(// `fco_` tokens never qualify: the hosted MCP keeps those for the issuer,// so a REST call carrying one comes from the client itself. Origin and// integration are client-set, so they never change the limit.+ hostedMcpCall =+ hostedMcpDelegation ||+ (!token.startsWith("fco_") &&+ timingSafeSecretEqual(+ req.headers["x-firecrawl-keyless-secret"],+ config.KEYLESS_PROXY_SECRET,+ ));const hostedMcpRaise =- options?.hostedMcpRateLimit === true &&- (hostedMcpDelegation ||- (!token.startsWith("fco_") &&- timingSafeSecretEqual(- req.headers["x-firecrawl-keyless-secret"],- config.KEYLESS_PROXY_SECRET,- )));+ options?.hostedMcpRateLimit === true && hostedMcpCall;// The tiers follow the team's own plan multiplier, not the one trusted// agent traffic floors at hobby, so a free team never gets the hobby tier.const hostedMcpLimiter = hostedMcpRaise@@ -1264,5 +1266,6 @@ async function supaAuthenticateUser(team_id: teamId ?? undefined,org_id: chunk?.org_id ?? null,chunk,+ ...(hostedMcpCall ? { hostedMcp: true } : {}),};}diff --git a/apps/api/src/controllers/v1/types.ts b/apps/api/src/controllers/v1/types.tsindex db0e066a6..f7fc262bc 100644--- a/apps/api/src/controllers/v1/types.ts+++ b/apps/api/src/controllers/v1/types.ts@@ -1318,6 +1318,9 @@ type AuthObject = {// Set only by authMiddleware from the raw request; controllers may re-parse// the body and drop `__agentInterop`, so read this instead.agentInterop?: AgentInteropStatus;+ // Set only by authMiddleware, from the hosted MCP verification in+ // supaAuthenticateUser; never from the request body or headers directly.+ hostedMcp?: boolean;};type Account = {diff --git a/apps/api/src/controllers/v2/batch-scrape.ts b/apps/api/src/controllers/v2/batch-scrape.tsindex ea304cad1..285ac3fea 100644--- a/apps/api/src/controllers/v2/batch-scrape.ts+++ b/apps/api/src/controllers/v2/batch-scrape.ts@@ -150,6 +150,7 @@ export async function batchScrapeController(? { endpoint: "agent" as const, jobId: id }: { endpoint: "batch_scrape" as const, jobId: id }),externalRequestId: externalRequestId(req),+ hostedMcp: req.auth.hostedMcp,};const logger = _logger.child({crawlId: id,diff --git a/apps/api/src/controllers/v2/crawl.ts b/apps/api/src/controllers/v2/crawl.tsindex 1438ae7c6..6cd2d9e5e 100644--- a/apps/api/src/controllers/v2/crawl.ts+++ b/apps/api/src/controllers/v2/crawl.ts@@ -134,7 +134,11 @@ export async function crawlController(// No chargeId: a fresh crawl id is minted per request and the// rejected crawl is never persisted or queued, so there is no// stable per-charge identity that could dedupe a retry.- { endpoint: "crawl" },+ {+ endpoint: "crawl",+ externalRequestId: externalRequestId(req),+ hostedMcp: req.auth.hostedMcp,+ },).catch(error => {_logger.error(`Failed to bill team ${req.auth.team_id} for ${threatScanCredits} threat scan credit(s): ${error}`,@@ -402,6 +406,7 @@ export async function crawlController(endpoint: "crawl",jobId: id,externalRequestId: externalRequestId(req),+ hostedMcp: req.auth.hostedMcp,},crawl_id: id,webhook: req.body.webhook,diff --git a/apps/api/src/controllers/v2/map.ts b/apps/api/src/controllers/v2/map.tsindex 363ed14e2..5eb32af53 100644--- a/apps/api/src/controllers/v2/map.ts+++ b/apps/api/src/controllers/v2/map.ts@@ -149,6 +149,7 @@ export async function mapController(// map charge below, even if both ever billed the same mapId.chargeId: `${mapId}:avgrab`,externalRequestId: externalRequestId(req),+ hostedMcp: req.auth.hostedMcp,},).catch(error => {logger.error(@@ -292,6 +293,7 @@ export async function mapController(externalRequestId: externalRequestId(req),jobId: mapId,chargeId: mapId,+ hostedMcp: req.auth.hostedMcp,},).catch(error => {logger.error("Failed to bill team for map credits", {diff --git a/apps/api/src/controllers/v2/parse.ts b/apps/api/src/controllers/v2/parse.tsindex bfecd83c1..6ea287874 100644--- a/apps/api/src/controllers/v2/parse.ts+++ b/apps/api/src/controllers/v2/parse.ts@@ -375,6 +375,7 @@ export async function parseController(? { endpoint: "agent" as const, jobId }: { endpoint: "parse" as const, jobId }),externalRequestId: externalRequestId(req),+ hostedMcp: req.auth.hostedMcp,};if (diff --git a/apps/api/src/controllers/v2/research-proxy.ts b/apps/api/src/controllers/v2/research-proxy.tsindex e5d4863d4..c1552f307 100644--- a/apps/api/src/controllers/v2/research-proxy.ts+++ b/apps/api/src/controllers/v2/research-proxy.ts@@ -37,6 +37,7 @@ const searchCreditGate = () =>checkCreditsMiddleware(SEARCH_CREDITS_PER_TEN_RESULTS,SEARCH_CREDITS_FEATURE_ID,+ { mcpCredits: true },);const ZDR_SEARCH_CREDITS_PER_TEN_RESULTS = 10;@@ -468,6 +469,7 @@ function createResearchController(endpoint: endpoint.billAs === "scrape" ? "scrape" : "search",jobId,chargeId: jobId,+ hostedMcp: authedReq.auth.hostedMcp,},).catch(billingError => {logger.error("Failed to bill research request", {diff --git a/apps/api/src/controllers/v2/scrape.ts b/apps/api/src/controllers/v2/scrape.tsindex f81fddc73..1f89cd99a 100644--- a/apps/api/src/controllers/v2/scrape.ts+++ b/apps/api/src/controllers/v2/scrape.ts@@ -225,6 +225,7 @@ export async function scrapeController(? { endpoint: "agent" as const, jobId }: { endpoint: "scrape" as const, jobId }),externalRequestId: externalRequestId(req),+ hostedMcp: req.auth.hostedMcp,};if (diff --git a/apps/api/src/controllers/v2/search.ts b/apps/api/src/controllers/v2/search.tsindex e43b4782b..6f43f2d41 100644--- a/apps/api/src/controllers/v2/search.ts+++ b/apps/api/src/controllers/v2/search.ts@@ -315,6 +315,7 @@ async function searchControllerInner(? { endpoint: "agent" as const, jobId }: { endpoint: "search" as const, jobId }),externalRequestId: externalRequestId(req),+ hostedMcp: req.auth.hostedMcp,};logger = logger.child({diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.tsindex dc8d05c39..ab9df62cc 100644--- a/apps/api/src/controllers/v2/types.ts+++ b/apps/api/src/controllers/v2/types.ts@@ -2120,6 +2120,9 @@ type AuthObject = {// Set only by authMiddleware from the raw request; controllers may re-parse// the body and drop `__agentInterop`, so read this instead.agentInterop?: AgentInteropStatus;+ // Set only by authMiddleware, from the hosted MCP verification in+ // supaAuthenticateUser; never from the request body or headers directly.+ hostedMcp?: boolean;};type Account = {diff --git a/apps/api/src/routes/shared.ts b/apps/api/src/routes/shared.tsindex 743053bcd..f904326a9 100644--- a/apps/api/src/routes/shared.ts+++ b/apps/api/src/routes/shared.ts@@ -48,6 +48,8 @@ import { resolveIntegration } from "../utils/integration";export function checkCreditsMiddleware(_minimum?: number,featureId: string = CREDITS_FEATURE_ID,+ // Set on routes whose billing spends a hosted MCP call's MCP credits first.+ { mcpCredits = false }: { mcpCredits?: boolean } = {},): (req: RequestWithAuth, res: Response, next: NextFunction) => void {return (req, res, next) => {let minimum = _minimum;@@ -191,6 +193,27 @@ export function checkCreditsMiddleware(return next();}+ // A hosted MCP call the team's balance can't cover still runs when its+ // MCP credits can, which billing then spends first (see billTeam).+ if (+ !autumnResult.allowed &&+ mcpCredits &&+ req.auth.hostedMcp &&+ (await autumnService.mcpCreditsAvailable({+ teamId: req.auth.team_id,+ orgId,+ value: requestedCredits,+ properties: {+ source: "checkCreditsMiddleware:mcp",+ path: req.path,+ apiKeyId: req.acuc?.api_key_id ?? null,+ },+ })) >= requestedCredits+ ) {+ req.account = { remainingCredits: Infinity };+ return next();+ }+const success = autumnResult.allowed;// When Autumn allows the request (including overage), don't let a// small remaining balance clamp downstream limits (e.g. crawl).@@ -322,9 +345,14 @@ export function authMiddleware(}}- const { team_id, org_id, chunk } = auth;+ const { team_id, org_id, chunk, hostedMcp } = auth;- req.auth = { team_id, org_id, agentInterop: agentInteropStatus(req) };+ req.auth = {+ team_id,+ org_id,+ agentInterop: agentInteropStatus(req),+ ...(hostedMcp ? { hostedMcp: true } : {}),+ };req.acuc = chunk ?? undefined;next();})().catch(err => next(err));diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.tsindex 5b0e2fca6..4865edb9e 100644--- a/apps/api/src/routes/v2.ts+++ b/apps/api/src/routes/v2.ts@@ -213,7 +213,9 @@ v2Router.post(}),inferIntegrationMiddleware,restrictedOptionsCountryCheck,- checkCreditsMiddleware(undefined, SEARCH_CREDITS_FEATURE_ID),+ checkCreditsMiddleware(undefined, SEARCH_CREDITS_FEATURE_ID, {+ mcpCredits: true,+ }),blocklistMiddleware,wrap(searchController),);@@ -257,7 +259,7 @@ v2Router.post("/parse",authMiddleware(RateLimiterMode.Scrape, { allowKeyless: true }),restrictedOptionsCountryCheck,- checkCreditsMiddleware(1),+ checkCreditsMiddleware(1, undefined, { mcpCredits: true }),parsePayloadMiddleware,inferIntegrationMiddleware,wrap(parseController),@@ -271,7 +273,7 @@ v2Router.post(}),inferIntegrationMiddleware,restrictedOptionsCountryCheck,- checkCreditsMiddleware(1),+ checkCreditsMiddleware(1, undefined, { mcpCredits: true }),scrapeBlocklistMiddleware,wrap(scrapeController),);@@ -304,7 +306,7 @@ v2Router.post(authMiddleware(RateLimiterMode.Scrape, { allowAgentManagedKey: true }),inferIntegrationMiddleware,restrictedOptionsCountryCheck,- checkCreditsMiddleware(),+ checkCreditsMiddleware(undefined, undefined, { mcpCredits: true }),blocklistMiddleware,wrap(batchScrapeController),);@@ -313,7 +315,7 @@ v2Router.post("/map",authMiddleware(RateLimiterMode.Map),inferIntegrationMiddleware,- checkCreditsMiddleware(1),+ checkCreditsMiddleware(1, undefined, { mcpCredits: true }),blocklistMiddleware,wrap(mapController),);@@ -323,7 +325,7 @@ v2Router.post(authMiddleware(RateLimiterMode.Crawl),inferIntegrationMiddleware,restrictedOptionsCountryCheck,- checkCreditsMiddleware(),+ checkCreditsMiddleware(undefined, undefined, { mcpCredits: true }),scrapeBlocklistMiddleware,idempotencyMiddleware,wrap(crawlController),diff --git a/apps/api/src/services/autumn/__tests__/mcp-credits.test.ts b/apps/api/src/services/autumn/__tests__/mcp-credits.test.tsnew file mode 100644index 000000000..14b61b177--- /dev/null+++ b/apps/api/src/services/autumn/__tests__/mcp-credits.test.ts@@ -0,0 +1,369 @@+/**+ * Unit tests for hosted MCP charges in AutumnService: how much the team's MCP+ * credits can pay (mcpCreditsAvailable), and how a charge is split between+ * them and the endpoint's own feature (trackHostedMcpCredits).+ */++import { vi } from "vitest";++const { mockCheck, mockTrack, mockAutumnClient, state, redis } = vi.hoisted(+ () => {+ const store = new Map<string, string>();+ const redis = {+ store,+ get: vi.fn(async (key: string) => store.get(key) ?? null),+ set: vi.fn(async (key: string, value: unknown, ...args: unknown[]) => {+ if (args.includes("NX") && store.has(key)) return null;+ store.set(key, String(value));+ return "OK";+ }),+ };+ const mockCheck = vi.fn<(args: any) => Promise<any>>();+ const mockTrack = vi.fn<(args: any) => Promise<void>>();+ const mockAutumnClient = {+ customers: { getOrCreate: vi.fn(), get: vi.fn() },+ entities: {+ get: vi.fn().mockResolvedValue({ id: "team-1" }),+ create: vi.fn(),+ },+ balances: { finalize: vi.fn() },+ check: mockCheck,+ track: mockTrack,+ };+ return {+ mockCheck,+ mockTrack,+ mockAutumnClient,+ state: { gatewayStubRow: null as unknown },+ redis,+ };+ },+);++vi.mock("../client", () => ({+ autumnClient: mockAutumnClient,+}));++vi.mock("../../queue-service", () => ({+ getFirebillTrackRetryQueue: () => ({ add: vi.fn() }),+ getRedisConnection: () => redis,+}));++vi.mock("../../../db/connection", () => ({+ get dbRr() {+ return {+ select: () => ({+ from: () => ({+ where: () => ({+ limit: () =>+ Promise.resolve(+ state.gatewayStubRow ? [state.gatewayStubRow] : [],+ ),+ }),+ }),+ }),+ };+ },+}));++vi.mock("../../../config", () => ({+ config: { MCP_CREDITS_FEATURE_ID: "MCP_CREDITS_FROM_CONFIG" },+}));++import { AutumnService, MCP_CREDITS_FEATURE_ID } from "../autumn.service";++const charge = {+ teamId: "team-1",+ orgId: "org-1",+ value: 5,+ properties: { source: "billTeam", endpoint: "scrape" },+ featureId: "CREDITS",+ idempotencyKey: "fc:track:scrape:job-1",+ externalRequestId: "op-1",+};++/** MCP credits balance as Autumn's check reports it. */+function mcpBalance(remaining: number | null) {+ mockCheck.mockImplementation(async ({ featureId, requiredBalance }) => ({+ allowed:+ featureId === MCP_CREDITS_FEATURE_ID &&+ remaining !== null &&+ remaining >= requiredBalance,+ customerId: "org-1",+ balance: remaining === null ? null : { remaining },+ }));+}++/** The Autumn track calls a run of fn makes. */+async function tracksOf(fn: (service: AutumnService) => Promise<unknown>) {+ mockTrack.mockClear();+ await fn(new AutumnService());+ return mockTrack.mock.calls.map(([args]) => args);+}++beforeEach(() => {+ vi.clearAllMocks();+ state.gatewayStubRow = null;+ redis.store.clear();+ mockTrack.mockResolvedValue(undefined);+ mcpBalance(100);+});++describe("mcpCreditsAvailable", () => {+ it("reads the feature id from config", () => {+ expect(MCP_CREDITS_FEATURE_ID).toBe("MCP_CREDITS_FROM_CONFIG");+ });++ it("pays the whole charge when the MCP credits cover it", async () => {+ expect(await new AutumnService().mcpCreditsAvailable(charge)).toBe(5);+ expect(mockCheck).toHaveBeenCalledExactlyOnceWith(+ expect.objectContaining({+ customerId: "org-1",+ entityId: "team-1",+ featureId: MCP_CREDITS_FEATURE_ID,+ requiredBalance: 5,+ }),+ );+ });++ it("pays what is left when the MCP credits fall short", async () => {+ mcpBalance(3.5);+ expect(await new AutumnService().mcpCreditsAvailable(charge)).toBe(3);+ });++ it.each([+ ["used up", 0],+ ["missing from the team's plan", null],+ ])("pays nothing when the MCP credits are %s", async (_name, remaining) => {+ mcpBalance(remaining);+ expect(await new AutumnService().mcpCreditsAvailable(charge)).toBe(0);+ });++ it("pays nothing when Autumn can't answer", async () => {+ mockCheck.mockRejectedValue(new Error("ECONNRESET"));+ expect(await new AutumnService().mcpCreditsAvailable(charge)).toBe(0);+ });++ it("never asks Autumn for a partner-provisioned or preview team, or a zero charge", async () => {+ const service = new AutumnService();+ state.gatewayStubRow = { team_id: "team-1" };+ expect(await service.mcpCreditsAvailable(charge)).toBe(0);+ state.gatewayStubRow = null;+ expect(+ await service.mcpCreditsAvailable({ ...charge, teamId: "preview_1" }),+ ).toBe(0);+ expect(await service.mcpCreditsAvailable({ ...charge, value: 0 })).toBe(0);+ expect(mockCheck).not.toHaveBeenCalled();+ });+});++describe("trackHostedMcpCredits", () => {+ it("tracks the whole charge on MCP credits that cover it", async () => {+ const tracks = await tracksOf(service =>+ service+ .trackHostedMcpCredits(charge)+ .then(result =>+ expect(result).toEqual({ tracked: true, mcpCredits: 5 }),+ ),+ );++ expect(tracks).toEqual([+ expect.objectContaining({+ featureId: MCP_CREDITS_FEATURE_ID,+ value: 5,+ properties: charge.properties,+ }),+ ]);+ });++ it("splits a charge the MCP credits only partly cover", async () => {+ mcpBalance(3);++ const tracks = await tracksOf(service =>+ service+ .trackHostedMcpCredits(charge)+ .then(result =>+ expect(result).toEqual({ tracked: true, mcpCredits: 3 }),+ ),+ );++ expect(tracks).toHaveLength(2);+ expect(tracks).toContainEqual(+ expect.objectContaining({ featureId: MCP_CREDITS_FEATURE_ID, value: 3 }),+ );+ expect(tracks).toContainEqual(+ expect.objectContaining({+ featureId: "CREDITS",+ value: 2,+ overageBehavior: "overflow",+ }),+ );+ });++ it("gives the MCP part its own firebill idempotency key", async () => {+ mcpBalance(3);+ const service = new AutumnService();+ const trackCredits = vi.spyOn(service, "trackCredits");++ await service.trackHostedMcpCredits(charge);++ expect(trackCredits).toHaveBeenCalledWith(+ expect.objectContaining({+ featureId: MCP_CREDITS_FEATURE_ID,+ idempotencyKey: "fc:track:scrape:job-1:mcp",+ }),+ );+ expect(trackCredits).toHaveBeenCalledWith({ ...charge, value: 2 });+ });++ it.each([+ ["used up", 0],+ ["missing from the team's plan", null],+ ])(+ "tracks exactly what trackCredits would when the MCP credits are %s",+ async (_name, remaining) => {+ mcpBalance(remaining);++ const hostedMcp = await tracksOf(service =>+ service+ .trackHostedMcpCredits(charge)+ .then(result =>+ expect(result).toEqual({ tracked: true, mcpCredits: 0 }),+ ),+ );+ const regular = await tracksOf(service => service.trackCredits(charge));++ expect(hostedMcp).toEqual(regular);+ expect(hostedMcp).toEqual([+ expect.objectContaining({ featureId: "CREDITS", value: 5 }),+ ]);+ },+ );++ it("reports an untracked MCP part as not paid by MCP credits", async () => {+ mcpBalance(3);+ mockTrack.mockImplementation(async ({ featureId }) => {+ if (featureId === MCP_CREDITS_FEATURE_ID) throw new Error("track failed");+ });++ expect(await new AutumnService().trackHostedMcpCredits(charge)).toEqual({+ tracked: false,+ mcpCredits: 0,+ });+ });+});++describe("refundHostedMcpCredits", () => {+ const refund = { ...charge, idempotencyKey: "fc:refund:scrape:job-1" };++ it("refunds each part of a split charge to the balance it was tracked on", async () => {+ const service = new AutumnService();+ const refundCredits = vi.spyOn(service, "refundCredits");++ expect(+ await service.refundHostedMcpCredits({ ...refund, mcpCredits: 3 }),+ ).toBe(true);++ expect(refundCredits).toHaveBeenCalledTimes(2);+ expect(refundCredits).toHaveBeenCalledWith({+ ...refund,+ value: 3,+ featureId: MCP_CREDITS_FEATURE_ID,+ idempotencyKey: "fc:refund:scrape:job-1:mcp",+ });+ expect(refundCredits).toHaveBeenCalledWith({ ...refund, value: 2 });+ });++ it("refunds a charge MCP credits paid in full to them only", async () => {+ const service = new AutumnService();+ const refundCredits = vi.spyOn(service, "refundCredits");++ await service.refundHostedMcpCredits({ ...refund, mcpCredits: 5 });++ expect(refundCredits).toHaveBeenCalledExactlyOnceWith(+ expect.objectContaining({ value: 5, featureId: MCP_CREDITS_FEATURE_ID }),+ );+ });++ it("refunds exactly as refundCredits would when MCP credits paid nothing", async () => {+ const service = new AutumnService();+ const refundCredits = vi.spyOn(service, "refundCredits");++ await service.refundHostedMcpCredits({ ...refund, mcpCredits: 0 });++ expect(refundCredits).toHaveBeenCalledExactlyOnceWith(refund);+ });+});++describe("hosted MCP charge retries", () => {+ it("splits a retried charge as the first attempt did, after it used the MCP credits up", async () => {+ mcpBalance(5);+ const first = await tracksOf(service =>+ service.trackHostedMcpCredits(charge),+ );+ mcpBalance(0);+ const retry = await tracksOf(service =>+ service+ .trackHostedMcpCredits(charge)+ .then(result =>+ expect(result).toEqual({ tracked: true, mcpCredits: 5 }),+ ),+ );++ expect(retry).toEqual(first);+ expect(retry).toEqual([+ expect.objectContaining({ featureId: MCP_CREDITS_FEATURE_ID, value: 5 }),+ ]);+ });++ it("records the allocation once, for 7 days, under the charge's key", async () => {+ mcpBalance(3);++ await new AutumnService().trackHostedMcpCredits(charge);++ expect(redis.set).toHaveBeenCalledExactlyOnceWith(+ "fc:mcp-credits:allocation:fc:track:scrape:job-1",+ 3,+ "EX",+ 7 * 24 * 60 * 60,+ "NX",+ );+ });++ it("works the split out afresh for a charge without a key", async () => {+ mcpBalance(3);++ await new AutumnService().trackHostedMcpCredits({+ ...charge,+ idempotencyKey: undefined,+ });++ expect(redis.get).not.toHaveBeenCalled();+ expect(redis.set).not.toHaveBeenCalled();+ });++ it("works the split out afresh when Redis hangs", async () => {+ vi.useFakeTimers();+ try {+ mcpBalance(3);+ redis.get.mockReturnValueOnce(new Promise<string | null>(() => {}));++ const result = new AutumnService().trackHostedMcpCredits(charge);+ await vi.advanceTimersByTimeAsync(1000);++ expect(await result).toEqual({ tracked: true, mcpCredits: 3 });+ } finally {+ vi.useRealTimers();+ }+ });++ it("works the split out afresh when Redis can't answer", async () => {+ mcpBalance(3);+ redis.get.mockRejectedValueOnce(new Error("redis down"));++ expect(await new AutumnService().trackHostedMcpCredits(charge)).toEqual({+ tracked: true,+ mcpCredits: 3,+ });+ });+});diff --git a/apps/api/src/services/autumn/autumn.service.ts b/apps/api/src/services/autumn/autumn.service.tsindex 873c61352..e43685b28 100644--- a/apps/api/src/services/autumn/autumn.service.ts+++ b/apps/api/src/services/autumn/autumn.service.ts@@ -19,6 +19,7 @@ import {autumnEntityCreatedInlineTotal,billingRouteTotal,} from "./metrics";+import { getRedisConnection } from "../queue-service";import type {CreateEntityParams,CreateEntityResult,@@ -37,6 +38,12 @@ import { ExistingCreditsLockError } from "./types";export const TEAM_FEATURE_ID = "TEAM";export const CREDITS_FEATURE_ID = "CREDITS";export const SEARCH_CREDITS_FEATURE_ID = "SEARCH_CREDITS";+/**+ * The balance hosted MCP calls spend before the endpoint's own feature (see+ * AutumnService.trackHostedMcpCredits). Configurable so the id can follow the+ * Autumn feature without a code change.+ */+export const MCP_CREDITS_FEATURE_ID = config.MCP_CREDITS_FEATURE_ID;const CONCURRENCY_FEATURE_ID = "CONCURRENCY";const RATE_LIMIT_FEATURE_ID = "rate_limits";@@ -567,6 +574,158 @@ export class AutumnService {}}+ /**+ * How much of a hosted MCP charge of `value` the team's MCP credits+ * (MCP_CREDITS_FEATURE_ID) can pay: all of it, or what is left when that is+ * less. 0 for a team without the feature or with none left, for a+ * partner-provisioned team (its usage is split with the partner on the+ * regular features), and when Autumn can't answer.+ */+ async mcpCreditsAvailable({+ teamId,+ orgId,+ value,+ properties,+ }: Pick<+ TrackCreditsParams,+ "teamId" | "orgId" | "value" | "properties"+ >): Promise<number> {+ if (!(value > 0) || this.isPreviewTeam(teamId)) return 0;+ if (await this.isGatewayProvisioned(teamId)) return 0;+ const result = await this.checkCredits({+ teamId,+ orgId,+ value,+ properties,+ featureId: MCP_CREDITS_FEATURE_ID,+ });+ if (!result) return 0;+ if (result.allowed) return value;+ return Math.max(0, Math.min(value, Math.floor(result.remaining)));+ }++ /**+ * The MCP credits part of a keyed hosted MCP charge. The first attempt+ * records it, so a retry under the same key (a stalled job re-running its+ * charge) splits the charge the same way and each part dedupes against its+ * first track, even after that first track used the MCP credits up. Without+ * a key, or when Redis doesn't answer within a second, it is worked out+ * afresh. The shared connection queues commands while Redis is down rather+ * than failing them, hence the bound.+ */+ private async hostedMcpAllocation(params: TrackCreditsParams) {+ if (!params.idempotencyKey) return this.mcpCreditsAvailable(params);+ const key = `fc:mcp-credits:allocation:${params.idempotencyKey}`;+ const redis = getRedisConnection();+ const bounded = async <T>(command: Promise<T>): Promise<T> => {+ let timer: NodeJS.Timeout | undefined;+ try {+ return await Promise.race([+ command,+ new Promise<never>((_, reject) => {+ timer = setTimeout(+ () => reject(new Error("Redis did not answer in time")),+ 1000,+ );+ }),+ ]);+ } finally {+ clearTimeout(timer);+ }+ };+ try {+ const recorded = await bounded(redis.get(key));+ if (recorded !== null) return Number(recorded);+ } catch (error) {+ logger.warn("Failed to read a hosted MCP charge's allocation", {+ key,+ error,+ });+ return this.mcpCreditsAvailable(params);+ }+ const mcpCredits = await this.mcpCreditsAvailable(params);+ try {+ if (+ (await bounded(+ redis.set(key, mcpCredits, "EX", 7 * 24 * 60 * 60, "NX"),+ )) === null+ ) {+ const recorded = await bounded(redis.get(key));+ if (recorded !== null) return Number(recorded);+ }+ } catch (error) {+ logger.warn("Failed to record a hosted MCP charge's allocation", {+ key,+ error,+ });+ }+ return mcpCredits;+ }++ /**+ * Tracks a hosted MCP charge: the part the team's MCP credits can pay (see+ * mcpCreditsAvailable) on MCP_CREDITS_FEATURE_ID, and the rest on+ * `featureId`, the endpoint's own feature. When the MCP credits pay nothing,+ * the whole charge is tracked exactly as trackCredits would track it.+ * Resolves whether every part was tracked, and the credits tracked on+ * MCP_CREDITS_FEATURE_ID: those were charged even when `tracked` is false,+ * so a caller reversing the charge reverses them on their own.+ */+ async trackHostedMcpCredits(+ params: TrackCreditsParams,+ ): Promise<{ tracked: boolean; mcpCredits: number }> {+ const mcpCredits = await this.hostedMcpAllocation(params);+ const rest = params.value - mcpCredits;+ const [mcpTracked, restTracked] = await Promise.all([+ mcpCredits > 0+ ? this.trackCredits({+ ...params,+ value: mcpCredits,+ featureId: MCP_CREDITS_FEATURE_ID,+ // Its own charge event: the rest keeps the caller's key, and the+ // same key would dedupe one part against the other.+ idempotencyKey:+ params.idempotencyKey && `${params.idempotencyKey}:mcp`,+ })+ : true,+ mcpCredits === 0 || rest > 0+ ? this.trackCredits({ ...params, value: rest })+ : true,+ ]);+ return {+ tracked: mcpTracked && restTracked,+ mcpCredits: mcpTracked ? mcpCredits : 0,+ };+ }++ /**+ * Reverses a trackHostedMcpCredits charge: `mcpCredits` back to+ * MCP_CREDITS_FEATURE_ID and the rest to `featureId`, each part keyed as it+ * was tracked. With no MCP credits it is exactly refundCredits. Resolves+ * whether every part was refunded.+ */+ async refundHostedMcpCredits({+ mcpCredits,+ ...params+ }: TrackCreditsParams & { mcpCredits: number }): Promise<boolean> {+ const rest = params.value - mcpCredits;+ const [mcpRefunded, restRefunded] = await Promise.all([+ mcpCredits > 0+ ? this.refundCredits({+ ...params,+ value: mcpCredits,+ featureId: MCP_CREDITS_FEATURE_ID,+ idempotencyKey:+ params.idempotencyKey && `${params.idempotencyKey}:mcp`,+ })+ : true,+ mcpCredits === 0 || rest > 0+ ? this.refundCredits({ ...params, value: rest })+ : true,+ ]);+ return mcpRefunded && restRefunded;+ }+/*** Whether the org has an auto top-up that can actually fire for CREDITS: it* is enabled, and the org holds a prepaid CREDITS item for it to buy. Autumndiff --git a/apps/api/src/services/billing/__tests__/batch_billing.test.ts b/apps/api/src/services/billing/__tests__/batch_billing.test.tsindex 69432224a..d1b41827e 100644--- a/apps/api/src/services/billing/__tests__/batch_billing.test.ts+++ b/apps/api/src/services/billing/__tests__/batch_billing.test.ts@@ -10,6 +10,7 @@ const {refundCredits,billTeam7,getACUCTeam,+ reportExchangeBilling,} = vi.hoisted(() => {const logger: any = {info: vi.fn(),@@ -24,9 +25,14 @@ const {refundCredits: vi.fn<(args: any) => Promise<void>>(),billTeam7: vi.fn<(params: any) => Promise<{ api_key: string }[]>>(),getACUCTeam: vi.fn<(teamId: string) => Promise<any>>(),+ reportExchangeBilling: vi.fn<(args: any) => Promise<boolean>>(),};});+vi.mock("../../../lib/exchange", () => ({+ reportExchangeBilling,+}));+vi.mock("../../../lib/logger", () => ({logger,}));@@ -42,6 +48,7 @@ vi.mock("../../autumn/autumn.service", () => ({},featureIdForBillingEndpoint: (endpoint?: string) =>endpoint === "search" ? "SEARCH_CREDITS" : "CREDITS",+ MCP_CREDITS_FEATURE_ID: "MCP_CREDITS",}));vi.mock("../../../db/rpc", () => ({@@ -120,6 +127,7 @@ vi.mock("../../queue-service", () => ({import {processBillingBatch,+ queueBillingOperation,startBillingBatchProcessing,} from "../batch_billing";@@ -428,3 +436,150 @@ describe("startBillingBatchProcessing", () => {expect(queue).toHaveLength(0);});});++describe("MCP credits on the ledger", () => {+ it("records the part MCP credits paid as its own tagged row", async () => {+ await queueBillingOperation(+ "team-1",+ "org-1",+ 5,+ 123,+ { endpoint: "scrape", hostedMcp: true, mcpCredits: 3 },+ false,+ true,+ );+ expect(queue).toHaveLength(1);++ await processBillingBatch();++ expect(billTeam7).toHaveBeenCalledTimes(2);+ expect(billTeam7).toHaveBeenCalledWith(+ expect.objectContaining({ credits: 2, subscription_id: null }),+ );+ expect(billTeam7).toHaveBeenCalledWith(+ expect.objectContaining({ credits: 3, subscription_id: "mcp_credits" }),+ );+ });++ it("records a charge MCP credits paid in full as one tagged row", async () => {+ await queueBillingOperation(+ "team-1",+ "org-1",+ 5,+ 123,+ { endpoint: "scrape", hostedMcp: true, mcpCredits: 5 },+ false,+ true,+ );+ await processBillingBatch();++ expect(billTeam7).toHaveBeenCalledExactlyOnceWith(+ expect.objectContaining({ credits: 5, subscription_id: "mcp_credits" }),+ );+ });++ it("records a charge MCP credits paid nothing of as today's untagged row", async () => {+ await queueBillingOperation(+ "team-1",+ "org-1",+ 5,+ 123,+ { endpoint: "scrape", hostedMcp: true },+ false,+ true,+ );+ await processBillingBatch();++ expect(billTeam7).toHaveBeenCalledExactlyOnceWith({+ team_id: "team-1",+ subscription_id: null,+ credits: 5,+ api_key_id: 123,+ is_extract: false,+ });+ });++ it("refunds each part to the balance it was tracked on when the ledger fails", async () => {+ await queueBillingOperation(+ "team-1",+ "org-1",+ 5,+ 123,+ { endpoint: "scrape", hostedMcp: true, mcpCredits: 3 },+ false,+ true,+ );+ billTeam7.mockRejectedValue(new Error("db failed"));++ await processBillingBatch();++ expect(refundCredits).toHaveBeenCalledTimes(2);+ expect(refundCredits).toHaveBeenCalledWith(+ expect.objectContaining({ value: 2, featureId: "CREDITS" }),+ );+ expect(refundCredits).toHaveBeenCalledWith(+ expect.objectContaining({ value: 3, featureId: "MCP_CREDITS" }),+ );+ });++ it("refunds only the MCP credits part when the rest was not tracked", async () => {+ await queueBillingOperation(+ "team-1",+ "org-1",+ 5,+ 123,+ { endpoint: "scrape", hostedMcp: true, mcpCredits: 3 },+ false,+ false,+ );+ billTeam7.mockRejectedValue(new Error("db failed"));++ await processBillingBatch();++ expect(refundCredits).toHaveBeenCalledExactlyOnceWith(+ expect.objectContaining({ value: 3, featureId: "MCP_CREDITS" }),+ );+ });++ it("confirms a split charge's Exchange access once, after both rows commit", async () => {+ await queueBillingOperation(+ "team-1",+ "org-1",+ 5,+ 123,+ { endpoint: "scrape", hostedMcp: true, mcpCredits: 3 },+ false,+ true,+ { accessEventId: "access-1", billingReference: "ref-1" },+ );+ await processBillingBatch();++ expect(reportExchangeBilling).toHaveBeenCalledExactlyOnceWith({+ accessEventId: "access-1",+ status: "confirmed",+ billingReference: "ref-1",+ });+ });++ it("leaves a split charge's Exchange access pending when one row fails", async () => {+ await queueBillingOperation(+ "team-1",+ "org-1",+ 5,+ 123,+ { endpoint: "scrape", hostedMcp: true, mcpCredits: 3 },+ false,+ true,+ { accessEventId: "access-1" },+ );+ billTeam7.mockImplementation(async ({ subscription_id }) => {+ if (subscription_id === "mcp_credits") throw new Error("db failed");+ return [];+ });++ await processBillingBatch();++ expect(billTeam7).toHaveBeenCalledTimes(2);+ expect(reportExchangeBilling).not.toHaveBeenCalled();+ });+});diff --git a/apps/api/src/services/billing/__tests__/credit_billing.test.ts b/apps/api/src/services/billing/__tests__/credit_billing.test.tsindex c5ad2c54c..a54e0b288 100644--- a/apps/api/src/services/billing/__tests__/credit_billing.test.ts+++ b/apps/api/src/services/billing/__tests__/credit_billing.test.ts@@ -7,6 +7,8 @@ const {trackCredits,refundCredits,isRoutedThroughFirebill,+ trackHostedMcpCredits,+ refundHostedMcpCredits,} = vi.hoisted(() => ({withAuth: vi.fn((fn: any) => fn),queueBillingOperation: vi.fn<(args: any[]) => Promise<any>>(),@@ -14,6 +16,9 @@ const {refundCredits: vi.fn<(args: any) => Promise<void>>(),isRoutedThroughFirebill:vi.fn<(teamId: string, orgId: string) => Promise<boolean>>(),+ trackHostedMcpCredits:+ vi.fn<(args: any) => Promise<{ tracked: boolean; mcpCredits: number }>>(),+ refundHostedMcpCredits: vi.fn<(args: any) => Promise<boolean>>(),}));vi.mock("../../../lib/withAuth", () => ({@@ -29,6 +34,8 @@ vi.mock("../../autumn/autumn.service", () => ({trackCredits,refundCredits,isRoutedThroughFirebill,+ trackHostedMcpCredits,+ refundHostedMcpCredits,},featureIdForBillingEndpoint: (endpoint?: string) =>endpoint === "search" ? "SEARCH_CREDITS" : "CREDITS",@@ -57,6 +64,7 @@ beforeEach(() => {trackCredits.mockResolvedValue(true);refundCredits.mockResolvedValue(undefined);isRoutedThroughFirebill.mockResolvedValue(false);+ trackHostedMcpCredits.mockResolvedValue({ tracked: true, mcpCredits: 0 });});describe("billTeam", () => {@@ -231,3 +239,140 @@ describe("billTeam", () => {expect(refundCredits).not.toHaveBeenCalled();});});++describe("billTeam MCP credits", () => {+ const hostedMcpScrape = {+ endpoint: "scrape" as const,+ jobId: "job-1",+ chargeId: "job-1",+ hostedMcp: true,+ };++ it("charges a hosted MCP call through the MCP credits split", async () => {+ trackHostedMcpCredits.mockResolvedValue({ tracked: true, mcpCredits: 2 });++ await billTeam("team-1", "org-1", 3, 123, hostedMcpScrape);++ expect(trackHostedMcpCredits).toHaveBeenCalledExactlyOnceWith({+ teamId: "team-1",+ orgId: "org-1",+ value: 3,+ properties: {+ source: "billTeam",+ endpoint: "scrape",+ jobId: "job-1",+ apiKeyId: 123,+ },+ featureId: "CREDITS",+ idempotencyKey: "fc:track:scrape:job-1",+ externalRequestId: undefined,+ });+ expect(trackCredits).not.toHaveBeenCalled();+ // The ledger records the MCP-paid part apart from regular credits.+ expect(queueBillingOperation).toHaveBeenCalledWith([+ "team-1",+ "org-1",+ 3,+ 123,+ { ...hostedMcpScrape, mcpCredits: 2 },+ false,+ true,+ ]);+ });++ it("queues an unchanged ledger operation when MCP credits paid nothing", async () => {+ trackHostedMcpCredits.mockResolvedValue({ tracked: true, mcpCredits: 0 });++ await billTeam("team-1", "org-1", 3, 123, hostedMcpScrape);++ expect(queueBillingOperation).toHaveBeenCalledWith([+ "team-1",+ "org-1",+ 3,+ 123,+ hostedMcpScrape,+ false,+ true,+ ]);+ });++ it("refunds a failed enqueue to the balances the charge was tracked on", async () => {+ trackHostedMcpCredits.mockResolvedValue({ tracked: true, mcpCredits: 2 });+ queueBillingOperation.mockResolvedValueOnce({ success: false });++ await billTeam("team-1", "org-1", 3, 123, hostedMcpScrape);++ expect(refundHostedMcpCredits).toHaveBeenCalledExactlyOnceWith({+ teamId: "team-1",+ orgId: "org-1",+ value: 3,+ mcpCredits: 2,+ properties: {+ source: "billTeam",+ endpoint: "scrape",+ jobId: "job-1",+ apiKeyId: 123,+ },+ featureId: "CREDITS",+ idempotencyKey: "fc:refund:scrape:job-1",+ externalRequestId: undefined,+ });+ expect(refundCredits).not.toHaveBeenCalled();+ });++ it("refunds the MCP credits part of a failed enqueue even when the rest was not tracked", async () => {+ trackHostedMcpCredits.mockResolvedValue({ tracked: false, mcpCredits: 2 });+ queueBillingOperation.mockResolvedValueOnce({ success: false });++ await billTeam("team-1", "org-1", 3, 123, hostedMcpScrape);++ expect(queueBillingOperation).toHaveBeenCalledWith(+ expect.arrayContaining([false]),+ );+ expect(refundHostedMcpCredits).toHaveBeenCalledExactlyOnceWith(+ expect.objectContaining({ value: 2, mcpCredits: 2 }),+ );+ expect(refundCredits).not.toHaveBeenCalled();+ });++ it("refunds nothing for a failed enqueue when nothing was tracked", async () => {+ trackHostedMcpCredits.mockResolvedValue({ tracked: false, mcpCredits: 0 });+ queueBillingOperation.mockResolvedValueOnce({ success: false });++ await billTeam("team-1", "org-1", 3, 123, hostedMcpScrape);++ expect(refundHostedMcpCredits).not.toHaveBeenCalled();+ expect(refundCredits).not.toHaveBeenCalled();+ });++ it("refunds a failed enqueue MCP credits paid nothing of as today", async () => {+ trackHostedMcpCredits.mockResolvedValue({ tracked: true, mcpCredits: 0 });+ queueBillingOperation.mockResolvedValueOnce({ success: false });++ await billTeam("team-1", "org-1", 3, 123, hostedMcpScrape);++ expect(refundCredits).toHaveBeenCalledWith(+ expect.objectContaining({ value: 3, featureId: "CREDITS" }),+ );+ expect(refundHostedMcpCredits).not.toHaveBeenCalled();+ });++ it("never goes through the MCP credits split for a call the hosted MCP did not make", async () => {+ await billTeam("team-1", "org-1", 3, 123, {+ endpoint: "scrape",+ jobId: "job-1",+ });++ expect(trackHostedMcpCredits).not.toHaveBeenCalled();+ expect(trackCredits).toHaveBeenCalledWith(+ expect.objectContaining({ featureId: "CREDITS" }),+ );+ });++ it("never charges Autumn for a team without an org", async () => {+ await billTeam("preview_abc", null, 3, null, hostedMcpScrape);++ expect(trackHostedMcpCredits).not.toHaveBeenCalled();+ expect(trackCredits).not.toHaveBeenCalled();+ });+});diff --git a/apps/api/src/services/billing/batch_billing.ts b/apps/api/src/services/billing/batch_billing.tsindex 0fbb35c6d..4e8d57c8d 100644--- a/apps/api/src/services/billing/batch_billing.ts+++ b/apps/api/src/services/billing/batch_billing.ts@@ -5,6 +5,7 @@ import { withAuth } from "../../lib/withAuth";import {autumnService,featureIdForBillingEndpoint,+ MCP_CREDITS_FEATURE_ID,} from "../autumn/autumn.service";import {resolveBillingMetadata,@@ -83,6 +84,9 @@ const BATCH_LOCK_KEY = "billing_batch_lock";const BATCH_SIZE = 5000; // Batch size for processingconst BATCH_TIMEOUT = 15000; // 15 seconds processing intervalconst LOCK_TIMEOUT = 30000; // 30 seconds lock timeout+// The ledger's tag for usage the team's MCP credits paid. bill_team_7 stores it+// in credit_usage.subscription_id, which it passes through as a tag.+const MCP_CREDITS_LEDGER_TAG = "mcp_credits";// Define interfaces for billing operationsinterface BillingOperation {@@ -115,6 +119,7 @@ interface GroupedBillingOperation {billing: BillingMetadata;is_extract: boolean;api_key_id: number | null;+ ledger_tag?: string;operations: BillingOperation[];}@@ -186,7 +191,11 @@ async function refundRequestTrackedCredits(...toAutumnBillingProperties(group.billing),apiKeyId: group.api_key_id,},- featureId: featureIdForBillingEndpoint(group.billing.endpoint),+ // The part MCP credits paid goes back to them.+ featureId:+ group.ledger_tag === MCP_CREDITS_LEDGER_TAG+ ? MCP_CREDITS_FEATURE_ID+ : featureIdForBillingEndpoint(group.billing.endpoint),});} catch (error) {logger.warn("Failed to refund Autumn request-tracked credits", {@@ -211,8 +220,11 @@ export async function processBillingBatch() {}// Exchange operations whose debit committed this run; their ledger- // confirmations are delivered after the lock is released.+ // confirmations are delivered after the lock is released. An operation+ // MCP credits paid part of is split across ledger rows, so each access+ // counts the rows it spans.const committedExchangeOps: BillingOperation[] = [];+ const exchangeRowCounts = new Map<string, number>();try {// Get all operations from Redis list@@ -287,23 +299,51 @@ export async function processBillingBatch() {} else {orgId = op.org_id;}- const key = `${op.team_id}:${orgId}:${billing.endpoint}:${op.is_extract}:${op.api_key_id}`;-- if (!groupedOperations.has(key)) {- groupedOperations.set(key, {- team_id: op.team_id,- org_id: orgId,- total_credits: 0,- billing,- is_extract: op.is_extract,- api_key_id: op.api_key_id,- operations: [],- });+ // The part the team's MCP credits paid is its own ledger row, tagged so+ // MCP-paid usage is counted apart from regular credits used.+ const mcpCredits = Math.min(billing.mcpCredits ?? 0, op.credits);+ const parts = [+ ...(mcpCredits === 0 || mcpCredits < op.credits+ ? [{ credits: op.credits - mcpCredits, ledger_tag: undefined }]+ : []),+ ...(mcpCredits > 0+ ? [{ credits: mcpCredits, ledger_tag: MCP_CREDITS_LEDGER_TAG }]+ : []),+ ];+ if (op.exchange_access_event_id !== undefined) {+ exchangeRowCounts.set(+ op.exchange_access_event_id,+ (exchangeRowCounts.get(op.exchange_access_event_id) ?? 0) ++ parts.length,+ );}+ for (const { credits, ledger_tag } of parts) {+ const key = `${op.team_id}:${orgId}:${billing.endpoint}:${ledger_tag ?? ""}:${op.is_extract}:${op.api_key_id}`;++ if (!groupedOperations.has(key)) {+ groupedOperations.set(key, {+ team_id: op.team_id,+ org_id: orgId,+ total_credits: 0,+ billing,+ is_extract: op.is_extract,+ api_key_id: op.api_key_id,+ ledger_tag,+ operations: [],+ });+ }- const group = groupedOperations.get(key)!;- group.total_credits += op.credits;- group.operations.push(op);+ const group = groupedOperations.get(key)!;+ group.total_credits += credits;+ // MCP credits are only recorded once their track succeeded, so their+ // row is refundable even when the rest of the charge was not tracked.+ group.operations.push({+ ...op,+ credits,+ autumnTrackInRequest:+ ledger_tag === MCP_CREDITS_LEDGER_TAG || op.autumnTrackInRequest,+ });+ }}if (unresolvedOperations.length > 0) {@@ -350,6 +390,7 @@ export async function processBillingBatch() {group.api_key_id,logger,group.is_extract,+ group.ledger_tag ?? null,);if (!billingResult.success) {@@ -401,7 +442,23 @@ export async function processBillingBatch() {await releaseLock();}- await confirmExchangeOutcomes(committedExchangeOps);+ // An access is confirmed once, and only after every row it spans committed.+ const committedRows = new Map<string, BillingOperation[]>();+ for (const op of committedExchangeOps) {+ const accessEventId = op.exchange_access_event_id!;+ committedRows.set(accessEventId, [+ ...(committedRows.get(accessEventId) ?? []),+ op,+ ]);+ }+ await confirmExchangeOutcomes(+ [...committedRows]+ .filter(+ ([accessEventId, rows]) =>+ rows.length === exchangeRowCounts.get(accessEventId),+ )+ .map(([, rows]) => rows[0]),+ );}// Start periodic batch processing@@ -515,6 +572,7 @@ async function supaBillTeam(api_key_id: number | null,__logger?: any,is_extract: boolean = false,+ subscription_id: string | null = null,) {const _logger = (__logger ?? logger).child({module: "credit_billing",@@ -534,7 +592,7 @@ async function supaBillTeam(try {data = await billTeam7({team_id,- subscription_id: null,+ subscription_id,credits,api_key_id: api_key_id ?? null,is_extract,diff --git a/apps/api/src/services/billing/credit_billing.ts b/apps/api/src/services/billing/credit_billing.tsindex a8d54da0a..6aefa9c10 100644--- a/apps/api/src/services/billing/credit_billing.ts+++ b/apps/api/src/services/billing/credit_billing.ts@@ -40,10 +40,11 @@ export async function billTeam(const featureId = featureIdForBillingEndpoint(billing.endpoint);let trackedInRequest = false;+ let mcpCredits = 0;if (org_id !== null) {// Stable per-charge key (firebill route only): a caller retry or re-run// job with the same chargeId dedupes instead of double-billing.- trackedInRequest = await autumnService.trackCredits({+ const charge = {teamId: team_id,orgId: org_id,value: credits,@@ -53,7 +54,14 @@ export async function billTeam(? `fc:track:${billing.endpoint}:${billing.chargeId}`: undefined,externalRequestId: billing.externalRequestId ?? undefined,- });+ };+ // A hosted MCP charge spends the team's MCP credits first.+ if (billing.hostedMcp) {+ ({ tracked: trackedInRequest, mcpCredits } =+ await autumnService.trackHostedMcpCredits(charge));+ } else {+ trackedInRequest = await autumnService.trackCredits(charge);+ }} else if (team_id !== "preview" && !team_id.startsWith("preview_")) {// Preview teams are never tracked anyway; a real team arriving without// an org is not expected, and its usage is about to go unmetered.@@ -68,13 +76,19 @@ export async function billTeam(org_id,credits,api_key_id,- billing,+ mcpCredits > 0 ? { ...billing, mcpCredits } : billing,false,trackedInRequest,);// A track only happens with an org in hand; named again so the type says so.- if (!result.success && trackedInRequest && org_id !== null) {+ // A charge the MCP credits paid part of is refundable for that part even+ // when the rest was not tracked.+ if (+ !result.success &&+ (trackedInRequest || mcpCredits > 0) &&+ org_id !== null+ ) {if (await autumnService.isRoutedThroughFirebill(team_id, org_id)) {// No compensating refund on the firebill route: the tracked charge// is durable and correct, and a refund here poisons a retried@@ -86,10 +100,12 @@ export async function billTeam({ team_id, credits, billing },);} else {- await autumnService.refundCredits({+ const refund = {teamId: team_id,orgId: org_id,- value: credits,+ // Only what was charged: the rest when it was tracked, and the+ // MCP credits part (refunded on its own below).+ value: (trackedInRequest ? credits - mcpCredits : 0) + mcpCredits,properties: autumnProperties,featureId,// Distinct from the track key: the refund is its own charge event.@@ -97,7 +113,11 @@ export async function billTeam(? `fc:refund:${billing.endpoint}:${billing.chargeId}`: undefined,externalRequestId: billing.externalRequestId ?? undefined,- });+ };+ // A split charge refunds each part to the balance it was tracked on.+ await (mcpCredits > 0+ ? autumnService.refundHostedMcpCredits({ ...refund, mcpCredits })+ : autumnService.refundCredits(refund));}}diff --git a/apps/api/src/services/billing/types.ts b/apps/api/src/services/billing/types.tsindex 2b078a1fe..6c63d9732 100644--- a/apps/api/src/services/billing/types.ts+++ b/apps/api/src/services/billing/types.ts@@ -39,6 +39,19 @@ export type BillingMetadata = {* Unset when the caller sent no header or the charge has no request.*/externalRequestId?: string | null;+ /**+ * The hosted MCP made the request, as verified at authentication (see+ * `AuthObject.hostedMcp`). Its charges spend the team's MCP credits first+ * (see AutumnService.trackHostedMcpCredits). Rides the job payload like the+ * rest of this metadata, so a crawl's pages carry it too.+ */+ hostedMcp?: boolean;+ /**+ * Credits of this charge the team's MCP credits paid, set by the charge that+ * tracks them to Autumn (billTeam or billScrapeJob). The ledger records them as their own row, tagged apart from+ * regular credits used (see queueBillingOperation).+ */+ mcpCredits?: number;};export function resolveBillingMetadata({diff --git a/apps/api/src/services/worker/scrape-worker.ts b/apps/api/src/services/worker/scrape-worker.tsindex 64b4b3602..80ba0c14e 100644--- a/apps/api/src/services/worker/scrape-worker.ts+++ b/apps/api/src/services/worker/scrape-worker.ts@@ -171,6 +171,7 @@ async function billScrapeJob(// request's own credits. Standalone scrapes stay on CREDITS.const featureId = featureIdForBillingEndpoint(billing.endpoint);let trackedInRequest = false;+ let mcpCredits = 0;if (job.data.is_scrape !== true && !job.data.internalOptions?.bypassBilling) {creditsToBeBilled = await calculateCreditsToBeBilled(@@ -209,24 +210,31 @@ async function billScrapeJob(routedToFirebill = orgId? await autumnService.isRoutedThroughFirebill(job.data.team_id, orgId): false;- trackedInRequest = orgId- ? await autumnService.trackCredits({- teamId: job.data.team_id,- orgId,- value: creditsToBeBilled,- properties: autumnProperties,- featureId,- // The worker job id is the one identity that is unique per charge- // (a crawl id is shared by every page β keying on it would collapse- // a crawl's pages into one billed event) AND survives a stall- // requeue, which re-runs the job under the same id: with this key,- // the re-run dedupes instead of double-billing (firebill route).- idempotencyKey: `fc:track:${billing.endpoint}:${job.id}`,- // The caller's own operation id, carried on the charge so- // firebill reports it without a request lookup.- externalRequestId: billing.externalRequestId ?? undefined,- })- : false;+ if (orgId) {+ const charge = {+ teamId: job.data.team_id,+ orgId,+ value: creditsToBeBilled,+ properties: autumnProperties,+ featureId,+ // The worker job id is the one identity that is unique per charge+ // (a crawl id is shared by every page β keying on it would collapse+ // a crawl's pages into one billed event) AND survives a stall+ // requeue, which re-runs the job under the same id: with this key,+ // the re-run dedupes instead of double-billing (firebill route).+ idempotencyKey: `fc:track:${billing.endpoint}:${job.id}`,+ // The caller's own operation id, carried on the charge so+ // firebill reports it without a request lookup.+ externalRequestId: billing.externalRequestId ?? undefined,+ };+ // A hosted MCP charge spends the team's MCP credits first.+ if (billing.hostedMcp) {+ ({ tracked: trackedInRequest, mcpCredits } =+ await autumnService.trackHostedMcpCredits(charge));+ } else {+ trackedInRequest = await autumnService.trackCredits(charge);+ }+ }// On the firebill route the ledger enqueue must be idempotent by the// originating job: a stalled job reruns under the same job.id, the// track dedupes in firebill, and a fresh random billing job id would@@ -265,7 +273,7 @@ async function billScrapeJob(team_id: job.data.team_id,org_id: orgId,credits: creditsToBeBilled,- billing,+ billing: mcpCredits > 0 ? { ...billing, mcpCredits } : billing,is_extract: false,timestamp: new Date().toISOString(),originating_job_id: job.id,@@ -298,7 +306,10 @@ async function billScrapeJob(`Failed to add billing job to queue for team ${job.data.team_id} for ${creditsToBeBilled} credits`,{ error },);- if (trackedInRequest && creditsToBeBilled !== null) {+ if (+ (trackedInRequest || mcpCredits > 0) &&+ creditsToBeBilled !== null+ ) {if (routedToFirebill) {// No compensating refund on the firebill route: the tracked charge// is durable and correct (the scrape ran), and refunding it here@@ -319,17 +330,25 @@ async function billScrapeJob(},);} else if (orgId) {- await autumnService.refundCredits({+ const refund = {teamId: job.data.team_id,orgId,- value: creditsToBeBilled,+ // Only what was charged: the rest when it was tracked, and the+ // MCP credits part (refunded on its own below).+ value:+ (trackedInRequest ? creditsToBeBilled - mcpCredits : 0) ++ mcpCredits,properties: autumnProperties,featureId,// Distinct from the track key: a refund is its own charge event// (same key would 409 as a duplicate of the track and be dropped).idempotencyKey: `fc:refund:${billing.endpoint}:${job.id}`,externalRequestId: billing.externalRequestId ?? undefined,- });+ };+ // A split charge refunds each part to the balance it was tracked on.+ await (mcpCredits > 0+ ? autumnService.refundHostedMcpCredits({ ...refund, mcpCredits })+ : autumnService.refundCredits(refund));}}// The billing operation never reached the queue, so no debit willdiff --git a/apps/api/src/types.ts b/apps/api/src/types.tsindex 85c4a81c7..a5a0d38fb 100644--- a/apps/api/src/types.ts+++ b/apps/api/src/types.ts@@ -172,6 +172,8 @@ export type AuthResponse =org_id?: string | null;api_key?: string;chunk: AuthCreditUsageChunk | null;+ // The hosted MCP made the call, as verified in supaAuthenticateUser.+ hostedMcp?: boolean;}| {success: false;