Skip to content

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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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, "");
}