Skip to content

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

feat(onboarding): async provision state + selective agent scope

Yuting Zhongd2abb7a48dcf
diff --git a/src/server/actions/projects.ts b/src/server/actions/projects.ts
index 50a219b2..25cd0000 100644
--- a/src/server/actions/projects.ts
+++ b/src/server/actions/projects.ts
@@ -17,6 +17,7 @@ import {
setActiveProject,
} from "@/server/active-project";
import { ensureProjectAgents } from "@/server/agent-templates";
+import { startProvisioning } from "@/server/onboarding/provisioning-state";
import { listProjectAgents, readAgentMeta } from "@/server/agent-meta";
import { cascadeDeleteAgent, relocateAgent } from "@/server/actions/agents";
import { listCronsForProject, disableCron } from "@/server/openclaw/crons";
@@ -40,21 +41,29 @@ export async function createProjectAction(formData: FormData): Promise<void> {
const result = createProject({ display_name });
if (!result.ok) throw new Error(result.reason);
- // Provision OpenClaw agents inline so the project is immediately usable.
- // If provisioning fails (e.g., OpenClaw down), the project row still exists
- // and the user can re-run provisioning from project home later.
- try {
- const prov = await ensureProjectAgents(result.project.slug);
- logAgentAction({
- project_slug: result.project.slug,
- agent_id: "system",
- action_type: "project_created",
- summary: `Project '${result.project.display_name}' created. ${prov.created.length} agents provisioned.`,
- payload: prov,
+ // Per D6: provision CMO + Google Ads asynchronously so the form returns
+ // immediately. The audit step (after OAuth) gates on completion via
+ // `awaitProvisioning` from server/onboarding/provisioning-state.
+ // Per D4: scope to CMO + Google Ads only; SEO is opt-in later.
+ const provisionPromise = ensureProjectAgents(result.project.slug, [
+ "cmo",
+ "google_ads",
+ ]);
+ startProvisioning(result.project.slug, provisionPromise);
+ // Log on completion (best-effort, doesn't block form return).
+ provisionPromise
+ .then((prov) => {
+ logAgentAction({
+ project_slug: result.project.slug,
+ agent_id: "system",
+ action_type: "project_created",
+ summary: `Project '${result.project.display_name}' created. ${prov.created.length} agents provisioned${prov.failed.length > 0 ? `, ${prov.failed.length} failed` : ""}.`,
+ payload: prov,
+ });
+ })
+ .catch((err) => {
+ console.error("Agent provisioning failed; project created but no agents:", err);
});
- } catch (err) {
- console.error("Agent provisioning failed; project created but no agents:", err);
- }
await setActiveProject(result.project.slug);
revalidatePath("/", "layout");
diff --git a/src/server/agent-templates.ts b/src/server/agent-templates.ts
index 51f3265f..6cb3a99e 100644
--- a/src/server/agent-templates.ts
+++ b/src/server/agent-templates.ts
@@ -181,14 +181,37 @@ export function agentNameFor(project_slug: string, template_key: AgentTemplate["
return `${project_slug}-${safe_template}`;
}
-export async function ensureProjectAgents(project_slug: string): Promise<{
+export type EnsureAgentsResult = {
created: string[];
existed: string[];
-}> {
+ failed: Array<{ name: string; error: string }>;
+};
+
+/**
+ * Idempotently provision OpenClaw agents for a project.
+ *
+ * Pass `scope` to provision only a subset (per D4: onboarding ships with CMO
+ * + Google Ads only; SEO becomes opt-in later). Omit `scope` to provision
+ * every template — preserved for back-compat with existing call sites like
+ * the reprovision endpoint.
+ *
+ * The result includes `failed`: when a subprocess fails for one agent, the
+ * loop logs + continues (partial provisioning is recoverable) and the
+ * caller can decide whether `failed.length > 0` is fatal for their flow.
+ */
+export async function ensureProjectAgents(
+ project_slug: string,
+ scope?: AgentTemplateKey[],
+): Promise<EnsureAgentsResult> {
const created: string[] = [];
const existed: string[] = [];
+ const failed: Array<{ name: string; error: string }> = [];
+
+ const templates = scope
+ ? TEMPLATES.filter((t) => scope.includes(t.key))
+ : TEMPLATES;
- for (const template of TEMPLATES) {
+ for (const template of templates) {
const name = agentNameFor(project_slug, template.key);
const workspaceAbs = workspaceDirFor(name);
const already = await agentExists(name);
@@ -237,11 +260,13 @@ export async function ensureProjectAgents(project_slug: string): Promise<{
created.push(name);
} catch (err) {
// Surface but don't crash the loop; partial provisioning recoverable on retry.
+ const message = err instanceof Error ? err.message : String(err);
console.error(`Failed to create agent ${name}:`, err);
+ failed.push({ name, error: message });
}
}
- return { created, existed };
+ return { created, existed, failed };
}
function workspaceDirFor(name: string): string {
@@ -264,7 +289,7 @@ ${template.system_prompt}
}
}
-async function agentExists(name: string): Promise<boolean> {
+export async function agentExists(name: string): Promise<boolean> {
try {
// `agents list` doesn't currently take a name filter, so list-all and grep.
// V1 acceptable; revisit if list grows large.
diff --git a/src/server/onboarding/provisioning-state.test.ts b/src/server/onboarding/provisioning-state.test.ts
new file mode 100644
index 00000000..2be50d95
--- /dev/null
+++ b/src/server/onboarding/provisioning-state.test.ts
@@ -0,0 +1,94 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const agentExistsMock = vi.fn<(name: string) => Promise<boolean>>();
+vi.mock("@/server/agent-templates", () => ({
+ agentExists: (name: string) => agentExistsMock(name),
+}));
+
+import {
+ __resetProvisioningForTesting,
+ awaitProvisioning,
+ startProvisioning,
+ type ProvisionResult,
+} from "./provisioning-state";
+
+const okResult: ProvisionResult = {
+ created: ["acme-cmo", "acme-google-ads"],
+ existed: [],
+ failed: [],
+};
+
+describe("provisioning-state", () => {
+ beforeEach(() => {
+ __resetProvisioningForTesting();
+ agentExistsMock.mockReset();
+ });
+
+ afterEach(() => {
+ __resetProvisioningForTesting();
+ });
+
+ describe("happy path (Promise present)", () => {
+ it("resolves to ready with the provisioning result", async () => {
+ const promise = Promise.resolve(okResult);
+ startProvisioning("acme", promise);
+ const r = await awaitProvisioning("acme", 5_000);
+ expect(r).toEqual({ kind: "ready", via_fallback: false, result: okResult });
+ });
+
+ it("consumes the map entry after resolution", async () => {
+ startProvisioning("acme", Promise.resolve(okResult));
+ await awaitProvisioning("acme", 5_000);
+ // Second call should hit the cold-start path now.
+ agentExistsMock.mockResolvedValue(true);
+ const r2 = await awaitProvisioning("acme", 5_000);
+ expect(r2).toEqual({ kind: "ready", via_fallback: true });
+ });
+ });
+
+ describe("timeout", () => {
+ it("returns timeout when Promise doesn't resolve in time", async () => {
+ const slowPromise = new Promise<ProvisionResult>((resolve) =>
+ setTimeout(() => resolve(okResult), 200),
+ );
+ startProvisioning("acme", slowPromise);
+ const r = await awaitProvisioning("acme", 50);
+ expect(r).toEqual({ kind: "timeout" });
+ });
+ });
+
+ describe("Promise rejection", () => {
+ it("returns timeout when the provisioning Promise rejects", async () => {
+ const rejected = Promise.reject(new Error("openclaw blew up"));
+ // Pre-catch to avoid Node's unhandled-rejection warning in the test runner.
+ rejected.catch(() => {});
+ startProvisioning("acme", rejected);
+ const r = await awaitProvisioning("acme", 5_000);
+ expect(r).toEqual({ kind: "timeout" });
+ });
+ });
+
+ describe("cold-start fallback (Map empty)", () => {
+ it("returns ready when both expected agents exist on disk", async () => {
+ agentExistsMock.mockImplementation(async (name) =>
+ name === "acme-cmo" || name === "acme-google-ads",
+ );
+ const r = await awaitProvisioning("acme", 5_000);
+ expect(r).toEqual({ kind: "ready", via_fallback: true });
+ expect(agentExistsMock).toHaveBeenCalledWith("acme-cmo");
+ expect(agentExistsMock).toHaveBeenCalledWith("acme-google-ads");
+ });
+
+ it("returns no-agents when neither agent exists", async () => {
+ agentExistsMock.mockResolvedValue(false);
+ const r = await awaitProvisioning("acme", 5_000);
+ expect(r).toEqual({ kind: "no-agents", via_fallback: true });
+ });
+
+ it("returns no-agents when only one of the expected agents exists", async () => {
+ agentExistsMock.mockImplementation(async (name) => name === "acme-cmo");
+ const r = await awaitProvisioning("acme", 5_000);
+ expect(r).toEqual({ kind: "no-agents", via_fallback: true });
+ });
+ });
+});
diff --git a/src/server/onboarding/provisioning-state.ts b/src/server/onboarding/provisioning-state.ts
new file mode 100644
index 00000000..a976a6ca
--- /dev/null
+++ b/src/server/onboarding/provisioning-state.ts
@@ -0,0 +1,108 @@
+import { agentExists } from "@/server/agent-templates";
+
+/**
+ * In-process map tracking async OpenClaw agent provisioning per project.
+ *
+ * Why this exists: per D6, `createProjectAction` fires `ensureProjectAgents`
+ * without awaiting it so the form returns immediately and the user can begin
+ * the OAuth redirect. The audit SSE route (a separate request, after OAuth)
+ * still needs to wait until provisioning completes before calling MCP — per
+ * D13 with an 8s ceiling. The Promise from the form action's request scope
+ * is gone by the time the audit route runs; we stash it here so the audit
+ * route can `await` it.
+ *
+ * Pattern mirrors `server/mcp-pending.ts`: globalThis-pinned map that
+ * survives Next.js dev hot-reload. Single-process invariant holds because
+ * the CLI launches one Next.js server per user.
+ *
+ * Cold-start fallback: if the process restarted between form submit and
+ * audit start (user closed the tab and returned hours later), the Map is
+ * empty. `awaitProvisioning` falls back to a fast filesystem-level check via
+ * `agentExists` so the audit can still proceed.
+ */
+
+export type ProvisionResult = {
+ created: string[];
+ existed: string[];
+ failed: Array<{ name: string; error: string }>;
+};
+
+export type AwaitResult =
+ | { kind: "ready"; via_fallback: boolean; result?: ProvisionResult }
+ | { kind: "timeout" }
+ | { kind: "no-agents"; via_fallback: true };
+
+const GLOBAL_KEY = "__notfair_cmo_provisioning__";
+type GlobalSlot = { store?: Map<string, Promise<ProvisionResult>> };
+const slot = globalThis as unknown as Record<string, GlobalSlot>;
+const STORE: Map<string, Promise<ProvisionResult>> =
+ (slot[GLOBAL_KEY] ??= {}).store ??
+ ((slot[GLOBAL_KEY] as GlobalSlot).store = new Map());
+
+/**
+ * Register a provisioning Promise for a project slug. The Promise is held
+ * until consumed by `awaitProvisioning`; subsequent calls for the same slug
+ * after consumption see no entry and fall through to the agentExists
+ * fast-check.
+ */
+export function startProvisioning(
+ slug: string,
+ promise: Promise<ProvisionResult>,
+): void {
+ STORE.set(slug, promise);
+}
+
+/**
+ * Wait for provisioning to complete (Promise resolution) or fall back to
+ * checking agentExists if no Promise is registered (cold-start path).
+ * Returns:
+ * - `ready` with the result when the Promise resolves before the timeout
+ * - `ready` via_fallback when the Map was empty but both expected agents
+ * are present on disk (process restart, work is done)
+ * - `no-agents` when the Map was empty AND agents are NOT present (cold
+ * start before any provisioning ever happened — caller should error)
+ * - `timeout` when the Promise didn't resolve within timeoutMs
+ */
+export async function awaitProvisioning(
+ slug: string,
+ timeoutMs: number,
+): Promise<AwaitResult> {
+ const existing = STORE.get(slug);
+
+ if (existing) {
+ try {
+ const result = await Promise.race([
+ existing.then((r) => ({ kind: "ready" as const, result: r })),
+ new Promise<{ kind: "timeout" }>((resolve) =>
+ setTimeout(() => resolve({ kind: "timeout" }), timeoutMs),
+ ),
+ ]);
+ if (result.kind === "ready") {
+ STORE.delete(slug);
+ return { kind: "ready", via_fallback: false, result: result.result };
+ }
+ return { kind: "timeout" };
+ } catch {
+ // Promise rejected. Treat as "not ready" — caller can decide to retry.
+ STORE.delete(slug);
+ return { kind: "timeout" };
+ }
+ }
+
+ // Cold-start path: check whether the expected agents exist on disk.
+ const cmoId = `${slug}-cmo`;
+ const googleAdsId = `${slug}-google-ads`;
+ const [hasCmo, hasGoogleAds] = await Promise.all([
+ agentExists(cmoId),
+ agentExists(googleAdsId),
+ ]);
+ if (hasCmo && hasGoogleAds) {
+ return { kind: "ready", via_fallback: true };
+ }
+ return { kind: "no-agents", via_fallback: true };
+}
+
+/** Test helper: drain the global Map. Never call in production code. */
+export function __resetProvisioningForTesting(): void {
+ STORE.clear();
+}