@apex-inc/mcp-server 0.14.0 → 0.16.0

package/dist/tools.js

@@ -64,6 +64,28 @@ function appUrl(path) {
 function journeyLink(id) {
     return appUrl(`/dashboard/communications/journeys/${id}`);
 }
+/**
+ * Render the author-time conflict guard advisory (non-blocking). `selfId` is the
+ * candidate experiment's id when known (so the set_experiment_mutex suggestion
+ * is copy-pasteable); omitted during pre-create previews.
+ */
+function renderConflictAdvisory(data, selfId) {
+    const lines = [];
+    for (const h of data.differentMetric) {
+        const soft = h.confidence === "low" ? " (same data source — only a real conflict if it targets the same screen)" : "";
+        lines.push(`⚠ Overlaps "${h.name}" (${h.experimentId}) on ${h.location}${soft}. It measures ${h.primaryMetricLabel}; this measures a different goal — running both at once contaminates both results.`);
+        lines.push(selfId
+            ? `   → Run both safely in parallel: set_experiment_mutex({ experimentId: "${selfId}", withExperimentId: "${h.experimentId}" }). Or sequence: activate this only after "${h.name}" concludes.`
+            : `   → After creating it, run both safely in parallel: set_experiment_mutex({ experimentId: "<new id>", withExperimentId: "${h.experimentId}" }). Or sequence after "${h.name}" concludes.`);
+    }
+    for (const h of data.sameMetric) {
+        const soft = h.confidence === "low" ? " (same data source — only a real conflict if it targets the same screen)" : "";
+        lines.push(`↔ "${h.name}" (${h.experimentId}) already tests ${h.location} for ${h.primaryMetricLabel} — the SAME metric${soft}. These look like two arms of one question: consider adding your change as a variant of "${h.name}" rather than a separate experiment.`);
+    }
+    if (lines.length === 0)
+        return "✓ No overlap with live experiments on this surface.";
+    return `Conflict guard:\n${lines.join("\n")}`;
+}
 /**
  * Detect a MOBILE experiment surface from repo signals (the MCP runs in the
  * merchant's repo). Walks up a few dirs looking for capacitor.config.* or a
@@ -495,6 +517,25 @@ export const toolDefinitions = {
                 };
             }
             if (isPreview) {
+                // Author-time conflict guard (best-effort, non-blocking): warn if this
+                // overlaps a LIVE experiment on the same surface before it's created.
+                let conflictAdvisory;
+                try {
+                    const cc = await apiPost("/api/experiments/check-conflicts", {
+                        surface: experimentSurface,
+                        target_component: args.targetComponent,
+                        target_url: args.targetUrl,
+                        target_anchor: args.targetAnchor,
+                        data_source_id: args.dataSourceId,
+                        primary_metric_event: primaryMetric.source.eventType,
+                    });
+                    if (cc.data.sameMetric.length || cc.data.differentMetric.length) {
+                        conflictAdvisory = renderConflictAdvisory(cc.data);
+                    }
+                }
+                catch {
+                    /* conflict check is advisory; never block the preview */
+                }
                 const recipe = {
                     _apex: true,
                     _type: "experiment_preview",
@@ -511,7 +552,8 @@ export const toolDefinitions = {
                     beliefId: args.beliefId || null,
                     beliefStatement: args.beliefStatement || null,
                     predictionId: args.predictionId || null,
-                    _instructions: "Before proposing variant copy, ground every factual claim in .apex/brand-truth.md (read it; cite the line each claim traces to; if a claim isn't backed there, ask the user instead of inventing it). Then present this as a summary and ask the user to confirm (1), adjust (2), or cancel (3). Do NOT create the experiment until confirmed.",
+                    ...(conflictAdvisory ? { _conflict_advisory: conflictAdvisory } : {}),
+                    _instructions: `Before proposing variant copy, ground every factual claim in .apex/brand-truth.md (read it; cite the line each claim traces to; if a claim isn't backed there, ask the user instead of inventing it).${conflictAdvisory ? " IMPORTANT: _conflict_advisory is set — show it to the user and resolve the overlap (mutex / variant / sequence) before creating." : ""} Then present this as a summary and ask the user to confirm (1), adjust (2), or cancel (3). Do NOT create the experiment until confirmed.`,
                 };
                 return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
             }
