Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

feat(monitor): flat deterministic search billing β€” 2/10 results + 5 per judged result

Developers Digest36a3d0aa1251
diff --git a/apps/api/src/services/monitoring/runner.ts b/apps/api/src/services/monitoring/runner.ts
index abf2e2585..a9cbcf081 100644
--- a/apps/api/src/services/monitoring/runner.ts
+++ b/apps/api/src/services/monitoring/runner.ts
@@ -122,6 +122,16 @@ type MonitorTargetRun =
// Persisted into target_results so an empty-but-degraded run is visible
// and not mistaken for a confident "no changes".
searchDegraded?: boolean;
+ // FLAT, deterministic search-target billing, recorded onto the check's
+ // target_results the moment the synchronous search completes. The check's
+ // actual_credits is summed from THESE values (plus non-search page
+ // credits), not reconstructed from per-page metadata β€” so a missing page,
+ // a reconciler race, or an empty CostTracking can never zero them out.
+ // searchCredits = ceil(totalSearchResults/10)*2 (per check)
+ // judgeCredits = 5 * resultsJudged (0 when judging off)
+ searchCredits?: number;
+ judgeCredits?: number;
+ resultsJudged?: number;
};
function createMonitorTargetRun(target: MonitorTarget): MonitorTargetRun {
@@ -963,6 +973,10 @@ async function runMonitorSearchTarget(params: {
matches: number;
summary: string;
searchDegraded: boolean;
+ // FLAT, deterministic credits, recorded onto target_results by the caller.
+ searchCredits: number;
+ judgeCredits: number;
+ resultsJudged: number;
}> {
if (params.target.type !== "search") {
return {
@@ -971,6 +985,9 @@ async function runMonitorSearchTarget(params: {
matches: 0,
summary: "",
searchDegraded: false,
+ searchCredits: 0,
+ judgeCredits: 0,
+ resultsJudged: 0,
};
}
const { monitor, check, target } = params;
@@ -1024,23 +1041,24 @@ async function runMonitorSearchTarget(params: {
}),
});
- // Run-level credits that aren't tied to a single page: the search() calls
- // (~2 credits / 10 results) and every LLM/judge call (router, snippet judge,
- // criteria compile, skeptic, resolver, material-dev, summarizer), all billed
- // at cost by runSearchTarget. Fold this overhead onto the first persisted page
- // so the page-sum reconciler (calculateMonitorCheckActualCredits) deducts it.
- const overheadCredits = result.searchCredits + result.llmCredits;
-
- const pages: PageResult[] = [];
- result.pageUpserts.forEach((upsert, index) => {
+ // FLAT, deterministic search-target billing. These two numbers are known the
+ // instant the synchronous search finishes and are returned to the caller,
+ // which records them onto the check's target_results in a single DB write.
+ // The check's actual_credits is summed from target_results (NOT from per-page
+ // metadata), so search credits are recorded reliably regardless of how many
+ // pages persist, page ordering, reconciler timing, or CostTracking state β€”
+ // closing the old "completed deep check with actual_credits = 0" hole.
+ // searchCredits = ceil(totalSearchResults/10) * 2 (per check)
+ // judgeCredits = 5 * resultsJudged (0 when judging off)
+ const searchCredits = result.searchCredits;
+ const judgeCredits = result.judgeCredits;
+
+ // Search pages no longer carry per-page credit metadata: their cost is the
+ // flat figure above, billed once at the check level. Writing creditsUsed here
+ // would double-count against the page-sum for NON-search targets β€” so omit it.
+ const pages: PageResult[] = result.pageUpserts.map(upsert => {
const status = searchStatusToPageStatus(upsert.status);
- // Real per-page scrape cost from calculateCreditsToBeBilled (0 when the page
- // was not scraped β€” e.g. already_seen or snippet-only depth).
- const pageScrapeCredits = upsert.creditsUsed ?? 0;
- const creditsUsed =
- index === 0 ? pageScrapeCredits + overheadCredits : pageScrapeCredits;
- const metadata = { ...upsert.metadata, creditsUsed };
- pages.push({
+ return {
check_id: check.id,
monitor_id: monitor.id,
team_id: monitor.team_id,
@@ -1048,10 +1066,10 @@ async function runMonitorSearchTarget(params: {
url: upsert.url,
url_hash: upsert.urlHash,
status,
- metadata,
+ metadata: upsert.metadata,
judgment: upsert.judgment ?? null,
emailStatus: status,
- });
+ };
});
for (let i = 0; i < pages.length; i++) {
@@ -1069,25 +1087,6 @@ async function runMonitorSearchTarget(params: {
});
}
- // No pages persisted (e.g. zero search results) but the search() call + any
- // criteria-compile LLM still cost credits. Persist a synthetic overhead page
- // so the reconciler bills it.
- if (pages.length === 0 && overheadCredits > 0) {
- const overheadUrl = `monitor-search-overhead:${target.id}`;
- const overheadPage: PageResult = {
- check_id: check.id,
- monitor_id: monitor.id,
- team_id: monitor.team_id,
- target_id: target.id,
- url: overheadUrl,
- url_hash: hashMonitorUrl(overheadUrl),
- status: "same",
- metadata: { creditsUsed: overheadCredits, searchOverhead: true },
- emailStatus: "same",
- };
- pages.push(overheadPage);
- }
-
await insertMonitorCheckPages(pages);
for (const page of pages) {
@@ -1109,6 +1108,9 @@ async function runMonitorSearchTarget(params: {
matches: result.matches,
summary: result.summary,
searchDegraded: result.searchDegraded,
+ searchCredits,
+ judgeCredits,
+ resultsJudged: result.resultsJudged,
};
}
@@ -1215,6 +1217,13 @@ export async function processMonitorCheckJob(
targetRun.matches = searchResult.matches;
targetRun.summary = searchResult.summary;
targetRun.searchDegraded = searchResult.searchDegraded;
+ // Record the FLAT, deterministic credits onto target_results. The
+ // updateMonitorCheck below persists target_results on the check row, so
+ // these numbers (known now) survive to finalization and are summed into
+ // actual_credits β€” never reconstructed from page metadata.
+ targetRun.searchCredits = searchResult.searchCredits;
+ targetRun.judgeCredits = searchResult.judgeCredits;
+ targetRun.resultsJudged = searchResult.resultsJudged;
}
}
@@ -1588,6 +1597,10 @@ export async function reconcileRunningMonitorChecks(
const actualCredits = await calculateMonitorCheckActualCredits({
checkId: check.id,
targets: monitor.targets,
+ // Flat search-target credits are read from the persisted target_results,
+ // not reconstructed from page metadata β€” so a completed deep check that
+ // judged results always records them (the old actual_credits=0 bug).
+ targetResults,
});
let finalized = await updateMonitorCheck(check.id, {
diff --git a/apps/api/src/services/monitoring/search/cost.test.ts b/apps/api/src/services/monitoring/search/cost.test.ts
index e624df95e..522e3bc69 100644
--- a/apps/api/src/services/monitoring/search/cost.test.ts
+++ b/apps/api/src/services/monitoring/search/cost.test.ts
@@ -1,7 +1,17 @@
import { CostTracking } from "../../../lib/cost-tracking";
-import { recordLlmCall, llmCostToCredits } from "./cost";
+import { recordLlmCall } from "./cost";
-describe("search-monitor LLM cost billing", () => {
+// Mirror of JUDGE_CREDITS_PER_RESULT in ./run.ts. We intentionally do NOT import
+// from ./run here: run.ts pulls in the search/scrape stack (ESM `uuid`, native
+// modules) which the jest transform can't load in this suite. The value is a
+// stable billing constant; this test pins it and the flat-billing arithmetic.
+const JUDGE_CREDITS_PER_RESULT = 5;
+
+// Monitor judge billing is now a FLAT, deterministic figure (5 credits per
+// result the judge evaluates). recordLlmCall still records token usage into a
+// shared CostTracking, but that is ONLY for observability β€” it no longer feeds
+// the credits a team is charged.
+describe("search-monitor LLM cost recording (observability only)", () => {
it("records a call's token cost into the shared CostTracking", () => {
const ct = new CostTracking();
recordLlmCall({
@@ -25,22 +35,6 @@ describe("search-monitor LLM cost billing", () => {
expect(ct.toJSON().totalCost).toBeCloseTo(0.1, 6);
});
- it("converts accumulated dollar cost to credits via the platform's at-cost rule", () => {
- const ct = new CostTracking();
- recordLlmCall({
- costTracking: ct,
- model: "gemini-flash-lite-latest",
- usage: { inputTokens: 1_000_000, outputTokens: 1_000_000 },
- stage: "routeSearchResults",
- });
- // tokensBilled = ceil(0.5 * 20000) = 10000; credits = ceil(10000 / 15) = 667.
- expect(llmCostToCredits(ct)).toBe(667);
- });
-
- it("returns 0 credits when no LLM calls were made", () => {
- expect(llmCostToCredits(new CostTracking())).toBe(0);
- });
-
it("returns 0 cost for an unknown/unpriced model rather than throwing", () => {
const ct = new CostTracking();
recordLlmCall({
@@ -50,6 +44,19 @@ describe("search-monitor LLM cost billing", () => {
stage: "test",
});
expect(ct.toJSON().totalCost).toBe(0);
- expect(llmCostToCredits(ct)).toBe(0);
+ });
+});
+
+describe("search-monitor FLAT judge billing rate", () => {
+ it("is a deterministic 5 credits per judged result", () => {
+ expect(JUDGE_CREDITS_PER_RESULT).toBe(5);
+ });
+
+ it("computes judge credits as 5 * resultsJudged", () => {
+ const judgeCreditsFor = (resultsJudged: number) =>
+ resultsJudged * JUDGE_CREDITS_PER_RESULT;
+ expect(judgeCreditsFor(0)).toBe(0); // raw / judge-off
+ expect(judgeCreditsFor(3)).toBe(15); // deep, 3 results judged
+ expect(judgeCreditsFor(10)).toBe(50);
});
});
diff --git a/apps/api/src/services/monitoring/search/cost.ts b/apps/api/src/services/monitoring/search/cost.ts
index b88bf75b3..dc8a3f6d4 100644
--- a/apps/api/src/services/monitoring/search/cost.ts
+++ b/apps/api/src/services/monitoring/search/cost.ts
@@ -1,6 +1,5 @@
import { CostTracking } from "../../../lib/cost-tracking";
import { calculateCost } from "../../../scraper/scrapeURL/transformers/llmExtract";
-import { calculateThinkingCost } from "../../../lib/extract/usage/llm-cost";
// AI SDK `generateObject` returns token usage under `usage.inputTokens` /
// `usage.outputTokens`. Older SDK builds expose `promptTokens` /
@@ -25,9 +24,14 @@ function outputTokensOf(usage: RawUsage): number {
/**
* Record a single monitor LLM call against a shared CostTracking, mirroring how
- * the scrape/extract path bills LLM work "at cost" (llmExtract.ts β†’ calculateCost
- * β†’ CostTracking.addCall). The dollar cost is later converted to credits via
- * {@link llmCostToCredits}, the same conversion extract uses.
+ * the scrape/extract path records LLM work (llmExtract.ts β†’ calculateCost β†’
+ * CostTracking.addCall).
+ *
+ * NOTE: monitor JUDGE BILLING NO LONGER reads from this CostTracking. Judge
+ * credits are a FLAT 5 per judged result (see JUDGE_CREDITS_PER_RESULT in
+ * run.ts), computed deterministically at check time. This recording is retained
+ * purely for observability/debugging of token usage β€” it does not affect the
+ * credits a team is charged.
*/
export function recordLlmCall(params: {
costTracking: CostTracking;
@@ -45,15 +49,3 @@ export function recordLlmCall(params: {
tokens: { input, output },
});
}
-
-/**
- * Convert the accumulated LLM dollar cost into credits. Uses the platform's
- * canonical at-cost conversion: calculateThinkingCost(ct) = ceil(totalCost *
- * 20000) tokens, then ceil(tokens / 15) credits β€” identical to how the extract
- * endpoint bills its fire-1 / thinking LLM work (extraction-service.ts).
- */
-export function llmCostToCredits(costTracking: CostTracking): number {
- const tokensBilled = calculateThinkingCost(costTracking);
- if (tokensBilled <= 0) return 0;
- return Math.ceil(tokensBilled / 15);
-}
diff --git a/apps/api/src/services/monitoring/search/run-defenses.test.ts b/apps/api/src/services/monitoring/search/run-defenses.test.ts
index 864aeb901..245c37468 100644
--- a/apps/api/src/services/monitoring/search/run-defenses.test.ts
+++ b/apps/api/src/services/monitoring/search/run-defenses.test.ts
@@ -366,8 +366,9 @@ describe("judgeEnabled gates the LLM judge", () => {
expect(summarizeRunMock).not.toHaveBeenCalled();
expect(criteriaLlmMock).not.toHaveBeenCalled();
- // No LLM credits billed; search still ran and was billed.
- expect(result.llmCredits).toBe(0);
+ // No judge credits billed (raw β†’ nothing judged); search still ran and was billed.
+ expect(result.judgeCredits).toBe(0);
+ expect(result.resultsJudged).toBe(0);
expect(result.resultCount).toBe(2);
// Raw alerts: deterministic searchStatus from dedup, but no LLM
@@ -388,7 +389,8 @@ describe("judgeEnabled gates the LLM judge", () => {
);
expect(result.resultCount).toBe(1);
- expect(result.llmCredits).toBe(0);
+ expect(result.judgeCredits).toBe(0);
+ expect(result.resultsJudged).toBe(0);
expect(scrapeURLMock).not.toHaveBeenCalled();
});
diff --git a/apps/api/src/services/monitoring/search/run.ts b/apps/api/src/services/monitoring/search/run.ts
index bd83bc215..d548cf997 100644
--- a/apps/api/src/services/monitoring/search/run.ts
+++ b/apps/api/src/services/monitoring/search/run.ts
@@ -5,8 +5,6 @@ import { buildSearchQuery } from "../../../lib/search-query-builder";
import { scrapeURL } from "../../../scraper/scrapeURL";
import { scrapeOptions } from "../../../controllers/v2/types";
import { CostTracking } from "../../../lib/cost-tracking";
-import { calculateCreditsToBeBilled } from "../../../lib/scrape-billing";
-import { llmCostToCredits } from "./cost";
import { hashMonitorUrl } from "../store";
import { canonicalizeUrl, stableSerpFingerprint } from "./dedupe";
import {
@@ -41,6 +39,11 @@ import {
} from "./verify";
import { hasGeminiKey } from "./tuning";
+// FLAT judge billing rate: credits charged per result the judge evaluates this
+// check (a result that receives an AI verdict β€” scraped + judged in deep mode).
+// Deterministic and known at check time β€” no token/at-cost math.
+export const JUDGE_CREDITS_PER_RESULT = 5;
+
function windowToTbs(window: string): string {
if (window === "5m" || window === "15m" || window === "1h") return "qdr:h";
if (window === "6h" || window === "24h") return "qdr:d";
@@ -192,17 +195,21 @@ type SearchTargetRunResult = {
// Credits attributable to the search() calls themselves (β‰ˆ2 per 10 results),
// matching executeSearch's search-credit math.
searchCredits: number;
- // Credits for all monitor LLM/judge calls (router, snippet judge, criteria
- // compile, skeptic, resolver, material-dev, summarizer), billed at cost.
- llmCredits: number;
+ // FLAT, deterministic judge billing: JUDGE_CREDITS_PER_RESULT (5) for every
+ // result the judge actually evaluated this check β€” i.e. each result that
+ // received an AI verdict (scraped + judged in deep mode). Zero when judging is
+ // off (raw mode). Replaces the old at-cost token→credit `llmCredits` and the
+ // per-scrape `calculateCreditsToBeBilled` contribution: the flat 5 covers both
+ // the scrape and the judge for a search result.
+ judgeCredits: number;
+ // Number of results that received a judge verdict this check (the denominator
+ // for judgeCredits). Carried through for observability / estimate parity.
+ resultsJudged: number;
pageUpserts: Array<{
url: string;
urlHash: Buffer;
status: string;
scraped?: boolean;
- // Real per-page scrape credits from calculateCreditsToBeBilled() β€” includes
- // the scrape's own JSON/LLM extraction cost. 0 when the page was not scraped.
- creditsUsed?: number;
metadata: Record<string, unknown>;
judgment?: {
meaningful: boolean;
@@ -255,12 +262,17 @@ export async function runSearchTarget(params: {
let pagesChecked = 0;
let skipped = 0;
let matches = 0;
- // Single CostTracking shared by every LLM/judge call (and the per-page scrape
- // extraction) in this run, so the run's LLM dollar cost converts to credits
- // once via llmCostToCredits β€” the platform's canonical at-cost LLM billing.
+ // Shared CostTracking passed to the LLM/judge stages so they can record token
+ // usage for observability/debugging. Billing NO LONGER reads from it β€” judge
+ // credits are a flat per-judged-result figure (JUDGE_CREDITS_PER_RESULT),
+ // computed deterministically below. The object is kept only because the judge
+ // helpers require a CostTracking argument.
const costTracking = new CostTracking();
// Search calls bill β‰ˆ2 credits / 10 results, mirroring executeSearch().
let searchResultsBilled = 0;
+ // Count of results that received an AI judge verdict this check. This is the
+ // single, clear denominator for flat judge billing: judgeCredits = 5 * this.
+ let resultsJudged = 0;
// Count of queries that ultimately FAILED at the provider (rate-limit / HTTP
// error) after retries, as opposed to legitimately returning zero results.
// Used to mark the run degraded so an empty check isn't reported as a
@@ -600,7 +612,6 @@ export async function runSearchTarget(params: {
let verdict: SearchVerdict | null = null;
let pageText = "";
let realDate: string | null = null;
- let scrapeCredits = 0;
if (depth === "standard") {
verdict = snippetVerdicts.get(canonical) ?? null;
if (!verdict) {
@@ -646,26 +657,6 @@ export async function runSearchTarget(params: {
}
pagesChecked += 1;
- // Bill the scrape at actual cost via the same primitive the worker uses
- // (calculateCreditsToBeBilled): base + JSON-extraction + any premium
- // surcharges + the scrape's own LLM extraction cost. This replaces the
- // dummy searchPageCredits() estimate.
- try {
- scrapeCredits = await calculateCreditsToBeBilled(
- scrapeParsedOptions,
- { teamId, zeroDataRetention: params.zeroDataRetention },
- res.document,
- scrapeCostTracking,
- {},
- );
- } catch (error) {
- logger.warn("search monitor scrape credit calc failed; using base", {
- url: c.url,
- error,
- });
- scrapeCredits = res.document.metadata?.creditsUsed ?? 1;
- }
-
verdict = parseVerdict(res.document.json);
if (!verdict) {
skipped += 1;
@@ -679,6 +670,11 @@ export async function runSearchTarget(params: {
null;
}
+ // This result received an AI judge verdict (snippet judge in standard, or
+ // scrape+judge in deep). It is the unit of flat judge billing: each such
+ // result costs JUDGE_CREDITS_PER_RESULT, regardless of the verdict outcome.
+ resultsJudged += 1;
+
let decision = verdictToDecision(verdict);
let verification: VerificationResult | null = null;
@@ -754,7 +750,6 @@ export async function runSearchTarget(params: {
urlHash: hashMonitorUrl(canonical),
status: "ignored",
scraped: depth === "deep",
- creditsUsed: scrapeCredits,
metadata: { ...baseMeta, searchStatus: "ignored" },
});
continue;
@@ -771,7 +766,6 @@ export async function runSearchTarget(params: {
urlHash: hashMonitorUrl(canonical),
status: "watching",
scraped: depth === "deep",
- creditsUsed: scrapeCredits,
metadata: { ...baseMeta, searchStatus: "watching" },
});
continue;
@@ -844,7 +838,6 @@ export async function runSearchTarget(params: {
urlHash: hashMonitorUrl(canonical),
status: "already_seen",
scraped: depth === "deep",
- creditsUsed: scrapeCredits,
metadata: { ...eventMeta, searchStatus: "already_seen" },
});
continue;
@@ -879,7 +872,6 @@ export async function runSearchTarget(params: {
urlHash: hashMonitorUrl(canonical),
status: "alert",
scraped: depth === "deep",
- creditsUsed: scrapeCredits,
metadata: {
...eventMeta,
searchStatus: "alert",
@@ -947,7 +939,10 @@ export async function runSearchTarget(params: {
const isZDR = params.zeroDataRetention;
const searchCredits =
Math.ceil(searchResultsBilled / 10) * (isZDR ? 10 : 2);
- const llmCredits = llmCostToCredits(costTracking);
+ // FLAT, deterministic judge billing: 5 credits per result the judge evaluated
+ // this check. No token/at-cost conversion. Zero when judging was off (raw),
+ // where resultsJudged stays 0. Known at check time β†’ recorded reliably.
+ const judgeCredits = resultsJudged * JUDGE_CREDITS_PER_RESULT;
return {
targetId: target.id,
@@ -961,7 +956,8 @@ export async function runSearchTarget(params: {
searchDegraded,
sources,
searchCredits,
- llmCredits,
+ judgeCredits,
+ resultsJudged,
pageUpserts,
};
}
diff --git a/apps/api/src/services/monitoring/store.test.ts b/apps/api/src/services/monitoring/store.test.ts
index a86f1f921..4008913f4 100644
--- a/apps/api/src/services/monitoring/store.test.ts
+++ b/apps/api/src/services/monitoring/store.test.ts
@@ -5,6 +5,7 @@ jest.mock("uuid", () => ({
import {
calculateMonitorCheckActualCreditsFromPages,
estimateMonitorCreditsPerRun,
+ flatSearchTargetCredits,
} from "./store";
import type { MonitorTarget } from "./types";
@@ -209,3 +210,112 @@ describe("monitoring store credit helpers", () => {
).toBe(5);
});
});
+
+describe("FLAT deterministic search-monitor billing", () => {
+ const searchTarget = (
+ overrides: Partial<Extract<MonitorTarget, { type: "search" }>> = {},
+ ): MonitorTarget =>
+ ({
+ id: "search-1",
+ type: "search",
+ queries: ["nvidia gpu launch"],
+ searchWindow: "24h",
+ maxResults: 10,
+ scrapeOptions: {},
+ ...overrides,
+ }) as MonitorTarget;
+
+ describe("estimate (upper bound)", () => {
+ it("judge OFF (raw billing): only the search call, 2 per 10 results", () => {
+ // ceil(10/10)*2 * 1 query = 2.
+ expect(estimateMonitorCreditsPerRun([searchTarget()], false)).toBe(2);
+ });
+
+ it("judge ON: search call + flat 5 per judged result (all results, all queries)", () => {
+ // search = ceil(10/10)*2*1 = 2; judge = 5 * (10 results * 1 query) = 50.
+ expect(estimateMonitorCreditsPerRun([searchTarget()], true)).toBe(52);
+ });
+
+ it("legacy depth:raw target is never judged even when judging is on", () => {
+ expect(
+ estimateMonitorCreditsPerRun([searchTarget({ depth: "raw" })], true),
+ ).toBe(2);
+ });
+
+ it("scales with queries and maxResults as an upper bound", () => {
+ const t = searchTarget({
+ maxResults: 20,
+ queries: ["a", "b", "c"],
+ });
+ // search = ceil(20/10)*2*3 = 12; judge = 5 * (20*3) = 300 β†’ 312.
+ expect(estimateMonitorCreditsPerRun([t], true)).toBe(312);
+ });
+ });
+
+ describe("flatSearchTargetCredits (the deterministic actual)", () => {
+ it("sums searchCredits + judgeCredits across search target_results", () => {
+ // The headline trace: search 2 + judge 5*3 = 17.
+ const targetResults = [
+ {
+ targetId: "search-1",
+ type: "search",
+ searchCredits: 2,
+ judgeCredits: 15,
+ resultsJudged: 3,
+ },
+ ];
+ expect(flatSearchTargetCredits(targetResults)).toBe(17);
+ });
+
+ it("raw / judge-off: just the 2 search credits, 0 judge", () => {
+ expect(
+ flatSearchTargetCredits([
+ {
+ targetId: "search-1",
+ type: "search",
+ searchCredits: 2,
+ judgeCredits: 0,
+ resultsJudged: 0,
+ },
+ ]),
+ ).toBe(2);
+ });
+
+ it("ignores non-search target runs and malformed entries", () => {
+ expect(
+ flatSearchTargetCredits([
+ { targetId: "scrape-1", type: "scrape", expectedJobs: ["a"] },
+ { targetId: "search-1", type: "search", searchCredits: 4 },
+ null,
+ "garbage",
+ { type: "search" }, // missing credits β†’ contributes 0
+ ]),
+ ).toBe(4);
+ });
+
+ it("returns 0 for non-array / empty target_results", () => {
+ expect(flatSearchTargetCredits(undefined)).toBe(0);
+ expect(flatSearchTargetCredits(null)).toBe(0);
+ expect(flatSearchTargetCredits([])).toBe(0);
+ });
+ });
+
+ it("page-sum never bills search-target pages (cost is at the check level)", () => {
+ const targets: MonitorTarget[] = [searchTarget()];
+ // Even with judgment + status, a search page contributes 0 to the page sum;
+ // its credits live in target_results via flatSearchTargetCredits.
+ expect(
+ calculateMonitorCheckActualCreditsFromPages(
+ [
+ {
+ target_id: "search-1",
+ metadata: {},
+ judgment: { meaningful: true },
+ status: "new",
+ },
+ ],
+ targets,
+ ),
+ ).toBe(0);
+ });
+});
diff --git a/apps/api/src/services/monitoring/store.ts b/apps/api/src/services/monitoring/store.ts
index d29c5ab85..2526c5903 100644
--- a/apps/api/src/services/monitoring/store.ts
+++ b/apps/api/src/services/monitoring/store.ts
@@ -41,13 +41,16 @@ const REMOVED_PAGE_CREDITS = 0;
const X_TWITTER_POSTPROCESSOR_CREDIT_BONUS = 29;
const DEFAULT_CRAWL_LIMIT_FOR_ESTIMATE = 10000;
const MONITOR_CHECK_PAGE_BATCH_SIZE = 1000;
-// Search monitors also bill the search() call (~2 credits / 10 results) and
-// every LLM/judge call at cost. The estimate adds a per-result LLM allowance so
-// the reserved credits roughly cover the new at-cost actuals (router + snippet
-// judge + skeptic + resolver + summarizer). Tuned to typical gemini-flash-lite
-// usage; the actual deduction is always the at-cost figure, never this estimate.
+// FLAT, deterministic search-monitor billing:
+// - The search() call bills 2 credits per 10 results, per query.
+// - The judge bills a FLAT 5 credits per result it evaluates (scraped+judged
+// in deep). No token/at-cost conversion. The estimate is an upper bound
+// (all results of all queries judged); real runs dedupe + cap, so actual ≀
+// estimate. The actual deduction is the flat figure recorded on the check.
+// SEARCH_JUDGE_CREDITS_PER_RESULT MUST stay in sync with
+// JUDGE_CREDITS_PER_RESULT in ./search/run.ts (the runtime billing rate).
const SEARCH_CREDITS_PER_TEN_RESULTS = 2;
-const SEARCH_LLM_CREDITS_PER_RESULT = 2;
+const SEARCH_JUDGE_CREDITS_PER_RESULT = 5;
type MonitorCreditMetadata = {
creditsUsed?: unknown;
@@ -145,41 +148,48 @@ function estimateBaseCreditsPerPage(
return credits;
}
-function estimateTargetBaseCredits(target: MonitorTarget): number {
+// Upper bound on the number of results a search target's judge could evaluate
+// in one run: every result of every query (before dedupe). Used by the FLAT
+// judge estimate (5 per judged result). Real runs dedupe and the router caps
+// selection, so actual judged results ≀ this β€” keeping estimate β‰₯ actual.
+function estimateSearchJudgedResults(
+ target: Extract<MonitorTarget, { type: "search" }>,
+): number {
+ return Math.max(1, target.maxResults) * Math.max(1, target.queries.length);
+}
+
+function estimateSearchTargetCredits(
+ target: Extract<MonitorTarget, { type: "search" }>,
+ judgeEnabled: boolean,
+): number {
+ // FLAT model: search call (2 per 10 results, per query) + flat judge (5 per
+ // result the judge could evaluate). No at-cost scrape/LLM components.
+ const searchCallCredits =
+ Math.ceil(Math.max(1, target.maxResults) / 10) *
+ SEARCH_CREDITS_PER_TEN_RESULTS *
+ Math.max(1, target.queries.length);
+ // Judging is skipped entirely in raw mode or when the judge is off.
+ if (target.depth === "raw" || !judgeEnabled) {
+ return searchCallCredits;
+ }
+ return (
+ searchCallCredits +
+ estimateSearchJudgedResults(target) * SEARCH_JUDGE_CREDITS_PER_RESULT
+ );
+}
+
+function estimateTargetBaseCredits(
+ target: MonitorTarget,
+ judgeEnabled: boolean = false,
+): number {
const creditsPerPage = estimateBaseCreditsPerPage(target.scrapeOptions);
if (target.type === "scrape") {
return target.urls.length * creditsPerPage;
}
if (target.type === "search") {
- // The search() call bills ~2 credits / 10 results regardless of depth.
- const searchCallCredits =
- Math.ceil(Math.max(1, target.maxResults) / 10) *
- SEARCH_CREDITS_PER_TEN_RESULTS *
- Math.max(1, target.queries.length);
- // depth is no longer settable via the API; absent depth means the runtime
- // default ("deep" when judging is on). Only legacy stored targets carry an
- // explicit "raw"/"standard". Treat absent depth as deep below.
- if (target.depth === "raw") {
- // No scrape, no LLM β€” only the search call.
- return searchCallCredits;
- }
- // Every result may drive LLM/judge work billed at cost.
- const llmCredits = target.maxResults * SEARCH_LLM_CREDITS_PER_RESULT;
- if (target.depth === "standard") {
- // Snippet-only: no per-result scrape, but LLM snippet judging still runs.
- return (
- searchCallCredits + Math.max(1, target.queries.length) + llmCredits
- );
- }
- // Deep: each selected result is scraped with JSON extraction.
- return (
- searchCallCredits +
- llmCredits +
- target.maxResults *
- estimateBaseCreditsPerPage({
- formats: [{ type: "json" }],
- } as MonitorTarget["scrapeOptions"])
- );
+ // Search targets carry their FULL estimate (search + flat judge) here; they
+ // are excluded from the global per-page judge loop to avoid double-counting.
+ return estimateSearchTargetCredits(target, judgeEnabled);
}
const limit =
@@ -209,13 +219,18 @@ export function estimateMonitorCreditsPerRun(
judgeEnabled: boolean = false,
): number {
const baseCredits = targets.reduce(
- (sum, target) => sum + estimateTargetBaseCredits(target),
+ (sum, target) => sum + estimateTargetBaseCredits(target, judgeEnabled),
0,
);
+ // Search targets bill judging via the FLAT 5-per-judged-result model, already
+ // folded into estimateTargetBaseCredits above. The global per-page judge
+ // allowance applies only to scrape/crawl targets, so exclude search here.
const judgeCredits = judgeEnabled
? targets.reduce(
(sum, target) =>
- sum + estimateTargetPageCount(target) * JUDGE_CREDITS_PER_PAGE,
+ target.type === "search"
+ ? sum
+ : sum + estimateTargetPageCount(target) * JUDGE_CREDITS_PER_PAGE,
0,
)
: 0;
@@ -309,6 +324,15 @@ export function calculateMonitorCheckActualCreditsFromPages(
}
return pages.reduce((total, page) => {
+ // Search-target pages carry NO per-page credit. Their entire cost (search
+ // call + flat judge) is billed once at the check level from target_results
+ // (see flatSearchTargetCredits / calculateMonitorCheckActualCredits). Summing
+ // a per-page base here would double-bill them, so skip search pages.
+ const target = targetsById.get(page.target_id ?? "");
+ if (target?.type === "search") {
+ return total;
+ }
+
const metadata = page.metadata as MonitorCreditMetadata | null;
const recordedCredits = metadata?.creditsUsed;
let baseCredits = fallbackBaseCreditsForPage(page);
@@ -325,6 +349,37 @@ export function calculateMonitorCheckActualCreditsFromPages(
}, 0);
}
+/**
+ * Sum the FLAT, deterministic credits recorded on a check's target_results for
+ * every search target: searchCredits (2 per 10 results) + judgeCredits (5 per
+ * judged result). These are computed and persisted onto target_results the
+ * moment the synchronous search completes, so they are always present at
+ * finalization β€” independent of which pages persisted, page ordering, reconciler
+ * timing, or any CostTracking object. This is what guarantees a completed deep
+ * check can never record actual_credits = 0 while it actually judged results.
+ */
+export function flatSearchTargetCredits(targetResults: unknown): number {
+ if (!Array.isArray(targetResults)) return 0;
+ return targetResults.reduce((total: number, run: unknown) => {
+ if (!run || typeof run !== "object") return total;
+ const r = run as {
+ type?: unknown;
+ searchCredits?: unknown;
+ judgeCredits?: unknown;
+ };
+ if (r.type !== "search") return total;
+ const searchCredits =
+ typeof r.searchCredits === "number" && Number.isFinite(r.searchCredits)
+ ? r.searchCredits
+ : 0;
+ const judgeCredits =
+ typeof r.judgeCredits === "number" && Number.isFinite(r.judgeCredits)
+ ? r.judgeCredits
+ : 0;
+ return total + searchCredits + judgeCredits;
+ }, 0);
+}
+
function toMonitorSummary(check: MonitorCheckRow): MonitorSummary {
return {
totalPages: check.total_pages,
@@ -896,8 +951,13 @@ export async function countMonitorCheckPages(params: {
export async function calculateMonitorCheckActualCredits(params: {
checkId: string;
targets: MonitorTarget[];
+ // The check's persisted target_results. Search-target credits (flat, known at
+ // check time) are summed from here deterministically; pass the value read off
+ // the check row so an empty/missing pages table can never zero them out.
+ targetResults?: unknown;
}): Promise<number> {
- let total = 0;
+ // Flat search-target credits first: deterministic and independent of pages.
+ let total = flatSearchTargetCredits(params.targetResults);
let offset = 0;
while (true) {