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(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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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) {