@@ -602,6 +644,9 @@ export const toolDefinitions = {
                 name: args.name,
                 targetUrl: args.targetUrl,
                 targetAnchor: args.targetAnchor,
+                // Persist the component (e.g. "ProductCard") as a precise location
+                // signal for the author-time conflict guard — esp. mobile/SDK arms.
+                ...(args.targetComponent ? { targetComponent: args.targetComponent } : {}),
                 createdFrom: "cursor",
                 status: "draft",
                 ...(args.dataSourceId ? { dataSourceId: args.dataSourceId } : {}),
@@ -978,6 +1023,17 @@ export const toolDefinitions = {
             else if (wiring && !wiring.bothArmsLive && force === true) {
                 notes.push(`  ⚠ Launched with force: true despite an incomplete wiring check`, `    (verdict: ${wiring.verdict}, ${wiring.armsLive}/${wiring.totalArms} arm(s) live).`, `    Some arm(s) may not be collecting data yet.`, ``);
             }
+            // Author-time conflict guard (advisory): if this now-running experiment
+            // overlaps another live one on the same surface, surface the fix.
+            try {
+                const cc = await apiPost("/api/experiments/check-conflicts", { experiment_id: experimentId });
+                if (cc.data.sameMetric.length || cc.data.differentMetric.length) {
+                    notes.push(`  ${renderConflictAdvisory(cc.data, experimentId).split("\n").join("\n  ")}`, ``);
+                }
+            }
+            catch {
+                /* advisory only — never affect the launch result */
+            }
             return {
                 content: [
                     {
@@ -1445,6 +1501,53 @@ export const toolDefinitions = {
             }
         },
     },
+    check_experiment_conflicts: {
+        description: `${APEX} — Before you create or activate an experiment, check whether it overlaps a LIVE experiment on the same surface. Same location + DIFFERENT metric → they'll contaminate each other (make them mutually exclusive with set_experiment_mutex, or sequence). Same location + SAME metric → add a variant to the existing experiment instead. Pass either experimentId (an existing draft) OR the candidate's location + primaryMetricEvent. Advisory only — nothing is blocked.`,
+        schema: z.object({
+            experimentId: z.string().optional().describe("Check an existing experiment by id (loads its location + metric)."),
+            surface: z.enum(["web", "mobile"]).optional(),
+            targetComponent: z.string().optional().describe("Component/file the experiment changes, e.g. 'ProductCard'."),
+            targetUrl: z.string().optional(),
+            targetAnchor: z.string().optional(),
+            dataSourceId: z.string().optional(),
+            primaryMetricEvent: z.string().optional().describe("Canonical primary-metric event, e.g. 'add_to_cart'."),
+        }),
+        handler: async (args) => {
+            try {
+                const res = await apiPost("/api/experiments/check-conflicts", {
+                    ...(args.experimentId ? { experiment_id: args.experimentId } : {}),
+                    surface: args.surface,
+                    target_component: args.targetComponent,
+                    target_url: args.targetUrl,
+                    target_anchor: args.targetAnchor,
+                    data_source_id: args.dataSourceId,
+                    primary_metric_event: args.primaryMetricEvent,
+                });
+                return { content: [{ type: "text", text: `${APEX} ${renderConflictAdvisory(res.data, args.experimentId)}` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
+    set_experiment_mutex: {
+        description: `${APEX} — Put two experiments in a mutual-exclusion group: no visitor is ever assigned to both, so they run concurrently with partitioned traffic (the scientifically clean way to run two experiments that touch the same surface). Bidirectional. Pass mode:"remove" to unlink. Safe on running experiments — only affects future assignments.`,
+        schema: z.object({
+            experimentId: z.string(),
+            withExperimentId: z.string().describe("The other experiment to make mutually exclusive with."),
+            mode: z.enum(["add", "remove"]).optional().describe("'add' (default) links; 'remove' unlinks."),
+        }),
+        handler: async ({ experimentId, withExperimentId, mode }) => {
+            try {
+                await apiPost(`/api/experiments/${encodeURIComponent(experimentId)}/mutex`, { withExperimentId, mode });
+                const verb = mode === "remove" ? "are no longer" : "are now";
+                return { content: [{ type: "text", text: `${APEX} ${experimentId} and ${withExperimentId} ${verb} mutually exclusive — no visitor will be assigned to both.` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
     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({
@@ -1496,6 +1599,283 @@ export const toolDefinitions = {
             };
         },
     },
+    get_channel_economics: {
+        description: `${APEX} — "Where should my next dollar go?" Per acquisition channel (raw first-touch): gross-margin-adjusted LTV:CAC, 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`);
+            const ranked = [...channels].sort((a, b) => (b.ltvCacRatio ?? -1) - (a.ltvCacRatio ?? -1));
+            const acquisition = ranked.filter((c) => c.spend !== null && c.spend > 0);
+            const leverage = ranked.filter((c) => c.spend === null || c.spend === 0);
+            const fmt = (c) => `  • ${label(c.channel)}: ${ratio(c.ltvCacRatio)} LTV:CAC · payback ${c.paybackMonths != null ? `${c.paybackMonths}mo` : "—"} · CAC ${money(c.cac)} · ${c.customers.toLocaleString()} customers`;
+            const lines = [
+                `${APEX} Channel economics — gross-margin LTV:CAC`,
+                "═".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 LTV:CAC is healthy; <1x loses margin on every customer; >5x is likely underinvested.");
+            if (res.data?.grossMarginFromDefault) {
+                lines.push(`(Using a default ${res.data.grossMargin != null
+                    ? `${Math.round(res.data.grossMargin * 100)}%`
+                    : ""} gross margin — set your real margin in workspace settings to sharpen this.)`);
+            }
+            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)."),
+        }),
+        handler: async ({ months }) => {
+            const q = months ? `?months=${months}` : "";
+            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)."),
+        }),
+        handler: async ({ months }) => {
+            const q = months ? `?months=${months}` : "";
+            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_dtc_merchandising: {
+        description: `${APEX} — DTC merchandising: 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 180)."),
+        }),
+        handler: async ({ days }) => {
+            const q = days ? `?days=${days}` : "";
+            const res = await apiGet(`/api/dtc/merchandising${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} Merchandising — ${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") }] };
+        },
+    },
+    get_dtc_returns: {
+        description: `${APEX} — DTC 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 180)."),
+        }),
+        handler: async ({ days }) => {
+            const q = days ? `?days=${days}` : "";
+            const res = await apiGet(`/api/dtc/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 180)."),
+            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, category, geo, priceBand, }) => {
+            const params = new URLSearchParams();
+            if (days)
+                params.set("days", String(days));
+            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") }] };
+        },
+    },
     suggest_experiment: {
         description: `${APEX} — Get smart experiment suggestions based on context. Analyzes your assumptions, past experiments, and confidence gaps to recommend what to test next.`,
         schema: z.object({
@@ -1976,19 +2356,20 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     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/lead.`,
+        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/lead. Pass avatarUrl (a canonical attribute) to give the Contact a profile photo that renders across Apex — Customers list, detail page, and Live Customers widget.`,
         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, metadata }) => {
+        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, ...metadata, source: "mcp" },
+                metadata: { name, company, avatar_url: avatarUrl, ...metadata, source: "mcp" },
             });
             return {
                 content: [{
@@ -2047,6 +2428,52 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             };
         },
     },
+    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({
@@ -3786,5 +4213,136 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             };
         },
     },
+    // ─── Conversions & Targets (Goals & Conversions Convergence — PR8) ──────────
+    // A Conversion is the merchant-facing definition of a valued action (the
+    // owned-event matcher managed on /dashboard/conversions). A Target is an
+    // aggregate KPI number to hit by a date. "Goal" is retired as a noun.
+    list_conversions: {
+        description: `${APEX} — List the workspace's Conversions (the owned-event definitions of valued actions, e.g. "Purchase", "Signup"). Call this when the user asks what conversions are defined, or before creating an experiment/journey that needs an objective. The one flagged primary drives default experiment objectives, funnel metrics, and scoring.`,
+        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. "purchase", "signup") matching an Apex Spec event you send via track. Set isPrimary to make it the default objective for experiments and the headline funnel metric.`,
+        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 primary one. Experiments without an explicit objective default to the primary conversion, and the headline funnel + scoring use it. 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)}`,
+                    },
+                ],
+            };
+        },
+    },
 };
 //# sourceMappingURL=tools.js.map