@apex-inc/mcp-server 0.7.0 → 0.9.0

package/dist/tools.js

@@ -1,6 +1,16 @@
 import { z } from "zod";
-import { apiGet, apiPost, apiPatch, apiDelete, postWithIdempotency, setActiveProject, getActiveProject, setActiveOrg, getActiveOrg, getUserContext } from "./api-client.js";
+import { apiGet, apiPost, apiPatch, apiDelete, postWithIdempotency, setActiveWorkspace, getActiveWorkspace, setActiveOrg, getActiveOrg, getUserContext } from "./api-client.js";
 const APEX = "∧ Apex";
+/**
+ * MOBX-006 — stable synthetic visitor id for agent-fired events.
+ *
+ * `/api/events` only counts an event toward wiring detection when it
+ * carries a top-level `visitorId`. A per-process random suffix keeps
+ * the id stable for the MCP server's lifetime (so repeated track_event
+ * calls roll up to one synthetic "visitor") while distinguishing
+ * separate agent sessions from each other.
+ */
+const MCP_AGENT_VISITOR_ID = `mcp-agent-${Math.random().toString(36).slice(2, 10)}`;
 export const toolDefinitions = {
     plan_experiment: {
         description: `${APEX} — PLANNING ONLY, does not create anything. Analyzes a goal against existing beliefs and experiments, then returns structured options for the user to choose from. After calling, you MUST present the returned options as a numbered list or poll and wait for the user to pick before calling any other Apex tools.`,
@@ -916,27 +926,40 @@ The Apex Spec ships two peer registries:
 
 \u2022 **Platform events** (\`APEX_PLATFORM_EVENTS\`) — events Apex's own dashboard fires as merchants use it. Names: \`user_invitation_created\`, \`user_invitation_accepted\`, \`developer_invite_sent\`, \`integration_connected\`, \`integration_sync_completed\`, \`integration_sync_failed\`, \`badge_awarded\`, \`user_level_up\`, \`nudge_scheduled\`, \`drip_step_scheduled\`, \`experiment_launched\`, \`experiment_significant\`, \`experiment_concluded\`, \`experiment_promoted\`, \`portfolio_access_requested\`, \`portfolio_access_approved\`, \`portfolio_access_rejected\`, \`portfolio_share_accepted\`, \`subscription_upgraded\`, \`subscription_downgraded\`, \`tier_limit_approaching\`, \`anomaly_detected\`, \`weekly_digest_scheduled\`, \`cognito_verification_code\`, \`user_signup\`. Use these when an agent is acting *as* the Apex platform (admin tooling, dashboard automation), not as the customer's product.
 
-Custom event names are accepted (the spec is open by default), but agents should prefer canonical names from one of the two registries so the event flows directly into the catalog templates, the journey trigger system, and the conversion-goal helpers without manual wiring. The full spec lives at https://docs.apex.inc/spec.`,
+Custom event names are accepted (the spec is open by default), but agents should prefer canonical names from one of the two registries so the event flows directly into the catalog templates, the journey trigger system, and the conversion-goal helpers without manual wiring. The full spec lives at https://docs.apex.inc/spec.
+
+Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*, fixed for this MCP process) and a timestamp, so they WILL count toward wiring detection (the same signal the Set up Apex page and get_wiring_status read). They are flagged as agent-fired (source: "mcp" in the event data + the x-apex-source header), so dashboards can distinguish them from real app traffic — but they are NOT test-mode events; fire them deliberately.`,
         schema: z.object({
             event: z.string().describe("Event name — snake_case from APEX_EVENTS or APEX_PLATFORM_EVENTS (e.g. 'page_view', 'in_app_purchase', 'user_invitation_created'). Custom names are accepted but prefer canonical ones."),
             properties: z.record(z.unknown()).optional().describe("Flat snake_case properties matching the spec entry for this event (e.g. { product_id: 'prod_abc', value: 29.99, currency: 'USD' })."),
         }),
         handler: async ({ event, properties }) => {
+            // MOBX-006 — the batch path of /api/events reads `visitorId`,
+            // `type`, and the event bag (`data`) at the TOP LEVEL of each
+            // event. Without a visitorId the event lands in the raw SDK
+            // firehose but never reaches the tracking-event store that
+            // powers wiring detection / readiness (the route reports it
+            // under `untracked`). Stamp the per-process synthetic visitor
+            // id + timestamp so agent-fired events actually count.
             const result = await apiPost("/api/events", {
-                projectKey: process.env.APEX_PROJECT_KEY || "default",
+                workspaceKey: (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY) || "default",
                 userId: "mcp-agent",
                 events: [
                     {
                         type: event,
-                        payload: { ...properties, source: "mcp" },
+                        visitorId: MCP_AGENT_VISITOR_ID,
                         timestamp: new Date().toISOString(),
+                        data: { ...properties, source: "mcp" },
                     },
                 ],
             });
+            const wiringNote = result.untracked && result.untracked.length > 0
+                ? `\nNOT counted toward wiring detection: ${result.untracked[0].reason}`
+                : `\nCounts toward wiring detection (visitorId: ${MCP_AGENT_VISITOR_ID}, flagged agent-fired via source: "mcp").`;
             return {
                 content: [{
                         type: "text",
-                        text: `Event tracked: "${event}" — ${result.received} event(s) stored.${properties ? `\nProperties: ${JSON.stringify(properties)}` : ""}`,
+                        text: `Event tracked: "${event}" — ${result.received} event(s) stored.${wiringNote}${properties ? `\nProperties: ${JSON.stringify(properties)}` : ""}`,
                     }],
             };
         },
@@ -989,7 +1012,7 @@ Custom event names are accepted (the spec is open by default), but agents should
             await apiPost("/api/identity/stitch", {
                 visitorId: `mcp-${email}`,
                 email,
-                projectKey: process.env.APEX_PROJECT_KEY || "default",
+                workspaceKey: (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY) || "default",
                 metadata: { name, company, ...metadata, source: "mcp" },
             });
             return {
@@ -1004,7 +1027,7 @@ Custom event names are accepted (the spec is open by default), but agents should
         description: `${APEX} — Read the workspace's canonical Schema (data dictionary): entities, their fields, which fields are wired (observed in live data) vs not, surface coverage, and any canonical mappings. Use to see what variables/attributes a workspace has and what's still unwired before authoring comms or segments.`,
         schema: z.object({}),
         handler: async () => {
-            const dict = await apiGet("/api/data-dictionary");
+            const dict = await apiGet("/api/schema");
             const lines = [];
             for (const entity of Object.values(dict.entities)) {
                 lines.push(`\n${entity.label}  {{${entity.key}.<field>}}`);
@@ -1035,7 +1058,7 @@ Custom event names are accepted (the spec is open by default), but agents should
                 .describe("Canonical snake_case name (e.g. 'first_name'), or null to clear"),
         }),
         handler: async ({ entityKey, fieldName, canonicalName, }) => {
-            const res = await apiPost("/api/data-dictionary/map", { entityKey, fieldName, canonicalName: canonicalName ?? null });
+            const res = await apiPost("/api/schema/map", { entityKey, fieldName, canonicalName: canonicalName ?? null });
             const mapped = res.data?.canonicalName;
             return {
                 content: [
@@ -1101,48 +1124,51 @@ Custom event names are accepted (the spec is open by default), but agents should
         },
     },
     list_projects: {
-        description: "List all projects available to your API key. Use this to see which projects you can work with.",
+        description: "List all workspaces available to your API key. Use this to see which workspaces you can work with.",
         schema: z.object({}),
         handler: async () => {
-            const projects = await apiGet("/api/projects");
-            const current = getActiveProject();
-            if (!projects.length) {
+            // NOTE: `/api/projects` is the PERMANENT alias path this tool has
+            // shipped against — it returns the flat row shape below. Do not
+            // point at `/api/workspaces` (different response shape).
+            const workspaces = await apiGet("/api/projects");
+            const current = getActiveWorkspace();
+            if (!workspaces.length) {
                 return {
                     content: [{
                             type: "text",
-                            text: "No projects found for this API key.",
+                            text: "No workspaces found for this API key.",
                         }],
                 };
             }
-            const lines = projects.map((p) => {
-                const active = p.projectKey === current ? " ← active" : "";
-                return `  ${p.projectKey} — ${p.name} (${p.url})${active}`;
+            const lines = workspaces.map((p) => {
+                const active = p.workspaceKey === current ? " ← active" : "";
+                return `  ${p.workspaceKey} — ${p.name} (${p.url})${active}`;
             });
             return {
                 content: [{
                         type: "text",
-                        text: [`Projects (${projects.length}):`, ...lines].join("\n"),
+                        text: [`Workspaces (${workspaces.length}):`, ...lines].join("\n"),
                     }],
             };
         },
     },
     switch_project: {
-        description: "Switch the active project for this session. All subsequent API calls will use this project.",
+        description: "Switch the active workspace for this session. All subsequent API calls will use this workspace.",
         schema: z.object({
-            projectKey: z.string().describe("The project key to switch to"),
+            workspaceKey: z.string().describe("The workspace key to switch to"),
         }),
         handler: async (args) => {
-            setActiveProject(args.projectKey);
+            setActiveWorkspace(args.workspaceKey);
             return {
                 content: [{
                         type: "text",
-                        text: `Switched to project: ${args.projectKey}. All subsequent calls will use this project.`,
+                        text: `Switched to workspace: ${args.workspaceKey}. All subsequent calls will use this workspace.`,
                     }],
             };
         },
     },
     list_orgs: {
-        description: "List all organizations you have access to, with their projects. Use this to see which orgs and projects are available.",
+        description: "List all organizations you have access to, with their workspaces. Use this to see which orgs and workspaces are available.",
         schema: z.object({}),
         handler: async () => {
             const ctx = getUserContext();
@@ -1157,8 +1183,8 @@ Custom event names are accepted (the spec is open by default), but agents should
             const activeOrg = getActiveOrg();
             const lines = ctx.orgs.map((org) => {
                 const active = org.orgId === activeOrg ? " ← active" : "";
-                const projects = org.projects.map((p) => `    ${p.projectKey} — ${p.name}`).join("\n");
-                return `  ${org.orgName} (${org.orgId}, ${org.role})${active}\n${projects || "    (no projects)"}`;
+                const workspaces = org.workspaces.map((p) => `    ${p.workspaceKey} — ${p.name}`).join("\n");
+                return `  ${org.orgName} (${org.orgId}, ${org.role})${active}\n${workspaces || "    (no workspaces)"}`;
             });
             return {
                 content: [{
@@ -1169,7 +1195,7 @@ Custom event names are accepted (the spec is open by default), but agents should
         },
     },
     switch_org: {
-        description: "Switch the active organization. This also switches to the first project in that org.",
+        description: "Switch the active organization. This also switches to the first workspace in that org.",
         schema: z.object({
             orgId: z.string().describe("The organization ID to switch to (from list_orgs)"),
         }),
@@ -1196,12 +1222,12 @@ Custom event names are accepted (the spec is open by default), but agents should
                 };
             }
             setActiveOrg(args.orgId);
-            const project = getActiveProject();
-            const projectInfo = project ? `, active project: ${project}` : "";
+            const workspace = getActiveWorkspace();
+            const projectInfo = workspace ? `, active workspace: ${workspace}` : "";
             return {
                 content: [{
                         type: "text",
-                        text: `Switched to org: ${org.orgName} (${org.projects.length} project${org.projects.length !== 1 ? "s" : ""})${projectInfo}.`,
+                        text: `Switched to org: ${org.orgName} (${org.workspaces.length} workspace${org.workspaces.length !== 1 ? "s" : ""})${projectInfo}.`,
                     }],
             };
         },
@@ -1322,26 +1348,37 @@ Custom event names are accepted (the spec is open by default), but agents should
         },
     },
     get_event_taxonomy: {
-        description: "Get the standard events your app should track for this vertical. Shows event names, descriptions, and apex.track() examples.",
+        // MOBX-002 (post-mortem #9) — this tool used to read the legacy
+        // comms registry (`/api/communications/events`), which disagreed
+        // with the Apex Spec on names AND casing (purchase_completed vs
+        // in_app_purchase, userId vs order_id) and rendered "undefined"
+        // descriptions. There is ONE event vocabulary: the Apex Spec.
+        // This tool now serves it and points agents at get_event_spec.
+        description: "DEPRECATED alias of get_event_spec — the canonical Apex Spec event registry (one vocabulary; the legacy comms taxonomy this used to serve disagreed with it). Prefer get_event_spec.",
         schema: z.object({}),
         handler: async () => {
-            const data = await apiGet("/api/communications/events");
-            const events = Array.isArray(data) ? data : [];
-            if (events.length === 0) {
-                return { content: [{ type: "text", text: "No event taxonomy configured. Set up your project's vertical first." }] };
+            const res = await apiGet("/api/spec/events");
+            const events = res.data?.events ?? {};
+            const names = Object.keys(events);
+            if (names.length === 0) {
+                return { content: [{ type: "text", text: "Spec bundle unavailable. Use get_event_spec." }] };
             }
-            const summary = events.map((e) => {
-                const evt = e;
-                return `• ${evt.id}: ${evt.name} — ${evt.description || ""}`;
-            }).join("\n");
-            return { content: [{ type: "text", text: `${events.length} events in taxonomy:\n\n${summary}\n\nFull data:\n${JSON.stringify(data, null, 2)}` }] };
+            const summary = names
+                .map((n) => `• ${n} — ${events[n]?.description ?? ""}`)
+                .join("\n");
+            return {
+                content: [{
+                        type: "text",
+                        text: `${names.length} canonical events (Apex Spec ${res.data?.specVersion ?? ""}). Use get_event_spec for full schemas.\n\n${summary}`,
+                    }],
+            };
         },
     },
     // ─── Partner Network (MMP-161) ──────────────────────────────────────────
     //
     // Merchant-scoped tools for managing an affiliate program through the
     // Apex Partner Network. Every tool authenticates via the caller's
-    // active project + API key (same pattern as experiments / comms).
+    // active workspace + API key (same pattern as experiments / comms).
     // Partner-facing flows (self-signup, portal) + admin Fraud Ops are
     // intentionally not wrapped — they require different auth.
     list_partner_programs: {
@@ -1516,7 +1553,7 @@ Custom event names are accepted (the spec is open by default), but agents should
                 const tag = f.isCustom ? " (custom)" : "";
                 return `• ${kind}: ${display}${tag} — source: ${f.source}`;
             }).join("\n");
-            return { content: [{ type: "text", text: `Fees for ${data.projectKey}:\n\n${lines}\n\nFull data:\n${JSON.stringify(data, null, 2)}` }] };
+            return { content: [{ type: "text", text: `Fees for ${data.workspaceKey}:\n\n${lines}\n\nFull data:\n${JSON.stringify(data, null, 2)}` }] };
         },
     },
     vouch_for_partner: {
@@ -1536,7 +1573,7 @@ Custom event names are accepted (the spec is open by default), but agents should
     // Pair with the AudienceActivationWizard (Layer 2) to give agents
     // a way to wire up audience instrumentation without leaving the
     // editor. Both tools are PROJECT-SCOPED via the api-client's
-    // active-project context — the merchant's CLI run pins which
+    // active-workspace context — the merchant's CLI run pins which
     // workspace they're acting on.
     wire_audience_seed: {
         description: `${APEX} — Wire up the events and traits a campaign audience seed depends on. Use this when the merchant says "wire up the active customers audience" or after the AudienceActivationWizard's Screen 1 hands off to Cursor. Returns the per-event/trait code snippets, the file recommendations, and fires a test event with is_test=1 so the wizard's polling loop confirms the wiring landed end-to-end. Idempotent: calling twice does NOT double-instrument; the agent should still review existing code before adding the snippet.`,
@@ -1554,13 +1591,13 @@ Custom event names are accepted (the spec is open by default), but agents should
                 .describe("When true (default), fires a test event with is_test=1 for each event the seed depends on. The wizard's poll loop sees these and advances. Set to false if the agent only wants to read the snippets without writing test data."),
         }),
         handler: async ({ seedId, framework = "typescript", fireTestEvent = true, }) => {
-            const projectKey = getActiveProject() || process.env.APEX_PROJECT_KEY;
-            if (!projectKey) {
+            const workspaceKey = getActiveWorkspace() || (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY);
+            if (!workspaceKey) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: "No active project. Call set_active_project first or set APEX_PROJECT_KEY.",
+                            text: "No active workspace. Call set_active_project first or set APEX_PROJECT_KEY.",
                         },
                     ],
                 };
@@ -1622,7 +1659,7 @@ Custom event names are accepted (the spec is open by default), but agents should
                     ? `## Test events fired\nFired test events for: ${firedTests.join(", ")}. The wizard's polling loop will see these and advance. Confirm the merchant fires REAL events from production code paths before relying on the audience.`
                     : `## Test events\nNo test events fired (per fireTestEvent=false). Run the wizard's "Send a test event" button manually after wiring.`,
                 ``,
-                `Project: ${projectKey}`,
+                `Workspace: ${workspaceKey}`,
             ].join("\n");
             return { content: [{ type: "text", text: summary }] };
         },
