Open-source SEO, GEO, and marketing skills for AI agents.
fix(onboarding): unwrap runScript envelope + accept numeric campaign.status
Yuting Zhong997dc9ce83c4
diff --git a/src/server/onboarding/audit.test.ts b/src/server/onboarding/audit.test.tsindex c4c2b827..dbdd0129 100644--- a/src/server/onboarding/audit.test.ts+++ b/src/server/onboarding/audit.test.ts@@ -31,81 +31,107 @@ import { runAudit, type AuditEvent } from "./audit";// ── Fixtures ───────────────────────────────────────────────────────-const NORMAL_REPORTS = {+/**+ * Fixtures mirror the REAL `ads.gaqlParallel` envelope shape (verified live+ * against notfair.co/api/mcp/google_ads on 2026-05-19): the script's return+ * is wrapped in `{ ok, result, resultTruncated, logs, timedOut, elapsedMs }`.+ * Campaign status comes as numeric enum + `status_name` string companion.+ * Rows use object-nested shape (campaign.name, metrics.cost_micros) — NOT+ * dotted keys. Bugs that ship under fixtures that don't match the live shape+ * silently classify accounts as empty (the regression that triggered this+ * test rewrite).+ */+const NORMAL_REPORTS_INNER = {wasted_spend: {+ rowCount: 4,rows: [{- "ad_group_criterion": { keyword: { text: "marketing automation" } },- "ad_group": { name: "Brand" },- "campaign": { name: "Brand-US" },- "metrics": { cost_micros: 420_000_000, conversions: 0, clicks: 300 },+ ad_group_criterion: { keyword: { text: "marketing automation" } },+ ad_group: { name: "Brand" },+ campaign: { name: "Brand-US" },+ metrics: { cost_micros: 420_000_000, conversions: 0, clicks: 300 },},{- "ad_group_criterion": { keyword: { text: "saas crm" } },- "ad_group": { name: "Brand" },- "campaign": { name: "Brand-US" },- "metrics": { cost_micros: 420_000_000, conversions: 0, clicks: 300 },+ ad_group_criterion: { keyword: { text: "saas crm" } },+ ad_group: { name: "Brand" },+ campaign: { name: "Brand-US" },+ metrics: { cost_micros: 420_000_000, conversions: 0, clicks: 300 },},{- "ad_group_criterion": { keyword: { text: "best crm" } },- "ad_group": { name: "Brand" },- "campaign": { name: "Brand-US" },- "metrics": { cost_micros: 210_000_000, conversions: 0, clicks: 150 },+ ad_group_criterion: { keyword: { text: "best crm" } },+ ad_group: { name: "Brand" },+ campaign: { name: "Brand-US" },+ metrics: { cost_micros: 210_000_000, conversions: 0, clicks: 150 },},{- "ad_group_criterion": { keyword: { text: "ad ops" } },- "ad_group": { name: "Brand" },- "campaign": { name: "Brand-US" },- "metrics": { cost_micros: 210_000_000, conversions: 0, clicks: 450 },+ ad_group_criterion: { keyword: { text: "ad ops" } },+ ad_group: { name: "Brand" },+ campaign: { name: "Brand-US" },+ metrics: { cost_micros: 210_000_000, conversions: 0, clicks: 450 },},],},low_qs: {+ rowCount: 1,rows: [{- "ad_group_criterion": {+ ad_group_criterion: {keyword: { text: "kw1" },quality_info: { quality_score: 3 },},- "ad_group": { name: "Generic" },- "campaign": { name: "Generic-US" },- "metrics": { impressions: 500, cost_micros: 50_000_000 },+ ad_group: { name: "Generic" },+ campaign: { name: "Generic-US" },+ metrics: { impressions: 500, cost_micros: 50_000_000 },},],},- search_term_gap: { rows: [] },- budget_pacing: { rows: [] },+ search_term_gap: { rowCount: 0, rows: [] },+ budget_pacing: { rowCount: 0, rows: [] },campaigns_summary: {+ rowCount: 1,rows: [{- "campaign": { name: "Brand-US", status: "ENABLED" },- "metrics": { cost_micros: 3_000_000_000, impressions: 50_000 },+ campaign: { name: "Brand-US", status: 2, status_name: "ENABLED" },+ metrics: { cost_micros: 3_000_000_000, impressions: 50_000 },},],},};-const EMPTY_REPORTS = {- wasted_spend: { rows: [] },- low_qs: { rows: [] },- search_term_gap: { rows: [] },- budget_pacing: { rows: [] },- campaigns_summary: { rows: [] },+const EMPTY_REPORTS_INNER = {+ wasted_spend: { rowCount: 0, rows: [] },+ low_qs: { rowCount: 0, rows: [] },+ search_term_gap: { rowCount: 0, rows: [] },+ budget_pacing: { rowCount: 0, rows: [] },+ campaigns_summary: { rowCount: 0, rows: [] },};+/** Wrap inner reports in the runScript envelope and the MCP tool-call envelope. */function mockToolCallResult(reports: unknown): {ok: true;result: { content: Array<{ type: string; text: string }>; isError: boolean };} {+ const scriptEnvelope = {+ ok: true,+ result: reports,+ resultTruncated: false,+ logs: [],+ logsTruncated: false,+ timedOut: false,+ elapsedMs: 950,+ };return {ok: true,result: {- content: [{ type: "text", text: JSON.stringify(reports) }],+ content: [{ type: "text", text: JSON.stringify(scriptEnvelope) }],isError: false,},};}+const NORMAL_REPORTS = NORMAL_REPORTS_INNER;+const EMPTY_REPORTS = EMPTY_REPORTS_INNER;+async function collect(slug: string, signal?: AbortSignal): Promise<AuditEvent[]> {const out: AuditEvent[] = [];for await (const e of runAudit(slug, signal)) out.push(e);@@ -313,6 +339,93 @@ describe("runAudit", () => {});});+ describe("regression — real MCP envelope shape", () => {+ it("unwraps the runScript {ok, result} envelope (Demo2 bug — 2026-05-19)", async () => {+ // Build a payload WITHOUT the helper so we can exercise the unwrap path+ // explicitly. Live MCP wraps the script's return in {ok, result, ...}.+ // Before the fix, our parser returned the wrapper as the category dict+ // and findings disappeared (classified as empty).+ const inner = {+ wasted_spend: NORMAL_REPORTS_INNER.wasted_spend,+ low_qs: NORMAL_REPORTS_INNER.low_qs,+ search_term_gap: { rows: [] },+ budget_pacing: { rows: [] },+ campaigns_summary: NORMAL_REPORTS_INNER.campaigns_summary,+ };+ const envelopeText = JSON.stringify({+ ok: true,+ result: inner,+ resultTruncated: false,+ logs: [],+ timedOut: false,+ elapsedMs: 950,+ });+ mcpRpcMock.mockResolvedValueOnce({+ ok: true,+ result: {+ content: [{ type: "text", text: envelopeText }],+ isError: false,+ },+ });+ const events = await collect("acme");+ const complete = events.find((e) => e.type === "audit:complete");+ expect(complete, "should reach audit:complete with findings, not classify empty").toBeDefined();+ if (complete && complete.type === "audit:complete") {+ expect(complete.summary.account_state).toBe("normal");+ expect(complete.summary.count).toBeGreaterThan(0);+ }+ });++ it("treats campaign.status_name='ENABLED' as enabled even when status is the numeric enum (Demo2 bug — 2026-05-19)", async () => {+ // Live shape: campaign.status is the integer enum (2 = ENABLED) and+ // campaign.status_name is the string companion. Before the fix, the+ // classifier checked .status === 'ENABLED' (string compare against+ // an integer), got false, and classified the account empty even+ // when a real campaign was running.+ const numericOnly = {+ ...EMPTY_REPORTS_INNER,+ campaigns_summary: {+ rowCount: 1,+ rows: [+ {+ campaign: { name: "NotFair - Google Ads", status: 2, status_name: "ENABLED" },+ metrics: { cost_micros: 39_390_000, impressions: 42 },+ },+ ],+ },+ };+ mcpRpcMock.mockResolvedValueOnce(mockToolCallResult(numericOnly));+ const events = await collect("acme");+ // Spend is $39 (over the $10 threshold) and status enum says ENABLED,+ // so account_state should NOT be 'empty'.+ const complete = events.find((e) => e.type === "audit:complete");+ if (complete && complete.type === "audit:complete") {+ expect(complete.summary.account_state).toBe("normal");+ }+ });++ it("classifies as empty when ok=false (script-side error in envelope)", async () => {+ // Defensive: if the runScript envelope reports ok=false, treat as+ // malformed_response so the user sees a real error instead of silent+ // 'empty' misclassification.+ const errorEnvelope = JSON.stringify({+ ok: false,+ error: { message: "GAQL syntax error" },+ });+ mcpRpcMock.mockResolvedValueOnce({+ ok: true,+ result: {+ content: [{ type: "text", text: errorEnvelope }],+ isError: false,+ },+ });+ const events = await collect("acme");+ expect(events.find((e) => e.type === "audit:error")).toMatchObject({+ kind: "malformed_response",+ });+ });+ });+describe("D7: best-effort FIRST_TURN.md + memory writes", () => {beforeEach(() => {mcpRpcMock.mockResolvedValue(mockToolCallResult(NORMAL_REPORTS));diff --git a/src/server/onboarding/audit.ts b/src/server/onboarding/audit.tsindex 80664c77..414f57bc 100644--- a/src/server/onboarding/audit.ts+++ b/src/server/onboarding/audit.ts@@ -183,6 +183,22 @@ type GaqlRow = Record<string, unknown>;type GaqlReport = { rows?: GaqlRow[]; error?: string };type ScriptResult = Record<string, GaqlReport | { error: string }>;+/**+ * The MCP runScript tool wraps the script's return value in this envelope.+ * Real shape observed against notfair.co/api/mcp/google_ads:+ * { ok: true, result: { <name>: GaqlReport }, resultTruncated, logs,+ * logsTruncated, timedOut, elapsedMs }+ * Our script returns the `ads.gaqlParallel([...])` result; the MCP server+ * wraps it. We must unwrap `result` before treating it as the category dict.+ */+type RunScriptEnvelope = {+ ok?: boolean;+ result?: ScriptResult;+ resultTruncated?: boolean;+ timedOut?: boolean;+ error?: { message?: string };+};+type McpToolCallResult = {content?: Array<{ type?: string; text?: string }>;isError?: boolean;@@ -340,8 +356,11 @@ function mapRpcError(/*** MCP wraps the runScript return value in `{content: [{type: 'text', text: <JSON>}], isError}`.- * Extract and parse the inner JSON. Returns null if the payload doesn't match- * the expected shape (treat as malformed_response upstream).+ * Inside that, the script's return value is itself wrapped by the runScript+ * tool in `{ ok, result, resultTruncated, ... }` (verified live against+ * notfair.co/api/mcp/google_ads). We unwrap both layers and return just the+ * category dict (`result`). Returns null when any layer is missing or shaped+ * unexpectedly (treat as malformed_response upstream).*/function parseScriptResult(payload: McpToolCallResult): ScriptResult | null {if (!payload || typeof payload !== "object") return null;@@ -350,13 +369,25 @@ function parseScriptResult(payload: McpToolCallResult): ScriptResult | null {if (!Array.isArray(content) || content.length === 0) return null;const text = content[0]?.text;if (typeof text !== "string") return null;+ let parsed: unknown;try {- const parsed = JSON.parse(text) as unknown;- if (!parsed || typeof parsed !== "object") return null;- return parsed as ScriptResult;+ parsed = JSON.parse(text);} catch {return null;}+ if (!parsed || typeof parsed !== "object") return null;+ const envelope = parsed as RunScriptEnvelope & ScriptResult;+ // Preferred path: the runScript envelope with `result`.+ if (envelope.ok === true && envelope.result && typeof envelope.result === "object") {+ return envelope.result;+ }+ // Tool-side script error — surface as malformed_response so the caller+ // emits a clear audit:error event rather than silently classifying empty.+ if (envelope.ok === false) return null;+ // Tolerate older or alternate shapes where the script returned the dict+ // directly. Safe because the runScript envelope always carries `ok`; if+ // it's absent we assume the body IS the category dict.+ return envelope as ScriptResult;}function classifyAccountState(@@ -375,11 +406,29 @@ function classifyAccountState(0,);if (last30Spend < 10) return "empty";- const enabled = rows.some((r) => getString(r, "campaign.status") === "ENABLED");- if (!enabled) return "empty";+ if (!rows.some(isEnabledCampaign)) return "empty";return "normal";}+/**+ * Google Ads returns campaign.status as BOTH a numeric protobuf enum and a+ * string-named convenience field. The numeric value of ENABLED is 2; the+ * gaqlParallel result includes a `status_name: "ENABLED"` companion field.+ * We accept either shape so behavior survives MCP/library upgrades that+ * tighten or loosen the response. Numeric enum reference:+ * UNSPECIFIED=0, UNKNOWN=1, ENABLED=2, PAUSED=3, REMOVED=4+ */+const CAMPAIGN_STATUS_ENABLED_ENUM = 2;+function isEnabledCampaign(row: GaqlRow): boolean {+ const nameStr = getString(row, "campaign.status_name");+ if (nameStr === "ENABLED") return true;+ const numeric = getMetric(row, "campaign.status");+ if (numeric === CAMPAIGN_STATUS_ENABLED_ENUM) return true;+ const statusStr = getString(row, "campaign.status");+ if (statusStr === "ENABLED") return true;+ return false;+}+/** Top Fix = highest dollar_impact_usd; tie-break by CATEGORY_PRIORITY order. */function pickTopFix(findings: Finding[]): Finding | null {if (findings.length === 0) return null;