Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

feat(onboarding): real Google Ads audit module

Yuting Zhong06da3e4931e8
diff --git a/src/server/onboarding/audit.test.ts b/src/server/onboarding/audit.test.ts
new file mode 100644
index 00000000..c4c2b827
--- /dev/null
+++ b/src/server/onboarding/audit.test.ts
@@ -0,0 +1,333 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// ── Mocks ──────────────────────────────────────────────────────────
+
+const getMcpConfigMock = vi.fn();
+const mcpRpcMock = vi.fn();
+vi.mock("@/server/mcp/rpc", () => ({
+ getMcpConfig: (...args: unknown[]) => getMcpConfigMock(...args),
+ mcpRpc: (...args: unknown[]) => mcpRpcMock(...args),
+}));
+
+const logAgentActionMock = vi.fn();
+vi.mock("@/server/db/agent-actions", () => ({
+ logAgentAction: (...args: unknown[]) => logAgentActionMock(...args),
+}));
+
+const writeFileMock = vi.fn();
+const mkdirMock = vi.fn();
+vi.mock("node:fs/promises", () => ({
+ writeFile: (...args: unknown[]) => writeFileMock(...args),
+ mkdir: (...args: unknown[]) => mkdirMock(...args),
+}));
+
+const openclawMock = vi.fn();
+vi.mock("@/server/openclaw/cli", () => ({
+ openclaw: (...args: unknown[]) => openclawMock(...args),
+ OpenClawError: class OpenClawError extends Error {},
+}));
+
+import { runAudit, type AuditEvent } from "./audit";
+
+// ── Fixtures ───────────────────────────────────────────────────────
+
+const NORMAL_REPORTS = {
+ wasted_spend: {
+ 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: "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: "ad ops" } },
+ "ad_group": { name: "Brand" },
+ "campaign": { name: "Brand-US" },
+ "metrics": { cost_micros: 210_000_000, conversions: 0, clicks: 450 },
+ },
+ ],
+ },
+ low_qs: {
+ rows: [
+ {
+ "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 },
+ },
+ ],
+ },
+ search_term_gap: { rows: [] },
+ budget_pacing: { rows: [] },
+ campaigns_summary: {
+ rows: [
+ {
+ "campaign": { name: "Brand-US", status: "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: [] },
+};
+
+function mockToolCallResult(reports: unknown): {
+ ok: true;
+ result: { content: Array<{ type: string; text: string }>; isError: boolean };
+} {
+ return {
+ ok: true,
+ result: {
+ content: [{ type: "text", text: JSON.stringify(reports) }],
+ isError: false,
+ },
+ };
+}
+
+async function collect(slug: string, signal?: AbortSignal): Promise<AuditEvent[]> {
+ const out: AuditEvent[] = [];
+ for await (const e of runAudit(slug, signal)) out.push(e);
+ return out;
+}
+
+// ── Tests ──────────────────────────────────────────────────────────
+
+describe("runAudit", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ getMcpConfigMock.mockResolvedValue({
+ url: "https://notfair.co/api/mcp/google_ads",
+ token: "tok",
+ });
+ mkdirMock.mockResolvedValue(undefined);
+ writeFileMock.mockResolvedValue(undefined);
+ openclawMock.mockResolvedValue(undefined);
+ });
+
+ describe("happy path (normal account)", () => {
+ beforeEach(() => {
+ mcpRpcMock.mockResolvedValue(mockToolCallResult(NORMAL_REPORTS));
+ });
+
+ it("emits start → findings → complete in order", async () => {
+ const events = await collect("acme");
+ expect(events[0]).toEqual({ type: "audit:start" });
+ expect(events.at(-1)).toMatchObject({ type: "audit:complete" });
+ const findingEvents = events.filter((e) => e.type === "audit:finding");
+ expect(findingEvents.length).toBeGreaterThan(0);
+ });
+
+ it("WASTED_SPEND finding references the offending campaign by name", async () => {
+ const events = await collect("acme");
+ const wasted = events.find(
+ (e) => e.type === "audit:finding" && e.finding.category === "WASTED_SPEND",
+ );
+ expect(wasted).toBeDefined();
+ if (wasted && wasted.type === "audit:finding") {
+ expect(wasted.finding.headline).toContain("Brand-US");
+ expect(wasted.finding.headline).toMatch(/burn/);
+ }
+ });
+
+ it("persists the audit to agent_actions with category-errored count", async () => {
+ await collect("acme");
+ expect(logAgentActionMock).toHaveBeenCalledTimes(1);
+ const call = logAgentActionMock.mock.calls[0]![0];
+ expect(call.project_slug).toBe("acme");
+ expect(call.action_type).toBe("audit_completed");
+ expect(call.agent_id).toBe("acme-google-ads");
+ expect(call.payload.summary.count).toBeGreaterThan(0);
+ });
+
+ it("writes FIRST_TURN.md to the CMO workspace", async () => {
+ await collect("acme");
+ expect(writeFileMock).toHaveBeenCalled();
+ const [path, body] = writeFileMock.mock.calls[0]!;
+ expect(String(path)).toMatch(/acme-cmo[\\/]FIRST_TURN\.md$/);
+ expect(String(body)).toContain("# First-turn context for the CMO");
+ expect(String(body)).toContain("acme");
+ expect(String(body)).toContain("Top finding");
+ });
+
+ it("writes a memory tag via openclaw subprocess", async () => {
+ await collect("acme");
+ expect(openclawMock).toHaveBeenCalled();
+ const [args] = openclawMock.mock.calls[0]!;
+ expect(args).toContain("memory");
+ expect(args).toContain("write");
+ expect(args).toContain("--agent");
+ expect(args).toContain("acme-cmo");
+ });
+
+ it("picks the highest-$-impact finding as top_fix", async () => {
+ const events = await collect("acme");
+ const complete = events.find((e) => e.type === "audit:complete");
+ if (complete && complete.type === "audit:complete") {
+ expect(complete.summary.top_fix_id).toMatch(/^wasted_spend:/);
+ }
+ });
+ });
+
+ describe("empty account (D5)", () => {
+ beforeEach(() => {
+ mcpRpcMock.mockResolvedValue(mockToolCallResult(EMPTY_REPORTS));
+ });
+
+ it("emits audit:empty before audit:complete", async () => {
+ const events = await collect("acme");
+ const emptyIdx = events.findIndex((e) => e.type === "audit:empty");
+ const completeIdx = events.findIndex((e) => e.type === "audit:complete");
+ expect(emptyIdx).toBeGreaterThan(-1);
+ expect(completeIdx).toBeGreaterThan(emptyIdx);
+ });
+
+ it("records account_state='empty' on the agent_actions row", async () => {
+ await collect("acme");
+ const call = logAgentActionMock.mock.calls[0]![0];
+ expect(call.payload.summary.account_state).toBe("empty");
+ });
+
+ it("FIRST_TURN.md contains the empty-account roadmap content", async () => {
+ await collect("acme");
+ const [, body] = writeFileMock.mock.calls[0]!;
+ expect(String(body)).toContain("Set a daily budget");
+ expect(String(body)).toContain("just getting started");
+ });
+ });
+
+ describe("MCP failure modes", () => {
+ it("emits stale_token error on 401", async () => {
+ mcpRpcMock.mockResolvedValue({ ok: false, kind: "http_error", status: 401 });
+ const events = await collect("acme");
+ const err = events.find((e) => e.type === "audit:error");
+ expect(err).toMatchObject({ type: "audit:error", kind: "stale_token" });
+ // Did NOT persist or write FIRST_TURN.md when MCP failed.
+ expect(logAgentActionMock).not.toHaveBeenCalled();
+ expect(writeFileMock).not.toHaveBeenCalled();
+ });
+
+ it("emits unreachable error on 500", async () => {
+ mcpRpcMock.mockResolvedValue({ ok: false, kind: "http_error", status: 500 });
+ const events = await collect("acme");
+ expect(events.find((e) => e.type === "audit:error")).toMatchObject({
+ kind: "unreachable",
+ });
+ });
+
+ it("emits timeout error on timeout", async () => {
+ mcpRpcMock.mockResolvedValue({ ok: false, kind: "timeout" });
+ const events = await collect("acme");
+ expect(events.find((e) => e.type === "audit:error")).toMatchObject({
+ kind: "timeout",
+ });
+ });
+
+ it("emits rpc_error on JSON-RPC error envelope", async () => {
+ mcpRpcMock.mockResolvedValue({
+ ok: false,
+ kind: "rpc_error",
+ code: -32601,
+ message: "Method not found",
+ });
+ const events = await collect("acme");
+ expect(events.find((e) => e.type === "audit:error")).toMatchObject({
+ kind: "rpc_error",
+ });
+ });
+
+ it("emits malformed_response when MCP returns non-text content", async () => {
+ mcpRpcMock.mockResolvedValue({
+ ok: true,
+ result: { content: [], isError: false },
+ });
+ const events = await collect("acme");
+ expect(events.find((e) => e.type === "audit:error")).toMatchObject({
+ kind: "malformed_response",
+ });
+ });
+
+ it("emits mcp_not_configured when getMcpConfig returns null", async () => {
+ getMcpConfigMock.mockResolvedValueOnce(null);
+ mcpRpcMock.mockResolvedValue(mockToolCallResult(NORMAL_REPORTS));
+ const events = await collect("acme");
+ expect(events.find((e) => e.type === "audit:error")).toMatchObject({
+ kind: "mcp_not_configured",
+ });
+ expect(mcpRpcMock).not.toHaveBeenCalled();
+ });
+ });
+
+ describe("category-level errors (partial audit)", () => {
+ it("emits audit:finding-error per failing category but continues", async () => {
+ const mixed = {
+ ...NORMAL_REPORTS,
+ low_qs: { error: "quota exceeded for this surface" },
+ };
+ mcpRpcMock.mockResolvedValue(mockToolCallResult(mixed));
+ const events = await collect("acme");
+ const findingErr = events.find((e) => e.type === "audit:finding-error");
+ expect(findingErr).toMatchObject({ category: "LOW_QS" });
+ // Other findings still emitted + completion still fired.
+ expect(events.some((e) => e.type === "audit:finding")).toBe(true);
+ expect(events.some((e) => e.type === "audit:complete")).toBe(true);
+ });
+ });
+
+ describe("D12: load-bearing SQLite write fail-loud", () => {
+ beforeEach(() => {
+ mcpRpcMock.mockResolvedValue(mockToolCallResult(NORMAL_REPORTS));
+ });
+
+ it("emits audit:persist-failed and stops (no complete) when logAgentAction throws", async () => {
+ logAgentActionMock.mockImplementationOnce(() => {
+ throw new Error("disk is full");
+ });
+ const events = await collect("acme");
+ expect(events.some((e) => e.type === "audit:persist-failed")).toBe(true);
+ expect(events.some((e) => e.type === "audit:complete")).toBe(false);
+ // FIRST_TURN.md and memory writes did NOT run after persist failed.
+ expect(writeFileMock).not.toHaveBeenCalled();
+ expect(openclawMock).not.toHaveBeenCalled();
+ });
+ });
+
+ describe("D7: best-effort FIRST_TURN.md + memory writes", () => {
+ beforeEach(() => {
+ mcpRpcMock.mockResolvedValue(mockToolCallResult(NORMAL_REPORTS));
+ });
+
+ it("completes audit even when FIRST_TURN.md write fails", async () => {
+ writeFileMock.mockRejectedValueOnce(new Error("ENOSPC"));
+ const events = await collect("acme");
+ expect(events.some((e) => e.type === "audit:complete")).toBe(true);
+ });
+
+ it("completes audit even when memory write fails", async () => {
+ openclawMock.mockRejectedValueOnce(new Error("memory service down"));
+ const events = await collect("acme");
+ expect(events.some((e) => e.type === "audit:complete")).toBe(true);
+ });
+ });
+});
diff --git a/src/server/onboarding/audit.ts b/src/server/onboarding/audit.ts
new file mode 100644
index 00000000..80664c77
--- /dev/null
+++ b/src/server/onboarding/audit.ts
@@ -0,0 +1,700 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { logAgentAction } from "@/server/db/agent-actions";
+import { getMcpConfig, mcpRpc } from "@/server/mcp/rpc";
+import { openclaw } from "@/server/openclaw/cli";
+import { storedMcpKey } from "@/server/mcp-catalog";
+
+/**
+ * Google Ads onboarding audit.
+ *
+ * Flow:
+ * 1. Read project-scoped MCP credentials via getMcpConfig
+ * 2. Call MCP `tools/call runScript` with a fixed GAQL fan-out script
+ * (deterministic, no LLM in critical path per D11)
+ * 3. Iterate categories, classify findings, emit per-finding events
+ * 4. Persist canonical record to agent_actions (D10 + D12: load-bearing)
+ * 5. Best-effort write FIRST_TURN.md for the CMO + memory tag (D7)
+ *
+ * Events are emitted via an AsyncGenerator. The SSE route (Lane A4) pipes
+ * them to the client with small stagger for visual rhythm (D17).
+ *
+ * Decisions wired in:
+ * - D7 — FIRST_TURN.md sentinel for CMO first-turn greeting
+ * - D10 — agent_actions canonical record; OpenClaw memory derived
+ * - D11 — direct HTTP to MCP runScript via shared rpc helper
+ * - D12 — fail-loud on SQLite write; best-effort on memory/file
+ * - D17 — backend constructs the stream; MCP returns bulk
+ * - D5 — empty-account branch when no campaigns or near-zero spend
+ */
+
+export type FindingCategory =
+ | "WASTED_SPEND"
+ | "LOW_QS"
+ | "SEARCH_TERM_GAP"
+ | "BUDGET_PACING";
+
+/** Category-display order; also the tie-break order for Top Fix selection. */
+const CATEGORY_PRIORITY: FindingCategory[] = [
+ "WASTED_SPEND",
+ "LOW_QS",
+ "SEARCH_TERM_GAP",
+ "BUDGET_PACING",
+];
+
+export type Finding = {
+ id: string;
+ category: FindingCategory;
+ headline: string;
+ evidence: string;
+ suggested_action: string;
+ /** Estimated dollar impact per month — used for Top Fix promotion. */
+ dollar_impact_usd: number;
+};
+
+export type AccountState = "normal" | "empty";
+
+export type AuditSummary = {
+ count: number;
+ account_state: AccountState;
+ top_fix_id: string | null;
+ category_errors: Array<{ category: string; message: string }>;
+};
+
+export type AuditEvent =
+ | { type: "audit:start" }
+ | { type: "audit:finding"; finding: Finding }
+ | { type: "audit:finding-error"; category: string; message: string }
+ | { type: "audit:empty" }
+ | { type: "audit:complete"; summary: AuditSummary }
+ | {
+ type: "audit:error";
+ kind: "mcp_not_configured" | "stale_token" | "unreachable" | "rpc_error" | "malformed_response" | "timeout" | "aborted";
+ message: string;
+ }
+ | { type: "audit:persist-failed"; message: string };
+
+const MCP_CATALOG_KEY = "notfair-googleads";
+const MCP_TIMEOUT_MS = 30_000;
+
+/**
+ * GAQL fan-out script. Runs ~5 SELECT queries in parallel inside the MCP's
+ * QuickJS sandbox via `ads.gaqlParallel`. Returns one object keyed by query
+ * name. All queries have LIMIT 50–100 to bound response size on large
+ * advertiser accounts (per §2 GAP 2.4). Scoped to LAST_30_DAYS for recency.
+ *
+ * Iterate on the SQL strings as you observe real accounts — the orchestration
+ * code in this file only cares about the response shape, not the WHERE
+ * clauses.
+ */
+const AUDIT_SCRIPT = `
+return await ads.gaqlParallel([
+ {
+ name: "wasted_spend",
+ query: \`
+ SELECT
+ ad_group_criterion.keyword.text,
+ ad_group_criterion.keyword.match_type,
+ ad_group.name,
+ campaign.name,
+ metrics.cost_micros,
+ metrics.conversions,
+ metrics.clicks
+ FROM keyword_view
+ WHERE segments.date DURING LAST_30_DAYS
+ AND metrics.cost_micros > 100000
+ AND metrics.conversions = 0
+ AND ad_group_criterion.status = 'ENABLED'
+ AND campaign.status = 'ENABLED'
+ ORDER BY metrics.cost_micros DESC
+ LIMIT 50
+ \`,
+ },
+ {
+ name: "low_qs",
+ query: \`
+ SELECT
+ ad_group_criterion.keyword.text,
+ ad_group.name,
+ campaign.name,
+ ad_group_criterion.quality_info.quality_score,
+ metrics.impressions,
+ metrics.cost_micros
+ FROM keyword_view
+ WHERE ad_group_criterion.quality_info.quality_score < 5
+ AND ad_group_criterion.quality_info.quality_score > 0
+ AND segments.date DURING LAST_30_DAYS
+ AND metrics.impressions > 100
+ ORDER BY metrics.impressions DESC
+ LIMIT 50
+ \`,
+ },
+ {
+ name: "search_term_gap",
+ query: \`
+ SELECT
+ search_term_view.search_term,
+ metrics.conversions,
+ metrics.cost_micros,
+ campaign.name,
+ search_term_view.status
+ FROM search_term_view
+ WHERE segments.date DURING LAST_30_DAYS
+ AND metrics.conversions > 0
+ AND search_term_view.status = 'NONE'
+ ORDER BY metrics.conversions DESC
+ LIMIT 50
+ \`,
+ },
+ {
+ name: "budget_pacing",
+ query: \`
+ SELECT
+ campaign.name,
+ campaign_budget.amount_micros,
+ metrics.cost_micros,
+ metrics.impressions
+ FROM campaign
+ WHERE segments.date DURING YESTERDAY
+ AND campaign.status = 'ENABLED'
+ ORDER BY metrics.cost_micros DESC
+ LIMIT 50
+ \`,
+ },
+ {
+ name: "campaigns_summary",
+ query: \`
+ SELECT
+ campaign.name,
+ campaign.status,
+ metrics.cost_micros,
+ metrics.impressions
+ FROM campaign
+ WHERE segments.date DURING LAST_30_DAYS
+ LIMIT 100
+ \`,
+ },
+], { partial: true });
+`;
+
+type GaqlRow = Record<string, unknown>;
+type GaqlReport = { rows?: GaqlRow[]; error?: string };
+type ScriptResult = Record<string, GaqlReport | { error: string }>;
+
+type McpToolCallResult = {
+ content?: Array<{ type?: string; text?: string }>;
+ isError?: boolean;
+};
+
+/**
+ * Run the audit and yield events. Caller is responsible for piping events
+ * to whichever surface the user is watching (SSE, log, etc).
+ */
+export async function* runAudit(
+ project_slug: string,
+ signal?: AbortSignal,
+): AsyncGenerator<AuditEvent, void, void> {
+ yield { type: "audit:start" };
+
+ const cfg = await getMcpConfig(storedMcpKey(project_slug, MCP_CATALOG_KEY));
+ if (!cfg) {
+ yield {
+ type: "audit:error",
+ kind: "mcp_not_configured",
+ message: "Google Ads MCP is not configured for this project.",
+ };
+ return;
+ }
+
+ const rpcResult = await mcpRpc<McpToolCallResult>(
+ cfg.url,
+ cfg.token,
+ "tools/call",
+ { name: "runScript", arguments: { code: AUDIT_SCRIPT, timeoutMs: 45_000 } },
+ { timeoutMs: MCP_TIMEOUT_MS, signal },
+ );
+
+ if (!rpcResult.ok) {
+ yield mapRpcError(rpcResult);
+ return;
+ }
+
+ const reports = parseScriptResult(rpcResult.result);
+ if (!reports) {
+ yield {
+ type: "audit:error",
+ kind: "malformed_response",
+ message: "MCP runScript returned an unexpected payload shape.",
+ };
+ return;
+ }
+
+ const findings: Finding[] = [];
+ const categoryErrors: Array<{ category: string; message: string }> = [];
+
+ for (const category of CATEGORY_PRIORITY) {
+ const report = reports[category.toLowerCase()];
+ if (!report) continue;
+ if ("error" in report && report.error) {
+ yield {
+ type: "audit:finding-error",
+ category,
+ message: report.error,
+ };
+ categoryErrors.push({ category, message: report.error });
+ continue;
+ }
+ const rows = (report as GaqlReport).rows ?? [];
+ const transformed = TRANSFORMERS[category](rows);
+ for (const f of transformed) {
+ findings.push(f);
+ yield { type: "audit:finding", finding: f };
+ }
+ }
+
+ const accountState = classifyAccountState(reports, findings);
+ if (accountState === "empty") {
+ yield { type: "audit:empty" };
+ }
+
+ const topFix = pickTopFix(findings);
+ const summary: AuditSummary = {
+ count: findings.length,
+ account_state: accountState,
+ top_fix_id: topFix?.id ?? null,
+ category_errors: categoryErrors,
+ };
+
+ // D12: agent_actions write is load-bearing. If it throws, fail loud.
+ try {
+ logAgentAction({
+ project_slug,
+ agent_id: `${project_slug}-google-ads`,
+ action_type: "audit_completed",
+ summary: buildSummaryLine(findings, accountState, topFix),
+ reasoning: buildReasoningLine(summary),
+ payload: { findings, summary, category_errors: categoryErrors },
+ });
+ } catch (err) {
+ yield {
+ type: "audit:persist-failed",
+ message: err instanceof Error ? err.message : String(err),
+ };
+ return;
+ }
+
+ // D7: FIRST_TURN.md + OpenClaw memory writes are best-effort projections.
+ // Failure must NOT block the completion event — the canonical record is
+ // already in agent_actions.
+ await safeWriteFirstTurn(project_slug, findings, topFix, accountState);
+ await safeWriteMemoryTag(project_slug, summary);
+
+ yield { type: "audit:complete", summary };
+}
+
+function mapRpcError(
+ r: Extract<Awaited<ReturnType<typeof mcpRpc>>, { ok: false }>,
+): AuditEvent {
+ if (r.kind === "http_error" && (r.status === 401 || r.status === 403)) {
+ return {
+ type: "audit:error",
+ kind: "stale_token",
+ message: `Google Ads token rejected (HTTP ${r.status}).`,
+ };
+ }
+ if (r.kind === "http_error") {
+ return {
+ type: "audit:error",
+ kind: "unreachable",
+ message: `MCP returned HTTP ${r.status}.`,
+ };
+ }
+ if (r.kind === "timeout") {
+ return { type: "audit:error", kind: "timeout", message: "MCP call timed out." };
+ }
+ if (r.kind === "aborted") {
+ return { type: "audit:error", kind: "aborted", message: "Audit cancelled." };
+ }
+ if (r.kind === "rpc_error") {
+ return {
+ type: "audit:error",
+ kind: "rpc_error",
+ message: `RPC error ${r.code}: ${r.message}`,
+ };
+ }
+ if (r.kind === "malformed_response") {
+ return {
+ type: "audit:error",
+ kind: "malformed_response",
+ message: r.message,
+ };
+ }
+ return {
+ type: "audit:error",
+ kind: "unreachable",
+ message: r.message,
+ };
+}
+
+/**
+ * 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).
+ */
+function parseScriptResult(payload: McpToolCallResult): ScriptResult | null {
+ if (!payload || typeof payload !== "object") return null;
+ if (payload.isError) return null;
+ const content = payload.content;
+ if (!Array.isArray(content) || content.length === 0) return null;
+ const text = content[0]?.text;
+ if (typeof text !== "string") return null;
+ try {
+ const parsed = JSON.parse(text) as unknown;
+ if (!parsed || typeof parsed !== "object") return null;
+ return parsed as ScriptResult;
+ } catch {
+ return null;
+ }
+}
+
+function classifyAccountState(
+ reports: ScriptResult,
+ findings: Finding[],
+): AccountState {
+ const summary = reports.campaigns_summary;
+ if (!summary || "error" in summary) {
+ // No summary data — fall back to findings count.
+ return findings.length === 0 ? "empty" : "normal";
+ }
+ const rows = (summary as GaqlReport).rows ?? [];
+ if (rows.length === 0) return "empty";
+ const last30Spend = rows.reduce(
+ (acc, r) => acc + microsAsDollars(getMetric(r, "metrics.cost_micros")),
+ 0,
+ );
+ if (last30Spend < 10) return "empty";
+ const enabled = rows.some((r) => getString(r, "campaign.status") === "ENABLED");
+ if (!enabled) return "empty";
+ return "normal";
+}
+
+/** Top Fix = highest dollar_impact_usd; tie-break by CATEGORY_PRIORITY order. */
+function pickTopFix(findings: Finding[]): Finding | null {
+ if (findings.length === 0) return null;
+ return findings.slice().sort((a, b) => {
+ if (a.dollar_impact_usd !== b.dollar_impact_usd) {
+ return b.dollar_impact_usd - a.dollar_impact_usd;
+ }
+ return (
+ CATEGORY_PRIORITY.indexOf(a.category) -
+ CATEGORY_PRIORITY.indexOf(b.category)
+ );
+ })[0]!;
+}
+
+const TRANSFORMERS: Record<FindingCategory, (rows: GaqlRow[]) => Finding[]> = {
+ WASTED_SPEND: (rows) => {
+ if (rows.length === 0) return [];
+ // Group by campaign — one finding per campaign with multiple wasted kws.
+ const byCampaign = new Map<string, GaqlRow[]>();
+ for (const r of rows) {
+ const cn = getString(r, "campaign.name") ?? "(unknown)";
+ const arr = byCampaign.get(cn) ?? [];
+ arr.push(r);
+ byCampaign.set(cn, arr);
+ }
+ // Pick the campaign with the biggest wasted spend total — one finding.
+ let top: { campaign: string; rows: GaqlRow[]; spend: number } | null = null;
+ for (const [campaign, group] of byCampaign) {
+ const spend = group.reduce(
+ (acc, r) => acc + microsAsDollars(getMetric(r, "metrics.cost_micros")),
+ 0,
+ );
+ if (!top || spend > top.spend) top = { campaign, rows: group, spend };
+ }
+ if (!top) return [];
+ const dailyBurn = top.spend / 30;
+ const monthlyBurn = top.spend;
+ const clicks = top.rows.reduce(
+ (acc, r) => acc + (getMetric(r, "metrics.clicks") ?? 0),
+ 0,
+ );
+ return [
+ {
+ id: `wasted_spend:${slugifyForId(top.campaign)}`,
+ category: "WASTED_SPEND",
+ headline: `${top.campaign} is burning $${dailyBurn.toFixed(0)}/day on ${top.rows.length} zero-conv keyword${top.rows.length === 1 ? "" : "s"}`,
+ evidence: `Last 30 days · ${clicks.toLocaleString()} clicks · $${top.spend.toFixed(0)} spent · 0 conv`,
+ suggested_action: `Pause those ${top.rows.length} keywords; expected savings $${monthlyBurn.toFixed(0)}/mo`,
+ dollar_impact_usd: monthlyBurn,
+ },
+ ];
+ },
+ LOW_QS: (rows) => {
+ if (rows.length === 0) return [];
+ const count = rows.length;
+ const impressions = rows.reduce(
+ (acc, r) => acc + (getMetric(r, "metrics.impressions") ?? 0),
+ 0,
+ );
+ const monthlySpend = rows.reduce(
+ (acc, r) => acc + microsAsDollars(getMetric(r, "metrics.cost_micros")),
+ 0,
+ );
+ // Low QS roughly costs 20% extra in CPC — back-of-envelope impact.
+ const impact = monthlySpend * 0.2;
+ return [
+ {
+ id: "low_qs",
+ category: "LOW_QS",
+ headline: `${count} keyword${count === 1 ? "" : "s"} below Quality Score 5 — check ad relevance`,
+ evidence: `${impressions.toLocaleString()} impressions, ~$${monthlySpend.toFixed(0)}/mo spend with QS penalty`,
+ suggested_action: `Tighten ad copy + landing page match; ~$${impact.toFixed(0)}/mo recoverable`,
+ dollar_impact_usd: impact,
+ },
+ ];
+ },
+ SEARCH_TERM_GAP: (rows) => {
+ if (rows.length === 0) return [];
+ const count = rows.length;
+ const conversions = rows.reduce(
+ (acc, r) => acc + (getMetric(r, "metrics.conversions") ?? 0),
+ 0,
+ );
+ const spend = rows.reduce(
+ (acc, r) => acc + microsAsDollars(getMetric(r, "metrics.cost_micros")),
+ 0,
+ );
+ // Adding converting terms as keywords typically improves CPA 10-25%.
+ const impact = spend * 0.15;
+ return [
+ {
+ id: "search_term_gap",
+ category: "SEARCH_TERM_GAP",
+ headline: `${count} converting search term${count === 1 ? "" : "s"} not in your keyword list`,
+ evidence: `${conversions.toFixed(0)} conversions from $${spend.toFixed(0)} spend in 30d on unmatched terms`,
+ suggested_action: `Add as exact-match keywords; ~$${impact.toFixed(0)}/mo CPA upside`,
+ dollar_impact_usd: impact,
+ },
+ ];
+ },
+ BUDGET_PACING: (rows) => {
+ if (rows.length === 0) return [];
+ // Filter for campaigns that hit ≥95% of yesterday's budget.
+ const capped = rows.filter((r) => {
+ const spend = microsAsDollars(getMetric(r, "metrics.cost_micros"));
+ const budget = microsAsDollars(getMetric(r, "campaign_budget.amount_micros"));
+ return budget > 0 && spend >= budget * 0.95;
+ });
+ if (capped.length === 0) return [];
+ const monthlyImpact = capped.reduce((acc, r) => {
+ const budget = microsAsDollars(getMetric(r, "campaign_budget.amount_micros"));
+ // Budget-capped campaigns typically lose ~30% of available impressions.
+ return acc + budget * 30 * 0.3;
+ }, 0);
+ return [
+ {
+ id: "budget_pacing",
+ category: "BUDGET_PACING",
+ headline: `${capped.length} campaign${capped.length === 1 ? "" : "s"} hit daily cap yesterday`,
+ evidence: `Budget-capped at ≥95% by end of day — missed impressions`,
+ suggested_action: `Raise daily cap or shift budget across campaigns; ~$${monthlyImpact.toFixed(0)}/mo recoverable reach`,
+ dollar_impact_usd: monthlyImpact,
+ },
+ ];
+ },
+};
+
+function buildSummaryLine(
+ findings: Finding[],
+ state: AccountState,
+ topFix: Finding | null,
+): string {
+ if (state === "empty") return "Audit complete — account is empty or just getting started.";
+ if (topFix) {
+ return `Audit complete — ${findings.length} finding${findings.length === 1 ? "" : "s"}. Top: ${topFix.headline}`;
+ }
+ return `Audit complete — ${findings.length} findings.`;
+}
+
+function buildReasoningLine(summary: AuditSummary): string {
+ const parts = [
+ `${summary.count} actionable findings`,
+ `account_state=${summary.account_state}`,
+ ];
+ if (summary.category_errors.length > 0) {
+ parts.push(
+ `${summary.category_errors.length} category error${summary.category_errors.length === 1 ? "" : "s"}`,
+ );
+ }
+ return parts.join("; ");
+}
+
+/**
+ * Drop FIRST_TURN.md in the CMO's workspace per D19. Best-effort: never throw.
+ * The contract is the markdown shape in the CEO plan's D19 section.
+ */
+async function safeWriteFirstTurn(
+ project_slug: string,
+ findings: Finding[],
+ topFix: Finding | null,
+ accountState: AccountState,
+): Promise<void> {
+ try {
+ const dataDir = process.env.NOTFAIR_CMO_DATA_DIR ?? join(homedir(), ".notfair-cmo");
+ const cmoWorkspace = join(dataDir, "agents", `${project_slug}-cmo`);
+ await mkdir(cmoWorkspace, { recursive: true });
+ const body = renderFirstTurn(project_slug, findings, topFix, accountState);
+ await writeFile(join(cmoWorkspace, "FIRST_TURN.md"), body, "utf8");
+ } catch (err) {
+ console.warn(`FIRST_TURN.md write failed for ${project_slug}:`, err);
+ }
+}
+
+function renderFirstTurn(
+ project_slug: string,
+ findings: Finding[],
+ topFix: Finding | null,
+ accountState: AccountState,
+): string {
+ const ts = new Date().toISOString();
+ const lines: string[] = [
+ "# First-turn context for the CMO",
+ "",
+ "You have just connected the user's Google Ads account and run a baseline audit.",
+ "This is a one-shot context: on your FIRST chat turn after the user opens this",
+ "project's CMO chat, weave the highlights into your greeting, then move this",
+ "file to MEMORY/last-first-turn-<YYYY-MM-DD>.md so you don't repeat it.",
+ "",
+ "## Audit metadata",
+ `- Project: ${project_slug}`,
+ `- Audit run at: ${ts}`,
+ `- Account state: ${accountState}`,
+ `- Findings count: ${findings.length}`,
+ "",
+ ];
+
+ if (accountState === "empty") {
+ lines.push(
+ "## Top suggestion (new account — empty audit)",
+ `- Set a daily budget for your first campaign — most B2B starts at $50-100/day to gather signal.`,
+ "",
+ "## Other roadmap items",
+ `- Decide your first goal: leads vs traffic vs brand. I can help you pick.`,
+ `- Talk it through with me — 30 minutes and you'll have a campaign brief.`,
+ "",
+ "## Suggested opener",
+ "Greet the user by acknowledging they're just getting started with Google Ads.",
+ "Reference the budget recommendation by name. End with an open question that",
+ "invites them to talk through their first campaign. Keep it under 3 sentences.",
+ );
+ } else if (topFix) {
+ const others = findings.filter((f) => f.id !== topFix.id);
+ lines.push(
+ "## Top finding",
+ `- Category: ${topFix.category}`,
+ `- Headline: ${topFix.headline}`,
+ `- Evidence: ${topFix.evidence}`,
+ `- Suggested action: ${topFix.suggested_action}`,
+ "",
+ );
+ if (others.length > 0) {
+ lines.push("## Other findings");
+ for (const f of others) {
+ lines.push(`- ${f.category} — ${f.headline}`);
+ }
+ lines.push("");
+ }
+ lines.push(
+ "## Suggested opener",
+ "Greet the user by referencing the top finding by name with the dollar figure.",
+ "Make it personal and specific. End with an open question that invites them to",
+ "either fix the top finding now or talk through the broader audit. Keep it under",
+ "3 sentences.",
+ );
+ } else {
+ lines.push(
+ "## Top finding",
+ "(none — audit completed but no actionable findings classified)",
+ "",
+ "## Suggested opener",
+ "Acknowledge that the audit ran cleanly and the account looks healthy from a",
+ "30-day spend perspective. Ask the user what they'd like to optimize next.",
+ );
+ }
+ lines.push("");
+ return lines.join("\n");
+}
+
+/**
+ * Write a tagged memory entry on the CMO agent so later sessions can recall
+ * the audit via REM. Best-effort: subprocess failure does not block the
+ * audit's completion event. Logged for debugging.
+ */
+async function safeWriteMemoryTag(
+ project_slug: string,
+ summary: AuditSummary,
+): Promise<void> {
+ try {
+ const date = new Date().toISOString().slice(0, 10);
+ const tag = `google-ads-baseline:${date}`;
+ const content = `Google Ads baseline audit for ${project_slug} on ${date}: ${summary.count} findings, account_state=${summary.account_state}.`;
+ await openclaw(
+ [
+ "memory",
+ "write",
+ "--agent",
+ `${project_slug}-cmo`,
+ "--tag",
+ tag,
+ "--content",
+ content,
+ ],
+ { json: false },
+ );
+ } catch (err) {
+ console.warn(`OpenClaw memory write failed for ${project_slug}:`, err);
+ }
+}
+
+// ── tiny accessors ──────────────────────────────────────────────────
+
+function getMetric(row: GaqlRow, dotted: string): number | undefined {
+ const v = getNested(row, dotted);
+ if (typeof v === "number") return v;
+ if (typeof v === "string") {
+ const n = Number(v);
+ return Number.isFinite(n) ? n : undefined;
+ }
+ return undefined;
+}
+
+function getString(row: GaqlRow, dotted: string): string | undefined {
+ const v = getNested(row, dotted);
+ return typeof v === "string" ? v : undefined;
+}
+
+function getNested(row: GaqlRow, dotted: string): unknown {
+ const parts = dotted.split(".");
+ let cur: unknown = row;
+ for (const p of parts) {
+ if (!cur || typeof cur !== "object") return undefined;
+ cur = (cur as Record<string, unknown>)[p];
+ }
+ return cur;
+}
+
+function microsAsDollars(micros: number | undefined): number {
+ if (typeof micros !== "number" || !Number.isFinite(micros)) return 0;
+ return micros / 1_000_000;
+}
+
+function slugifyForId(s: string): string {
+ return s
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, "-")
+ .replace(/^-|-$/g, "")
+ .slice(0, 40);
+}