Skip to content

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

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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;
} & {