@@ -1643,13 +1680,13 @@ Custom event names are accepted (the spec is open by default), but agents should
                 .describe("When true (default), fires a test event with is_test=1 for each NON-AUTO-FIRED event the audience depends on. Auto-fired events (pageview, click, etc.) are skipped — they're already firing automatically and don't need a synthetic test."),
         }),
         handler: async ({ audienceId, framework = "typescript", fireTestEvent = true, }) => {
-            const projectKey = getActiveProject() || process.env.APEX_PROJECT_KEY;
-            if (!projectKey) {
+            const workspaceKey = getActiveWorkspace() || (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY);
+            if (!workspaceKey) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: "No active project. Call set_active_project first or set APEX_PROJECT_KEY.",
+                            text: "No active workspace. Call set_active_project first or set APEX_PROJECT_KEY.",
                         },
                     ],
                 };
@@ -1718,7 +1755,7 @@ Custom event names are accepted (the spec is open by default), but agents should
             else {
                 sections.push(`\n## Test events\nNo test events fired (per fireTestEvent=false). Run the wizard's "Send a test event" button manually after wiring.`);
             }
-            sections.push(`\nProject: ${projectKey}`);
+            sections.push(`\nWorkspace: ${workspaceKey}`);
             return { content: [{ type: "text", text: sections.join("\n") }] };
         },
     },
