Open-source SEO, GEO, and marketing skills for AI agents.
feat(notfair-cmo): ground every task kickoff in live platform facts
Yuting Zhong82696831fcfd
diff --git a/notfair-cmo/src/app/(app)/[project]/agents/[agent]/tasks/page.tsx b/notfair-cmo/src/app/(app)/[project]/agents/[agent]/tasks/page.tsxindex 4f136851..b98e3831 100644--- a/notfair-cmo/src/app/(app)/[project]/agents/[agent]/tasks/page.tsx+++ b/notfair-cmo/src/app/(app)/[project]/agents/[agent]/tasks/page.tsx@@ -17,6 +17,7 @@ import {import {buildTaskKickoffMessage,generateTaskThreadId,+ getProjectPlatformFacts,} from "@/server/orchestration/task-kickoff";import type { Approval, Question, Task } from "@/types";@@ -145,7 +146,13 @@ async function loadSelectedBundle(// — so reloads / concurrent tabs can't double-fire the agent.const kickoff =task.status === "proposed"- ? { taskId: task.id, message: buildTaskKickoffMessage(task) }+ ? {+ taskId: task.id,+ message: buildTaskKickoffMessage(+ task,+ getProjectPlatformFacts(projectSlug),+ ),+ }: null;return {diff --git a/notfair-cmo/src/server/orchestration/run-task.ts b/notfair-cmo/src/server/orchestration/run-task.tsindex 6daecb94..43fdb995 100644--- a/notfair-cmo/src/server/orchestration/run-task.ts+++ b/notfair-cmo/src/server/orchestration/run-task.ts@@ -11,6 +11,7 @@ import type { Task } from "@/types";import {buildTaskKickoffMessage,+ getProjectPlatformFacts,generateTaskThreadId,} from "./task-kickoff";@@ -62,7 +63,10 @@ export async function runTaskKickoffServerSide(task: Task): Promise<void> {task_id: finalTask.id,});- const kickoffMessage = buildTaskKickoffMessage(finalTask);+ const kickoffMessage = buildTaskKickoffMessage(+ finalTask,+ getProjectPlatformFacts(finalTask.project_slug),+ );appendTranscriptEvent(session.id, "user", { text: kickoffMessage, source: "kickoff" });console.log(diff --git a/notfair-cmo/src/server/orchestration/task-kickoff.test.ts b/notfair-cmo/src/server/orchestration/task-kickoff.test.tsindex a7ac900b..48cb5e3e 100644--- a/notfair-cmo/src/server/orchestration/task-kickoff.test.ts+++ b/notfair-cmo/src/server/orchestration/task-kickoff.test.ts@@ -2,7 +2,11 @@ import { describe, expect, it } from "vitest";import type { Task } from "@/types";-import { buildTaskKickoffMessage } from "./task-kickoff";+import {+ buildTaskKickoffMessage,+ formatPlatformFacts,+ type ProjectPlatformFacts,+} from "./task-kickoff";function makeTask(overrides: Partial<Task> = {}): Task {return {@@ -90,3 +94,43 @@ describe("buildTaskKickoffMessage", () => {expect(msg).toContain(brief);});});++describe("platform facts block", () => {+ const facts: ProjectPlatformFacts = {+ website_url: "https://example.com",+ codebase_path: null,+ connected: [+ { label: "Google Ads", detail: "account 7384288909" },+ { label: "X Ads", detail: null },+ ],+ notConnected: ["Meta Ads", "Google Search Console", "Google Analytics"],+ };++ it("renders connected platforms with details and NOT-connected ones explicitly", () => {+ const lines = formatPlatformFacts(facts).join("\n");+ expect(lines).toContain("ground truth from the platform database");+ expect(lines).toContain("- Google Ads: connected — account 7384288909");+ expect(lines).toContain("- X Ads: connected");+ expect(lines).toContain("- Meta Ads: NOT connected");+ expect(lines).toContain("- Website: https://example.com");+ expect(lines).not.toContain("Local codebase");+ });++ it("kickoff message embeds the facts block between brief and success criteria", () => {+ const msg = buildTaskKickoffMessage(makeTask(), facts);+ expect(msg).toContain("- Google Ads: connected — account 7384288909");+ expect(msg.indexOf("Brief:")).toBeLessThan(msg.indexOf("Google Ads: connected"));+ expect(msg.indexOf("Google Ads: connected")).toBeLessThan(+ msg.indexOf("Success criteria:"),+ );+ });++ it("kickoff message omits the block when facts are null/undefined", () => {+ expect(buildTaskKickoffMessage(makeTask(), null)).not.toContain(+ "Platform connections",+ );+ expect(buildTaskKickoffMessage(makeTask())).not.toContain(+ "Platform connections",+ );+ });+});diff --git a/notfair-cmo/src/server/orchestration/task-kickoff.ts b/notfair-cmo/src/server/orchestration/task-kickoff.tsindex 74935165..321ec256 100644--- a/notfair-cmo/src/server/orchestration/task-kickoff.ts+++ b/notfair-cmo/src/server/orchestration/task-kickoff.ts@@ -1,5 +1,7 @@import { randomUUID } from "node:crypto";+import { getProject } from "@/server/db/projects";+import { listProjectMcpTokens } from "@/server/mcp/tokens";import type { Task } from "@/types";/**@@ -13,17 +15,134 @@ export function generateTaskThreadId(): string {return randomUUID();}+/**+ * Deterministic snapshot of what's ACTUALLY connected for a project,+ * read from the platform DB at kickoff time. Injected into the kickoff+ * message so the agent never has to derive it — a real onboarding run+ * had the CMO write "no ad account attached" into PROJECT.md even+ * though get_project returned the picked account id.+ */+export interface ProjectPlatformFacts {+ website_url: string | null;+ codebase_path: string | null;+ /** Connected platforms, with the selected account/property when picked. */+ connected: Array<{ label: string; detail: string | null }>;+ /** Recommended platforms with no token — the agent must not assume them. */+ notConnected: string[];+}++const RECOMMENDED_PLATFORMS: Array<{+ key: string;+ label: string;+ detail?: (p: {+ google_ads_account_id: string | null;+ meta_ads_account_id: string | null;+ gsc_property_id: string | null;+ }) => string | null;+}> = [+ {+ key: "notfair-googleads",+ label: "Google Ads",+ detail: (p) =>+ p.google_ads_account_id+ ? `account ${p.google_ads_account_id}`+ : "no account picked yet",+ },+ {+ key: "notfair-metaads",+ label: "Meta Ads",+ detail: (p) =>+ p.meta_ads_account_id+ ? `ad account ${p.meta_ads_account_id}`+ : "no ad account picked yet",+ },+ {+ key: "notfair-googlesearchconsole",+ label: "Google Search Console",+ detail: (p) =>+ p.gsc_property_id ? `property ${p.gsc_property_id}` : "no property picked yet",+ },+ { key: "notfair-googleanalytics", label: "Google Analytics" },+ { key: "notfair-xads", label: "X Ads" },+];++/** Never throws — a facts block is an enhancement, not a gate. */+export function getProjectPlatformFacts(+ project_slug: string,+): ProjectPlatformFacts | null {+ try {+ const project = getProject(project_slug);+ if (!project) return null;+ const tokens = new Set(+ listProjectMcpTokens(project_slug).map((t) => t.server_name),+ );++ const connected: Array<{ label: string; detail: string | null }> = [];+ const notConnected: string[] = [];+ for (const platform of RECOMMENDED_PLATFORMS) {+ if (tokens.has(platform.key)) {+ connected.push({+ label: platform.label,+ detail: platform.detail?.(project) ?? null,+ });+ tokens.delete(platform.key);+ } else {+ notConnected.push(platform.label);+ }+ }+ // Extras connected via "More tools" (stripe, posthog, custom URLs…).+ for (const key of tokens) {+ connected.push({ label: key, detail: null });+ }++ return {+ website_url: project.website_url,+ codebase_path: project.codebase_path,+ connected,+ notConnected,+ };+ } catch {+ return null;+ }+}++/** Pure formatter — separated so tests don't need a DB. */+export function formatPlatformFacts(facts: ProjectPlatformFacts): string[] {+ const lines: string[] = [+ "Platform connections (ground truth from the platform database — trust",+ "this over inference). Point-in-time for THIS task only: more platforms",+ "may connect later, so never copy this list into PROJECT.md or other",+ "durable docs:",+ ];+ for (const c of facts.connected) {+ lines.push(`- ${c.label}: connected${c.detail ? ` — ${c.detail}` : ""}`);+ }+ for (const label of facts.notConnected) {+ lines.push(`- ${label}: NOT connected`);+ }+ if (facts.website_url) lines.push(`- Website: ${facts.website_url}`);+ if (facts.codebase_path) lines.push(`- Local codebase: ${facts.codebase_path}`);+ return lines;+}+/*** Build the hidden kickoff message the assignee receives on first open of* a task's per-task chat thread. Carries the brief + operating* instructions — the agent has everything it needs to acknowledge and* start working without the user typing anything.*+ * `facts` (from getProjectPlatformFacts, fetched by the caller at kickoff+ * time) grounds the turn in what's actually connected. Passed in rather+ * than fetched here so the formatter stays pure and testable.+ ** Kept server-side (in orchestration/) because the format mirrors what* the agent's system prompt expects; changing one without the other* desyncs the contract.*/-export function buildTaskKickoffMessage(task: Task): string {+export function buildTaskKickoffMessage(+ task: Task,+ facts?: ProjectPlatformFacts | null,+): string {const lines: string[] = ["(task assignment)","",@@ -36,6 +155,9 @@ export function buildTaskKickoffMessage(task: Task): string {task.brief,"",];+ if (facts) {+ lines.push(...formatPlatformFacts(facts), "");+ }if (task.success_criteria) {lines.push("Success criteria:", task.success_criteria, "");}