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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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();+}