@@ -1730,13 +1767,13 @@ Custom event names are accepted (the spec is open by default), but agents should
                 .describe("Audience id (the workspace's audience record, not the seed). Use list_audiences first to find it."),
         }),
         handler: async ({ audienceId }) => {
-            const projectKey = getActiveProject() || process.env.APEX_PROJECT_KEY;
-            if (!projectKey) {
+            const workspaceKey = getActiveWorkspace() || (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY);
+            if (!workspaceKey) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: "No active project. Call set_active_project first or set APEX_PROJECT_KEY.",
+                            text: "No active workspace. Call set_active_project first or set APEX_PROJECT_KEY.",
                         },
                     ],
                 };
@@ -1765,7 +1802,7 @@ Custom event names are accepted (the spec is open by default), but agents should
                 preview && preview.matchingCount === 0
                     ? `\n## Diagnosis\nZero matches. Most likely causes:\n  1. Events the predicate references aren't firing yet from the merchant's codebase. Run \`wire_audience_seed\` if this is a starter audience, or check the predicate's event names against your codebase.\n  2. The predicate's window (\`last_n_days\`, \`ever\`) is too narrow.\n  3. End-user identity isn't being stitched. Each \`apex.track()\` call must include \`endUserId\` in its data payload, or be preceded by an \`identify()\` call.\n`
                     : "",
