Skip to content

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

fix(onboarding): redirect to onboarding task; dedupe sidebar agents; quiet poll

Yuting Zhongb1095267298d
diff --git a/src/app/api/in-flight-counts/route.ts b/src/app/api/in-flight-counts/route.ts
new file mode 100644
index 00000000..87e9885b
--- /dev/null
+++ b/src/app/api/in-flight-counts/route.ts
@@ -0,0 +1,27 @@
+import { NextResponse } from "next/server";
+
+import { getActiveProject } from "@/server/active-project";
+import { actionableApprovalCount } from "@/server/db/approvals";
+import { inFlightCountsByAgent } from "@/server/db/tasks";
+
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+
+/**
+ * Lightweight liveness probe used by GlobalLivenessPoller to decide
+ * whether the sidebar actually needs a refresh. The poller fetches this
+ * a few times a minute; only when the response signature differs from
+ * the previous one does it call router.refresh(). That stops the
+ * sidebar from blinking on every poll cycle when nothing has changed.
+ */
+export async function GET() {
+ const project = await getActiveProject();
+ if (!project) {
+ return NextResponse.json({ project: null, agents: {}, approvals: 0 });
+ }
+ const countsMap = inFlightCountsByAgent(project.slug);
+ const agents: Record<string, number> = {};
+ for (const [agentId, count] of countsMap) agents[agentId] = count;
+ const approvals = actionableApprovalCount(project.slug);
+ return NextResponse.json({ project: project.slug, agents, approvals });
+}
diff --git a/src/components/global-liveness-poller.test.tsx b/src/components/global-liveness-poller.test.tsx
index eb88d469..54c4aa98 100644
--- a/src/components/global-liveness-poller.test.tsx
+++ b/src/components/global-liveness-poller.test.tsx
@@ -10,8 +10,30 @@ vi.mock("next/navigation", () => ({
import { GlobalLivenessPoller } from "./global-liveness-poller";
+// Fake fetch backed by a queue of payloads. The poller hashes the
+// response and only calls router.refresh() when the hash changes — so
+// these tests are about the queue → refresh-count mapping.
+type Payload = { project: string | null; agents: Record<string, number>; approvals: number };
+let payloadQueue: Payload[] = [];
+const fetchMock = vi.fn(async () => {
+ const next = payloadQueue.shift() ?? STABLE_PAYLOAD;
+ return new Response(JSON.stringify(next), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+});
+
+const STABLE_PAYLOAD: Payload = {
+ project: "acme",
+ agents: { "acme-cmo-greg": 1 },
+ approvals: 0,
+};
+
beforeEach(() => {
refresh.mockReset();
+ fetchMock.mockClear();
+ payloadQueue = [];
+ globalThis.fetch = fetchMock as unknown as typeof fetch;
vi.useFakeTimers();
});
@@ -20,73 +42,123 @@ afterEach(() => {
vi.useRealTimers();
});
+// Flush in-flight microtasks (the async fetch + await chain) inside the
+// fake-timer regime so the signature-tracking effect runs before we
+// assert.
+async function flushAsync() {
+ await act(async () => {
+ await Promise.resolve();
+ await Promise.resolve();
+ await Promise.resolve();
+ });
+}
+
describe("GlobalLivenessPoller", () => {
it("renders nothing in the DOM", () => {
const { container } = render(<GlobalLivenessPoller hasInFlight={true} />);
expect(container.firstChild).toBeNull();
});
- it("does not start a timer when hasInFlight is false", () => {
+ it("does not poll when hasInFlight is false", async () => {
render(<GlobalLivenessPoller hasInFlight={false} />);
act(() => {
vi.advanceTimersByTime(20_000);
});
+ await flushAsync();
+ expect(fetchMock).not.toHaveBeenCalled();
expect(refresh).not.toHaveBeenCalled();
});
- it("polls router.refresh() every 2 seconds while hasInFlight is true", () => {
+ it("polls every 2 s but does NOT call router.refresh when signature is unchanged", async () => {
+ payloadQueue = [STABLE_PAYLOAD, STABLE_PAYLOAD, STABLE_PAYLOAD];
render(<GlobalLivenessPoller hasInFlight={true} />);
+ await flushAsync(); // initial seed fetch
+ act(() => {
+ vi.advanceTimersByTime(2_000);
+ });
+ await flushAsync();
+ act(() => {
+ vi.advanceTimersByTime(2_000);
+ });
+ await flushAsync();
+ // 1 seed + 2 ticks = 3 fetches. No refresh because signature is stable.
+ expect(fetchMock.mock.calls.length).toBeGreaterThanOrEqual(3);
expect(refresh).not.toHaveBeenCalled();
+ });
+
+ it("calls router.refresh exactly when the signature changes", async () => {
+ payloadQueue = [
+ STABLE_PAYLOAD, // seed
+ { ...STABLE_PAYLOAD, agents: { "acme-cmo-greg": 2 } }, // first tick — change!
+ { ...STABLE_PAYLOAD, agents: { "acme-cmo-greg": 2 } }, // second tick — same as first
+ { ...STABLE_PAYLOAD, agents: { "acme-cmo-greg": 0 } }, // third tick — change!
+ ];
+ render(<GlobalLivenessPoller hasInFlight={true} />);
+ await flushAsync();
act(() => {
vi.advanceTimersByTime(2_000);
});
+ await flushAsync();
expect(refresh).toHaveBeenCalledTimes(1);
act(() => {
vi.advanceTimersByTime(2_000);
});
- expect(refresh).toHaveBeenCalledTimes(2);
+ await flushAsync();
+ expect(refresh).toHaveBeenCalledTimes(1); // unchanged tick — no refresh
act(() => {
vi.advanceTimersByTime(2_000);
});
- expect(refresh).toHaveBeenCalledTimes(3);
+ await flushAsync();
+ expect(refresh).toHaveBeenCalledTimes(2); // change again — refresh
});
- it("tears the interval down when hasInFlight flips to false", () => {
+ it("tears the interval down when hasInFlight flips to false", async () => {
+ payloadQueue = [STABLE_PAYLOAD, { ...STABLE_PAYLOAD, approvals: 1 }];
const { rerender } = render(<GlobalLivenessPoller hasInFlight={true} />);
+ await flushAsync();
act(() => {
vi.advanceTimersByTime(2_000);
});
+ await flushAsync();
expect(refresh).toHaveBeenCalledTimes(1);
rerender(<GlobalLivenessPoller hasInFlight={false} />);
+ fetchMock.mockClear();
+ refresh.mockClear();
act(() => {
vi.advanceTimersByTime(30_000);
});
- expect(refresh).toHaveBeenCalledTimes(1);
+ await flushAsync();
+ expect(fetchMock).not.toHaveBeenCalled();
+ expect(refresh).not.toHaveBeenCalled();
});
- it("clears the interval on unmount so no stray refreshes fire", () => {
+ it("clears the interval on unmount so no stray refreshes fire", async () => {
+ payloadQueue = [STABLE_PAYLOAD];
const { unmount } = render(<GlobalLivenessPoller hasInFlight={true} />);
- act(() => {
- vi.advanceTimersByTime(2_000);
- });
- expect(refresh).toHaveBeenCalledTimes(1);
+ await flushAsync();
unmount();
+ fetchMock.mockClear();
act(() => {
vi.advanceTimersByTime(60_000);
});
- expect(refresh).toHaveBeenCalledTimes(1);
+ await flushAsync();
+ expect(fetchMock).not.toHaveBeenCalled();
});
- it("starts a fresh interval if hasInFlight flips back to true after being false", () => {
+ it("starts a fresh interval if hasInFlight flips back to true after being false", async () => {
const { rerender } = render(<GlobalLivenessPoller hasInFlight={false} />);
act(() => {
vi.advanceTimersByTime(10_000);
});
- expect(refresh).not.toHaveBeenCalled();
+ await flushAsync();
+ expect(fetchMock).not.toHaveBeenCalled();
+ payloadQueue = [STABLE_PAYLOAD, { ...STABLE_PAYLOAD, approvals: 5 }];
rerender(<GlobalLivenessPoller hasInFlight={true} />);
+ await flushAsync();
act(() => {
vi.advanceTimersByTime(2_000);
});
+ await flushAsync();
expect(refresh).toHaveBeenCalledTimes(1);
});
});
diff --git a/src/components/global-liveness-poller.tsx b/src/components/global-liveness-poller.tsx
index 57c35e0e..61358bf9 100644
--- a/src/components/global-liveness-poller.tsx
+++ b/src/components/global-liveness-poller.tsx
@@ -1,6 +1,6 @@
"use client";
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
import { useRouter } from "next/navigation";
/**
@@ -12,21 +12,62 @@ import { useRouter } from "next/navigation";
* Replaces the workspace-scoped AgentLivenessPoller. Same idea, just
* lifted to the layout level so non-workspace pages don't go stale.
*
+ * Strategy: poll a small JSON endpoint at /api/in-flight-counts, hash
+ * the response, and ONLY call router.refresh() when the hash differs
+ * from the previous one. Calling router.refresh() unconditionally on
+ * every tick re-renders the whole sidebar subtree which made it
+ * visibly blink even when nothing changed. With the signature gate,
+ * steady-state polling is silent.
+ *
* Cadence: 2 s while `hasInFlight` is true. The first refresh that lands
* a server-rendered `hasInFlight = false` flips the prop, the effect
* tears the interval down, and we stop spending requests on idle state.
- * Paperclip uses 10 s + a WebSocket push for instant invalidation; at
- * single-user local-CLI scale, 2 s polling keeps the sidebar badges
- * responsive without adding a WS server. The workspace's
- * AgentTaskWorkspace also refreshes on every in-flight transcript poll,
- * so the active task workspace itself is closer to ~800 ms.
*/
export function GlobalLivenessPoller({ hasInFlight }: { hasInFlight: boolean }) {
const router = useRouter();
+ const lastSignatureRef = useRef<string | null>(null);
useEffect(() => {
if (!hasInFlight) return;
- const interval = setInterval(() => router.refresh(), 2_000);
- return () => clearInterval(interval);
+ let cancelled = false;
+
+ async function tick() {
+ try {
+ const r = await fetch("/api/in-flight-counts", {
+ cache: "no-store",
+ credentials: "same-origin",
+ });
+ if (!r.ok) return;
+ const body = (await r.json()) as {
+ project: string | null;
+ agents: Record<string, number>;
+ approvals: number;
+ };
+ // Canonical signature: same shape ⇒ same string. Sort the agent
+ // keys so map-iteration order doesn't generate a false-positive.
+ const sig = JSON.stringify({
+ p: body.project,
+ a: Object.entries(body.agents)
+ .sort(([a], [b]) => a.localeCompare(b))
+ .map(([k, v]) => [k, v]),
+ v: body.approvals,
+ });
+ if (cancelled) return;
+ if (lastSignatureRef.current !== null && lastSignatureRef.current !== sig) {
+ router.refresh();
+ }
+ lastSignatureRef.current = sig;
+ } catch {
+ // Network/JSON hiccup — skip this tick; we'll catch up next.
+ }
+ }
+ // Seed the signature on mount so the first real change triggers
+ // a refresh (otherwise the very first tick would always refresh).
+ void tick();
+ const interval = setInterval(tick, 2_000);
+ return () => {
+ cancelled = true;
+ clearInterval(interval);
+ };
}, [hasInFlight, router]);
return null;
}
diff --git a/src/server/actions/crons.test.ts b/src/server/actions/crons.test.ts
index 94655779..b9990c34 100644
--- a/src/server/actions/crons.test.ts
+++ b/src/server/actions/crons.test.ts
@@ -31,7 +31,7 @@ vi.mock("@/server/db/agent-actions", () => ({
// scheduleCronAction looks up the agent's full id from the project's
// agent roster — the id encodes the personal name now, so we can't
// synthesize it from template key alone.
-const listProjectAgentsMock = vi.fn(async () => [
+const listProjectAgentsMock = vi.fn(async (..._a: unknown[]) => [
{
agent_id: "demo-cmo-greg",
slug: "cmo-greg",
diff --git a/src/server/agent-meta.ts b/src/server/agent-meta.ts
index cc5e813b..ff51b217 100644
--- a/src/server/agent-meta.ts
+++ b/src/server/agent-meta.ts
@@ -91,21 +91,25 @@ export type ProjectAgentEntry = {
* before `ensureProjectAgents` runs.
*/
export async function listProjectAgents(project_slug: string): Promise<ProjectAgentEntry[]> {
- const result = new Map<string, ProjectAgentEntry>();
+ // Two-phase merge:
+ // - Template agents are deduplicated by template_key. The agent_id
+ // encodes the personal name (e.g. demo-cmo-greg), so the seed and
+ // the overlay COULD disagree on the id if the on-disk sidecar still
+ // uses an older naming. Keying by template_key prevents that from
+ // showing two CMO entries in the sidebar.
+ // - Cloned/custom agents (no template_key) key by their agent_id since
+ // a project may have many of them.
+ const byRole = new Map<string, ProjectAgentEntry>();
+ const byAgentId = new Map<string, ProjectAgentEntry>();
// 1) Seed with the templates an onboarded project actually has. Opt-in
// templates (e.g. SEO until v1.1 lights it up) live in TEMPLATES but
// are NOT pre-seeded — they only appear when a meta sidecar shows
- // one was actually provisioned. This is how we keep the sidebar from
- // pretending SEO exists when the onboarding scope is cmo+google-ads.
+ // one was actually provisioned.
for (const t of TEMPLATES) {
if (!t.default_onboarding) continue;
- // Placeholder entry shown before a meta sidecar exists on disk.
- // Both the agent_id and the URL slug encode the template's
- // default_name; the moment ensureProjectAgents writes a sidecar
- // with the user-chosen name, the overlay below replaces this row.
const agentId = agentNameFor(project_slug, t.key, t.default_name);
- result.set(agentId, {
+ byRole.set(t.key, {
agent_id: agentId,
slug: agentUrlSlug(t.key, t.default_name),
name: t.default_name,
@@ -123,32 +127,45 @@ export async function listProjectAgents(project_slug: string): Promise<ProjectAg
entries = await readdir(agentsRoot);
} catch {
// No agents dir yet — keep templates-only view.
- return Array.from(result.values());
+ return Array.from(byRole.values());
}
const prefix = `${project_slug}-`;
for (const entry of entries) {
if (!entry.startsWith(prefix)) continue;
const meta = readAgentMeta(entry);
if (!meta) continue;
- // Template agents: slug is COMPUTED from template_key + name; we
- // ignore any stored slug (templates don't write one).
- // Cloned/custom: slug came from the sidecar (clone-agent writes it).
const template = meta.template_key
? TEMPLATES.find((t) => t.key === meta.template_key)
: undefined;
- const slug = template
- ? agentUrlSlug(template.key, meta.name)
- : meta.slug ?? slugifyForCustom(meta.name);
- result.set(meta.agent_id, {
- agent_id: meta.agent_id,
- slug,
- name: meta.name,
- template_key: meta.template_key,
- source_agent_id: meta.source_agent_id,
- is_template_default: false,
- });
+ if (template) {
+ // Template agent: replace the seed row keyed by role.
+ const slug = agentUrlSlug(template.key, meta.name);
+ byRole.set(template.key, {
+ agent_id: meta.agent_id,
+ slug,
+ name: meta.name,
+ template_key: meta.template_key,
+ source_agent_id: meta.source_agent_id,
+ is_template_default: false,
+ });
+ } else {
+ // Cloned/custom agent: key by agent_id.
+ const slug = meta.slug ?? slugifyForCustom(meta.name);
+ byAgentId.set(meta.agent_id, {
+ agent_id: meta.agent_id,
+ slug,
+ name: meta.name,
+ template_key: undefined,
+ source_agent_id: meta.source_agent_id,
+ is_template_default: false,
+ });
+ }
}
+ const result = new Map<string, ProjectAgentEntry>();
+ for (const v of byRole.values()) result.set(v.agent_id, v);
+ for (const v of byAgentId.values()) result.set(v.agent_id, v);
+
// Stable order: templates first (in declared order), then custom by slug.
const templateOrder = new Map(TEMPLATES.map((t, i) => [t.key, i]));
return Array.from(result.values()).sort((a, b) => {
diff --git a/src/server/onboarding/accounts.ts b/src/server/onboarding/accounts.ts
index b4d998ff..2006a146 100644
--- a/src/server/onboarding/accounts.ts
+++ b/src/server/onboarding/accounts.ts
@@ -199,25 +199,25 @@ export async function setOnboardingAccountAction(
const existingAudit = allTasks.find(
(t) => t.agent_id === cmoAgentId && t.title?.startsWith("Audit the account"),
);
- let task = existingAudit;
- if (!task) {
- // Find the project-onboarding task to gate on. Match by exact title
- // (createProjectForOnboardingAction uses a fixed string from
- // buildProjectOnboardingBrief). When it's missing or already terminal,
- // createTask drops the blocker automatically — the audit runs
- // immediately in that case.
- const onboardingTask = allTasks.find(
- (t) =>
- t.agent_id === cmoAgentId &&
- t.title === "Learn the project and write PROJECT.md",
- );
+ // Find the project-onboarding task. Created synchronously by
+ // createProjectForOnboardingAction; should always exist by the time
+ // the user gets here.
+ const onboardingTask = allTasks.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,
});
- task = createTask({
+ audit = createTask({
project_slug,
agent_id: cmoAgentId,
title,
@@ -229,23 +229,22 @@ export async function setOnboardingAccountAction(
});
}
- // Status now:
- // - If onboarding task was non-terminal at createTask time → audit is
- // `blocked`. The propagation hook in handleTaskStatus picks it up
- // when onboarding flips to `done`.
- // - Otherwise → audit is `proposed`. The task workspace the caller
- // redirects the user to auto-fires the kickoff client-side via
- // /api/chat (which atomically claims). For the resubmit branch
- // (audit already running/done) /api/chat is a safe no-op.
-
- // The CMO's URL slug was already resolved above (via listProjectAgents);
- // hand it to the client so the redirect uses the role-name path without
- // the client computing anything itself.
+ // 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.
+ // - Fall back to the audit when onboarding is already done (or never
+ // existed) so the user lands on the running task either way.
+ const TERMINAL = new Set(["done", "failed", "cancelled"]);
+ const surfaceTask =
+ onboardingTask && !TERMINAL.has(onboardingTask.status)
+ ? onboardingTask
+ : audit;
+
revalidatePath("/", "layout");
return {
ok: true,
project: updated,
- task_display_id: task.display_id,
+ task_display_id: surfaceTask.display_id,
cmo_agent_slug: cmo.slug,
};
}