Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
refactor(action-center): gather the engine's thresholds in one place (#821)
Gökhan Geyik3e6a783d420c
diff --git a/server/src/config/action-engine.js b/server/src/config/action-engine.jsnew file mode 100644index 000000000..354180114--- /dev/null+++ b/server/src/config/action-engine.js@@ -0,0 +1,128 @@+/**+ * Action Engine thresholds — the numbers that decide what counts (#818).+ *+ * Every value here answers a judgement call: how far something has to move+ * before it is a signal, how much evidence is enough to raise an action, how+ * long to wait before believing a measurement. They were scattered across the+ * detectors that used them, which is survivable at a dozen detectors and+ * unmanageable at forty — and phase 3 brings forty. Tuning the engine should+ * mean editing this file, not going hunting.+ *+ * Grouped by the question each number answers rather than by the file that+ * currently reads it, so a later refactor moving a detector does not move its+ * threshold.+ *+ * Resolution order, per the specification: system default → definition+ * default → workspace override. Only the first exists today; `resolve()` is+ * the seam the other two arrive through, so callers already read their+ * thresholds through a function rather than a constant and none of them has+ * to change when they do.+ *+ * What is deliberately *not* here: retry counts, page sizes, poll intervals,+ * display limits. Those are operational choices with one right answer, not+ * product judgements anyone would want to tune per workspace.+ */++/**+ * @typedef {typeof ENGINE_THRESHOLDS} EngineThresholds+ */+export const ENGINE_THRESHOLDS = Object.freeze({+ /** What a detector looks at, and how much movement it takes to speak up. */+ detection: Object.freeze({+ /** Days of history a detector compares against. */+ windowDays: 7,++ /**+ * A visibility fall has to clear both: enough absolute points that it is+ * visible on a chart, and enough of the brand's own level that it means+ * something. Either alone misfires — fifteen points is catastrophic at a+ * base of twenty and noise at a base of ninety.+ */+ visibilityDropPoints: 15,+ visibilityDropRatio: 0.3,+ /** Below this many tracked prompts the average is too thin to trust. */+ visibilityDropMinPrompts: 10,++ /** A competitor's rise, in points, before it is worth reporting. */+ competitorSurgePoints: 15,++ /** Cited on this share of days, then nothing — the pattern that makes a+ * gap look deliberate rather than random. */+ lostCitationCitedRatio: 0.6,+ /** Consecutive result-days with no citation before calling it lost. */+ lostCitationQuietDays: 3,++ /** A rise smaller than this is not a story worth telling. */+ moverMinGain: 5,++ /** Mentioned across at least this many prompts before an uncited-mentions+ * signal is worth an action: one prompt is an anecdote. */+ uncitedMinPrompts: 3,++ /** Site Audit score below this is a problem; an audit older than this is+ * not evidence about the page as it stands today. */+ auditLowScore: 50,+ auditMaxAgeDays: 90,++ /** A page earning at least this many sessions, in the top percentile of+ * its brand's pages, is worth acting on. Below it, the opportunity is+ * too small to spend anyone's week on. */+ pageMinSessions: 10,+ pageMinPercentile: 70,+ /** Window the page opportunity detector measures over. Longer than the+ * others: traffic needs weeks to say anything. */+ pageWindowDays: 28,+ }),++ /** Guards against the engine talking over itself. */+ noise: Object.freeze({+ /**+ * How long a kind rests after a cycle closes before a new one may open.+ * Without it, a condition that is still firing produces a fresh action+ * the night after someone closed the last one — a treadmill.+ */+ restAfterCloseDays: 14,++ /**+ * Platform-wide result volume collapsing to this fraction of its trailing+ * daily average is a collection incident on our side, not a visibility+ * change on the customer's. Signals are suppressed rather than reported.+ */+ outageCollapseRatio: 0.25,+ /** Below this daily baseline the ratio above is meaningless. */+ outageMinBaseline: 20,+ }),++ /** How an action's effect is measured once it closes. */+ validation: Object.freeze({+ /** Length of the before and after windows. Equal, so the comparison is+ * between like periods. */+ windowDays: 7,++ /**+ * How much a metric must move to count as movement, as a fraction of its+ * before value. These numbers drift week to week on their own; without a+ * floor every outcome would be a verdict and none would mean anything.+ */+ meaningfulChangeRatio: 0.05,+ }),+});++/**+ * Thresholds for one caller, with overrides layered over the defaults.+ *+ * Merges one group deep — `resolve({ detection: { windowDays: 14 } })` keeps+ * every other detection threshold. Deeper nesting would invite a config that+ * is harder to read than the code it configures.+ *+ * @param {Partial<Record<keyof EngineThresholds, Record<string, number>>>} [overrides]+ * @returns {EngineThresholds}+ */+export function resolve(overrides) {+ if (!overrides) return ENGINE_THRESHOLDS;+ const merged = {};+ for (const [group, defaults] of Object.entries(ENGINE_THRESHOLDS)) {+ merged[group] = Object.freeze({ ...defaults, ...(overrides[group] ?? {}) });+ }+ return Object.freeze(merged);+}diff --git a/server/src/config/action-engine.test.js b/server/src/config/action-engine.test.jsnew file mode 100644index 000000000..7f6e2f12f--- /dev/null+++ b/server/src/config/action-engine.test.js@@ -0,0 +1,68 @@+import { describe, expect, it } from 'vitest';+import { ENGINE_THRESHOLDS, resolve } from './action-engine.js';++describe('ENGINE_THRESHOLDS', () => {+ /**+ * The point of the module. A threshold someone can reach into and change at+ * runtime is not a configuration surface — it is a shared mutable global+ * that happens to live in a config file.+ */+ it('cannot be mutated', () => {+ expect(Object.isFrozen(ENGINE_THRESHOLDS)).toBe(true);+ for (const group of Object.values(ENGINE_THRESHOLDS)) {+ expect(Object.isFrozen(group)).toBe(true);+ }+ });++ it('holds only numbers', () => {+ for (const [name, group] of Object.entries(ENGINE_THRESHOLDS)) {+ for (const [key, value] of Object.entries(group)) {+ expect(typeof value, `${name}.${key}`).toBe('number');+ expect(Number.isFinite(value), `${name}.${key}`).toBe(true);+ }+ }+ });++ /** Ratios are fractions. A ratio above 1 reads as a percentage someone+ * forgot to divide, and would silently disable the guard it belongs to. */+ it('keeps every ratio between 0 and 1', () => {+ for (const [name, group] of Object.entries(ENGINE_THRESHOLDS)) {+ for (const [key, value] of Object.entries(group)) {+ if (!key.toLowerCase().endsWith('ratio')) continue;+ expect(value, `${name}.${key}`).toBeGreaterThan(0);+ expect(value, `${name}.${key}`).toBeLessThanOrEqual(1);+ }+ }+ });+});++describe('resolve', () => {+ it('returns the defaults when nothing overrides them', () => {+ expect(resolve()).toBe(ENGINE_THRESHOLDS);+ expect(resolve(undefined)).toBe(ENGINE_THRESHOLDS);+ });++ it('overrides one threshold and leaves its neighbours alone', () => {+ const tuned = resolve({ detection: { windowDays: 14 } });++ expect(tuned.detection.windowDays).toBe(14);+ expect(tuned.detection.visibilityDropPoints).toBe(+ ENGINE_THRESHOLDS.detection.visibilityDropPoints,+ );+ });++ it('leaves untouched groups whole', () => {+ const tuned = resolve({ detection: { windowDays: 14 } });++ expect(tuned.validation).toEqual(ENGINE_THRESHOLDS.validation);+ expect(tuned.noise).toEqual(ENGINE_THRESHOLDS.noise);+ });++ it('does not let a resolved set write back to the defaults', () => {+ const tuned = resolve({ noise: { restAfterCloseDays: 1 } });++ expect(tuned.noise.restAfterCloseDays).toBe(1);+ expect(ENGINE_THRESHOLDS.noise.restAfterCloseDays).not.toBe(1);+ expect(Object.isFrozen(tuned.noise)).toBe(true);+ });+});diff --git a/server/src/lib/action-center/generate.js b/server/src/lib/action-center/generate.jsindex 32f799489..c1381c349 100644--- a/server/src/lib/action-center/generate.js+++ b/server/src/lib/action-center/generate.js@@ -28,19 +28,13 @@import supabaseAdmin from '../../config/supabase.js';import { logger } from '../logger.js';+import { resolve } from '../../config/action-engine.js';-/**- * How long a kind rests after a cycle closes before a new one may open.- *- * Without it, a condition that is still firing would produce a fresh action- * the night after someone closed the last one — a treadmill. The old code- * used this window to decide whether to resurrect the completed row; now it- * decides when the next cycle may begin, and the completed row is never- * touched again.- */-const REST_AFTER_CLOSE_DAYS = 14;const DAY_MS = 86_400_000;+// Thresholds live in config/action-engine.js (#818 phase 2.5).+const { noise } = resolve();+const IMPACT_RANK = { high: 3, medium: 2, low: 1 };/**@@ -217,7 +211,7 @@ export async function generateActionsForBrand(brandId, { now = new Date() } = {}// night — the same restraint the old reopen window provided, minus the// resurrection.const closedAt = lastClosedAt.get(rule.kind) ?? 0;- if (closedAt && now.getTime() - closedAt < REST_AFTER_CLOSE_DAYS * DAY_MS) {+ if (closedAt && now.getTime() - closedAt < noise.restAfterCloseDays * DAY_MS) {resting += 1;continue;}diff --git a/server/src/lib/action-center/validate.js b/server/src/lib/action-center/validate.jsindex 28e370b41..115093575 100644--- a/server/src/lib/action-center/validate.js+++ b/server/src/lib/action-center/validate.js@@ -26,12 +26,17 @@import supabaseAdmin from '../../config/supabase.js';import { computeAiVisibilityScore } from '../../config/visibility-score.js';import { logger } from '../logger.js';+import { resolve } from '../../config/action-engine.js';const DAY_MS = 86_400_000;+// Windows and the noise floor live in config/action-engine.js (#818 phase+// 2.5), with every other number the engine judges by.+const { validation } = resolve();+/** Length of each measurement window. Equal on both sides so the comparison* is between like periods. */-export const MEASUREMENT_WINDOW_DAYS = 7;+export const MEASUREMENT_WINDOW_DAYS = validation.windowDays;/*** How long after closing before an action can be measured.@@ -49,10 +54,8 @@ export const VALIDATION_WAIT_DAYS = MEASUREMENT_WINDOW_DAYS + 1;* How much a metric must move to count as movement, as a fraction of its* before value. Below this, a difference is indistinguishable from the* week-to-week noise every one of these metrics carries.- *- * Centralised with the rest of the engine's thresholds in phase 2.5 (#818).*/-export const MEANINGFUL_CHANGE_RATIO = 0.05;+export const MEANINGFUL_CHANGE_RATIO = validation.meaningfulChangeRatio;/** Every metric here reads higher-is-better; a drop is a decline. */const MEASURABLE_KPIS = {diff --git a/server/src/lib/page-opportunities.js b/server/src/lib/page-opportunities.jsindex f64a1f628..c021182a3 100644--- a/server/src/lib/page-opportunities.js+++ b/server/src/lib/page-opportunities.js@@ -28,8 +28,12 @@import supabaseAdmin from '../config/supabase.js';import { isExcludedPath } from './page-paths.js';import { logger } from './logger.js';+import { resolve } from '../config/action-engine.js';-const WINDOW_DAYS = 28;+// Thresholds live in config/action-engine.js (#818 phase 2.5).+const { detection } = resolve();++const WINDOW_DAYS = detection.pageWindowDays;/*** A page below this has too little behind it for a finding, whatever its@@ -38,10 +42,10 @@ const WINDOW_DAYS = 28;* of pages, so a brand with genuinely little to fix would still be handed a* full list.*/-const MIN_SESSIONS = 10;+const MIN_SESSIONS = detection.pageMinSessions;/** How far up its own site a page must rank before it is worth raising. */-const MIN_PERCENTILE = 70;+const MIN_PERCENTILE = detection.pageMinPercentile;/*** PostgREST returns at most 1000 rows per request whatever range is askeddiff --git a/server/src/lib/pulse/metrics.js b/server/src/lib/pulse/metrics.jsindex 43f8adb31..85d2e7e23 100644--- a/server/src/lib/pulse/metrics.js+++ b/server/src/lib/pulse/metrics.js@@ -2,6 +2,7 @@ import supabaseAdmin from '../../config/supabase.js';import { computeAiVisibilityScore } from '../../config/visibility-score.js';import { chunkIds, selectInChunks } from '../chunked-in.js';import { logger } from '../logger.js';+import { resolve } from '../../config/action-engine.js';/*** Daily Pulse metric computation (#540).@@ -15,20 +16,16 @@ import { logger } from '../logger.js';const DAY_MS = 86_400_000;-// Detector thresholds (issue #540 v1 scope).-const DROP_MIN_POINTS = 15;-const DROP_MIN_RELATIVE = 0.3;-const DROP_MIN_PROMPTS = 10;-const SURGE_MIN_POINTS = 15;-const LOST_CITED_RATIO = 0.6;-const LOST_CONSECUTIVE_DAYS = 3;-const MOVER_MIN_GAIN = 5;+// Detector thresholds live in config/action-engine.js, with every other+// number that decides what counts (#818 phase 2.5). Read through `resolve()`+// so per-definition and per-workspace overrides land without touching this+// file.+const { detection, noise } = resolve();++// How many risers the digest names. A presentation choice, not a detection+// threshold — it does not change what was found, only how much of it is+// listed — so it stays here.const MOVER_LIMIT = 3;-// A platform is considered degraded (data-collection incident, not a real-// visibility change) when its result volume across ALL orgs collapses below-// this fraction of its trailing 7-day daily average.-const OUTAGE_COLLAPSE_RATIO = 0.25;-const OUTAGE_MIN_BASELINE = 20;// Cloro scraper platforms, as stored in prompt_results.platform. Keep in// sync with SCRAPER_TASK_TYPES in ../cloro-scraper.js (minus shopping,@@ -306,12 +303,12 @@ async function lostCitationPrompts(brandId, promptById, now) {const lost = [];for (const [promptId, days] of byPrompt) {const ordered = [...days.entries()].sort(([a], [b]) => a.localeCompare(b));- if (ordered.length < LOST_CONSECUTIVE_DAYS + 2) continue;- const tail = ordered.slice(-LOST_CONSECUTIVE_DAYS);+ if (ordered.length < detection.lostCitationQuietDays + 2) continue;+ const tail = ordered.slice(-detection.lostCitationQuietDays);if (tail.some(([, cited]) => cited)) continue;- const head = ordered.slice(0, -LOST_CONSECUTIVE_DAYS);+ const head = ordered.slice(0, -detection.lostCitationQuietDays);const citedDays = head.filter(([, cited]) => cited).length;- if (citedDays / head.length >= LOST_CITED_RATIO) {+ if (citedDays / head.length >= detection.lostCitationCitedRatio) {lost.push({ promptId, promptText: promptById.get(promptId)?.text ?? '' });}}@@ -343,8 +340,8 @@ async function degradedPlatforms(now) {]);const dailyBaseline = (baseline ?? 0) / 7;if (- dailyBaseline >= OUTAGE_MIN_BASELINE &&- (today ?? 0) < dailyBaseline * OUTAGE_COLLAPSE_RATIO+ dailyBaseline >= noise.outageMinBaseline &&+ (today ?? 0) < dailyBaseline * noise.outageCollapseRatio) {degraded.push(platform);}@@ -473,7 +470,7 @@ export async function computePulseMetrics(brandId, { windowDays = 1, now = new Dconst prev = prevWeekPromptAvg.get(promptId);if (!prev) continue;const gain = round1(cur.score - prev.score);- if (gain >= MOVER_MIN_GAIN) {+ if (gain >= detection.moverMinGain) {movers.push({ promptId, text: promptById.get(promptId)?.text ?? '', gain });}}@@ -512,10 +509,10 @@ export async function computePulseMetrics(brandId, { windowDays = 1, now = new Dconst drop = round1(prevWeekRate.rate - weekRate.rate);if (!outage &&- weekRate.total >= DROP_MIN_PROMPTS &&- drop >= DROP_MIN_POINTS &&+ weekRate.total >= detection.visibilityDropMinPrompts &&+ drop >= detection.visibilityDropPoints &&prevWeekRate.rate > 0 &&- drop / prevWeekRate.rate >= DROP_MIN_RELATIVE+ drop / prevWeekRate.rate >= detection.visibilityDropRatio) {warnings.push({type: 'sharp_drop',@@ -530,7 +527,7 @@ export async function computePulseMetrics(brandId, { windowDays = 1, now = new Dconst prev = prevWeekComp.competitors.get(id);if (!prev) continue;const surge = round1(comp.rate - prev.rate);- if (surge >= SURGE_MIN_POINTS) {+ if (surge >= detection.competitorSurgePoints) {warnings.push({type: 'competitor_surge',key: `competitor_surge:${id}`,diff --git a/server/src/lib/signals/record.js b/server/src/lib/signals/record.jsindex 3b4238500..a76e8695b 100644--- a/server/src/lib/signals/record.js+++ b/server/src/lib/signals/record.js@@ -29,20 +29,13 @@import supabaseAdmin from '../../config/supabase.js';import { computePulseMetrics } from '../pulse/metrics.js';import { logger } from '../logger.js';+import { resolve } from '../../config/action-engine.js';-const DETECTION_WINDOW_DAYS = 7;const DAY_MS = 86_400_000;-/** A "mentioned but never cited" pattern needs at least this many prompts- * before it is a signal — one or two uncited mentions are normal noise. */-const UNCITED_MIN_PROMPTS = 3;--/** Audits older than this no longer describe the page (it may have been- * rewritten since); their findings age out instead of nagging forever. */-const AUDIT_MAX_AGE_DAYS = 90;--/** Latest completed audit below this total score raises a technical signal. */-const AUDIT_LOW_SCORE = 50;+// What counts as a signal is decided in config/action-engine.js (#818 phase+// 2.5), alongside every other threshold the engine judges by.+const { detection } = resolve();/*** Static knowledge per detector kind. Mirrored by the web registry@@ -184,7 +177,7 @@ function fromPulseEntry(entry) {* to point at. One consolidated signal (brief §29), not one per prompt.*/async function uncitedMentionCandidates(brandId, now) {- const from = new Date(now.getTime() - DETECTION_WINDOW_DAYS * DAY_MS);+ const from = new Date(now.getTime() - detection.windowDays * DAY_MS);const { data, error } = await supabaseAdmin.rpc('prompt_visibility_summaries', {p_brand_id: brandId,p_date_from: from.toISOString(),@@ -196,7 +189,7 @@ async function uncitedMentionCandidates(brandId, now) {(row) =>Number(row.runs) > 0 && Number(row.total_mentions) > 0 && Number(row.total_citations) === 0,);- if (uncited.length < UNCITED_MIN_PROMPTS) return [];+ if (uncited.length < detection.uncitedMinPrompts) return [];return [{@@ -223,7 +216,7 @@ async function uncitedMentionCandidates(brandId, now) {* the drawer; the full list lives on the Site Audit page.*/async function auditCandidates(brandId, now) {- const since = new Date(now.getTime() - AUDIT_MAX_AGE_DAYS * DAY_MS).toISOString();+ const since = new Date(now.getTime() - detection.auditMaxAgeDays * DAY_MS).toISOString();const { data, error } = await supabaseAdmin.from('site_audits').select('url, total_score, completed_at')@@ -242,7 +235,7 @@ async function auditCandidates(brandId, now) {const low = [...latestByUrl.values()].map((audit) => ({ url: audit.url, score: Number(audit.total_score) }))- .filter((audit) => audit.score < AUDIT_LOW_SCORE)+ .filter((audit) => audit.score < detection.auditLowScore).sort((a, b) => a.score - b.score);if (low.length === 0) return [];@@ -291,7 +284,7 @@ async function pageOpportunityCandidates(brandId) {*/export async function recordSignalsForBrand(brandId, { now = new Date() } = {}) {const metrics = await computePulseMetrics(brandId, {- windowDays: DETECTION_WINDOW_DAYS,+ windowDays: detection.windowDays,now,});