-                `\nProject: ${projectKey}`,
+                `\nWorkspace: ${workspaceKey}`,
             ].join("\n");
             return { content: [{ type: "text", text: summary }] };
         },
@@ -1934,7 +1971,7 @@ Custom event names are accepted (the spec is open by default), but agents should
         description: `${APEX} — READ-ONLY. Returns the current Set up Apex state for the active workspace: which steps the merchant has marked complete or skipped, plus the live signal flags (snippet installed, mobile live, sender domain verified, etc.). Use to answer "where am I in onboarding?" or to surface "your next step is X" recommendations. WRITE tools (complete_setup_step, skip_setup_step) are deliberately NOT exposed pending a server-enforced confirmation nonce.`,
         schema: z.object({}),
         handler: async () => {
-            // The active project key is encoded in the x-apex-project header
+            // The active workspace key is encoded in the x-apex-workspace header
             // that apiGet sends automatically.
             const data = await apiGet("/api/setup-state");
             const { overrides, signal, workspaceKey } = data.data;
@@ -1973,7 +2010,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
                 .describe("Include archived sources. Defaults to false."),
         }),
         handler: async ({ includeArchived }) => {
-            const proj = getActiveProject();
+            const proj = getActiveWorkspace();
             const qs = includeArchived ? "?includeArchived=true" : "";
             const json = await apiGet(`/api/workspaces/${proj}/data-sources${qs}`);
             const sources = json.data ?? [];
@@ -1993,7 +2030,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             name: z.string().describe("Display name, e.g. 'Marketing site' or 'Backend API'."),
         }),
         handler: async ({ kind, name }) => {
-            const proj = getActiveProject();
+            const proj = getActiveWorkspace();
             const json = await apiPost(`/api/workspaces/${proj}/data-sources`, { kind, name });
             const s = json.data;
             return { content: [{ type: "text", text: `✓ Created data source **${s.name}** (${s.kind}) — ${s.status} · \`${s.id}\`` }] };
@@ -2005,7 +2042,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             id: z.string().describe("The data source id (ds_...)."),
         }),
         handler: async ({ id }) => {
-            const proj = getActiveProject();
+            const proj = getActiveWorkspace();
             const json = await apiGet(`/api/workspaces/${proj}/data-sources/${encodeURIComponent(id)}/health`);
             const h = json.data;
             return { content: [{ type: "text", text: `# ${h.kind} source ${h.id}\n\n- status: **${h.status}**\n- first seen: ${h.firstSeenAt ?? "never"}\n- last seen: ${h.lastSeenAt ?? "never"}` }] };
@@ -2041,5 +2078,109 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             return { content: [{ type: "text", text: hosts.length ? `# Hostnames (${hosts.length})\n\n${lines.join("\n")}` : "No hostnames seen yet." }] };
         },
     },
