@apex-inc/mcp-server 0.32.0 → 0.34.0

package/dist/tools/measurement.js

@@ -0,0 +1,1353 @@
+import { z } from "zod";
+import { apiGet, apiPost, apiPatch, apiPut, postWithIdempotency, getActiveWorkspace, } from "../api-client.js";
+import { getPersonLabel, lowerPerson } from "../person-label.js";
+import { APEX, MCP_AGENT_VISITOR_ID, windowQuery, } from "../tool-shared.js";
+export const measurementTools = {
+    list_events: {
+        description: `${APEX} — List the workspace's ACTIVE events: the canonical event names actually firing, with total volume and the platforms they arrive on, from the ingest catalog. Use this to discover which events exist / are wired before choosing a primary metric or guardrail in create_experiment, or to confirm an event is live. Distinct from list_metrics (which lists typed rate/revenue/duration GOALS) — this is the raw observed-event catalog.`,
+        schema: z.object({
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("Max events to return, by volume descending (default 50)."),
+        }),
+        handler: async (args) => {
+            const catalog = await apiGet("/api/events/catalog");
+            const rows = catalog?.events ?? [];
+            // Aggregate per event name across platforms (the catalog is keyed by
+            // (eventName, platform); the agent wants one row per event).
+            const byName = new Map();
+            for (const r of rows) {
+                const e = byName.get(r.eventName) ?? { count: 0, platforms: new Set() };
+                e.count += r.count ?? 0;
+                if (r.platform)
+                    e.platforms.add(r.platform);
+                byName.set(r.eventName, e);
+            }
+            const events = [...byName.entries()]
+                .map(([name, v]) => ({
+                event: name,
+                count: v.count,
+                platforms: [...v.platforms].sort(),
+            }))
+                .sort((a, b) => b.count - a.count)
+                .slice(0, args.limit ?? 50);
+            if (events.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No active events yet — nothing has been tracked in this workspace. Install the snippet / SDK and fire events, then re-check.`,
+                        },
+                    ],
+                };
+            }
+            const lines = events.map((e) => `  • ${e.event} — ${e.count.toLocaleString()} events (${e.platforms.join(", ") || "web"})`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Active events (${events.length}, by volume):`,
+                            ...lines,
+                            ``,
+                            `Pick a measurable OUTCOME event (e.g. purchase/signup) as primaryMetricEvent in create_experiment. Use list_metrics to see which are typed goals.`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    list_metrics: {
+        description: `${APEX} — List the canonical metric/goal catalog for this workspace: typed metrics (rate/revenue/duration) with whether each is DETECTED (firing, with volume) and its outcome tier. Use this to pick a measurable OUTCOME goal (purchase/signup) over a proxy (email_open) before create_experiment, or role:'guardrail' to see protective harm signals.`,
+        schema: z.object({
+            onlyMeasurable: z
+                .boolean()
+                .optional()
+                .describe("Only return metrics the engine can estimate today (default true)."),
+            role: z
+                .enum(["goal", "guardrail"])
+                .optional()
+                .describe("Filter to goal metrics (optimize) or guardrail metrics (protect against harm)."),
+        }),
+        handler: async ({ onlyMeasurable, role }) => {
+            const res = await apiGet(role ? `/api/metrics/catalog?role=${role}` : "/api/metrics/catalog");
+            const all = res.data ?? [];
+            const list = (onlyMeasurable === false ? all : all.filter((m) => m.measurable)).slice(0, 60);
+            if (list.length === 0) {
+                return {
+                    content: [{ type: "text", text: `${APEX} No metrics in the catalog yet.` }],
+                };
+            }
+            const lines = list
+                .map((m) => {
+                const tags = [
+                    m.type,
+                    m.outcomeTier === "proximal" ? "proxy" : m.outcomeTier,
+                    m.wired === "detected"
+                        ? `DETECTED${m.trailingVolume ? ` (${m.trailingVolume})` : ""}`
+                        : "not firing",
+                    m.measurable ? null : "not measurable",
+                ]
+                    .filter(Boolean)
+                    .join(", ");
+                return `  • ${m.key} — ${m.label} (${tags})`;
+            })
+                .join("\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Metric catalog (${list.length})`,
+                            `${"═".repeat(40)}`,
+                            lines,
+                            ``,
+                            `Prefer a DETECTED outcome metric. Pass its event to create_experiment as primaryMetricEvent (+ primaryMetricType 'revenue' for value goals).`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    get_growth_reality: {
+        description: `${APEX} — "Is our growth real?" Per goal, the cumulative lift of everything Apex did (journeys + experiments) vs a persistent do-nothing global holdout, with a 95% CI. The honest, holdout-gated answer to "would this have happened anyway?" Forward-only; goals still collecting are flagged, not faked.`,
+        schema: z.object({
+            days: z
+                .union([z.number(), z.literal("all")])
+                .optional()
+                .describe("Trailing window in days, or 'all' for since-inception (default)."),
+        }),
+        handler: async ({ days }) => {
+            const q = days && days !== "all" ? `?days=${days}` : "?days=all";
+            const res = await apiGet(`/api/growth/reality${q}`);
+            const goals = res.data?.goals ?? [];
+            if (goals.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No growth-reality data yet. Counting is forward-only from when the global holdout went live — check back once exposed + holdout cohorts are flowing.`,
+                        },
+                    ],
+                };
+            }
+            const pctFmt = (v) => v == null ? "—" : `${v > 0 ? "+" : ""}${(v * 100).toFixed(1)}%`;
+            const lines = goals.map((g) => {
+                if (!g.isDecisive) {
+                    return `  • ${g.goalName}: COLLECTING (directional ${pctFmt(g.lift)}, since ${g.collectingSince || "—"})`;
+                }
+                const ci = g.liftCI
+                    ? ` [${pctFmt(g.liftCI.lower)}, ${pctFmt(g.liftCI.upper)}]`
+                    : "";
+                const rev = typeof g.incrementalRevenue === "number"
+                    ? ` · ~$${Math.round(g.incrementalRevenue).toLocaleString()} incremental`
+                    : "";
+                return `  • ${g.goalName}: ${pctFmt(g.lift)} vs holdout${ci} — DECISIVE${rev}`;
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Is our growth real? (vs ${res.data?.holdoutPct ?? 5}% do-nothing holdout)`,
+                            `${"═".repeat(40)}`,
+                            ...lines,
+                            ``,
+                            `Decisive = both cohorts cleared the minimum size AND the CI excludes zero. Everything else is directional, not proven.`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    get_channel_economics: {
+        description: `${APEX} — "Where should my next dollar go?" Per acquisition channel (raw first-touch): LTGP:CAC (lifetime gross profit over CAC) where the merchant reports product cost, LTV:CAC (lifetime revenue over CAC) everywhere else, plus payback months, CAC, and customers, split into Acquisition (paid) vs Leverage (owned/organic, no spend). Computed from real contacts + spend + revenue — metrics with missing inputs are shown as "—", never fabricated. Free intelligence; the verdict is never gated.`,
+        schema: z.object({
+            days: z
+                .union([z.number(), z.literal("all")])
+                .optional()
+                .describe("Trailing window in days, or 'all' for since-inception (default)."),
+        }),
+        handler: async ({ days }) => {
+            const q = days && days !== "all" ? `?days=${days}` : "?days=all";
+            const res = await apiGet(`/api/channels/economics${q}`);
+            const channels = res.data?.channels ?? [];
+            if (channels.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No channel economics yet — connect attributed traffic (Apex Links auto-tag it) and revenue so acquisition channels can be measured.`,
+                        },
+                    ],
+                };
+            }
+            const label = (slug) => ({
+                linkedin: "LinkedIn Ads",
+                google: "Google",
+                meta: "Meta",
+                microsoft: "Microsoft Ads",
+                tiktok: "TikTok",
+                twitter: "Twitter / X",
+                direct: "Direct",
+                email: "Email",
+                affiliate: "Partner Network",
+            })[slug] ?? slug.charAt(0).toUpperCase() + slug.slice(1);
+            const money = (n) => n == null ? "—" : `$${Math.round(n).toLocaleString()}`;
+            const ratio = (r) => (r == null ? "—" : `${r.toFixed(2)}x`);
+            // Each channel is ranked on its best available multiple. Both are real
+            // metrics — LTGP:CAC nets out cost of goods, LTV:CAC doesn't — so the
+            // line names which one it printed rather than dropping the number.
+            const best = (c) => c.ltgpCac ?? c.ltvCac;
+            const metric = (c) => c.ltgpCac !== null ? "LTGP:CAC" : "LTV:CAC";
+            const ranked = [...channels].sort((a, b) => (best(b) ?? -1) - (best(a) ?? -1));
+            const acquisition = ranked.filter((c) => c.spend !== null && c.spend > 0);
+            const leverage = ranked.filter((c) => c.spend === null || c.spend === 0);
+            // The merchant reads this back on a screen that says "Leads" or
+            // "Clients" if that's their vertical — say the same word they do.
+            const person = lowerPerson(await getPersonLabel());
+            const fmt = (c) => `  • ${label(c.channel)}: ${ratio(best(c))} ${metric(c)} · payback ${c.paybackMonths != null ? `${c.paybackMonths}mo` : "—"} · CAC ${money(c.cac)} · ${c.customers.toLocaleString()} ${person.plural}`;
+            const lines = [
+                `${APEX} Channel economics — LTGP:CAC where product cost is reported, LTV:CAC otherwise`,
+                "═".repeat(40),
+            ];
+            if (res.data?.needsReferee) {
+                lines.push("Revenue figures hidden: two live revenue sources with no referee picked. Choose one in Connect revenue.", "");
+            }
+            if (acquisition.length > 0) {
+                lines.push("Acquisition (paid):", ...acquisition.map(fmt), "");
+            }
+            if (leverage.length > 0) {
+                lines.push("Leverage (owned / organic):", ...leverage.map(fmt), "");
+            }
+            lines.push(`3-5x is healthy; <1x loses money on every ${person.label}; >5x is likely underinvested.`);
+            if (ranked.some((c) => c.ltgpCac === null && c.ltvCac !== null)) {
+                lines.push(`(Channels above marked LTV:CAC are measured on revenue. Send product.unit_cost on every purchased item and Apex reports LTGP:CAC for them too — the same read with cost of goods netted out. unit_cost is PER UNIT and gets multiplied by quantity; if you only know the order's total cost, send cost at the order level instead. Cost is all-or-nothing per order: an order with an uncosted line contributes to LTV:CAC only, so a partial rollout never inflates gross profit.)`);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    // ─── Vertical Widget Packs read tools (2026-07-02) ─────────────────────
+    // One tool per pack read API. All aggregate-only (analytics:read scope);
+    // small-n suppression applies to API responses exactly as to widgets.,
+    get_saas_recurring_revenue: {
+        description: `${APEX} — SaaS recurring-revenue economics: MRR, ARR, the monthly waterfall (new / expansion / reactivation / contraction / churn — accounting-identity tested), and NRR/GRR for the last complete month. Computed from materialized monthly snapshots (calendar months, UTC); the current month is flagged in-progress. NRR/GRR read "collecting history" until 13 months of snapshots exist — never fabricated.`,
+        schema: z.object({
+            months: z
+                .number()
+                .optional()
+                .describe("Months of waterfall history to include (2-36, default 13)."),
+            start: z
+                .string()
+                .optional()
+                .describe("Explicit window start, YYYY-MM-DD (mapped to calendar months; use with end — overrides months)."),
+            end: z
+                .string()
+                .optional()
+                .describe("Explicit window end, YYYY-MM-DD (use with start)."),
+        }),
+        handler: async ({ months, start, end }) => {
+            const q = windowQuery({ months, start, end });
+            const res = await apiGet(`/api/saas/recurring-revenue${q}`);
+            const d = res.data;
+            if (!d?.hasData) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No MRR state yet — connect Stripe or send subscription events (subscription_started / subscription_event with amount + period_type) and monthly snapshots build from there.`,
+                        },
+                    ],
+                };
+            }
+            const money = (n) => n == null ? "—" : `$${Math.round(n).toLocaleString()}`;
+            const pct = (r) => r == null ? "collecting history" : `${Math.round(r * 1000) / 10}%`;
+            const lines = [
+                `${APEX} Recurring revenue`,
+                "═".repeat(40),
+                `MRR ${money(d.currentMrr)} (month in progress) · ARR ${money(d.currentArr)} · ${d.payingAccounts ?? "—"} paying accounts`,
+                `NRR ${pct(d.retention?.nrr ?? null)} · GRR ${pct(d.retention?.grr ?? null)} (trailing 12mo, ${d.retention?.cohortSize ?? 0}-account cohort)`,
+                "",
+                "Waterfall (last months):",
+                ...d.waterfall
+                    .slice(-6)
+                    .map((m) => `  • ${m.month}${m.inProgress ? " (in progress)" : ""}: ${money(m.startMrr)} → ${money(m.endMrr)}  (+${money(m.newMrr)} new, +${money(m.expansionMrr)} expansion, +${money(m.reactivationMrr)} reactivation, −${money(m.contractionMrr)} contraction, −${money(m.churnedMrr)} churn)`),
+            ];
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    get_saas_expansion: {
+        description: `${APEX} — SaaS expansion economics: expansion vs contraction MRR for the last complete month, accounts expanding (counts — small-n honest), and seat growth from seat_count. Metrics with missing inputs come back null, never fabricated.`,
+        schema: z.object({
+            months: z
+                .number()
+                .optional()
+                .describe("Months of series history to include (2-36, default 13)."),
+            start: z
+                .string()
+                .optional()
+                .describe("Explicit window start, YYYY-MM-DD (mapped to calendar months; use with end — overrides months)."),
+            end: z
+                .string()
+                .optional()
+                .describe("Explicit window end, YYYY-MM-DD (use with start)."),
+        }),
+        handler: async ({ months, start, end }) => {
+            const q = windowQuery({ months, start, end });
+            const res = await apiGet(`/api/saas/expansion${q}`);
+            const d = res.data;
+            if (!d?.hasData) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No subscription data yet — expansion metrics unlock once MRR snapshots exist.`,
+                        },
+                    ],
+                };
+            }
+            const money = (n) => n == null ? "—" : `$${Math.round(n).toLocaleString()}`;
+            const seatsLine = d.seatCount != null
+                ? `Seats: ${d.seatCount}${d.seatCountPrevMonth != null ? ` (${d.seatCount - d.seatCountPrevMonth >= 0 ? "+" : ""}${d.seatCount - d.seatCountPrevMonth} vs last month)` : ""}`
+                : "Seats: — (send seat_count on subscription events to unlock)";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Expansion (last complete month)`,
+                            "═".repeat(40),
+                            `Expansion MRR ${money(d.expansionMrrLastMonth)} · Contraction MRR ${money(d.contractionMrrLastMonth)}`,
+                            `Accounts expanding: ${d.expandedAccounts ?? "—"} of ${d.payingAccountsAtStart ?? "—"} paying at month start`,
+                            seatsLine,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    get_ecommerce_product_sales: {
+        description: `${APEX} — E-commerce product sales: top products by revenue with the per-product view → add-to-cart → purchase funnel and refund counts. Products need a product_id on commerce events; never-wired signals are reported as unwired, not zero.`,
+        schema: z.object({
+            days: z.number().optional().describe("Trailing window in days (default 90, max 396 — the 13-month event log)."),
+            start: z
+                .string()
+                .optional()
+                .describe("Explicit window start, YYYY-MM-DD (use with end — overrides days)."),
+            end: z
+                .string()
+                .optional()
+                .describe("Explicit window end, YYYY-MM-DD (use with start)."),
+        }),
+        handler: async ({ days, start, end }) => {
+            const q = windowQuery({ days, start, end });
+            const res = await apiGet(`/api/ecommerce/product-sales${q}`);
+            const d = res.data;
+            if (!d?.hasData) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No product-scoped events yet — fire product_view / add_to_cart / purchases with a product_id.`,
+                        },
+                    ],
+                };
+            }
+            const money = (n) => `$${Math.round(n).toLocaleString()}`;
+            const lines = [
+                `${APEX} Product sales — ${money(d.totals.revenue)} product revenue, ${d.totals.purchases} purchases`,
+                "═".repeat(40),
+                ...d.items
+                    .slice(0, 10)
+                    .map((i) => `  • ${i.label ?? i.itemKey}${i.category ? ` [${i.category}]` : ""}: ${money(i.revenue)} · ${i.views} views → ${i.adds} adds → ${i.purchases} purchases${i.refunds > 0 ? ` · ${i.refunds} refunds` : ""}`),
+            ];
+            if (!d.wired.views)
+                lines.push("(product_view not wired — funnel rates unavailable)");
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    list_product_costs: {
+        description: `${APEX} — What each product costs, and which ones Apex has no cost for. Lists every SKU with a declared cost PLUS every SKU the merchant's orders have sold in the last 30 days, so an uncosted product is visible rather than merely absent. Apex reports gross profit and LTGP:CAC only where cost is known, so the uncosted rows are the gap worth closing. Two columns matter: "orders" is the per-unit cost the merchant's own purchase events reported (preferred — it tracks their real costs over time), "declared" is a standing cost set in Apex that fills orders reporting none. Use this before set_product_cost so you never overwrite a cost that is already right.`,
+        schema: z.object({
+            uncostedOnly: z
+                .boolean()
+                .optional()
+                .describe("Only SKUs with no cost from either route — the actionable list."),
+            limit: z.number().optional().describe("Max rows to show (default 25)."),
+        }),
+        handler: async ({ uncostedOnly, limit, }) => {
+            const res = await apiGet("/api/products");
+            const all = res.data?.products ?? [];
+            if (all.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            // Not "no products" — an empty list here means Apex has neither a
+                            // declared cost NOR an order it could name a product from, and
+                            // those are different problems with different fixes.
+                            text: `${APEX} No products on file. Apex lists a product once it either has a declared cost or appears on an order — so send purchase events with product_id on each line item (see get_apex_spec for "order_placed"), or connect Shopify to import variant costs.`,
+                        },
+                    ],
+                };
+            }
+            const costKnown = (p) => p.costUsd !== undefined || p.unitCostUsd !== undefined;
+            const rows = uncostedOnly ? all.filter((p) => !costKnown(p)) : all;
+            const money = (n) => `$${n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+            const withCost = all.filter(costKnown).length;
+            const lines = [
+                `${APEX} Product cost — Apex knows the cost of ${withCost} of ${all.length} products`,
+                "═".repeat(40),
+                ...rows.slice(0, limit ?? 25).map((p) => {
+                    const observed = p.unitCostUsd !== undefined
+                        ? `orders ${money(p.unitCostUsd)}`
+                        : "orders: not reported";
+                    const declared = p.costUsd !== undefined
+                        ? `declared ${money(p.costUsd)}${p.costSource ? ` (${p.costSource})` : ""}${p.costEffectiveFrom ? ` from ${p.costEffectiveFrom.slice(0, 10)}` : ""}`
+                        : "declared: none";
+                    const sold = p.revenue !== undefined && p.revenue > 0
+                        ? ` · ${money(p.revenue)} in 30d`
+                        : "";
+                    return `  • ${p.name ?? p.itemKey} [${p.itemKey}]: ${observed} · ${declared}${sold}`;
+                }),
+            ];
+            if (rows.length > (limit ?? 25)) {
+                lines.push(`  … and ${rows.length - (limit ?? 25)} more`);
+            }
+            const uncosted = all.filter((p) => !costKnown(p)).length;
+            if (uncosted > 0) {
+                lines.push("", `${uncosted} product${uncosted === 1 ? "" : "s"} have no cost. The durable fix is sending unit_cost (per unit) on each purchase line item, which keeps up as costs change. Use set_product_cost to declare a standing cost where the checkout can't report one, or to backfill history.`);
+            }
+            if (res.metadata?.observed?.truncated) {
+                lines.push("", "(The 30-day sales scan hit its read cap, so this list is a lower bound — a SKU that sold only in the unread remainder is missing.)");
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    set_product_cost: {
+        description: `${APEX} — Declare what one product costs per unit, so Apex can report gross profit on orders that didn't carry a cost of their own. PREFER instrumenting unit_cost on purchase line items instead where you can: an order carries the cost that was true when it happened, whereas a standing cost declared here is a snapshot that goes stale silently. Use this to backfill history, or for a SKU whose checkout can't report cost. NEVER invent or estimate a cost — a fabricated margin looks measured and is not, and the merchant has no way to tell downstream. Ask them for the number. Rules: the cost is PER UNIT (not a line total), it never overrides a cost an order reported for itself, and it never applies backward before effective_from.`,
+        schema: z.object({
+            item_key: z
+                .string()
+                .describe("The product identifier Apex knows this SKU by — the product_id or sku on the merchant's order lines. Get it from list_product_costs."),
+            cost_usd: z
+                .number()
+                .describe("Cost PER UNIT in USD. A four-figure value on a low-priced item is usually cents typed as dollars; values above 1000000 are refused."),
+            effective_from: z
+                .string()
+                .optional()
+                .describe("ISO date the cost applies from. Defaults to NOW, which is deliberate — defaulting backward would restate the merchant's whole order history at today's supplier price. Pass an explicit date only when they know the older price."),
+            name: z
+                .string()
+                .optional()
+                .describe("Display name, if Apex has no name for this SKU yet."),
+        }),
+        handler: async ({ item_key, cost_usd, effective_from, name, }) => {
+            const res = await apiPut(`/api/products/${encodeURIComponent(item_key)}/cost`, {
+                cost_usd,
+                ...(effective_from ? { effective_from } : {}),
+                ...(name ? { name } : {}),
+            });
+            const d = res.data;
+            if (d && !d.changed) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} ${item_key} already had that cost on file — nothing changed, no log entry written.`,
+                        },
+                    ],
+                };
+            }
+            const from = d?.entry?.effectiveFrom?.slice(0, 10) ?? "now";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${APEX} Set ${item_key} to $${cost_usd.toFixed(2)} per unit, applying from ${from} forward. Orders before that date, and orders that reported their own cost, are untouched. Check list_product_costs to see what's still uncosted.`,
+                    },
+                ],
+            };
+        },
+    },
+    upload_product_catalog: {
+        description: `${APEX} — Tell Apex what the merchant sells, in bulk, BEFORE the first sale. Every other way a product reaches Apex needs a sale to have happened already, so a merchant setting up pre-launch has a catalog Apex knows nothing about. Use this when you can read their catalog from somewhere — a products table, a Shopify/Stripe export, a CSV they hand you. NEVER invent, estimate, or derive a cost from a price: a fabricated margin looks measured and nobody downstream can tell. Ask them, or send only the fields you actually know. cost_usd is applied to orders that report no cost of their own, from effective_from forward. price_usd is reference only — revenue, LTV and gross profit always come from what orders actually report, so a price here can never distort them; it makes the catalog complete before launch and lets Apex flag it when real orders disagree with it. Re-running with the same data is safe. Max 500 products per call — page through a larger catalog. This does not replace instrumenting unit_cost on purchase line items, which stays the durable fix because an order then carries the cost that was true when it happened; a catalog cost is a snapshot that goes stale silently.`,
+        schema: z.object({
+            products: z
+                .array(z.object({
+                item_key: z
+                    .string()
+                    .describe("The identifier the merchant's ORDERS will send for this SKU — their product_id or sku. If this doesn't match what the order lines carry, Apex can't connect the two."),
+                name: z.string().optional().describe("Display name."),
+                cost_usd: z
+                    .number()
+                    .optional()
+                    .describe("What the product costs the MERCHANT, per unit. Omit rather than guess."),
+                price_usd: z
+                    .number()
+                    .optional()
+                    .describe("What the merchant SELLS it for, per unit. Reference data — never used as revenue."),
+                effective_from: z
+                    .string()
+                    .optional()
+                    .describe("ISO date cost_usd applies from. Defaults to now, which is deliberate — defaulting backward would restate order history at today's supplier price."),
+            }))
+                .describe("Up to 500 products. Each needs item_key plus at least one of name, cost_usd, price_usd."),
+        }),
+        handler: async ({ products, }) => {
+            const res = await apiPost("/api/products", { products });
+            const d = res.data;
+            if (!d) {
+                return {
+                    content: [
+                        { type: "text", text: `${APEX} Catalog upload returned no result.` },
+                    ],
+                };
+            }
+            const parts = [
+                `${APEX} Saved ${d.upserted} product${d.upserted === 1 ? "" : "s"} — ${d.costChanged} with a new cost, ${d.priceSet} with a price.`,
+            ];
+            if (d.rejected > 0) {
+                // Named rather than counted: a rejected row is a line the merchant can
+                // fix, and "12 rejected" sends them back through the whole file.
+                const listed = (d.errors ?? [])
+                    .slice(0, 10)
+                    .map((e) => `  - ${e.item_key || "(no item_key)"}: ${e.error}`)
+                    .join("\n");
+                parts.push(`${d.rejected} row${d.rejected === 1 ? "" : "s"} rejected:\n${listed}`);
+                if ((d.errors?.length ?? 0) > 10) {
+                    parts.push(`…and ${(d.errors?.length ?? 0) - 10} more.`);
+                }
+            }
+            parts.push(`Costs apply only to orders that report no cost of their own. The durable fix is still sending unit_cost on each purchase line item — run list_product_costs once orders start arriving to see what's still uncovered.`);
+            return { content: [{ type: "text", text: parts.join("\n\n") }] };
+        },
+    },
+    get_ecommerce_returns: {
+        description: `${APEX} — E-commerce returns & refunds: refund rate (money back, order basis), return rate (goods back — separate metric, never summed), reason breakdown, refund cycle time, AOV, and repeat purchase. Refund data lands automatically from Stripe; return_requested / return_completed events power the goods-back story.`,
+        schema: z.object({
+            days: z.number().optional().describe("Trailing window in days (default 90, max 396 — the 13-month event log)."),
+            start: z
+                .string()
+                .optional()
+                .describe("Explicit window start, YYYY-MM-DD (use with end — overrides days)."),
+            end: z
+                .string()
+                .optional()
+                .describe("Explicit window end, YYYY-MM-DD (use with start)."),
+        }),
+        handler: async ({ days, start, end }) => {
+            const q = windowQuery({ days, start, end });
+            const res = await apiGet(`/api/ecommerce/returns${q}`);
+            const d = res.data;
+            if (!d?.hasData) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No order data in the window yet — connect Stripe or send purchase events.`,
+                        },
+                    ],
+                };
+            }
+            const lines = [
+                `${APEX} Returns & refunds`,
+                "═".repeat(40),
+                `Refunded orders: ${d.refundedOrders} of ${d.ordersInWindow} ($${Math.round(d.refundedAmount).toLocaleString()})`,
+                `Returns (goods back): ${d.returnsCompleted ?? "— (wire return_completed to unlock)"}`,
+                `Refund cycle: ${d.refundCycleHours != null ? `${d.refundCycleHours}h median` : "—"} · AOV: ${d.aov != null ? `$${d.aov}` : "—"} · Repeat: ${d.repeatCustomers} of ${d.purchasingCustomers} customers`,
+            ];
+            if (d.reasons.length > 0) {
+                lines.push("", "Reasons:", ...d.reasons.map((r) => `  • ${r.reason}: ${r.count}`));
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    get_marketplace_metrics: {
+        description: `${APEX} — Marketplace health across six pillars: liquidity (search→transaction, match rate, zero-result searches, unfulfilled demand), supply & demand balance, economics (GMV vs the take — fee_amount is the platform's revenue, GMV never inflates LTV), buyer retention, trust rates, and concentration risk. Sliceable by category / geo / price_band (low-volume slices are suppressed for privacy). Metrics whose events aren't wired come back as unwired hints, never fabricated zeros.`,
+        schema: z.object({
+            days: z.number().optional().describe("Trailing window in days (default 90, max 396 — the 13-month event log)."),
+            start: z
+                .string()
+                .optional()
+                .describe("Explicit window start, YYYY-MM-DD (use with end — overrides days)."),
+            end: z
+                .string()
+                .optional()
+                .describe("Explicit window end, YYYY-MM-DD (use with start)."),
+            category: z.string().optional().describe("Slice: listing category."),
+            geo: z.string().optional().describe("Slice: transaction geo."),
+            priceBand: z.string().optional().describe("Slice: price band (e.g. '100-250')."),
+        }),
+        handler: async ({ days, start, end, category, geo, priceBand, }) => {
+            const params = new URLSearchParams();
+            if (days)
+                params.set("days", String(days));
+            if (start && end) {
+                params.set("start", start);
+                params.set("end", end);
+            }
+            if (category)
+                params.set("category", category);
+            if (geo)
+                params.set("geo", geo);
+            if (priceBand)
+                params.set("price_band", priceBand);
+            const qs = params.toString();
+            const res = await apiGet(`/api/marketplace/metrics${qs ? `?${qs}` : ""}`);
+            const d = res.data;
+            if (!d?.hasData) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No marketplace events yet — wire seller_signup, listing_created, search, offer_submitted, and transaction_completed (with fee_amount, buyer_id, seller_id).`,
+                        },
+                    ],
+                };
+            }
+            if (d.sliceSuppressed) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} That slice has too few participants to report honestly (privacy floor). Broaden the slice.`,
+                        },
+                    ],
+                };
+            }
+            const money = (n) => n == null ? "—" : `$${Math.round(n).toLocaleString()}`;
+            const L = d.liquidity;
+            const lines = [
+                `${APEX} Marketplace metrics`,
+                "═".repeat(40),
+                `Liquidity: ${L.searchersWhoTransacted}/${L.searchers} searchers transacted (7d)` +
+                    (L.searchesWithResultCount > 0
+                        ? ` · ${L.zeroResultSearches}/${L.searchesWithResultCount} zero-result searches`
+                        : "") +
+                    ` · ${L.transactions} transactions / ${L.offers} offers` +
+                    (L.medianHoursToMatch != null ? ` · ${L.medianHoursToMatch}h median to match` : "") +
+                    ` · ${L.buyersUnfulfilled}/${L.buyersWithIntent} buyers unfulfilled`,
+                `Supply & demand: ${d.supplyDemand.activeBuyers} buyers · ${d.supplyDemand.activeSellers} sellers (${d.supplyDemand.sellersWithTransaction} transacting) · ${d.supplyDemand.newListings} new listings`,
+                `Economics: GMV ${money(d.economics.gmv)} (refund-adj ${money(d.economics.refundAdjustedGmv)}) · take ${money(d.economics.netRevenue)}${d.economics.takeRate != null ? ` (${Math.round(d.economics.takeRate * 1000) / 10}%)` : ""} · contribution ${money(d.economics.contributionMargin)} · payouts ${money(d.economics.sellerPayouts)} · AOV ${money(d.economics.aov)}`,
+                d.demandMix
+                    ? `Demand mix: paid ${money(d.demandMix.paidGmv)} · organic ${money(d.demandMix.organicGmv)} · unattributed ${money(d.demandMix.unattributedGmv)} (buyer first-touch)`
+                    : "Demand mix: — (needs identified buyers with acquisition attribution)",
+                `Trust: ${d.trust.canceled} cancels · ${d.trust.refunded} refunds · ${d.trust.disputes} disputes over ${d.trust.transactions} transactions` +
+                    (d.trust.averageRating != null ? ` · ${d.trust.averageRating}/5 avg rating` : ""),
+                d.concentration.suppressed
+                    ? `Concentration: needs ≥5 sellers (currently ${d.concentration.sellerCount}) for an honest read`
+                    : `Concentration: top 10% of sellers = ${Math.round((d.concentration.topSellerGmvShare?.top10 ?? 0) * 1000) / 10}% of GMV (${d.concentration.sellerCount} sellers)`,
+            ];
+            if (!d.wired.searches)
+                lines.push("(search not wired — liquidity is partial)");
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    track_event: {
+        description: `${APEX} — Track an event through the Apex Spec.
+
+Identical to the SDK's track() and the snippet's apex.track(). Use this to instrument events from agent workflows, CI pipelines, or IDE actions.
+
+The public Spec is one registry (\`APEX_EVENTS\`): \`page_view\`, \`product_view\`, \`add_to_cart\`, \`checkout_started\`, \`order_placed\`, \`in_app_purchase\`, \`user_signed_up\`, \`waitlist_joined\`, \`user_invited\`, \`user_invite_accepted\`, \`user_identified\`, \`app_open\`, \`session_start\`, \`form_submit\`, \`feature_used\`, \`ui_action\`. Field names are flat snake_case. Named in-product controls are \`ui_action\` with \`action\` + \`name\` + optional \`location\`. SDK helper: \`trackUiAction({ action, name, location })\`.
+
+Custom event names are accepted, but prefer canonical names from GET /api/spec/events so templates, journeys, and conversions wire without aliases. Full spec: 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. They are flagged as agent-fired (source: "mcp") — not test-mode. Fire them deliberately.`,
+        schema: z.object({
+            event: z.string().describe("Event name — snake_case from the Apex Spec (e.g. 'page_view', 'user_signed_up', 'order_placed'). 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", {
+                workspaceKey: (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY) || "default",
+                userId: "mcp-agent",
+                events: [
+                    {
+                        type: event,
+                        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.${wiringNote}${properties ? `\nProperties: ${JSON.stringify(properties)}` : ""}`,
+                    }],
+            };
+        },
+    },
+    send_server_event: {
+        description: `${APEX} — Server Events API. Send a server-to-server event via the /api/v1/events endpoint (clientType: "server", batch cap 100, idempotency-key supported). Use this from agent workflows that simulate backend integrations (Stripe webhook flows, CRM-driven conversions, billing events) or to test the Server Events API end-to-end. Differs from track_event in that it stamps clientType: "server" and uses the v1 ingest contract.`,
+        schema: z.object({
+            type: z.string().describe("Event type (e.g. 'order_placed', 'user_signed_up', or any custom verb)"),
+            visitorId: z.string().optional().describe("Visitor ID to stitch back to a web/mobile session (apex_vid)"),
+            email: z.string().optional().describe("Email to stitch by identity when no visitorId is known"),
+            data: z.record(z.unknown()).optional().describe("Event payload (value, currency, order_id, …)"),
+            environment: z
+                .enum(["production", "preview", "localhost"])
+                .optional()
+                .describe("Dashboard slice only. Omit to leave Unclassified. Never use this to force Production dollars."),
+            release_channel: z
+                .string()
+                .optional()
+                .describe("Optional OS channel (testflight, app-store, xcode-debug, …). Dashboard slice only."),
+            idempotencyKey: z.string().optional().describe("Stable key to prevent double-counting on retry (defaults to a fresh UUID)"),
+        }),
+        handler: async ({ type, visitorId, email, data, environment, release_channel, idempotencyKey, }) => {
+            const key = idempotencyKey ??
+                (typeof globalThis.crypto?.randomUUID === "function"
+                    ? globalThis.crypto.randomUUID()
+                    : `idk_${Date.now()}_${Math.random().toString(36).slice(2, 12)}`);
+            const result = await postWithIdempotency("/api/v1/events", key, {
+                events: [
+                    {
+                        type,
+                        visitorId,
+                        email,
+                        data,
+                        environment,
+                        release_channel,
+                        timestamp: new Date().toISOString(),
+                    },
+                ],
+            });
+            const lines = [
+                `Server Events API event sent: "${type}"`,
+                `  received: ${result.data.received}, duplicates: ${result.data.duplicates}`,
+                `  idempotency-key: ${key}`,
+            ];
+            if (result.data.errors.length > 0) {
+                lines.push(`  errors: ${JSON.stringify(result.data.errors)}`);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    identify_user: {
+        description: `${APEX} — Identify a user by email for identity stitching. Works identically to the SDK's identify() and the snippet's apex.identify(). Links an anonymous visitor to a known email. Pass avatarUrl (a canonical attribute) to give the Contact a profile photo that renders across Apex — the people list, detail page, and Live widget. The workspace's own word for a person (Customer / Lead / Client / User, from its vertical) is what its dashboard shows; use that word when reporting back.`,
+        schema: z.object({
+            email: z.string().describe("User email address"),
+            name: z.string().optional().describe("User name"),
+            company: z.string().optional().describe("Company name"),
+            avatarUrl: z.string().optional().describe("Profile photo URL (https). Maps to the canonical avatar_url attribute; renders across Apex. Validated on write — non-https/invalid URLs are dropped and the UI falls back to initials. From OIDC logins this is the `picture` claim (`photoURL` in Firebase)."),
+            metadata: z.record(z.unknown()).optional().describe("Additional traits"),
+        }),
+        handler: async ({ email, name, company, avatarUrl, metadata }) => {
+            await apiPost("/api/identity/stitch", {
+                visitorId: `mcp-${email}`,
+                email,
+                workspaceKey: (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY) || "default",
+                metadata: { name, company, avatar_url: avatarUrl, ...metadata, source: "mcp" },
+            });
+            const person = lowerPerson(await getPersonLabel());
+            return {
+                content: [{
+                        type: "text",
+                        text: `Identity stitched: ${email}${name ? ` (${name})` : ""}${company ? ` at ${company}` : ""}\nA ${person.label} record has been created/linked in Apex.`,
+                    }],
+            };
+        },
+    },
+    get_schema: {
+        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/schema");
+            const lines = [];
+            for (const entity of Object.values(dict.entities)) {
+                lines.push(`\n${entity.label}  {{${entity.key}.<field>}}`);
+                for (const f of Object.values(entity.fields)) {
+                    const wired = f.source === "discovered" || Boolean(f.lastSeenAt);
+                    const canon = f.canonicalName ? ` -> ${f.canonicalName}` : "";
+                    const surf = f.surfaces?.length ? ` [${f.surfaces.join(",")}]` : "";
+                    lines.push(`  ${wired ? "[wired]" : "[ not ]"} ${f.name}${canon} (${f.type})${surf}`);
+                }
+            }
+            lines.push("\n[wired] = observed in live data   [ not ] = canonical field not sent yet");
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    map_attribute: {
+        description: `${APEX} — Map a discovered field onto its canonical Apex Spec name (e.g. firstName -> first_name) so templates resolve it cleanly at send time. Pass canonicalName: null to clear an existing mapping.`,
+        schema: z.object({
+            entityKey: z
+                .string()
+                .describe("Entity key (user, account, order, product, or a custom entity)"),
+            fieldName: z
+                .string()
+                .describe("The field to map, as stored (e.g. 'firstName')"),
+            canonicalName: z
+                .string()
+                .nullable()
+                .optional()
+                .describe("Canonical snake_case name (e.g. 'first_name'), or null to clear"),
+        }),
+        handler: async ({ entityKey, fieldName, canonicalName, }) => {
+            const res = await apiPost("/api/schema/map", { entityKey, fieldName, canonicalName: canonicalName ?? null });
+            const mapped = res.data?.canonicalName;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: mapped
+                            ? `Mapped ${entityKey}.${fieldName} -> ${mapped}`
+                            : `Cleared canonical mapping on ${entityKey}.${fieldName}`,
+                    },
+                ],
+            };
+        },
+    },
+    define_event: {
+        description: `${APEX} — Define a governed custom event in the workspace's Schema (the customer-extensible registry). Promotes one of the merchant's own events to a first-class, typed, versioned definition that behaves like a canonical Apex Spec event (selectable as a journey trigger/goal, resolvable as comm tokens, validated at ingest). Names must be snake_case and CANNOT shadow a canonical Apex Spec event — call get_event_spec first and reuse the canonical event when one fits. Propose the schema from the merchant's observed payloads (get_schema) and codebase, then confirm with them before defining.`,
+        schema: z.object({
+            name: z.string().describe("snake_case event name, not already in the Apex Spec"),
+            description: z.string().describe("One sentence: when this event fires"),
+            fields: z
+                .record(z.string())
+                .describe('Field name -> type. Types: "string" | "number" | "boolean" | "object" | "array"; append "?" for optional (e.g. {"widget_id":"string","width":"number?"})'),
+            scope: z
+                .enum(["workspace", "org"])
+                .optional()
+                .describe("workspace (default) or org (shared across the org's workspaces)"),
+            primary_metric: z
+                .boolean()
+                .optional()
+                .describe("True if this is a conversion/outcome that can be a journey goal"),
+            recommended_transport: z
+                .enum(["client", "server", "either"])
+                .optional()
+                .describe("Where to fire it: server for money-truth, client for intent/engagement"),
+        }),
+        handler: async (args) => {
+            const res = await apiPost("/api/schema/events", {
+                name: args.name,
+                description: args.description,
+                fields: args.fields,
+                scope: args.scope,
+                primaryMetric: args.primaryMetric,
+                recommendedTransport: args.recommendedTransport,
+            });
+            if (res.error) {
+                const hint = res.suggestion
+                    ? ` Use the canonical event "${res.suggestion}" instead.`
+                    : "";
+                return { content: [{ type: "text", text: `Could not define "${args.name}": ${res.error}.${hint}` }] };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Defined governed event "${res.name}" (SchemaVer ${res.schemaVer ?? "1-0-0"}, draft). It's now selectable as a trigger/goal and resolvable as comm tokens once published.`,
+                    },
+                ],
+            };
+        },
+    },
+    log_prediction: {
+        description: `${APEX} — Log a prediction about a metric change. Feeds the calibration loop. Before calling, present the metric, expected change, and confidence as options the user can pick from or adjust.`,
+        schema: z.object({
+            metric: z.string().describe("The metric being predicted (e.g. 'conversion_rate', 'signup_rate')"),
+            expectedChange: z.number().describe("Expected change as a decimal (e.g. 0.15 for +15%)"),
+            confidence: z.number().min(0).max(100).describe("How sure you are about this prediction (0-100%)"),
+            timeHorizon: z
+                .number()
+                .optional()
+                .describe("Days until the prediction should be evaluated (default: 14)"),
+            hypothesisId: z.string().optional().describe("ID of the linked hypothesis"),
+            beliefId: z.string().optional().describe("ID of the linked assumption"),
+        }),
+        handler: async (args) => {
+            const direction = args.expectedChange > 0 ? "increase" : args.expectedChange < 0 ? "decrease" : "no_change";
+            const prediction = await apiPost("/api/predictions", {
+                metric: args.metric,
+                expectedChange: args.expectedChange,
+                direction,
+                expectedRange: {
+                    low: Math.min(0, args.expectedChange),
+                    high: Math.max(0, args.expectedChange),
+                },
+                confidence: args.confidence / 100,
+                timeHorizon: args.timeHorizon ?? 14,
+                evaluationWindow: args.timeHorizon ?? 14,
+                hypothesisId: args.hypothesisId,
+                beliefId: args.beliefId,
+            });
+            const changeStr = `${args.expectedChange > 0 ? "+" : ""}${(args.expectedChange * 100).toFixed(1)}%`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Prediction logged [${prediction.id}]:`,
+                            `  Metric: ${args.metric}`,
+                            `  Expected: ${changeStr} ${direction}`,
+                            `  Confidence: ${args.confidence}%`,
+                            `  Evaluate in: ${args.timeHorizon ?? 14} days`,
+                            args.beliefId ? `  Linked assumption: ${args.beliefId}` : "",
+                            "",
+                            "This feeds the calibration loop. After the experiment runs, the actual result will be compared to this prediction to track forecasting accuracy.",
+                        ]
+                            .filter(Boolean)
+                            .join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    // `list_workspaces` is canonical; `list_projects` is the deprecated alias
+    // kept for the project→workspace rename. Both point at the same handler so
+    // existing agent calls keep working.,
+    get_event_taxonomy: {
+        // 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 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 = 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 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_data_sources: {
+        description: `${APEX} — List the workspace's Data Sources (the producers that send events: Website, iOS/Android apps, Backend). Shows each source's live status (live / listening / stalled / not-started). Call when the user asks "where is my data coming from?", "which sources are live?", or to audit collection coverage.`,
+        schema: z.object({
+            includeArchived: z
+                .boolean()
+                .optional()
+                .describe("Include archived sources. Defaults to false."),
+        }),
+        handler: async ({ includeArchived }) => {
+            const proj = getActiveWorkspace();
+            const qs = includeArchived ? "?includeArchived=true" : "";
+            const json = await apiGet(`/api/workspaces/${proj}/data-sources${qs}`);
+            const sources = json.data ?? [];
+            if (sources.length === 0) {
+                return { content: [{ type: "text", text: "No data sources registered yet. They auto-register on the first event, or add one in Integrations." }] };
+            }
+            const lines = sources.map((s) => `- **${s.name}** (${s.kind}) — ${s.status}${s.lastSeenAt ? ` · last seen ${s.lastSeenAt}` : ""} · \`${s.id}\``);
+            return { content: [{ type: "text", text: `# Data Sources (${sources.length})\n\n${lines.join("\n")}` }] };
+        },
+    },
+    create_data_source: {
+        description: `${APEX} — Register a new Data Source in the active workspace. Most sources auto-register on their first event; use this to set one up BEFORE events arrive (e.g. a Backend API source). Reporting-only — registering a source never changes access control.`,
+        schema: z.object({
+            kind: z
+                .enum(["website", "ios", "android", "server", "pos", "kiosk", "extension", "other"])
+                .describe("The producer kind."),
+            name: z.string().describe("Display name, e.g. 'Marketing site' or 'Backend API'."),
+        }),
+        handler: async ({ kind, name }) => {
+            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}\`` }] };
+        },
+    },
+    get_data_source_health: {
+        description: `${APEX} — Get the live status of one Data Source (live / listening / stalled / not-started) plus its first/last seen timestamps. Use to diagnose "why isn't my backend / app showing data?"`,
+        schema: z.object({
+            id: z.string().describe("The data source id (ds_...)."),
+        }),
+        handler: async ({ id }) => {
+            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"}` }] };
+        },
+    },
+    get_analytics_sources: {
+        description: `${APEX} — Unified analytics breakdown by Data Source, platform, and hostname over a date range. Use for "how much traffic from each source?", "web vs mobile split", or "which hostnames are busiest?".`,
+        schema: z.object({
+            days: z.number().optional().describe("Lookback window in days (default 30, max 365)."),
+        }),
+        handler: async ({ days }) => {
+            const qs = days ? `?days=${days}` : "";
+            const json = await apiGet(`/api/analytics/sources${qs}`);
+            const d = json.data;
+            const srcLines = d.sources.map((s) => `- ${s.name} (${s.kind}, ${s.status}): ${s.eventCount.toLocaleString()} events`);
+            const platLines = d.platforms.map((p) => `- ${p.platform}: ${p.count.toLocaleString()}`);
+            const hostLines = d.hostnames.slice(0, 10).map((h) => `- ${h.hostname}: ${h.count.toLocaleString()}`);
+            return {
+                content: [{ type: "text", text: `# Analytics by source\n\n## Sources\n${srcLines.join("\n") || "_none_"}\n\n## Platforms\n${platLines.join("\n") || "_none_"}\n\n## Top hostnames\n${hostLines.join("\n") || "_none_"}` }],
+            };
+        },
+    },
+    get_analytics_hostnames: {
+        description: `${APEX} — The hostname catalog for this workspace (every host the web snippet has reported, ranked by volume). Use to populate a hostname filter or audit which subdomains are sending events.`,
+        schema: z.object({
+            limit: z.number().optional().describe("Max hostnames to return (default 100)."),
+        }),
+        handler: async ({ limit }) => {
+            const qs = limit ? `?limit=${limit}` : "";
+            const json = await apiGet(`/api/analytics/hostnames${qs}`);
+            const hosts = json.data ?? [];
+            const lines = hosts.map((h) => `- ${h.hostname}: ${h.count.toLocaleString()}`);
+            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_workspace first (or set APEX_WORKSPACE_KEY)." }],
+                };
+            }
+            const json = await apiGet(`/api/workspaces/${encodeURIComponent(workspaceKey)}/readiness`);
+            const d = json.data;
+            const person = lowerPerson(await getPersonLabel());
+            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}, id: ${t.templateId}) — Ready to run${t.templateKind === "journey" ? ` → create_journey_from_template({ templateId: "${t.templateId}" })` : ""}`),
+                ...blockedTemplates.slice(0, 10).map((t) => `- ⏳ ${t.title} (${t.templateKind}, id: ${t.templateId}) — 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 ${person.label}: ${d.milestones.firstIdentifiedAt}`
+                    : `First identified ${person.label}: 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_workspace first (or set APEX_WORKSPACE_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".`,
+                    }],
+            };
+        },
+    },
+    // ─── Graduation Pipeline — Engineering Links (Wave 2) ─────────────────,
+    apex_test_event: {
+        description: `${APEX} — Send a test event through the public ingestion endpoint and confirm it was accepted. The fastest way to verify event tracking works after installing the SDK.`,
+        schema: z.object({
+            eventName: z.string().describe("Event name, e.g. user_signed_up"),
+            attributes: z.record(z.unknown()).optional().describe("Event attributes"),
+            visitorId: z.string().optional().describe("Visitor id (default a test id)"),
+        }),
+        handler: async (args) => {
+            const workspaceKey = getActiveWorkspace();
+            if (!workspaceKey) {
+                return { content: [{ type: "text", text: "No active workspace. Run /apex-login or set APEX_WORKSPACE_KEY." }] };
+            }
+            const visitorId = args.visitorId ?? `test-${Date.now()}`;
+            const res = await apiPost("/api/events", {
+                workspaceKey,
+                type: args.eventName,
+                visitorId,
+                timestamp: new Date().toISOString(),
+                data: { ...(args.attributes ?? {}), endUserId: visitorId },
+            });
+            const text = res.eventId
+                ? `Test event "${args.eventName}" accepted (id ${res.eventId}). It's flowing into ${workspaceKey}.`
+                : `Event rejected: ${res.error ?? "unknown error"}`;
+            return { content: [{ type: "text", text }] };
+        },
+    },
+    apex_recent_events: {
+        description: `${APEX} — List recent events for the workspace (optionally filtered by type). Use to debug SDK wiring without opening the dashboard.`,
+        schema: z.object({
+            type: z.string().optional().describe("Filter by event type"),
+            sinceMinutes: z.number().optional().describe("Lookback window in minutes (default 60)"),
+        }),
+        handler: async (args) => {
+            const qs = new URLSearchParams();
+            if (args.type)
+                qs.set("type", args.type);
+            const since = new Date(Date.now() - (args.sinceMinutes ?? 60) * 60_000).toISOString();
+            qs.set("since", since);
+            qs.set("limit", "25");
+            const res = await apiGet(`/api/events/live?${qs.toString()}`);
+            const events = res.events ?? [];
+            if (events.length === 0) {
+                return { content: [{ type: "text", text: "No recent events in that window." }] };
+            }
+            const lines = events.slice(0, 25).map((e) => `- ${e.timestamp} ${e.type}${e.visitorId ? ` (${e.visitorId})` : ""}`);
+            return { content: [{ type: "text", text: `# Recent events\n${lines.join("\n")}` }] };
+        },
+    },
+    apex_health: {
+        description: `${APEX} — One-shot health check of every connected integration (last sync, status). Use before adding a feature that depends on a connector.`,
+        schema: z.object({}),
+        handler: async () => {
+            // GET /api/integrations is the connector LIST. `/api/connectors/*` only
+            // has per-type auth + callback routes, so the old path 404'd and this
+            // tool reported "No connected integrations" for every workspace.
+            const connectors = await apiGet("/api/integrations");
+            const list = Array.isArray(connectors) ? connectors : [];
+            const connected = list.filter((c) => c.isConnected || c.status === "connected");
+            if (connected.length === 0) {
+                // Say which of the two it is. `apiGet` throws on a failed call, so
+                // reaching here means the list really came back and really was empty.
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No connected integrations (the workspace returned ${list.length} available connector${list.length === 1 ? "" : "s"}, none connected).`,
+                        },
+                    ],
+                };
+            }
+            const lines = connected.map((c) => `- ${c.name ?? c.type}: ${c.status ?? "connected"}${c.lastSyncAt ? ` (last sync ${c.lastSyncAt})` : ""}`);
+            return { content: [{ type: "text", text: `# Integration health\n${lines.join("\n")}` }] };
+        },
+    },
+    apex_spec_validate: {
+        description: `${APEX} — Fetch the canonical Apex Spec event taxonomy so you can validate the track()/identify()/useApexVariant() calls in the user's files against it (ESLint-like for Apex usage). Read the user's files, find the calls, and flag event names + attributes that don't match the returned spec.`,
+        schema: z.object({}),
+        handler: async () => {
+            const spec = await apiGet("/api/spec/events");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Apex Spec (validate the user's track/identify/useApexVariant calls against this — flag unknown event names + attribute shapes):\n\n${JSON.stringify(spec, null, 2)}`,
+                    },
+                ],
+            };
+        },
+    },
+    list_conversions: {
+        description: `${APEX} — List the workspace's Conversions (owned-event definitions of valued actions, e.g. "Purchase", "Signup"). Call this when the user asks what conversions are defined. The starred primary is a label for that Conversion — it does not pick the funnel stages and it is not the experiment default. Experiments name their own metric; the funnel follows the workspace conversion model.`,
+        schema: z.object({}),
+        handler: async () => {
+            const conversions = await apiGet("/api/conversion-goals");
+            const active = conversions.filter((c) => !c.archivedAt);
+            if (active.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No conversions defined yet. Use create_conversion to define one (e.g. a custom_event named 'purchase').",
+                        },
+                    ],
+                };
+            }
+            const lines = active.map((c) => `• ${c.name} (${c.id}) — ${c.type}${c.eventName ? ` [${c.eventName}]` : ""}${c.isPrimary ? " ★ primary" : ""}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${active.length} conversion${active.length === 1 ? "" : "s"}:\n\n${lines.join("\n")}`,
+                    },
+                ],
+            };
+        },
+    },
+    create_conversion: {
+        description: `${APEX} — Define a new Conversion (an owned-event definition of a valued action). Most conversions are a custom_event with an eventName (e.g. "order_placed", "user_signed_up") matching an Apex Spec event you send via track. isPrimary stars this Conversion as a label — it does not pick experiment defaults or drive the funnel.`,
+        schema: z.object({
+            name: z.string().describe('Human label, e.g. "Purchase" or "Signup"'),
+            type: z
+                .enum([
+                "form_submit",
+                "click",
+                "pageview",
+                "custom_event",
+                "file_download",
+                "engaged_time",
+            ])
+                .describe("How the conversion is detected. custom_event is the most common (set eventName)."),
+            eventName: z
+                .string()
+                .optional()
+                .describe("For custom_event: the Apex Spec event name to match, e.g. 'purchase'."),
+            selector: z
+                .string()
+                .optional()
+                .describe("For click/form_submit: a CSS selector to match."),
+            targetUrl: z
+                .string()
+                .optional()
+                .describe("For pageview: the URL (or path) that counts as a completion."),
+            isPrimary: z
+                .boolean()
+                .optional()
+                .describe("Make this the primary conversion (only one can be primary)."),
+        }),
+        handler: async (args) => {
+            const payload = {
+                name: args.name,
+                type: args.type,
+                metricType: "binary",
+                isPrimary: args.isPrimary ?? false,
+                ...(args.eventName ? { eventName: args.eventName } : {}),
+                ...(args.selector ? { selector: args.selector } : {}),
+                ...(args.targetUrl ? { targetUrl: args.targetUrl } : {}),
+            };
+            const data = await apiPost("/api/conversion-goals", payload);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Conversion created.\n\n${JSON.stringify(data, null, 2)}`,
+                    },
+                ],
+            };
+        },
+    },
+    set_primary_conversion: {
+        description: `${APEX} — Mark a Conversion as the starred primary. That star labels the Conversion — it does not set experiment defaults or drive the funnel. Experiments name their own metric. Pass the conversion id from list_conversions.`,
+        schema: z.object({
+            conversionId: z.string().describe("The conversion id to promote (from list_conversions)."),
+        }),
+        handler: async ({ conversionId }) => {
+            const data = await apiPatch("/api/conversion-goals", { id: conversionId, isPrimary: true });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Primary conversion set.\n\n${JSON.stringify(data, null, 2)}`,
+                    },
+                ],
+            };
+        },
+    },
+    create_target: {
+        description: `${APEX} — Create a Target: an aggregate KPI number to hit by a date (MRR, pipeline, "1,000 signups by Q3"). Optionally bind it to a Conversion (sourceConversionId from list_conversions) to auto-count progress from that conversion's completions; otherwise it's a manual number you update yourself.`,
+        schema: z.object({
+            metric: z.string().describe('What you\'re tracking, e.g. "MRR", "Signups", "Pipeline".'),
+            target: z.number().describe("The numeric goal to reach."),
+            deadline: z.string().describe('Target date, ISO "YYYY-MM-DD".'),
+            sourceConversionId: z
+                .string()
+                .optional()
+                .describe("Optional: bind to a Conversion (from list_conversions) to auto-track progress."),
+        }),
+        handler: async (args) => {
+            const payload = {
+                metric: args.metric,
+                target: args.target,
+                deadline: args.deadline,
+                ...(args.sourceConversionId
+                    ? { sourceConversionId: args.sourceConversionId }
+                    : {}),
+            };
+            const data = await apiPost("/api/targets", payload);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Target created.\n\n${JSON.stringify(data, null, 2)}`,
+                    },
+                ],
+            };
+        },
+    },
+    // ─── Adoption Engine ──────────────────────────────────────────────────────,
+};
+//# sourceMappingURL=measurement.js.map