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
feat(action-center): measure a night-engine action on the prompts or pages it names, brand-wide beside (learning A1) (#1688)
Cihane61a1fd074d4
diff --git a/docs/guides/action-center.mdx b/docs/guides/action-center.mdxindex 06aafc3e9..f6d44027f 100644--- a/docs/guides/action-center.mdx+++ b/docs/guides/action-center.mdx@@ -191,7 +191,7 @@ The **History** tab lists actions once they are In Progress, On Hold, CompletedClick an action to see **What was the goal?**, **What happened?** (the signals it was built from), its affected items and tasks, and the **Result**:-- When a completed action's week after closing is over, Ansvisor compares its metrics over the 7 days before it was raised with the 7 days after it closed. The result reads **Improved**, **No meaningful change** or **Declined**. It is measured after the action, not proven to be caused by it. The History drawer also says what became of the signals that raised it by then: how many ended, turned into another, were dismissed, or are still open.+- When a completed action's week after closing is over, Ansvisor compares its metrics over the 7 days before it was raised with the 7 days after it closed. The result reads **Improved**, **No meaningful change** or **Declined**. It is measured after the action, not proven to be caused by it. An action that names its prompts or pages is measured on them, with the brand-wide figures over the same days beside. The History drawer also says what became of the signals that raised it by then: how many ended, turned into another, were dismissed, or are still open.- A dismissed action is **Not measurable**, and so is one with no metric to read.- An action sent from a prompt's Improve tab reports on how many platforms its position improved. It is read again daily while the action is open and for 30 days after it is completed.diff --git a/server/src/lib/action-center/validate.js b/server/src/lib/action-center/validate.jsindex 03c80f6b2..a3826087c 100644--- a/server/src/lib/action-center/validate.js+++ b/server/src/lib/action-center/validate.js@@ -217,6 +217,52 @@ export function deriveOutcome(metrics) {return 'no_meaningful_change';}+/** A target the night engine names that a basket can be measured on (learning A1). */+const TARGET_BASKETS = new Set(['prompts', 'pages']);+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;++/** The brand's primary domain as a host, for a page target written as a path. */+async function primaryHost(brandId) {+ const { data, error } = await supabaseAdmin+ .from('brand_domains')+ .select('domain')+ .eq('brand_id', brandId)+ .order('is_primary', { ascending: false })+ .limit(1)+ .maybeSingle();+ if (error) throw new Error(`brand_domains: ${error.message}`);+ const host = String(data?.domain ?? '')+ .trim()+ .replace(/^https?:\/\//i, '')+ .replace(/[/?#].*$/, '');+ return host || null;+}++/**+ * The basket a night-engine action is measured on (learning A1): the+ * prompts or pages its payload names, every one it counts (`targetIds`)+ * when it shows fewer, a page written as a path read on the brand's primary+ * domain. Null for another kind of target, or none: such an action is+ * measured brand-wide, as before.+ */+export async function targetScope(action) {+ const payload = action.payload ?? {};+ if (!TARGET_BASKETS.has(payload.targetEntity)) return null;+ const listed = Array.isArray(payload.targetIds)+ ? payload.targetIds+ : (Array.isArray(payload.targets) ? payload.targets : []).map((t) => t?.id);+ const keys = [...new Set(listed.filter((k) => typeof k === 'string' && k.trim()))];+ if (payload.targetEntity === 'prompts') {+ const promptIds = keys.filter((k) => UUID.test(k));+ return promptIds.length ? { entity: 'prompts', promptIds, pages: [] } : null;+ }+ const host = keys.some((k) => k.startsWith('/')) ? await primaryHost(action.brand_id) : null;+ const pages = keys+ .map((k) => (k.startsWith('/') ? (host ? `https://${host}${k}` : null) : k))+ .filter((url) => url && /^https?:\/\//i.test(url));+ return pages.length ? { entity: 'pages', promptIds: [], pages } : null;+}+/*** What became of the signals that raised the action, when it is measured* (learning A3): how many ended (resolved, the condition gone), turned into@@ -311,6 +357,59 @@ export async function validateAction(action, { now = new Date() } = {}) {const kpiKeys = (action.kpi_keys ?? []).filter((key) => key in MEASURABLE_KPIS);+ // A night-engine action that names its prompts or pages is measured on+ // them (learning A1): "recover 6 prompts" moves those 6, which the whole+ // brand's numbers can bury. The brand-wide figures stay as a second line.+ // A basket that measured nothing (no answers, citations of prompts) leaves+ // the action to the brand-wide measure below.+ const targets = await targetScope(action);+ if (targets) {+ const asked = (action.kpi_keys ?? []).filter((key) => key in BASKET_KPIS);+ const keys = asked.length ? asked : Object.keys(BASKET_KPIS);+ const [before, after, brandBefore, brandAfter] = await Promise.all([+ measureBasket(action.brand_id, targets, beforeWindow.from, beforeWindow.to),+ measureBasket(action.brand_id, targets, afterWindow.from, afterWindow.to),+ kpiKeys.length+ ? measureKpis(action.brand_id, kpiKeys, beforeWindow.from, beforeWindow.to)+ : {},+ kpiKeys.length ? measureKpis(action.brand_id, kpiKeys, afterWindow.from, afterWindow.to) : {},+ ]);+ const metrics = keys.map((metric) => ({+ metric,+ unit: BASKET_KPIS[metric],+ before: before[metric] ?? null,+ after: after[metric] ?? null,+ }));+ if (metrics.some((m) => m.before != null && m.after != null)) {+ const brandWide = kpiKeys.map((metric) => ({+ metric,+ unit: MEASURABLE_KPIS[metric],+ before: brandBefore[metric] ?? null,+ after: brandAfter[metric] ?? null,+ }));+ const outcome = deriveOutcome(metrics);+ await write(+ action.id,+ withSignals({+ measuredAt: now.toISOString(),+ beforeWindow,+ afterWindow,+ metrics,+ scope: {+ kind: 'targets',+ entity: targets.entity,+ prompts: targets.promptIds.length,+ pages: targets.pages.length,+ },+ ...(brandWide.length ? { brandWide } : {}),+ }),+ outcome,+ now,+ );+ return outcome;+ }+ }+// An action with no success metrics has nothing to measure. That is a gap// in the rule that produced it, not a failure here — say so plainly rather// than inventing a metric it never claimed.diff --git a/server/src/lib/action-center/validate.test.js b/server/src/lib/action-center/validate.test.jsindex 2530137fe..b02bb379f 100644--- a/server/src/lib/action-center/validate.test.js+++ b/server/src/lib/action-center/validate.test.js@@ -32,6 +32,8 @@ function mockWrites(rows = {}) {lte: () => builder,not: () => builder,limit: () => builder,+ order: () => builder,+ maybeSingle: async () => ({ data: (rows[table] ?? [])[0] ?? null, error: null }),update: (patch) => {writes.updated.push({ table, patch });return builder;@@ -375,6 +377,94 @@ describe('validateAction', () => {});});+ describe('on its targets (learning A1)', () => {+ const P1 = '11111111-1111-4111-8111-111111111111';+ const P2 = '22222222-2222-4222-8222-222222222222';+ /** The basket answers `before` for the window before, `after` for the one after; the brand 100 citations. */+ const answers = (before, after) =>+ rpc.mockImplementation(async (name, args) =>+ name === 'opportunity_basket_metrics'+ ? { data: args.p_from < daysAgo(20).slice(0, 10) ? before : after, error: null }+ : { data: { total_citations: 100 }, error: null },+ );++ it('measures a night-engine action on the prompts it names, the brand-wide figures beside', async () => {+ const writes = mockWrites();+ answers({ cells: 10, visible: 2 }, { cells: 10, visible: 6 });++ const outcome = await validateAction(+ action({+ kind: 'recover_lost_visibility',+ kpi_keys: ['ai_visibility', 'citations'],+ payload: {+ targetEntity: 'prompts',+ targetCount: 2,+ targets: [{ id: P1, label: 'best beans' }],+ targetIds: [P1, P2, 'not-a-prompt-id'],+ },+ }),+ { now: NOW },+ );++ expect(outcome).toBe('improved');+ const basketCall = rpc.mock.calls.find(([name]) => name === 'opportunity_basket_metrics');+ expect(basketCall[1].p_prompt_ids).toEqual([P1, P2]);+ const { validation } = writes.updated.find((w) => w.table === 'actions').patch;+ expect(validation.scope).toEqual({+ kind: 'targets',+ entity: 'prompts',+ prompts: 2,+ pages: 0,+ });+ expect(validation.metrics).toEqual([+ { metric: 'ai_visibility', unit: 'percent', before: 20, after: 60 },+ // A prompt basket has no pages to count citations on.+ { metric: 'citations', unit: 'count', before: null, after: null },+ ]);+ expect(validation.brandWide.map((m) => m.metric)).toEqual(['ai_visibility', 'citations']);+ });++ it('reads a page written as a path on the brand’s primary domain', async () => {+ mockWrites({ brand_domains: [{ domain: 'https://www.acme.example/' }] });+ answers({}, {});++ await validateAction(+ action({+ kind: 'fix_underperforming_pages',+ kpi_keys: ['citations'],+ payload: { targetEntity: 'pages', targetCount: 1, targets: [{ id: '/pricing' }] },+ }),+ { now: NOW },+ );++ const basketCall = rpc.mock.calls.find(([name]) => name === 'opportunity_basket_metrics');+ expect(basketCall[1].p_page_keys).toEqual(['acme.example/pricing']);+ });++ it('measures brand-wide when the targets measured nothing, or are of another kind', async () => {+ let writes = mockWrites();+ answers({}, {});+ await validateAction(+ action({ payload: { targetEntity: 'prompts', targets: [{ id: P1 }] } }),+ { now: NOW },+ );+ let { validation } = writes.updated.find((w) => w.table === 'actions').patch;+ expect(validation.scope).toBeUndefined();+ expect(validation.metrics.map((m) => m.metric)).toEqual(['citations']);++ rpc.mockReset();+ writes = mockWrites();+ rpc.mockResolvedValue({ data: { total_citations: 10 }, error: null });+ await validateAction(+ action({ payload: { targetEntity: 'competitors', targets: [{ id: 'Rival' }] } }),+ { now: NOW },+ );+ expect(rpc.mock.calls.some(([name]) => name === 'opportunity_basket_metrics')).toBe(false);+ ({ validation } = writes.updated.find((w) => w.table === 'actions').patch);+ expect(validation.scope).toBeUndefined();+ });+ });+it('does nothing for an action that never closed', async () => {const writes = mockWrites();diff --git a/web/messages/en.json b/web/messages/en.jsonindex d7487f542..ea8c01df7 100644--- a/web/messages/en.json+++ b/web/messages/en.json@@ -2590,6 +2590,8 @@"goal": "What was the goal?","whatHappened": "What happened?","triggeredBy": "Consolidated from {count, plural, one {# signal} other {# signals}}",+ "measuredOn": "Measured on the {entity, select, pages {{count, plural, one {page} other {# pages}}} other {{count, plural, one {prompt} other {# prompts}}}} it named.",+ "brandWide": "Brand-wide over the same days: {list}","signalsAfter": "Of the {total, plural, one {signal} other {# signals}} that raised it, when measured: {ended} ended{replaced, plural, =0 {} other {, # turned into another}}{dismissed, plural, =0 {} other {, # dismissed}}{open, plural, =0 {} other {, # still open}}.","result": "Result","visibilityChange": "Visibility Change",diff --git a/web/src/components/action-center/history-drawer.test.tsx b/web/src/components/action-center/history-drawer.test.tsxindex c2d169057..7254e83a8 100644--- a/web/src/components/action-center/history-drawer.test.tsx+++ b/web/src/components/action-center/history-drawer.test.tsx@@ -153,6 +153,36 @@ describe('HistoryDrawer', () => {expect(under('Result')).not.toContain('that raised it');});+ it('says it was measured on the prompts it named, the brand-wide figures beside (learning A1)', async () => {+ getActionSignals.mockResolvedValue([]);+ const metric = (id: string, before: number, after: number) => ({+ id,+ label: id,+ metric: id as never,+ before,+ after,+ delta: after - before,+ unit: 'number' as const,+ direction: 'higher_is_better' as const,+ });+ render(+ <HistoryDrawer+ brandId="b1"+ item={{+ ...item,+ results: [metric('mentions', 2, 6)],+ measuredOn: { entity: 'prompts', count: 2 },+ brandWideResults: [metric('citations', 100, 104)],+ }}+ onOpenChange={() => {}}+ />,+ );+ await act(async () => {});+ const result = under('Result');+ expect(result).toContain('Measured on the 2 prompts it named.');+ expect(result).toMatch(/Brand-wide over the same days: \S.* 100 → 104/);+ });+it('keeps the general sentences when the signals cannot be read', async () => {getActionSignals.mockRejectedValue(new Error('offline'));render(<HistoryDrawer brandId="b1" item={item} onOpenChange={() => {}} />);diff --git a/web/src/components/action-center/history-drawer.tsx b/web/src/components/action-center/history-drawer.tsxindex 1b75cae84..0bc4adea3 100644--- a/web/src/components/action-center/history-drawer.tsx+++ b/web/src/components/action-center/history-drawer.tsx@@ -208,6 +208,11 @@ export function HistoryDrawer({<section><p className="text-xs font-medium text-muted-foreground">{t('drawer.result')}</p>+ {item.measuredOn && (+ <p className="mt-1 text-xs text-muted-foreground">+ {t('drawer.measuredOn', { ...item.measuredOn })}+ </p>+ )}{item.signalsAfter && (// The closest measure to the action's own aim: did what raised it end?<p className="mt-1 text-xs">{t('drawer.signalsAfter', { ...item.signalsAfter })}</p>@@ -241,6 +246,16 @@ export function HistoryDrawer({<p className="text-[11px] text-muted-foreground">{t('drawer.fromStart')}</p></div></div>+ {!!item.brandWideResults?.length && (+ // The second line: the whole brand over the same windows.+ <p className="mt-2 text-xs text-muted-foreground">+ {t('drawer.brandWide', {+ list: item.brandWideResults+ .map((m) => `${tRegistry(`${m.metric}.name`)} ${m.before} → ${m.after}`)+ .join(' · '),+ })}+ </p>+ )}</section><Separator />diff --git a/web/src/lib/action-center/history.ts b/web/src/lib/action-center/history.tsindex 7ccfd876c..dcf1960b6 100644--- a/web/src/lib/action-center/history.ts+++ b/web/src/lib/action-center/history.ts@@ -117,6 +117,12 @@ export interface ActionHistoryItem {results: ActionResultMetric[];/** Its signals when it was measured; absent before, or with no signal behind it. */signalsAfter?: SignalOutcome | null;+ /**+ * The prompts or pages it named, when it was measured on them (learning+ * A1), with the brand-wide figures kept as a second line.+ */+ measuredOn?: { entity: 'prompts' | 'pages'; count: number } | null;+ brandWideResults?: ActionResultMetric[];/** Improve actions only: positions per platform against the baseline (PROMPT-008). */positionOutcome: ImproveOutcome | null;tasks: ActionHistoryTask[];diff --git a/web/src/lib/actions/action-history.ts b/web/src/lib/actions/action-history.tsindex d9d044ee9..92e0503d6 100644--- a/web/src/lib/actions/action-history.ts+++ b/web/src/lib/actions/action-history.ts@@ -69,6 +69,21 @@ interface ValidationSnapshot {}[];/** What became of the signals that raised it (learning A3). */signals?: SignalOutcome;+ /** The basket it was measured on; 'targets' for the prompts or pages it named (learning A1). */+ scope?: { kind?: string; entity?: string; prompts?: number; pages?: number };+ /** The brand-wide figures, beside a measure on its targets. */+ brandWide?: ValidationSnapshot['metrics'];+}++/** The prompts or pages it was measured on, when it was measured on its own targets. */+function measuredOnFrom(+ validation: ValidationSnapshot | null,+): { entity: 'prompts' | 'pages'; count: number } | null {+ const scope = validation?.scope;+ if (scope?.kind !== 'targets') return null;+ const entity = scope.entity === 'pages' ? 'pages' : 'prompts';+ const count = Number(entity === 'pages' ? scope.pages : scope.prompts) || 0;+ return count > 0 ? { entity, count } : null;}/** The signals' counts, when the sweep kept them and they add up. */@@ -282,6 +297,10 @@ export async function getActionHistory(affected: affectedFrom(row.kind, row.payload ?? {}, triggerSignals.length),results,signalsAfter: signalsFrom(row.validation),+ measuredOn: measuredOnFrom(row.validation),+ brandWideResults: resultsFrom(+ row.validation?.brandWide ? { ...row.validation, metrics: row.validation.brandWide } : null,+ ),tasks: tasksByAction.get(row.id) ?? [],assignee: row.assignee_id ? (profiles.get(row.assignee_id) ?? null) : null,dueDate: row.due_date ?? null,