+    get_event_spec: {
+        description: `${APEX} — The canonical event reference for instrumenting Apex tracking: every event name, its fields (with required/optional markers), and example payloads, as a JSON Schema bundle. Call this BEFORE wiring apex.track()/Apex.track() calls or Server Events API posts into a codebase so you use canonical names and field shapes. Pair with get_wiring_status to verify your instrumentation afterwards.`,
+        schema: z.object({
+            event: z.string().optional().describe("Return only this event's schema (canonical name, e.g. 'add_to_cart'). Omit for the full bundle."),
+        }),
+        handler: async ({ event }) => {
+            const res = await apiGet("/api/spec/events");
+            const bundle = res.data ?? {};
+            if (event) {
+                const all = (bundle.events ?? {});
+                const match = all[event];
+                if (!match) {
+                    const names = Object.keys(all).slice(0, 50).join(", ");
+                    return {
+                        content: [{ type: "text", text: `Unknown event "${event}". Known events include: ${names}` }],
+                    };
+                }
+                return {
+                    content: [{ type: "text", text: `# ${event}\n\n\`\`\`json\n${JSON.stringify(match, null, 2)}\n\`\`\`` }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: `# Apex event reference\n\n\`\`\`json\n${JSON.stringify(bundle, null, 2)}\n\`\`\`` }],
+            };
+        },
+    },
+    get_wiring_status: {
+        description: `${APEX} — Live wiring verification for the active workspace: which canonical events have been received (tier: waiting → detected → verified), which identify traits (first_name, email, …) are arriving, per-data-source status, and which journey/communication templates are Ready to run. Call this AFTER instrumenting tracking code to verify your own work — iterate until each wired event reports "detected". Presence-only: never returns end-user values.`,
+        schema: z.object({}),
+        handler: async () => {
+            const workspaceKey = getActiveWorkspace();
+            if (!workspaceKey) {
+                return {
+                    content: [{ type: "text", text: "No active workspace. Use switch_project first (or set APEX_PROJECT_KEY)." }],
+                };
+            }
+            const json = await apiGet(`/api/workspaces/${encodeURIComponent(workspaceKey)}/readiness`);
+            const d = json.data;
+            const eventLines = d.events.map((e) => `- ${e.name}: ${e.tier} (${e.count.toLocaleString()} events, platforms: ${e.platforms.join("/") || "—"})${e.observedFields?.length ? ` — fields seen: ${e.observedFields.join(", ")}` : ""}`);
+            const traitLines = d.traits.map((t) => `- ${t.name}: ${t.present ? "arriving" : "not seen"}${t.inferredType ? ` (${t.inferredType})` : ""}`);
+            const sourceLines = d.sources.map((s) => `- ${s.name} (${s.kind}): ${s.status}${s.lastSeenAt ? ` — last event ${s.lastSeenAt}` : ""}`);
+            const readyTemplates = d.templates.filter((t) => t.ready);
+            const blockedTemplates = d.templates.filter((t) => !t.ready);
+            const templateLines = [
+                ...readyTemplates.map((t) => `- ✅ ${t.title} (${t.templateKind}) — Ready to run`),
+                ...blockedTemplates.slice(0, 10).map((t) => `- ⏳ ${t.title} (${t.templateKind}) — needs ${[...t.missingEvents, ...t.missingTraits].join(", ") || "?"}`),
+            ];
+            const milestones = [
+                d.milestones.firstEventAt ? `First event: ${d.milestones.firstEventAt}` : "First event: not yet",
+                d.milestones.firstIdentifiedAt ? `First identified customer: ${d.milestones.firstIdentifiedAt}` : "First identified customer: not yet",
+            ];
+            return {
+                content: [{
+                        type: "text",
+                        text: `# Wiring status — ${workspaceKey}\n\n## Milestones\n${milestones.map((m) => `- ${m}`).join("\n")}\n\n## Events received\n${eventLines.join("\n") || "_none yet_"}\n\n## Identify traits\n${traitLines.join("\n") || "_none yet_"}\n\n## Data sources\n${sourceLines.join("\n") || "_none yet_"}\n\n## Templates\n${templateLines.join("\n") || "_none derivable yet_"}`,
+                    }],
+            };
+        },
+    },
+    propose_wiring_plan: {
+        description: `${APEX} — Report the Apex Spec instrumentation opportunities you found by SCANNING the merchant's codebase (auth flows → identify + user_signed_up, checkout → purchase events, forms → form_submit, app purchases → in_app_purchase, server order paths → order_placed, …). Call this BEFORE wiring: the plan appears on the merchant's setup page as pending lights, each flipping green when its first real event arrives. Structure your scan report in three sections: (1) ALREADY WIRED — events the repo already instruments (include them here with wired: true; they're awaiting their first heartbeat), (2) GAPS TO WIRE — the work you propose, (3) WON'T WIRE + WHY — opportunities you're deliberately skipping (e.g. a server event with no backend, or a form that already fires a richer dedicated event). Then instrument each gap where the truth lives and verify with get_wiring_status. Scan first; never ask the merchant to enumerate events for you.`,
+        schema: z.object({
+            events: z
+                .array(z.object({
+                name: z
+                    .string()
+                    .describe("Canonical snake_case event name from the Apex Spec (use get_event_spec), or a custom snake_case name."),
+                surface: z
+                    .enum(["web", "mobile", "server"])
+                    .describe("Where this event should fire FROM — wire each event where the truth lives."),
+                note: z
+                    .string()
+                    .optional()
+                    .describe("Short pointer to where you found the opportunity, e.g. 'checkout/confirm.ts handlePayment()'."),
+                wired: z
+                    .boolean()
+                    .optional()
+                    .describe("True when the repo ALREADY instruments this event (awaiting its first heartbeat) — the merchant's board labels it 'wired' instead of 'agent plan'."),
+            }))
+                .min(1)
+                .describe("Every instrumentation opportunity found in the scan — both already-wired events (wired: true) and the gaps you propose to wire."),
+            summary: z.string().optional().describe("One-paragraph scan summary for the merchant — include what you're deliberately NOT wiring and why."),
+        }),
+        handler: async (args) => {
+            const workspaceKey = getActiveWorkspace();
+            if (!workspaceKey) {
+                return {
+                    content: [{ type: "text", text: "No active workspace. Use switch_project first (or set APEX_PROJECT_KEY)." }],
+                };
+            }
+            const json = await apiPost(`/api/workspaces/${encodeURIComponent(workspaceKey)}/wiring-plan`, {
+                events: args.events,
+                summary: args.summary,
+                source: "mcp",
+            });
+            const lines = json.data.events.map((e) => `- ${e.name} (${e.surface})${e.wired ? " — already wired, awaiting first heartbeat" : ""}`);
+            return {
+                content: [{
+                        type: "text",
+                        text: `# Wiring plan proposed — ${workspaceKey}\n\nThe merchant's setup page now shows ${json.data.events.length} pending event light${json.data.events.length === 1 ? "" : "s"}:\n${lines.join("\n")}\n\nNext: instrument each gap where it happens in the code (smallest change, never commit), then call get_wiring_status until every light reports "detected".`,
+                    }],
+            };
+        },
+    },
 };
 //# sourceMappingURL=tools.js.map