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
chore(monitor): trim excess comments in search-monitoring code
Developers Digest518bde9a774d
diff --git a/apps/api/src/services/monitoring/runner.ts b/apps/api/src/services/monitoring/runner.tsindex a9cbcf081..6abfa8ddf 100644--- a/apps/api/src/services/monitoring/runner.ts+++ b/apps/api/src/services/monitoring/runner.ts@@ -110,25 +110,18 @@ type MonitorTargetRun =crawlId: string;}| {- // Search runs inline during dispatch (self-contained: search + scrape + judge),- // so its run descriptor needs no async handle. Summary/counts are filled in after it runs.+ // Search runs inline during dispatch; counts/credits filled in after.targetId: string;type: "search";resultCount?: number;matches?: number;summary?: string;- // True when a query failed at the search provider (rate-limit / HTTP- // error) after retries rather than legitimately returning no results.- // Persisted into target_results so an empty-but-degraded run is visible- // and not mistaken for a confident "no changes".+ // True when a query failed at the provider after retries (not legitimately+ // empty); persisted so an empty-but-degraded run isn't read as "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)+ // Flat, deterministic credits recorded onto target_results when the search+ // completes; actual_credits is summed from these, not reconstructed from+ // per-page metadata, so a missing page / reconciler race can't zero them.searchCredits?: number;judgeCredits?: number;resultsJudged?: number;@@ -961,8 +954,8 @@ async function enqueueMonitorCrawlTarget(params: {return params.targetRun;}-// Runs inline (owns its search + scrape + judge), then persists onto the same-// monitor_pages / monitor_check_pages tables the reconciler tallies.+// Runs inline, then persists onto the same monitor_pages / monitor_check_pages+// tables the reconciler tallies.async function runMonitorSearchTarget(params: {monitor: MonitorRow;check: MonitorCheckRow;@@ -973,7 +966,7 @@ async function runMonitorSearchTarget(params: {matches: number;summary: string;searchDegraded: boolean;- // FLAT, deterministic credits, recorded onto target_results by the caller.+ // Flat, deterministic credits, recorded onto target_results by the caller.searchCredits: number;judgeCredits: number;resultsJudged: number;@@ -993,7 +986,7 @@ async function runMonitorSearchTarget(params: {const { monitor, check, target } = params;const goalVersion = computeGoalVersion(monitor.goal, target.queries);- // Rebuild per-URL dedup memory + the event index from prior pages of this target.+ // Rebuild per-URL dedup memory + event index from this target's prior pages.const priorPages = await listActiveMonitorPages({monitorId: monitor.id,targetId: target.id,@@ -1009,20 +1002,15 @@ async function runMonitorSearchTarget(params: {teamId: monitor.team_id,goal: monitor.goal,subject: monitor.name,- // Read fresh from the persisted monitor on every check, so toggling the- // "Only alert on meaningful changes" judge via PATCH/UI takes effect on- // the NEXT check (no redeploy). When false, runSearchTarget collapses to- // raw mode: deterministic URLs + dedup, no LLM judge, no LLM credits.+ // Read fresh each check so a PATCH/UI toggle takes effect next check.judgeEnabled: Boolean(monitor.judge_enabled),},target: {id: target.id,queries: target.queries,searchWindow: target.searchWindow,- // depth/alertMode are no longer settable via the API. Stored targets may- // still carry them (back-compat) so we pass them through; when absent,- // runSearchTarget derives depth (deep when judging on, raw when off) and- // alertMode defaults to "first_match".+ // depth/alertMode aren't settable via the API, but stored targets may+ // still carry them (back-compat), so pass them through.alertMode: target.alertMode ?? "first_match",includeDomains: target.includeDomains,excludeDomains: target.excludeDomains,@@ -1041,21 +1029,15 @@ async function runMonitorSearchTarget(params: {}),});- // 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)+ // Flat, deterministic credits, returned for recording onto target_results.+ // actual_credits sums from target_results (not per-page metadata), so these+ // are reliable regardless of page count/ordering/reconciler timing β closing+ // the old "completed deep check with actual_credits = 0" hole.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.+ // Search pages carry no per-page credit (cost is the flat figure above, billed+ // once at check level); writing creditsUsed here would double-count.const pages: PageResult[] = result.pageUpserts.map(upsert => {const status = searchStatusToPageStatus(upsert.status);return {@@ -1206,8 +1188,8 @@ export async function processMonitorCheckJob(} else if (target.type === "crawl" && targetRun.type === "crawl") {await enqueueMonitorCrawlTarget({ monitor, check, target, targetRun });} else if (target.type === "search" && targetRun.type === "search") {- // Search is synchronous: run it now and fold its outcome back into target_results- // so the reconciler (which treats search runs as already-complete) finalizes the check.+ // Search is synchronous: run now and fold the outcome into target_results+ // so the reconciler (which treats search as complete) finalizes the check.const searchResult = await runMonitorSearchTarget({monitor,check,@@ -1217,10 +1199,7 @@ 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.+ // Persisted onto target_results below so they survive to finalization.targetRun.searchCredits = searchResult.searchCredits;targetRun.judgeCredits = searchResult.judgeCredits;targetRun.resultsJudged = searchResult.resultsJudged;@@ -1597,9 +1576,8 @@ 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).+ // Flat search credits come from target_results, not page metadata, so a+ // completed deep check that judged always records them (fixes the old bug).targetResults,});diff --git a/apps/api/src/services/monitoring/search/cost.ts b/apps/api/src/services/monitoring/search/cost.tsindex dc8a3f6d4..a04f541ac 100644--- a/apps/api/src/services/monitoring/search/cost.ts+++ b/apps/api/src/services/monitoring/search/cost.ts@@ -1,9 +1,8 @@import { CostTracking } from "../../../lib/cost-tracking";import { calculateCost } from "../../../scraper/scrapeURL/transformers/llmExtract";-// AI SDK `generateObject` returns token usage under `usage.inputTokens` /-// `usage.outputTokens`. Older SDK builds expose `promptTokens` /-// `completionTokens`; normalize both so cost recording never silently drops to 0.+// Newer AI SDK exposes usage as inputTokens/outputTokens, older builds as+// promptTokens/completionTokens; accept both so cost never silently drops to 0.type RawUsage =| {inputTokens?: number;@@ -23,15 +22,10 @@ function outputTokensOf(usage: RawUsage): number {}/**- * Record a single monitor LLM call against a shared CostTracking, mirroring how- * 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.+ * Record a single monitor LLM call against a shared CostTracking, mirroring the+ * scrape/extract path (llmExtract.ts β calculateCost β CostTracking.addCall).+ * For observability only β judge billing is a flat per-result figure (see+ * JUDGE_CREDITS_PER_RESULT in run.ts) and does not read from this.*/export function recordLlmCall(params: {costTracking: CostTracking;diff --git a/apps/api/src/services/monitoring/search/run.ts b/apps/api/src/services/monitoring/search/run.tsindex d548cf997..f8a1bf369 100644--- a/apps/api/src/services/monitoring/search/run.ts+++ b/apps/api/src/services/monitoring/search/run.ts@@ -39,8 +39,7 @@ 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).+// Flat credits per result the judge evaluates (scraped + judged in deep mode).// Deterministic and known at check time β no token/at-cost math.export const JUDGE_CREDITS_PER_RESULT = 5;@@ -50,17 +49,12 @@ function windowToTbs(window: string): string {return "qdr:w";}-// Bounded retry for monitor searches. The upstream provider rate-limits-// near-simultaneous identical queries and can answer with either a thrown/HTTP-// error OR a clean HTTP 200 carrying an empty body β both of which otherwise-// look identical to a genuinely-empty result and silently drop real hits.-//-// Strategy: retry on a hard failure (search() reported it via onFailure) AND on-// an empty result, with exponential backoff + jitter so we don't hammer the-// rate-limiter. A genuinely-empty query simply runs out of attempts and returns-// empty cleanly (no failure flagged), so its correct "no results" behavior is-// preserved. `failed` is only true when the LAST attempt was a real failure,-// letting the caller mark the check degraded instead of confidently empty.+// The provider rate-limits near-simultaneous identical queries and may answer+// with an error OR a clean HTTP 200 with an empty body β indistinguishable from+// a genuinely-empty result. Retry both empty and failed responses with backoff;+// a real empty query just exhausts attempts and returns empty cleanly. `failed`+// is true only when the LAST attempt was a real failure, so the caller can mark+// the check degraded rather than confidently empty.const SEARCH_RETRY_BACKOFF_MS = [400, 1200] as const;async function searchWithRetry(@@ -83,11 +77,8 @@ async function searchWithRetry(lastFailureReason = failureReason;const hasResults = (response.web?.length ?? 0) > 0;- // Success: real results came back. Return immediately.if (hasResults) return { response, failed: false };- // No results. Could be a genuine empty OR a transient rate-limit (error or- // empty 200). Retry with backoff while attempts remain.const isLastAttempt = attempt === maxAttempts - 1;if (!isLastAttempt) {const base = SEARCH_RETRY_BACKOFF_MS[attempt];@@ -103,9 +94,8 @@ async function searchWithRetry(}}- // Exhausted attempts. If the final attempt was a real provider failure,- // surface it loudly (degraded) β this is the false-negative we must not hide.- // If it was just empty with no failure, it is a legitimate no-results.+ // Exhausted attempts: a real final failure is the false-negative we must not+ // hide; an empty with no failure is a legitimate no-results.if (lastFailureReason) {logger.warn("search monitor query failed after retries; reporting degraded (NOT clean no-results)",@@ -161,8 +151,8 @@ export type KnownPage = {goalVersion: string;lastCheckedAt?: string;lastStatus?: string;- // Full stored monitor_pages metadata, carried through so unchanged-page- // upserts don't wipe event/verdict fields persisted by earlier runs.+ // Carried through so unchanged-page upserts don't wipe event/verdict fields+ // persisted by earlier runs.metadata?: Record<string, unknown>;};@@ -185,25 +175,18 @@ type SearchTargetRunResult = {meaningful: number;matches: number;summary: string;- // True when one or more of this target's queries failed at the search- // provider (rate-limit / HTTP error) after retries, rather than legitimately- // returning zero results. Callers should treat an empty run with- // searchDegraded=true as "could not confirm" rather than a confident- // "no new results", so a swallowed rate-limit isn't a silent false negative.+ // True when a query failed at the provider after retries rather than+ // legitimately returning zero results. An empty-but-degraded run means "could+ // not confirm", not a confident "no new results" β avoids a silent false+ // negative on a swallowed rate-limit.searchDegraded: boolean;sources: SearchSource[];- // Credits attributable to the search() calls themselves (β2 per 10 results),- // matching executeSearch's search-credit math.+ // Search() call credits (β2 per 10 results), matching executeSearch's math.searchCredits: 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.+ // Flat judge billing: JUDGE_CREDITS_PER_RESULT per result the judge evaluated+ // (covers both the scrape and the judge). Zero in raw mode.judgeCredits: number;- // Number of results that received a judge verdict this check (the denominator- // for judgeCredits). Carried through for observability / estimate parity.+ // Denominator for judgeCredits; carried for observability / estimate parity.resultsJudged: number;pageUpserts: Array<{url: string;@@ -226,11 +209,8 @@ export async function runSearchTarget(params: {teamId: string;goal: string | null;subject: string;- // Read fresh from the persisted monitor every check. When false, the LLM- // judge (router, snippet judge, criteria, verify, skeptic, summarizer) is- // skipped entirely and the target behaves like depth:"raw" β deterministic- // URLs + dedup state only, with no LLM credits billed. Toggling this via- // PATCH/UI therefore takes effect on the NEXT check with no redeploy.+ // When false, every LLM judge stage is skipped and the target behaves like+ // depth:"raw" (deterministic URLs + dedup, no LLM credits).judgeEnabled: boolean;};target: SearchTargetInput;@@ -244,9 +224,7 @@ export async function runSearchTarget(params: {const judgeEnabled = params.monitor.judgeEnabled;const goal = params.monitor.goal?.trim();- // The LLM judge requires a goal; raw/no-LLM mode does not. Only enforce the- // goal when we'll actually judge, so a judge-off check still runs search and- // returns raw results even when the monitor has no (or a cleared) goal.+ // Only the LLM judge requires a goal; raw/judge-off checks still run search.if (judgeEnabled && !goal) {throw new Error("search monitor target requires a non-empty monitor goal");}@@ -262,21 +240,15 @@ export async function runSearchTarget(params: {let pagesChecked = 0;let skipped = 0;let matches = 0;- // 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+ // For observability only β billing does not read from it, but 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.+ // 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- // confident "no changes" when it was really a swallowed search failure.+ // Queries that failed at the provider after retries (vs. legitimately empty);+ // used to mark the run degraded.let searchFailures = 0;const seenThisRun = new Map<string, number>();@@ -302,14 +274,10 @@ export async function runSearchTarget(params: {logger,);if (failed) {- // A real provider failure (not a genuine empty). Record it so the run is- // reported as degraded rather than a clean "no changes" for this query.searchFailures += 1;}- // v2 search returns { web, news, images }; the monitor consumes web hits.const results = response.web ?? [];- // Bill the search call at the platform rate (executeSearch: ~2 credits / 10- // results) on the results this query actually returned, before dedupe/trim.+ // Bill on raw results, before dedupe/trim.searchResultsBilled += results.length;for (const r of results) {if (!r.url) continue;@@ -317,8 +285,8 @@ export async function runSearchTarget(params: {const canonical = canonicalizeUrl(r.url);const existingIdx = seenThisRun.get(canonical);if (existingIdx !== undefined) {- // Same URL surfaced by another query this run β record the extra query- // (mirrors the POC's queryHits) instead of dropping it.+ // Same URL from another query this run β record the extra query rather+ // than dropping it.const existing = candidates[existingIdx];if (!existing.matchedQueries.includes(query)) {existing.matchedQueries.push(query);@@ -338,11 +306,8 @@ export async function runSearchTarget(params: {resultCount = candidates.length;const llmStagesAvailable = hasGeminiKey();- // When the judge is disabled, collapse to "raw" so every LLM stage below- // (router, snippet judge, criteria-with-LLM, verify, skeptic, resolver,- // material-dev, summarizer) is skipped and no LLM credits are billed β- // reusing the deterministic raw path instead of scattering judgeEnabled- // conditionals. depth then drives judging only when judgeEnabled is true.+ // Judge off β collapse to "raw" so every LLM stage is skipped via the existing+ // raw path, rather than scattering judgeEnabled conditionals.const depth: "raw" | "standard" | "deep" = !judgeEnabled? "raw": target.depth === "raw"@@ -351,15 +316,11 @@ export async function runSearchTarget(params: {? "standard": "deep";- // From here on, any depth !== "raw" path requires a goal. The top-of-function- // guard guarantees judgeEnabled implies a non-empty goal; depth !== "raw"- // implies judgeEnabled, so this is always satisfied when judging actually- // runs; assert it for the type checker (and as a defensive invariant).+ // depth !== "raw" implies judgeEnabled implies a non-empty goal (top guard),+ // so judgeGoal is always populated when judging runs; "" only in raw mode.const judgeGoal: string = goal ?? "";let criteria: GoalCriteria = compileGoalCriteria({- // goal can be empty in raw/judge-off mode; criteria is only consumed by- // the LLM judge stages, which never run when depth === "raw".goal: judgeGoal,subject,goalVersion,@@ -523,9 +484,8 @@ export async function runSearchTarget(params: {url: canonical,urlHash: hashMonitorUrl(canonical),status: reusedStatus,- // Upserts replace the stored metadata wholesale, so spread the prior- // metadata to preserve event stamps (eventKey/eventLabel/...) that- // event reconstruction depends on.+ // Upserts replace metadata wholesale; spread prior metadata to preserve+ // event stamps (eventKey/eventLabel/...) that reconstruction needs.metadata: {...(knownCurrent?.metadata ?? {}),fingerprint,@@ -670,9 +630,7 @@ 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.+ // Judged this result β the unit of flat billing, regardless of outcome.resultsJudged += 1;let decision = verdictToDecision(verdict);@@ -920,7 +878,7 @@ export async function runSearchTarget(params: {const searchDegraded = searchFailures > 0;if (searchDegraded && matches === 0) {- // Don't let a swallowed provider failure masquerade as a clean no-results.+ // Don't let a swallowed provider failure masquerade as clean no-results.logger.warn("search monitor run is degraded: one or more queries failed at the provider after retries; results may be incomplete",{@@ -939,9 +897,6 @@ export async function runSearchTarget(params: {const isZDR = params.zeroDataRetention;const searchCredits =Math.ceil(searchResultsBilled / 10) * (isZDR ? 10 : 2);- // 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 {diff --git a/apps/api/src/services/monitoring/store.ts b/apps/api/src/services/monitoring/store.tsindex 2526c5903..9c700e004 100644--- a/apps/api/src/services/monitoring/store.ts+++ b/apps/api/src/services/monitoring/store.ts@@ -41,14 +41,11 @@ 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;-// 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).+// Flat search-monitor billing: search() bills 2 per 10 results per query; the+// judge bills 5 per result evaluated. The estimate is an upper bound (all+// results judged); real runs dedupe + cap, so actual β€ estimate.+// SEARCH_JUDGE_CREDITS_PER_RESULT MUST stay in sync with JUDGE_CREDITS_PER_RESULT+// in ./search/run.ts.const SEARCH_CREDITS_PER_TEN_RESULTS = 2;const SEARCH_JUDGE_CREDITS_PER_RESULT = 5;@@ -148,10 +145,8 @@ function estimateBaseCreditsPerPage(return credits;}-// 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.+// Upper bound on results the judge could evaluate in one run: every result of+// every query, before dedupe. Real runs dedupe/cap, so actual β€ this.function estimateSearchJudgedResults(target: Extract<MonitorTarget, { type: "search" }>,): number {@@ -162,13 +157,11 @@ 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.+ // No judging in raw mode or when the judge is off.if (target.depth === "raw" || !judgeEnabled) {return searchCallCredits;}@@ -187,8 +180,8 @@ function estimateTargetBaseCredits(return target.urls.length * creditsPerPage;}if (target.type === "search") {- // Search targets carry their FULL estimate (search + flat judge) here; they- // are excluded from the global per-page judge loop to avoid double-counting.+ // Full estimate (search + flat judge); excluded from the global per-page+ // judge loop below to avoid double-counting.return estimateSearchTargetCredits(target, judgeEnabled);}@@ -222,9 +215,8 @@ export function estimateMonitorCreditsPerRun((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.+ // Search judging is already folded into estimateTargetBaseCredits above; the+ // per-page allowance applies only to scrape/crawl, so exclude search here.const judgeCredits = judgeEnabled? targets.reduce((sum, target) =>@@ -310,24 +302,21 @@ export function calculateMonitorCheckActualCreditsFromPages(return 0;}- // Search-target pages bill all of their LLM/judge work at cost (folded into- // metadata.creditsUsed by the search runner), so the flat per-page judge- // credit would double-count them. Only scrape/crawl judge invocations get it.+ // Search judging is billed at the check level; the per-page judge credit+ // would double-count it. Only scrape/crawl get it.const target = targetsById.get(page.target_id ?? "");if (target?.type === "search") {return 0;}- // A persisted judgment means the judge ran for this page. Charge for that- // invocation whether the verdict was meaningful or not.+ // A persisted judgment means the judge ran for this page; charge for it+ // whether or not the verdict was meaningful.return JUDGE_CREDITS_PER_PAGE;}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.+ // Search pages carry no per-page credit (billed at check level via+ // flatSearchTargetCredits); summing a per-page base would double-bill.const target = targetsById.get(page.target_id ?? "");if (target?.type === "search") {return total;@@ -350,13 +339,10 @@ export function calculateMonitorCheckActualCreditsFromPages(}/**- * 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.+ * Sum the flat credits recorded on a check's target_results for every search+ * target (searchCredits + judgeCredits). Persisted when the search completes, so+ * they're always present at finalization regardless of which pages persisted β+ * guaranteeing a deep check that judged can never record actual_credits = 0.*/export function flatSearchTargetCredits(targetResults: unknown): number {if (!Array.isArray(targetResults)) return 0;@@ -951,12 +937,11 @@ 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.+ // The check's persisted target_results; search credits are summed from here so+ // an empty/missing pages table can't zero them out.targetResults?: unknown;}): Promise<number> {- // Flat search-target credits first: deterministic and independent of pages.+ // Flat search credits first: deterministic and independent of pages.let total = flatSearchTargetCredits(params.targetResults);let offset = 0;diff --git a/apps/api/src/services/monitoring/types.ts b/apps/api/src/services/monitoring/types.tsindex b9ca2f2b9..1506b44f6 100644--- a/apps/api/src/services/monitoring/types.ts+++ b/apps/api/src/services/monitoring/types.ts@@ -48,17 +48,9 @@ const monitorDomainSchema = z"Domain must be a valid hostname without protocol or path",);-// `depth` and `alertMode` are NOT part of the public create/update contract.-// They used to be settable; we now keep them internal-only with sane defaults-// (depth derived at runtime in runSearchTarget β absent β deep when judging is-// on, raw when off; alertMode defaults to "first_match" wherever it's read).-//-// We deliberately strip any client-supplied `depth`/`alertMode` BEFORE the-// strictObject validation runs, rather than rejecting them with a 400. This-// keeps older clients that still send these keys working β the values are-// simply ignored and never persisted. Existing stored targets that already-// carry depth/alertMode in the jsonb keep working: this only affects the API-// input path, and the runtime still reads stored values via MonitorTarget.+// `depth`/`alertMode` are internal-only (derived at runtime). Strip any+// client-supplied values BEFORE strictObject validation rather than 400ing, so+// older clients that still send them keep working (values ignored, not persisted).const searchTargetSchema = z.preprocess(value => {if (value && typeof value === "object" && !Array.isArray(value)) {@@ -201,10 +193,9 @@ export const createMonitorSchema = createMonitorBaseSchema.superRefine(requireGoalForSearchTargets).transform(applyJudgeEnabledDefault);-// Update bodies are partial: a patch adding search targets may rely on the-// goal already stored on the monitor, so only reject here when the patch-// itself includes search targets AND explicitly clears the goal. The-// controller re-validates the merged monitor (stored row + patch).+// Patches are partial and may rely on the already-stored goal, so only reject+// when the patch includes search targets AND explicitly clears the goal. The+// controller re-validates the merged monitor.function rejectGoalClearedWithSearchTargets(input: { targets?: unknown; goal?: unknown },ctx: z.RefinementCtx,@@ -263,11 +254,9 @@ export const monitorCheckDetailQuerySchema = z.object({status: z.enum(["same", "new", "changed", "removed", "error"]).optional(),});-// `depth`/`alertMode` are no longer accepted on the API input path (stripped by-// searchTargetSchema's preprocess), but EXISTING stored targets in-// monitors.targets jsonb may still carry them and the runtime must keep-// honoring those values. Surface them here as optional, internal-only fields so-// runner.ts / store.ts can read stored values without type errors.+// Stripped from API input (see searchTargetSchema), but stored targets may+// still carry them; surface as optional internal-only fields so runner/store+// can read stored values without type errors.export type MonitorTarget = z.infer<typeof monitorTargetSchema> & {id: string;} & {