@apex-inc/mcp-server 0.16.0 → 0.18.0

package/dist/tools.js

@@ -53,6 +53,24 @@ function titleCaseEvent(event) {
         .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
         .join(" ");
 }
+/**
+ * Query string for the pack report windows: relative (`days` / `months`)
+ * or explicit `start` + `end` (YYYY-MM-DD, both required together —
+ * explicit bounds win server-side).
+ */
+function windowQuery(opts) {
+    const params = new URLSearchParams();
+    if (opts.days)
+        params.set("days", String(opts.days));
+    if (opts.months)
+        params.set("months", String(opts.months));
+    if (opts.start && opts.end) {
+        params.set("start", opts.start);
+        params.set("end", opts.end);
+    }
+    const qs = params.toString();
+    return qs ? `?${qs}` : "";
+}
 function errMsg(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -437,15 +455,23 @@ export const toolDefinitions = {
             guardrailType: z.enum(["rate", "revenue", "duration"]).optional().describe("How the guardrail is measured. 'rate' (default) = how often the harm event fires. 'revenue' = sum a value (e.g. refund $)."),
             guardrailThreshold: z.number().optional().describe("Harm margin for the guardrail, RELATIVE (0.25 = flag a >25% rise). Defaults to 0.25."),
             predictionMagnitude: z.string().optional().describe("Your committed prediction of the effect, e.g. '10% lift'. Recorded with 'agent' provenance and used for calibration. Required before the experiment can be ACTIVATED."),
-            mode: z.enum(["sdk", "snippet"]).optional().describe("Experiment mode: 'sdk' for code-level (default via MCP), 'snippet' for runtime DOM"),
             surface: z.enum(["web", "mobile"]).optional().describe("The PROPERTY the experiment runs in (not the SDK used): 'web' for a website, 'mobile' for a native / Capacitor / React-Native app. OPTIONAL — when omitted it is auto-detected from repo signals (capacitor.config.* / @apex-inc/capacitor-plugin → mobile) and the workspace's registered data sources; pass it explicitly only to override or when both web and mobile sources exist. Sets the dashboard data-source label (Website vs Mobile app)."),
             dataSourceId: z.string().optional().describe("Optional explicit Data Source (property) id this experiment runs in, e.g. 'ds_website' or 'ds_ios'. Usually inferred from surface; pass it to bind to a specific registered source. Tenant-validated server-side."),
             randomizationUnit: z.enum(["device", "visitor", "person", "account", "org"]).optional().describe("What to bucket on. Default 'visitor' (per-device). Use 'person' to give one stitched user the same variant across their devices, or 'account'/'org' for B2B account-level tests where everyone in an account should see the same variant."),
+            minSamplePerArm: z.number().int().min(30).optional().describe("Minimum exposed subjects PER ARM before a winner can be claimed (the sample gate). Defaults to 50. Raise it to demand more evidence (detect a smaller lift); lower it (floor 30) for low-traffic properties that would otherwise stall. The real winner-gate is still the 95% probability-to-be-best — this only sets the traffic floor. Pre-registration: frozen once the experiment is running."),
+            runtimeDays: z.number().int().min(1).max(365).optional().describe("How long to run the experiment, in days (the decision window). Apex force-concludes at this point — decisive winner if reached, else inconclusive. Defaults to 14. Set e.g. 28 to run for four weeks. This is the max runtime, not a minimum: a decisive winner can conclude sooner. Pre-registration: frozen once the experiment is running (fork to change it)."),
             preview: z.boolean().optional().describe("If true, returns a preview without creating. Default: true."),
         }),
         handler: async (args) => {
             const split = args.trafficSplit ?? 50;
-            const mode = args.mode ?? "sdk";
+            // MCP experiments are ALWAYS code-native (SDK). Client-side snippet /
+            // runtime-DOM experiments are intentionally NOT offered here (founder
+            // decision 2026-07-05): the MCP audience is developers in an IDE with the
+            // code open, where `useApexVariant` is more reliable (no flicker, no
+            // fragile selectors, deterministic exposure) and plugs into the
+            // graduation pipeline. Snippet experiments live in the Apex web app's
+            // visual editor for the no-code / non-repo case.
+            const mode = "sdk";
             // Surface auto-detect (QA 2026-06-18): when the agent doesn't pass a
             // surface, infer it from repo signals + registered data sources instead of
             // silently defaulting to web (which mislabels mobile apps). Ambiguous →
@@ -464,16 +490,23 @@ export const toolDefinitions = {
             }
             const experimentSurface = surfaceResolution.surface;
             const isPreview = args.preview !== false;
-            // p1-metric — resolve the primary metric. Defaults to the form_submit
-            // conversion metric; an explicit primaryMetricEvent is validated against
-            // the workspace's canonical event spec before we accept it.
+            // p1-metric — resolve the primary metric (the conversion goal).
+            //
+            // Founder decision 2026-07-05: DO NOT silently default the conversion
+            // event to `form_submit`. A guessed goal ("Signups" that secretly counts
+            // form submits) is worse than none. When the caller doesn't name a
+            // conversion event, the draft is created UNWIRED (no `source`): it's a
+            // valid draft, but the activation gate blocks starting it until a real
+            // outcome event is set — and we nudge loudly to set one. An explicit
+            // primaryMetricEvent is validated against the workspace event spec.
+            const conversionEventSet = Boolean(args.primaryMetricEvent);
             let primaryMetric = {
-                key: "conversion_rate",
-                label: "Conversion rate",
+                key: "conversion_goal",
+                label: "Conversion goal (not set)",
                 type: "rate",
                 unit: "%",
                 direction: "increase",
-                source: { kind: "event", eventType: "form_submit" },
+                // No `source` — UNWIRED on purpose. Can't start until set.
             };
             if (args.primaryMetricEvent) {
                 const event = args.primaryMetricEvent.trim();
@@ -487,7 +520,7 @@ export const toolDefinitions = {
                     return {
                         content: [{
                                 type: "text",
-                                text: `Could not load the event spec to validate primaryMetricEvent "${event}" (${message}). Fix the connection or omit primaryMetricEvent to use the default conversion metric.`,
+                                text: `Could not load the event spec to validate primaryMetricEvent "${event}" (${message}). Fix the connection, or omit primaryMetricEvent to create the draft without a conversion goal (you'll set it before starting).`,
                             }],
                         isError: true,
                     };
@@ -527,7 +560,7 @@ export const toolDefinitions = {
                         target_url: args.targetUrl,
                         target_anchor: args.targetAnchor,
                         data_source_id: args.dataSourceId,
-                        primary_metric_event: primaryMetric.source.eventType,
+                        primary_metric_event: primaryMetric.source?.eventType,
                     });
                     if (cc.data.sameMetric.length || cc.data.differentMetric.length) {
                         conflictAdvisory = renderConflictAdvisory(cc.data);
@@ -546,14 +579,23 @@ export const toolDefinitions = {
                     targetComponent: args.targetComponent || null,
                     mode,
                     trafficSplit: { control: split, variant: 100 - split },
+                    decisionWindowDays: args.runtimeDays ?? 14,
+                    minSamplePerArm: args.minSamplePerArm ?? 50,
                     control: args.controlContent,
                     variant: args.variantContent,
-                    primaryMetric: primaryMetric.key,
+                    conversionGoal: conversionEventSet
+                        ? { event: primaryMetric.source?.eventType, type: primaryMetric.type }
+                        : "NOT SET — required before the experiment can start",
                     beliefId: args.beliefId || null,
                     beliefStatement: args.beliefStatement || null,
                     predictionId: args.predictionId || null,
                     ...(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.`,
+                    ...(conversionEventSet
+                        ? {}
+                        : {
+                            _conversion_goal_warning: "No conversion event set. The draft will be created, but it CANNOT be started until you set the outcome you're optimizing. Call list_events to see what's firing (prefer a real outcome like signup/purchase over form_submit), then pass primaryMetricEvent. Confirm the goal with the user before creating.",
+                        }),
+                    _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." : ""}${conversionEventSet ? "" : " IMPORTANT: _conversion_goal_warning is set — surface it and set a conversion event (list_events → primaryMetricEvent) before creating, unless the user explicitly wants a draft to fill in later."} 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) }] };
             }
@@ -651,6 +693,16 @@ export const toolDefinitions = {
                 status: "draft",
                 ...(args.dataSourceId ? { dataSourceId: args.dataSourceId } : {}),
                 ...(args.randomizationUnit ? { randomizationUnit: args.randomizationUnit } : {}),
+                // Sample-size floor (minPerVariant) and/or run duration (durationDays).
+                // The API merges evaluationWindow, so sending one never clobbers the other.
+                ...(() => {
+                    const ew = {};
+                    if (args.minSamplePerArm)
+                        ew.minPerVariant = args.minSamplePerArm;
+                    if (args.runtimeDays)
+                        ew.durationDays = args.runtimeDays;
+                    return Object.keys(ew).length > 0 ? { evaluationWindow: ew } : {};
+                })(),
                 hypothesis: resolvedHypothesis,
                 // Agent-authored: tagged "agent" provenance so calibration attributes it
                 // correctly. When the agent supplies predictionMagnitude it satisfies the
@@ -692,7 +744,8 @@ export const toolDefinitions = {
                         ],
                     }
                     : {}),
-                attributionWindow: { unit: "hours", value: 24, startFrom: "first_interaction" },
+                // VJATTR D1: 7-day exposure→conversion attribution window (was 24h).
+                attributionWindow: { unit: "days", value: 7, startFrom: "first_interaction" },
                 variants,
             });
             let previewUrl = "";
@@ -742,7 +795,9 @@ export const toolDefinitions = {
                 `7. Show the user the diff and ask them to preview at: ${previewUrl}`,
                 `8. After preview approval, commit and push`,
                 `9. Call track_deployment with the experiment ID and commit SHA`,
-                `10. Call verify_experiment_wiring, then activate_experiment once both arms report exposures`,
+                `10. Call activate_experiment (with the user's go-ahead). If the code isn't live yet, the`,
+                `    experiment holds in "Waiting on deploy" and starts automatically at the first exposure —`,
+                `    verify with verify_experiment_wiring after the deploy lands.`,
             ];
             const mobileSteps = [
                 "IMPLEMENT THE EXPERIMENT IN CODE (mobile / Capacitor):",
@@ -772,6 +827,18 @@ export const toolDefinitions = {
                 "- Before calling activate_experiment, tell the user the expected metered volume and get their explicit go-ahead.",
                 "- Activation also requires a measurable primary goal, a guardrail, and a committed prediction (the server enforces this). If you didn't pass predictionMagnitude, add one first.",
             ];
+            const conversionGoalNudge = conversionEventSet
+                ? []
+                : [
+                    "",
+                    "⚠️ CONVERSION GOAL NOT SET — this draft cannot be started yet:",
+                    "- No outcome event is wired, so there's nothing to measure a winner on.",
+                    "- Pick the real outcome: call list_events to see what's firing in this",
+                    "  workspace, then update_experiment({ experiment_id, primary_metric_event }).",
+                    "- Prefer a true outcome (signup / purchase / checkout_completed) over a",
+                    "  proxy like form_submit. Confirm the goal with the user.",
+                    "- activate_experiment will refuse until a measurable goal is set.",
+                ];
             const recipe = {
                 _apex: true,
                 _type: "experiment_created",
@@ -780,7 +847,11 @@ export const toolDefinitions = {
                 surface: experimentSurface,
                 status: exp.status,
                 mode,
-                primaryMetric: primaryMetric.key,
+                conversionGoal: conversionEventSet
+                    ? { event: primaryMetric.source?.eventType, type: primaryMetric.type }
+                    : "NOT SET — required before start (see _instructions)",
+                decisionWindowDays: args.runtimeDays ?? 14,
+                minSamplePerArm: args.minSamplePerArm ?? 50,
                 beliefId: beliefId || null,
                 hypothesisId: hypothesisId || null,
                 predictionId: args.predictionId || null,
@@ -804,20 +875,13 @@ export const toolDefinitions = {
                 } : null,
                 previewUrl,
                 trafficSplit: { control: split, variant: 100 - split },
-                _instructions: mode === "sdk"
-                    ? groundingGuidance
-                        .concat(isMobile ? mobileSteps : webSteps)
-                        .concat(styleGuidance)
-                        .concat(activationPolicy)
-                        .join("\n")
-                    : groundingGuidance
-                        .concat([
-                        "SNIPPET MODE — no code changes needed.",
-                        "The experiment will be applied via the Apex snippet at runtime.",
-                        `Preview: ${previewUrl}`,
-                    ])
-                        .concat(activationPolicy)
-                        .join("\n"),
+                // Always code-native (SDK) — see the `mode` note above.
+                _instructions: groundingGuidance
+                    .concat(isMobile ? mobileSteps : webSteps)
+                    .concat(styleGuidance)
+                    .concat(activationPolicy)
+                    .concat(conversionGoalNudge)
+                    .join("\n"),
             };
             return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
         },
@@ -871,6 +935,38 @@ export const toolDefinitions = {
             };
         },
     },
+    recapture_experiment_screenshots: {
+        description: `${APEX} — Re-run the hosted screenshot capture for a WEB experiment's arms (renders the target URL for control + variant and stores the images shown on the dashboard). Use when screenshots are missing or stale — e.g. the page changed, or an earlier capture failed. Web experiments only (mobile arms capture on-device via the SDK).`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to re-capture screenshots for."),
+        }),
+        handler: async ({ experimentId }) => {
+            try {
+                const res = await apiPost(`/api/experiments/${encodeURIComponent(experimentId)}/recapture`, {});
+                const { captured, errors } = res.data;
+                const lines = [
+                    `${APEX} Re-captured ${captured} screenshot${captured === 1 ? "" : "s"} for ${experimentId}.`,
+                ];
+                if (errors.length)
+                    lines.push(`  Arm(s) that failed: ${errors.join("; ")}`);
+                if (captured === 0) {
+                    lines.push(`  No images were produced — confirm the target URL is public and reachable.`);
+                }
+                return { content: [{ type: "text", text: lines.join("\n") }] };
+            }
+            catch (err) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    },
     verify_experiment_wiring: {
         description: `${APEX} — Verify an experiment is actually wired up before launch: check whether \`experiment_exposure\` events are arriving for BOTH arms. Use this before activate_experiment to avoid launching an experiment that silently collects no data. Returns a per-arm exposure breakdown and an actionable next step.`,
         schema: z.object({
@@ -904,8 +1000,14 @@ export const toolDefinitions = {
                 case "no_exposures":
                 default:
                     verdictLine = "NO EXPOSURES — no exposures recorded for any arm";
-                    nextStep =
-                        "No `experiment_exposure` events are arriving. The variant-serving code " +
+                    nextStep = wiring.sdkMode
+                        ? "No `experiment_exposure` events have reached Apex yet. This experiment is " +
+                            "code-wired (SDK hook), so you can activate it NOW: activate_experiment will " +
+                            "hold it in `pending_deployment` (\"Waiting on deploy\") and it starts " +
+                            "automatically the moment the deployed `useApexVariant(\"" +
+                            wiring.experimentId +
+                            "\")` code records its first exposure. Ship the code, and the test starts itself."
+                        : "No `experiment_exposure` events are arriving. The variant-serving code " +
                             "(useApexVariant / Apex.getVariant) probably isn't deployed or running yet, " +
                             "so nothing is being assigned. Deploy the experiment code and confirm it runs " +
                             "on the target surface, then re-run verify_experiment_wiring.";
@@ -940,7 +1042,7 @@ export const toolDefinitions = {
         },
     },
     activate_experiment: {
-        description: `${APEX} — Launch an experiment. Changes its status from draft to running. Traffic will be split immediately. Before flipping to running, this verifies BOTH arms are producing \`experiment_exposure\` events (wiring check) and refuses to launch an unwired experiment unless force is true. Ask the user to confirm before calling.`,
+        description: `${APEX} — Launch an experiment. Changes its status from draft to running. Traffic will be split immediately. Before flipping to running, this verifies BOTH arms are producing \`experiment_exposure\` events (wiring check). Code-wired (SDK-hook) experiments may be activated before their code ships: the server holds them in \`pending_deployment\` ("Waiting on deploy") and starts on the first exposure. Snippet experiments are applied by the Apex snippet at runtime, so they also don't need pre-activation exposures — they launch and wiring is verified afterward. Only wired experiments that genuinely can't self-start are refused unless force is true. Ask the user to confirm before calling.`,
         schema: z.object({
             experimentId: z.string().describe("The experiment ID to activate"),
             force: z
@@ -959,7 +1061,17 @@ export const toolDefinitions = {
             catch (err) {
                 wiringError = err instanceof Error ? err.message : String(err);
             }
-            if (wiring && !wiring.bothArmsLive && force !== true) {
+            // Code-wired (SDK-hook) AND snippet-applied experiments skip the hard
+            // refusal. SDK: the server holds them in `pending_deployment` and
+            // auto-starts on first exposure. Snippet: the Apex snippet only applies
+            // the experiment ONCE IT'S RUNNING, so it can't have pre-activation
+            // exposures — blocking on them is a chicken-and-egg. Both are safe to
+            // launch "early"; wiring is verified AFTER via verify_experiment_wiring.
+            if (wiring &&
+                !wiring.bothArmsLive &&
+                force !== true &&
+                !wiring.sdkMode &&
+                !wiring.snippetMode) {
                 const armLines = wiring.perArm.map(formatArmLine);
                 const zeroArms = wiring.perArm
                     .filter((a) => a.exposures === 0)
@@ -1005,7 +1117,56 @@ export const toolDefinitions = {
             const exp = await apiPatch("/api/experiments", {
                 id: experimentId,
                 status: "running",
+                // Deploy-wait override: the server holds an unwired code-wired
+                // experiment in `pending_deployment` unless the caller forces.
+                ...(force === true ? { force: true } : {}),
             });
+            // Deploy-wait hold — the server accepted the start but is waiting for
+            // the experiment code to go live. Report the held state precisely
+            // (claiming "LIVE" here would repeat the 2026-07-04 confusion).
+            if (exp.status === "pending_deployment") {
+                const held = [
+                    `${APEX} Experiment Waiting on Deploy`,
+                    `${"═".repeat(40)}`,
+                    ``,
+                    `  "${exp.name}" is armed but NOT collecting yet.`,
+                    `  ID: ${exp.id}`,
+                    `  Status: pending_deployment ("Waiting on deploy")`,
+                    ``,
+                    `  Apex hasn't received any \`experiment_exposure\` events from this`,
+                    `  experiment's code, so the start is on hold. Nothing is wrong —`,
+                    `  the experiment starts AUTOMATICALLY the moment the deployed code`,
+                    `  records its first exposure.`,
+                    ``,
+                    `  To go live:`,
+                    `  1. Render the variants through the SDK hook:`,
+                    `       const variant = useApexVariant("${exp.id}");`,
+                    `  2. Deploy that code to the target page.`,
+                    `  3. Done — the first visitor flips it to running. Verify with`,
+                    `     verify_experiment_wiring or the experiment page.`,
+                    ``,
+                    `  Certain the code is already live? Re-run activate_experiment`,
+                    `  with force: true to start immediately.`,
+                    ``,
+                    `${"═".repeat(40)}`,
+                ].join("\n");
+                return {
+                    content: [
+                        { type: "text", text: held },
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                _apex: true,
+                                _type: "activation_held",
+                                reason: "code_not_live",
+                                experimentId: exp.id,
+                                status: exp.status,
+                                autoStartsOnFirstExposure: true,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             // PATCH returns a minimal/legacy body — re-read the unified record to
             // derive the live traffic split from the allocation weights.
             let controlPct = 50;
@@ -1023,6 +1184,9 @@ 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.`, ``);
             }
+            else if (wiring && !wiring.bothArmsLive && wiring.snippetMode) {
+                notes.push(`  ℹ Snippet experiment — the Apex snippet applies it to visitors now`, `    that it's running, so exposures start flowing on the next visits.`, `    Confirm both arms record exposures shortly with`, `    verify_experiment_wiring (a mismatched selector would silently`, `    collect nothing).`, ``);
+            }
             // Author-time conflict guard (advisory): if this now-running experiment
             // overlaps another live one on the same surface, surface the fix.
             try {
@@ -1157,7 +1321,7 @@ export const toolDefinitions = {
         },
     },
     archive_experiment: {
-        description: `${APEX} — Archive an experiment. Removes it from active views but preserves all data, learnings, and belief graph connections. Archived experiments still contribute to intelligence scoring and recommendations. Ask the user to confirm before calling.`,
+        description: `${APEX} — Archive an experiment. Removes it from active views but preserves all data, learnings, and belief graph connections. Archived experiments still contribute to intelligence scoring and recommendations. A RUNNING experiment cannot be archived — end it first (conclude_experiment / promote_winner) so its result + belief are captured; the server returns 409 archive_requires_conclusion otherwise. Ask the user to confirm before calling.`,
         schema: z.object({
             experimentId: z.string().describe("The experiment ID to archive"),
         }),
@@ -1341,6 +1505,64 @@ export const toolDefinitions = {
             };
         },
     },
+    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({
@@ -1403,6 +1625,8 @@ export const toolDefinitions = {
             primaryMetricEvent: z.string().optional().describe("Change the primary metric's canonical event — draft only."),
             primaryMetricType: z.enum(["rate", "count", "revenue", "duration"]).optional(),
             guardrailEvent: z.string().optional().describe("Replace the guardrail with this canonical protective event — draft only."),
+            minSamplePerArm: z.number().int().min(30).optional().describe("Set the minimum exposed subjects PER ARM before a winner can be claimed (the sample gate; floor 30). Draft only — it's part of the pre-registration and freezes at launch (a running experiment returns experiment_locked; fork to change it)."),
+            runtimeDays: z.number().int().min(1).max(365).optional().describe("Set how long to run the experiment, in days (the decision window Apex force-concludes at). Draft only — part of the pre-registration; freezes at launch (fork to change it)."),
         }),
         handler: async (args) => {
             const body = { id: args.experimentId };
@@ -1412,6 +1636,16 @@ export const toolDefinitions = {
                 body.surface = args.surface;
             if (args.hypothesis !== undefined)
                 body.hypothesis = args.hypothesis;
+            // evaluationWindow patch — the API merges it, so setting one of
+            // minPerVariant / durationDays never clobbers the other.
+            if (args.minSamplePerArm !== undefined || args.runtimeDays !== undefined) {
+                const ew = {};
+                if (args.minSamplePerArm !== undefined)
+                    ew.minPerVariant = args.minSamplePerArm;
+                if (args.runtimeDays !== undefined)
+                    ew.durationDays = args.runtimeDays;
+                body.evaluationWindow = ew;
+            }
             if (args.primaryMetricEvent) {
                 const t = args.primaryMetricType ?? "rate";
                 const isValue = t === "revenue" || t === "duration";
@@ -1670,9 +1904,17 @@ export const toolDefinitions = {
                 .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 }) => {
-            const q = months ? `?months=${months}` : "";
+        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) {
@@ -1708,9 +1950,17 @@ export const toolDefinitions = {
                 .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 }) => {
-            const q = months ? `?months=${months}` : "";
+        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) {
@@ -1743,14 +1993,22 @@ export const toolDefinitions = {
             };
         },
     },
-    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.`,
+    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 180)."),
+            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 }) => {
-            const q = days ? `?days=${days}` : "";
-            const res = await apiGet(`/api/dtc/merchandising${q}`);
+        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 {
@@ -1764,7 +2022,7 @@ export const toolDefinitions = {
             }
             const money = (n) => `$${Math.round(n).toLocaleString()}`;
             const lines = [
-                `${APEX} Merchandising — ${money(d.totals.revenue)} product revenue, ${d.totals.purchases} purchases`,
+                `${APEX} Product sales — ${money(d.totals.revenue)} product revenue, ${d.totals.purchases} purchases`,
                 "═".repeat(40),
                 ...d.items
                     .slice(0, 10)
@@ -1775,14 +2033,22 @@ export const toolDefinitions = {
             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.`,
+    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 180)."),
+            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 }) => {
-            const q = days ? `?days=${days}` : "";
-            const res = await apiGet(`/api/dtc/returns${q}`);
+        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 {
@@ -1811,14 +2077,26 @@ export const toolDefinitions = {
         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)."),
+            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, category, geo, priceBand, }) => {
+        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)
@@ -3445,20 +3723,31 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         }),
         handler: async ({ journeyId, confirmLive }) => {
             const path = `/api/journeys/${encodeURIComponent(journeyId)}/publish`;
+            // Non-blocking coverage warnings ("we couldn't verify these until the
+            // journey fires") — surfaced so an agent can preview before publishing.
+            const warnText = (warnings) => {
+                const list = Array.isArray(warnings) ? warnings.filter((w) => w?.reason) : [];
+                if (list.length === 0)
+                    return "";
+                return (`\n\n${list.length} thing${list.length === 1 ? "" : "s"} we couldn't verify until it fires (preview with example data to check):\n` +
+                    list.map((w) => `  • ${w.reason}`).join("\n"));
+            };
             if (!confirmLive) {
                 try {
-                    await apiPost(`${path}?dryRun=true`, {});
-                    return { content: [{ type: "text", text: `${APEX} Dry-run passed — journey ${journeyId} is valid and ready. Re-call with confirmLive:true to publish it to live customers.` }] };
+                    const dr = await apiPost(`${path}?dryRun=true`, {});
+                    return { content: [{ type: "text", text: `${APEX} Dry-run passed — journey ${journeyId} is valid and ready.${warnText(dr?.warnings)}\nRe-call with confirmLive:true to publish it to live customers.` }] };
                 }
                 catch (err) {
-                    return { content: [{ type: "text", text: `${APEX} Dry-run found a problem before publishing: ${errMsg(err)}` }], isError: true };
+                    // A variable-coverage block arrives here with a plain message like
+                    // "This send uses {{first_name}}, but the trigger doesn't provide it."
+                    return { content: [{ type: "text", text: `${APEX} Dry-run found a problem before publishing: ${errMsg(err)}\nIf a variable won't resolve, map it to a field the trigger provides or remove it, then preview with example data.` }], isError: true };
                 }
             }
             try {
                 const res = await apiPost(path, {});
                 if (!tenantOk(res.workspaceKey))
                     return tenantMismatch();
-                return { content: [{ type: "text", text: `${APEX} Published journey ${journeyId} — it is now live on trigger events. View it: ${journeyLink(journeyId)}` }] };
+                return { content: [{ type: "text", text: `${APEX} Published journey ${journeyId} — it is now live on trigger events.${warnText(res?.warnings)} View it: ${journeyLink(journeyId)}` }] };
             }
             catch (err) {
                 return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
@@ -4344,5 +4633,104 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             };
         },
     },
+    // ─── Adoption Engine ──────────────────────────────────────────────────────
+    list_adoption_milestones: {
+        description: `${APEX} — List the workspace's adoption milestones (per-feature "has this user adopted X?" definitions). A milestone is NOT a goal.`,
+        schema: z.object({}),
+        handler: async () => {
+            const data = await apiGet("/api/adoption/milestones");
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(data?.data?.milestones ?? [], null, 2) },
+                ],
+            };
+        },
+    },
+    get_adoption_milestone: {
+        description: `${APEX} — Fetch one adoption milestone by id.`,
+        schema: z.object({ milestoneId: z.string().describe("The milestone id") }),
+        handler: async ({ milestoneId }) => {
+            const data = await apiGet(`/api/adoption/milestones/${encodeURIComponent(milestoneId)}`);
+            return {
+                content: [{ type: "text", text: JSON.stringify(data?.data?.milestone ?? null, null, 2) }],
+            };
+        },
+    },
+    create_adoption_milestone: {
+        description: `${APEX} — Create an adoption milestone. "Adopted" is defined by one of the workspace's own events (adoptedWhenKind="event", eventName) or a trait (adoptedWhenKind="trait", traitPath + traitValue). Starts OFF unless active=true.`,
+        schema: z.object({
+            name: z.string().describe("Human label, e.g. 'Ran first report'"),
+            featureKey: z.string().describe("Stable feature key, e.g. 'reporting'"),
+            adoptedWhenKind: z.enum(["event", "trait"]).describe("How adoption is detected"),
+            eventName: z.string().optional().describe("event kind: the event whose firing means adopted"),
+            traitPath: z.string().optional().describe("trait kind: dotted trait path, e.g. 'plan'"),
+            traitValue: z.string().optional().describe("trait kind: value to match (equals)"),
+            priority: z.number().optional().describe("Lower is nudged first. Default 100."),
+            gapDays: z.number().optional().describe("Nudge this many days after signup if not adopted. Default 3."),
+            active: z.boolean().optional().describe("Turn the milestone on. Default false."),
+        }),
+        handler: async (args) => {
+            const body = {
+                name: args.name,
+                featureKey: args.featureKey,
+                priority: args.priority ?? 100,
+                active: args.active ?? false,
+                gapPolicy: { kind: "days_since_signup", days: args.gapDays ?? 3 },
+                adoptedWhen: args.adoptedWhenKind === "event"
+                    ? { kind: "event", eventName: args.eventName }
+                    : { kind: "trait", traitPath: args.traitPath, traitOp: "equals", traitValue: args.traitValue },
+            };
+            const data = await apiPost("/api/adoption/milestones", body);
+            return {
+                content: [{ type: "text", text: JSON.stringify(data?.data?.milestone ?? data, null, 2) }],
+            };
+        },
+    },
+    update_adoption_milestone: {
+        description: `${APEX} — Update an adoption milestone (name, priority, active, gapDays, nudgeJourneyId).`,
+        schema: z.object({
+            milestoneId: z.string(),
+            name: z.string().optional(),
+            priority: z.number().optional(),
+            active: z.boolean().optional(),
+            gapDays: z.number().optional(),
+            nudgeJourneyId: z.string().optional(),
+        }),
+        handler: async (args) => {
+            const updates = {};
+            if (args.name !== undefined)
+                updates.name = args.name;
+            if (args.priority !== undefined)
+                updates.priority = args.priority;
+            if (args.active !== undefined)
+                updates.active = args.active;
+            if (args.nudgeJourneyId !== undefined)
+                updates.nudgeJourneyId = args.nudgeJourneyId;
+            if (args.gapDays !== undefined)
+                updates.gapPolicy = { days: args.gapDays };
+            const data = await apiPatch(`/api/adoption/milestones/${encodeURIComponent(args.milestoneId)}`, updates);
+            return {
+                content: [{ type: "text", text: JSON.stringify(data?.data?.milestone ?? data, null, 2) }],
+            };
+        },
+    },
+    delete_adoption_milestone: {
+        description: `${APEX} — Delete an adoption milestone.`,
+        schema: z.object({ milestoneId: z.string() }),
+        handler: async ({ milestoneId }) => {
+            await apiDelete(`/api/adoption/milestones/${encodeURIComponent(milestoneId)}`);
+            return { content: [{ type: "text", text: `Deleted milestone ${milestoneId}.` }] };
+        },
+    },
+    get_adoption_metrics: {
+        description: `${APEX} — Aggregated adoption metrics: per-milestone funnel + lift-vs-holdout, plus workspace health. Counts only (no user PII).`,
+        schema: z.object({}),
+        handler: async () => {
+            const data = await apiGet("/api/adoption/metrics");
+            return {
+                content: [{ type: "text", text: JSON.stringify(data?.data ?? {}, null, 2) }],
+            };
+        },
+    },
 };
 //# sourceMappingURL=tools.js.map