Open-source SEO, GEO, and marketing skills for AI agents.
feat(notfair-cmo): multi-platform onboarding audit, minted for any ads connect
Yuting Zhong1935e555204c
diff --git a/notfair-cmo/src/server/onboarding/accounts.test.ts b/notfair-cmo/src/server/onboarding/accounts.test.tsindex b620556a..f00ffbd8 100644--- a/notfair-cmo/src/server/onboarding/accounts.test.ts+++ b/notfair-cmo/src/server/onboarding/accounts.test.ts@@ -31,6 +31,18 @@ vi.mock("next/cache", () => ({revalidatePath: vi.fn(),}));+// getOnboardingTaskForSkipAction awaits provisioning + reads the token+// table to decide whether to mint the audit task.+vi.mock("./provisioning-state", () => ({+ awaitProvisioning: async () => ({ kind: "done" }),+}));+const listTokensMock = vi.fn<(slug: string) => Array<{ server_name: string }>>(+ () => [],+);+vi.mock("@/server/mcp/tokens", () => ({+ listProjectMcpTokens: (slug: string) => listTokensMock(slug),+}));+// Dynamic imports inside setOnboardingAccountAction need mocks too — it// auto-creates the CMO's onboarding task as the final step of the action.const createTaskMock = vi.fn();@@ -88,6 +100,7 @@ vi.mock("@/server/agent-meta", () => ({}));import {+ getOnboardingTaskForSkipAction,listGoogleAdsAccounts,setOnboardingAccountAction,listMetaAdsAccounts,@@ -498,3 +511,70 @@ describe("setOnboardingGscPropertyAction", () => {afterEach(() => {vi.clearAllMocks();});++describe("getOnboardingTaskForSkipAction", () => {+ const ONBOARDING_TASK = {+ id: "onboarding-uuid",+ display_id: "acme-0",+ project_slug: "acme",+ agent_id: "acme-cmo-greg",+ title: "Learn the project and write PROJECT.md",+ status: "done",+ };++ beforeEach(() => {+ getProjectMock.mockReturnValue({+ id: "p1",+ slug: "acme",+ display_name: "Acme",+ archived_at: null,+ google_ads_account_id: null,+ website_url: null,+ codebase_path: null,+ harness_adapter: "codex-local",+ });+ listTasksMock.mockReturnValue([ONBOARDING_TASK]);+ listTokensMock.mockReturnValue([]);+ createTaskMock.mockClear();+ });++ it("mints the audit for an X-Ads-only connect (no account picker on that path)", async () => {+ listTokensMock.mockReturnValue([{ server_name: "notfair-xads" }]);+ const r = await getOnboardingTaskForSkipAction("acme");+ expect(r.ok).toBe(true);+ expect(createTaskMock).toHaveBeenCalledWith(+ expect.objectContaining({+ agent_id: "acme-cmo-greg",+ title: expect.stringContaining("Audit the connected ad platforms"),+ }),+ );+ // Onboarding task is terminal → the freshly minted audit is surfaced.+ if (r.ok) expect(r.task_display_id).toBe("acme-1");+ });++ it("creates no audit on a true skip (nothing connected)", async () => {+ const r = await getOnboardingTaskForSkipAction("acme");+ expect(r.ok).toBe(true);+ expect(createTaskMock).not.toHaveBeenCalled();+ if (r.ok) expect(r.task_display_id).toBe("acme-0");+ });++ it("does not double-create when an audit already exists", async () => {+ listTokensMock.mockReturnValue([{ server_name: "notfair-googleads" }]);+ listTasksMock.mockReturnValue([+ ONBOARDING_TASK,+ {+ id: "audit-uuid",+ display_id: "acme-9",+ project_slug: "acme",+ agent_id: "acme-cmo-greg",+ title: "Audit the connected ad platforms and propose a starter playbook",+ status: "proposed",+ },+ ]);+ const r = await getOnboardingTaskForSkipAction("acme");+ expect(r.ok).toBe(true);+ expect(createTaskMock).not.toHaveBeenCalled();+ if (r.ok) expect(r.task_display_id).toBe("acme-9");+ });+});diff --git a/notfair-cmo/src/server/onboarding/accounts.ts b/notfair-cmo/src/server/onboarding/accounts.tsindex b335d9fd..6252cc14 100644--- a/notfair-cmo/src/server/onboarding/accounts.ts+++ b/notfair-cmo/src/server/onboarding/accounts.ts@@ -188,8 +188,7 @@ export async function setOnboardingAccountAction(//// Avoid duplicates if the user navigates back and resubmits — reuse// the existing one when a CMO audit task is already present.- const { buildOnboardingBrief } = await import("./cmo-task-brief");- const { listTasks, createTask } = await import("@/server/db/tasks");+ const { listTasks } = await import("@/server/db/tasks");const { listProjectAgents } = await import("@/server/agent-meta");// Resolve the CMO agent by template_key — agent_ids now encode the// personal name, so we can't synthesize one from project_slug alone.@@ -199,40 +198,18 @@ export async function setOnboardingAccountAction(return { ok: false, error: "CMO agent has not been provisioned yet." };}const cmoAgentId = cmo.agent_id;- const allTasks = listTasks(project_slug);- const existingAudit = allTasks.find(- (t) => t.agent_id === cmoAgentId && t.title?.startsWith("Audit the account"),- );- // Find the project-onboarding task. Created synchronously by- // createProjectForOnboardingAction; should always exist by the time- // the user gets here.- const onboardingTask = allTasks.find(+ const audit = await ensureAuditTask({+ project_slug,+ project_display_name: updated.display_name,+ google_ads_account_id: match.id,+ cmoAgentId,+ });+ const onboardingTask = listTasks(project_slug).find((t) =>t.agent_id === cmoAgentId &&t.title === "Learn the project and write PROJECT.md",);- let audit = existingAudit;- if (!audit) {- // When the onboarding task is missing or already terminal, createTask- // drops the blocker automatically — the audit runs immediately.- const { title, brief, success_criteria } = buildOnboardingBrief({- project_slug,- project_display_name: updated.display_name,- google_ads_account_id: match.id,- });- audit = createTask({- project_slug,- agent_id: cmoAgentId,- title,- brief,- success_criteria,- assigner_agent_id: null,- status: "proposed",- blocked_by_task_id: onboardingTask?.id ?? null,- });- }-// Pick the task to surface in the redirect:// - Prefer the onboarding task while it's still non-terminal — that's// what's actually executing; the audit sits blocked behind it.@@ -242,7 +219,10 @@ export async function setOnboardingAccountAction(const surfaceTask =onboardingTask && !TERMINAL.has(onboardingTask.status)? onboardingTask- : audit;+ : (audit ?? onboardingTask);+ if (!surfaceTask) {+ return { ok: false, error: "Onboarding task not found." };+ }revalidatePath("/", "layout");return {@@ -253,6 +233,63 @@ export async function setOnboardingAccountAction(};}+/** Ads platforms whose connection makes the CMO audit meaningful. */+const ADS_PLATFORM_KEYS = [+ "notfair-googleads",+ "notfair-metaads",+ "notfair-xads",+] as const;++/**+ * Mint the CMO's multi-platform audit task — shared by the Google Ads+ * account-pick path and the setup step (which covers X-Ads-only /+ * Meta-Ads-only connects that never pass through an account picker;+ * without the setup-step hook those projects got NO audit at all and+ * their specialists sat idle forever).+ *+ * Callers are responsible for only invoking this when at least one ads+ * platform is connected (the account-pick path just validated Google+ * Ads; the setup path checks the token table). Dedupes by title prefix+ * so back-navigation / both paths firing can't create two audits. Gated+ * on the PROJECT.md onboarding task while that's in flight; createTask+ * drops the blocker automatically when it's already terminal.+ */+async function ensureAuditTask(input: {+ project_slug: string;+ project_display_name: string;+ google_ads_account_id: string | null;+ cmoAgentId: string;+}): Promise<import("@/types").Task | null> {+ const { listTasks, createTask } = await import("@/server/db/tasks");+ const allTasks = listTasks(input.project_slug);+ const existing = allTasks.find(+ (t) => t.agent_id === input.cmoAgentId && t.title?.startsWith("Audit the"),+ );+ if (existing) return existing;++ const onboardingTask = allTasks.find(+ (t) =>+ t.agent_id === input.cmoAgentId &&+ t.title === "Learn the project and write PROJECT.md",+ );+ const { buildOnboardingBrief } = await import("./cmo-task-brief");+ const { title, brief, success_criteria } = buildOnboardingBrief({+ project_slug: input.project_slug,+ project_display_name: input.project_display_name,+ google_ads_account_id: input.google_ads_account_id,+ });+ return createTask({+ project_slug: input.project_slug,+ agent_id: input.cmoAgentId,+ title,+ brief,+ success_criteria,+ assigner_agent_id: null,+ status: "proposed",+ blocked_by_task_id: onboardingTask?.id ?? null,+ });+}+export type ProvisioningProgressResult =| { ok: true; steps: { key: string; label: string; status: string; error?: string }[]; overall: "running" | "done" | "failed" }| { ok: false; error: string };@@ -344,12 +381,14 @@ export type SkipAccountResult =| { ok: false; error: string };/**- * Skip-Google-Ads variant of the onboarding finish. Resolves the CMO agent- * and its already-created "Learn the project and write PROJECT.md" task so- * the client can land the user on the same task workspace the connect path- * lands on. No account is persisted, no audit task is minted — the audit- * task is only meaningful once Google Ads is wired up, and the user can- * always reach the connect screen later from /connections.+ * Resolve where the setup step lands the user (both the connect and the+ * skip paths route through here). Resolves the CMO agent + its+ * "Learn the project and write PROJECT.md" task, and — when at least one+ * ads platform is connected — ensures the multi-platform audit task+ * exists. This is what covers X-Ads-only / Meta-Ads-only connects: they+ * never pass through the Google Ads account picker, which used to be the+ * only place the audit was minted. With nothing connected (true skip) no+ * audit is created — the user can connect later from /connections.** Blocks until provisioning has fully resolved — `ensureProjectAgents`* itself waits for the gateway's runtime config to surface the new agent@@ -395,12 +434,34 @@ export async function getOnboardingTaskForSkipAction(t.agent_id === cmo.agent_id &&t.title === "Learn the project and write PROJECT.md",);- if (!onboardingTask) {+ // Only mint the audit when an ads platform is actually connected — a+ // true skip (nothing connected) lands on the PROJECT.md task alone.+ const { listProjectMcpTokens } = await import("@/server/mcp/tokens");+ const connected = new Set(+ listProjectMcpTokens(project_slug).map((t) => t.server_name),+ );+ const audit = ADS_PLATFORM_KEYS.some((k) => connected.has(k))+ ? await ensureAuditTask({+ project_slug,+ project_display_name: project.display_name,+ google_ads_account_id: project.google_ads_account_id,+ cmoAgentId: cmo.agent_id,+ })+ : null;+ // Land on whatever is actually executing: the onboarding task while+ // it's in flight, else the audit (which auto-kicks off on page open),+ // else the onboarding task as the terminal-state fallback.+ const TERMINAL = new Set(["done", "failed", "cancelled"]);+ const surfaceTask =+ onboardingTask && !TERMINAL.has(onboardingTask.status)+ ? onboardingTask+ : (audit ?? onboardingTask);+ if (!surfaceTask) {return { ok: false, error: "Onboarding task not found." };}return {ok: true,- task_display_id: onboardingTask.display_id,+ task_display_id: surfaceTask.display_id,cmo_agent_slug: cmo.slug,};}diff --git a/notfair-cmo/src/server/onboarding/cmo-task-brief.ts b/notfair-cmo/src/server/onboarding/cmo-task-brief.tsindex 6a98558c..42d69859 100644--- a/notfair-cmo/src/server/onboarding/cmo-task-brief.ts+++ b/notfair-cmo/src/server/onboarding/cmo-task-brief.ts@@ -57,6 +57,12 @@ export function buildProjectOnboardingBrief(args: {"understand it in 90 seconds of reading. Quote specifics from the","site/codebase rather than handwaving.","",+ "Do NOT write anything about which ad platforms / accounts are",+ "connected — this task runs while the user is still connecting them,",+ "so any claim you make goes stale immediately. The platform injects",+ "live connection facts into every task assignment; PROJECT.md is for",+ "the business, not the plumbing.",+ "","## 3. Close the task","","After `set_project_brief` returns ok, call `submit_task_status` with",@@ -75,10 +81,12 @@ export function buildProjectOnboardingBrief(args: {/*** Build the brief for the CMO's first task — the audit that used to be its* own special-purpose code path in src/server/onboarding/audit.ts. Now the- * audit IS a task: the CMO does the GAQL probes itself via the Google Ads- * MCP, writes findings inline, and delegates ongoing work via the- * notfair-orchestration MCP tools (the same surface the CMO uses for every- * other planning turn — see agent-templates.ts for the full teaching).+ * audit IS a task, and it covers EVERY connected ads platform (Google,+ * Meta, X) — the kickoff message's platform-connections facts block tells+ * the CMO which ones are live. The CMO runs the probes itself via each+ * platform's MCP, writes findings inline, and delegates ongoing work via+ * the notfair-orchestration MCP tools (the same surface the CMO uses for+ * every other planning turn — see agent-templates.ts for the full teaching).** Keeping this server-side so the wording stays in lockstep with the CMO* system prompt; templated rather than free-form so each new project@@ -91,20 +99,22 @@ export function buildOnboardingBrief(args: {}): { title: string; brief: string; success_criteria: string } {const account = args.google_ads_account_id ?? "(none picked — ask the user)";- const title = "Audit the account and propose a starter playbook";+ const title = "Audit the connected ad platforms and propose a starter playbook";const brief = [`Project: ${args.project_display_name} (${args.project_slug})`,`Google Ads account: ${account}`,"",- "This is your first turn as CMO for this project. Audit the connected",- "Google Ads account, present findings, then delegate ongoing work to",- "the google-ads specialist.",+ "This is your first turn as CMO for this project. Audit EVERY",+ "connected ads platform — the \"Platform connections\" list in this",+ "assignment is ground truth: audit each ads platform it shows as",+ "connected, skip the rest. Present findings per platform, then",+ "delegate ongoing work to each platform's specialist.","",- "## 1. Probe the account",+ "## 1. Probe each connected platform","",- "Use the notfair-googleads MCP `runScript` tool to gather (GAQL via",- "`ads.gaql`, fan out with `ads.gaqlParallel`):",+ "**Google Ads** — use the notfair-googleads MCP `runScript` tool",+ "(GAQL via `ads.gaql`, fan out with `ads.gaqlParallel`):","- Customer info: status, currency, time zone","- Last 30 days per enabled campaign: cost, impressions, clicks,"," conversions, conversion_value",@@ -113,40 +123,60 @@ export function buildOnboardingBrief(args: {"- Keywords with quality_score < 5","- Campaigns within $5 of their daily budget cap","",- "## 2. Classify the archetype",+ "**Meta Ads** — use the notfair-metaads MCP `runScript` tool",+ "(`ads.graphParallel`): campaign / ad set / ad listings with 30-day",+ "insights (spend, ROAS, CPM, CTR, frequency); flag learning-limited",+ "ad sets, creative fatigue (rising frequency + falling CTR), and",+ "audience overlap.",+ "",+ "**X Ads** — use the notfair-xads MCP tools: campaigns + line items",+ "with 30-day spend / impressions / engagement, promoted posts, and",+ "funding instruments; flag zero-spend or fully-paused accounts.","",- "One of:",- "- empty — no enabled campaigns",- "- no_tracking — campaigns but zero conversion_actions",- "- low_volume — < 50 clicks / month or < $200 spend",+ "## 2. Classify each platform's archetype",+ "",+ "One per audited platform:",+ "- empty — no enabled/serving campaigns",+ "- no_tracking — campaigns but no conversion tracking",+ "- low_volume — too little traffic/spend to optimize (< ~50 clicks or",+ " < ~$200 / month)","- active — meaningful data to optimize on","","## 3. Report findings to the user (in this reply)","",- "Markdown, scannable. Sections (skip any with no findings, don't pad):",- "- **Account snapshot** — 1-2 sentences naming the archetype + spend",- "- **Wasted spend** — top 3 search-term gaps with $ amounts",- "- **Low quality scores** — top 3 keywords + their QS",+ "Markdown, scannable, one section per audited platform (skip findings",+ "that don't exist, don't pad):",+ "- **Snapshot** — 1-2 sentences naming the archetype + spend",+ "- **Wasted spend** — top gaps with $ amounts (search terms on Google;",+ " fatigued creatives / overlapping audiences on Meta; dead line items on X)",+ "- **Quality issues** — low QS keywords, learning-limited ad sets, etc.","- **Budget pacing** — campaigns hitting cap",- "- **Next steps** — 3 concrete actions tailored to the archetype",+ "- **Next steps** — up to 3 concrete actions per platform, tailored to",+ " its archetype","","Lead with the dollar figure or the most actionable finding. Don't ask",'"want me to..." — you\'re an orchestrator; delegate, don\'t advise.',"","## 4. Delegate the ongoing work","",- "For each Next Step that's actionable + repeatable, delegate it to the",- "google_ads specialist. Include the cadence in the brief itself (\"daily",- "9am Pacific anomaly check on enabled campaigns\", \"weekly Monday",- "search-term review\", etc.) — the specialist will schedule its own cron.",- "",- "Tight one-line tail after delegating: \"Handed these to your Google Ads",- 'specialist — open the agent\'s Tasks tab to follow along."',+ "For each Next Step that's actionable + repeatable, delegate it to",+ "THAT platform's specialist (google_ads / meta_ads / x_ads — use",+ "`list_project_agents` to get exact agent ids). Include the cadence in",+ "the brief itself (\"daily 9am Pacific anomaly check on enabled",+ "campaigns\", \"weekly Monday search-term review\", etc.) — the",+ "specialist will schedule its own cron.",+ "",+ "ONLY IF you actually delegated tasks, close with a one-line tail",+ "naming which specialists got work (\"Handed these to your Google Ads",+ 'and X Ads specialists — open their Tasks tabs to follow along.").',+ "When you skipped delegation for a platform (e.g. empty account), say",+ "what would unlock it instead — don't claim a handoff that didn't happen.",].join("\n");const success_criteria = [- "Findings reported as inline markdown; ongoing work delegated to",- "google_ads (skip delegation when archetype = empty); this audit task",+ "Findings reported per connected ads platform as inline markdown;",+ "ongoing work delegated to each platform's specialist (skip a",+ "platform's delegation when its archetype = empty); this audit task","marked done.",].join(" ");