@apex-inc/mcp-server 0.9.4 → 0.9.8

package/dist/tools.js

@@ -11,6 +11,107 @@ const APEX = "∧ Apex";
  * separate agent sessions from each other.
  */
 const MCP_AGENT_VISITOR_ID = `mcp-agent-${Math.random().toString(36).slice(2, 10)}`;
+/** Control traffic % derived from the unified allocation weights (default 50). */
+function controlPctOf(exp) {
+    const w = exp.allocation?.weights?.control;
+    return typeof w === "number" ? Math.round(w * 100) : 50;
+}
+/**
+ * Days running, derived locally from startedAt/createdAt → completedAt/now.
+ * The legacy web shape carried a server-computed `daysRunning`; the unified
+ * shape does not, so we compute it from the lifecycle timestamps.
+ */
+function daysRunningOf(exp) {
+    const start = exp.startedAt || exp.createdAt;
+    if (!start)
+        return 0;
+    const startMs = new Date(start).getTime();
+    if (Number.isNaN(startMs))
+        return 0;
+    const endMs = exp.completedAt ? new Date(exp.completedAt).getTime() : Date.now();
+    return Math.max(0, Math.floor((endMs - startMs) / 86_400_000));
+}
+/** Find a unified variant by its key (e.g. "control", "variant_b"). */
+function findVariant(exp, key) {
+    return exp.variants?.find((v) => v.key === key);
+}
+/** Render a per-arm exposure line for wiring summaries. */
+function formatArmLine(arm) {
+    const live = arm.exposures > 0;
+    const dot = live ? "●" : "○";
+    const seen = arm.lastSeenAt ? `, last seen ${arm.lastSeenAt}` : "";
+    return `  ${dot} ${arm.label} (${arm.variantKey}): ${arm.exposures} exposure${arm.exposures === 1 ? "" : "s"}${seen}`;
+}
+/** "add_to_cart" → "Add To Cart" (for primaryMetric labels). */
+function titleCaseEvent(event) {
+    return event
+        .split(/[_\s]+/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
+/**
+ * Shared schema + handler for `switch_workspace` (canonical) and its
+ * deprecated alias `switch_project`. Both register against the same handler
+ * so existing agent calls keep working through the project→workspace rename.
+ *
+ * After updating the active workspace locally, we VALIDATE the switch with an
+ * authed read against `/api/setup-state` (which `apiGet` scopes to the active
+ * workspace). Validation is non-fatal: the local switch always succeeds, but
+ * we surface an auth/reachability warning so the user knows to connect or
+ * fix the workspace key.
+ */
+const switchWorkspaceSchema = z.object({
+    workspaceKey: z.string().optional().describe("The workspace key to switch to."),
+    projectKey: z
+        .string()
+        .optional()
+        .describe("Deprecated alias of workspaceKey. Use workspaceKey."),
+});
+async function switchWorkspaceHandler(args) {
+    const key = args.workspaceKey ?? args.projectKey;
+    if (!key) {
+        return {
+            content: [{
+                    type: "text",
+                    text: "Provide a workspaceKey to switch to (projectKey is accepted as a deprecated alias).",
+                }],
+            isError: true,
+        };
+    }
+    setActiveWorkspace(key);
+    const deprecationNote = !args.workspaceKey && args.projectKey
+        ? " (note: `projectKey` is deprecated — use `workspaceKey`.)"
+        : "";
+    // Validate the switch by reading setup-state for the now-active workspace.
+    let validation = " Verified — Apex can read this workspace.";
+    try {
+        await apiGet("/api/setup-state");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (/\(401\)|\(403\)|authentication failed/i.test(message)) {
+            validation =
+                "\n\n⚠️ Switched locally, but could not verify the workspace — authentication failed. " +
+                    "Connect the MCP server to Apex (run any Apex tool to get a one-time approval link), " +
+                    "or regenerate APEX_API_KEY in Apex → Settings → AI Agents, then try again.";
+        }
+        else if (/\(404\)/.test(message)) {
+            validation =
+                `\n\n⚠️ Switched locally, but Apex returned 404 for "${key}" — the workspace key may be wrong. ` +
+                    "Use list_projects to see the valid keys for your API key.";
+        }
+        else {
+            validation = `\n\n⚠️ Switched locally, but could not reach Apex to verify it (${message}).`;
+        }
+    }
+    return {
+        content: [{
+                type: "text",
+                text: `Switched to workspace: ${key}. All subsequent calls will use this workspace.${deprecationNote}${validation}`,
+            }],
+    };
+}
 export const toolDefinitions = {
     plan_experiment: {
         description: `${APEX} — PLANNING ONLY, does not create anything. Analyzes a goal against existing beliefs and experiments, then returns structured options for the user to choose from. After calling, you MUST present the returned options as a numbered list or poll and wait for the user to pick before calling any other Apex tools.`,
@@ -21,7 +122,7 @@ export const toolDefinitions = {
         handler: async ({ goal, targetUrl }) => {
             const [beliefs, experiments] = await Promise.all([
                 apiGet("/api/beliefs"),
-                apiGet("/api/experiments"),
+                apiGet("/api/experiments?unified=true"),
             ]);
             const keywords = goal
                 .toLowerCase()
@@ -167,6 +268,10 @@ export const toolDefinitions = {
             beliefId: z.string().optional().describe("ID of the assumption this tests"),
             hypothesisId: z.string().optional().describe("ID of the expected outcome"),
             predictionId: z.string().optional().describe("ID of the expected impact"),
+            beliefStatement: z.string().optional().describe("If you don't have a beliefId, pass the assumption statement and Apex will create the belief (and a hypothesis) and link them to this experiment."),
+            beliefConfidence: z.number().min(0).max(100).optional().describe("Confidence (0-100%) for the belief created from beliefStatement. Defaults to 50."),
+            hypothesisStatement: z.string().optional().describe("Optional hypothesis statement to record alongside a belief created from beliefStatement."),
+            primaryMetricEvent: z.string().optional().describe("Canonical event name the experiment optimizes, e.g. 'add_to_cart', 'checkout_completed', 'form_submit'. Validated against the workspace event spec."),
             mode: z.enum(["sdk", "snippet"]).optional().describe("Experiment mode: 'sdk' for code-level (default via MCP), 'snippet' for runtime DOM"),
             preview: z.boolean().optional().describe("If true, returns a preview without creating. Default: true."),
         }),
@@ -174,6 +279,53 @@ export const toolDefinitions = {
             const split = args.trafficSplit ?? 50;
             const mode = args.mode ?? "sdk";
             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.
+            let primaryMetric = {
+                key: "conversion_rate",
+                label: "Conversion rate",
+                type: "rate",
+                unit: "%",
+                direction: "increase",
+                source: { kind: "event", eventType: "form_submit" },
+            };
+            if (args.primaryMetricEvent) {
+                const event = args.primaryMetricEvent.trim();
+                let validEvents = [];
+                try {
+                    const spec = await apiGet("/api/spec/events");
+                    validEvents = Object.keys(spec.data?.events ?? {});
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    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.`,
+                            }],
+                        isError: true,
+                    };
+                }
+                if (validEvents.length && !validEvents.includes(event)) {
+                    const sample = validEvents.slice(0, 12).join(", ");
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `"${event}" is not a canonical event in this workspace's event spec. Valid options include: ${sample}${validEvents.length > 12 ? ", …" : ""}. Use get_event_spec for the full list.`,
+                            }],
+                        isError: true,
+                    };
+                }
+                primaryMetric = {
+                    key: `${event}_rate`,
+                    label: `${titleCaseEvent(event)} rate`,
+                    type: "rate",
+                    unit: "%",
+                    direction: "increase",
+                    source: { kind: "event", eventType: event },
+                };
+            }
             if (isPreview) {
                 const recipe = {
                     _apex: true,
@@ -186,25 +338,74 @@ export const toolDefinitions = {
                     trafficSplit: { control: split, variant: 100 - split },
                     control: args.controlContent,
                     variant: args.variantContent,
+                    primaryMetric: primaryMetric.key,
                     beliefId: args.beliefId || null,
+                    beliefStatement: args.beliefStatement || null,
                     predictionId: args.predictionId || null,
                     _instructions: "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) }] };
             }
+            // p2-linking — if the caller passed a belief statement instead of a
+            // pre-created beliefId, create the belief + hypothesis (mirroring
+            // start_reasoning) and link them to this experiment.
+            let beliefId = args.beliefId;
+            let hypothesisId = args.hypothesisId;
+            if (!beliefId && args.beliefStatement) {
+                const confidence = args.beliefConfidence != null ? args.beliefConfidence / 100 : 0.5;
+                const b = await apiPost("/api/beliefs", {
+                    statement: args.beliefStatement,
+                    confidence,
+                });
+                beliefId = b.id;
+                const hypothesisStatement = args.hypothesisStatement ??
+                    `If we act on "${args.beliefStatement.slice(0, 80)}", then we should see a measurable improvement in "${args.name}".`;
+                const h = await apiPost("/api/hypotheses", {
+                    beliefId: b.id,
+                    statement: hypothesisStatement,
+                    predictedEffect: `Impact related to: ${args.name.slice(0, 60)}`,
+                    confidence,
+                    status: "active",
+                });
+                hypothesisId = h.id;
+            }
+            const controlW = split / 100;
             const exp = await apiPost("/api/experiments", {
+                surface: "web",
                 name: args.name,
                 targetUrl: args.targetUrl,
-                trafficSplit: split,
-                beliefId: args.beliefId,
-                hypothesisId: args.hypothesisId,
-                predictionId: args.predictionId,
-                mode,
                 targetAnchor: args.targetAnchor,
-                variants: {
-                    control: { name: "Control", description: "Original content", changes: [] },
-                    variant_b: {
-                        name: "Variant B",
+                createdFrom: "cursor",
+                status: "draft",
+                hypothesis: "",
+                prediction: { direction: "increase", magnitude: "" },
+                confidence: 50,
+                beliefId,
+                hypothesisId,
+                predictionId: args.predictionId,
+                primaryMetric,
+                allocation: { strategy: "hash", weights: { control: controlW, variant_b: 1 - controlW } },
+                secondaryMetrics: [],
+                guardrailMetrics: [],
+                attributionWindow: { unit: "hours", value: 24, startFrom: "first_interaction" },
+                variants: [
+                    {
+                        id: "v_control",
+                        key: "control",
+                        label: "Control",
+                        surface: "web",
+                        mode,
+                        createdAt: new Date().toISOString(),
+                        description: "Original content",
+                        changes: [],
+                    },
+                    {
+                        id: "v_b",
+                        key: "variant_b",
+                        label: "Variant B",
+                        surface: "web",
+                        mode,
+                        createdAt: new Date().toISOString(),
                         description: "Modified content",
                         changes: [
                             {
@@ -215,7 +416,7 @@ export const toolDefinitions = {
                             },
                         ],
                     },
-                },
+                ],
             });
             let previewUrl = "";
             try {
@@ -234,9 +435,14 @@ export const toolDefinitions = {
                 name: exp.name,
                 status: exp.status,
                 mode,
+                primaryMetric: primaryMetric.key,
+                beliefId: beliefId || null,
+                hypothesisId: hypothesisId || null,
+                predictionId: args.predictionId || null,
                 sdk: mode === "sdk" ? {
                     hook: "useApexVariant",
-                    import: "@/lib/apex-sdk",
+                    import: "@apex-inc/react",
+                    install: "npm i @apex-inc/react",
                     experimentId: exp.id,
                     targetComponent: args.targetComponent || null,
                     targetAnchor: args.targetAnchor || null,
@@ -249,14 +455,15 @@ export const toolDefinitions = {
                     ? [
                         "IMPLEMENT THE EXPERIMENT IN CODE:",
                         `1. Open the target file${args.targetComponent ? ` (${args.targetComponent})` : ""}`,
-                        `2. Add: import { useApexVariant } from "@/lib/apex-sdk"`,
-                        `3. In the component, add: const variant = useApexVariant("${exp.id}")`,
-                        `4. Wrap the target content in a conditional:`,
+                        `2. Install the hook package: npm i @apex-inc/react`,
+                        `3. Add: import { useApexVariant } from "@apex-inc/react"`,
+                        `4. In the component, add: const variant = useApexVariant("${exp.id}")`,
+                        `5. Wrap the target content in a conditional:`,
                         `   {variant === "variant_b" ? <VARIANT_CONTENT> : <CONTROL_CONTENT>}`,
-                        `5. Show the user the diff and ask them to preview at: ${previewUrl}`,
-                        `6. After preview approval, commit and push`,
-                        `7. Call track_deployment with the experiment ID and commit SHA`,
-                        `8. Call activate_experiment after deployment confirms`,
+                        `6. Show the user the diff and ask them to preview at: ${previewUrl}`,
+                        `7. After preview approval, commit and push`,
+                        `8. Call track_deployment with the experiment ID and commit SHA`,
+                        `9. Call activate_experiment after deployment confirms`,
                     ].join("\n")
                     : [
                         "SNIPPET MODE — no code changes needed.",
@@ -268,16 +475,207 @@ export const toolDefinitions = {
             return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
         },
     },
+    attach_experiment_asset: {
+        description: `${APEX} — Attach a variant screenshot to an experiment. Use after capturing a control/variant screenshot: for localhost or auth-gated pages the agent captures, pass imageBase64; for an already-hosted image, pass url. The stored asset shows on the dashboard experiment card and the experiment detail gallery.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to attach the screenshot to"),
+            variantKey: z.string().describe("control | variant_b | …"),
+            imageBase64: z.string().optional().describe("Base64-encoded PNG/JPEG. For localhost/auth-gated pages captured by the agent."),
+            url: z.string().url().optional().describe("Already-hosted public image URL."),
+            viewport: z.enum(["desktop", "tablet", "mobile"]).optional().describe("Viewport the screenshot was captured at (default desktop)."),
+            format: z.enum(["png", "jpeg"]).optional().describe("Image format (default png)."),
+            label: z.string().optional().describe("Optional caption for the asset."),
+            commitSha: z.string().optional().describe("Optional commit SHA the screenshot corresponds to."),
+        }),
+        handler: async (args) => {
+            if (!args.imageBase64 && !args.url) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Provide either imageBase64 (for localhost/auth-gated captures) or url (an already-hosted image).",
+                        }],
+                    isError: true,
+                };
+            }
+            const res = await apiPost(`/api/experiments/${encodeURIComponent(args.experimentId)}/assets`, {
+                variantKey: args.variantKey,
+                source: "agent",
+                viewport: args.viewport ?? "desktop",
+                imageBase64: args.imageBase64,
+                url: args.url,
+                format: args.format ?? "png",
+                label: args.label,
+                commitSha: args.commitSha,
+            });
+            const asset = res.data;
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            `${APEX} Screenshot attached to experiment ${args.experimentId}`,
+                            ``,
+                            `  Variant: ${asset.variantKey}`,
+                            `  Viewport: ${asset.viewport}`,
+                            `  Stored at: ${asset.url}`,
+                            ``,
+                            `It now shows on the dashboard experiment card and the experiment detail gallery.`,
+                        ].join("\n"),
+                    }],
+            };
+        },
+    },
+    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({
+            experimentId: z.string().describe("The experiment ID to verify wiring for"),
+        }),
+        handler: async ({ experimentId }) => {
+            const wiring = (await apiGet(`/api/experiments/${experimentId}/wiring`)).data;
+            const armLines = wiring.perArm.map(formatArmLine);
+            const zeroArms = wiring.perArm.filter((a) => a.exposures === 0);
+            let verdictLine;
+            let nextStep;
+            switch (wiring.verdict) {
+                case "wired":
+                    verdictLine = `WIRED — all ${wiring.totalArms} arm(s) are producing exposures`;
+                    nextStep =
+                        "Safe to activate. Call activate_experiment to launch — both arms are " +
+                            "already receiving traffic and recording exposures.";
+                    break;
+                case "partial": {
+                    const names = zeroArms
+                        .map((a) => `${a.label} (${a.variantKey})`)
+                        .join(", ");
+                    verdictLine = `PARTIAL — ${wiring.armsLive}/${wiring.totalArms} arm(s) live`;
+                    nextStep =
+                        `These arm(s) have ZERO exposures: ${names}. ` +
+                            "Make sure the variant-serving code returns every variant key (not just the " +
+                            "control) and that traffic is reaching each branch, then re-check. Don't " +
+                            "activate until every arm is producing exposures.";
+                    break;
+                }
+                case "no_exposures":
+                default:
+                    verdictLine = "NO EXPOSURES — no exposures recorded for any arm";
+                    nextStep =
+                        "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.";
+                    break;
+            }
+            const summary = [
+                `${APEX} Experiment Wiring Check`,
+                `${"═".repeat(40)}`,
+                ``,
+                `  Experiment: ${wiring.experimentId}`,
+                `  Surface: ${wiring.surface}`,
+                `  Status: ${wiring.status}`,
+                `  Verdict: ${verdictLine}`,
+                `  Total exposures: ${wiring.totalExposures}`,
+                ``,
+                `  Per-arm exposures:`,
+                ...armLines,
+                ``,
+                `  Next step: ${nextStep}`,
+                ``,
+                `${"═".repeat(40)}`,
+            ].join("\n");
+            return {
+                content: [
+                    { type: "text", text: summary },
+                    {
+                        type: "text",
+                        text: JSON.stringify({ _apex: true, _type: "wiring_check", ...wiring }, null, 2),
+                    },
+                ],
+            };
+        },
+    },
     activate_experiment: {
-        description: `${APEX} — Launch an experiment. Changes its status from draft to running. Traffic will be split immediately. 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) and refuses to launch an unwired experiment 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
+                .boolean()
+                .optional()
+                .describe("Override the wiring safety check and activate even if both arms aren't producing exposures yet. Use only when you knowingly accept launching without verified wiring."),
         }),
-        handler: async ({ experimentId }) => {
+        handler: async ({ experimentId, force }) => {
+            // Best-effort wiring gate: don't launch an experiment that silently
+            // collects no data. If the wiring endpoint itself errors, don't hard-block.
+            let wiring;
+            let wiringError;
+            try {
+                wiring = (await apiGet(`/api/experiments/${experimentId}/wiring`)).data;
+            }
+            catch (err) {
+                wiringError = err instanceof Error ? err.message : String(err);
+            }
+            if (wiring && !wiring.bothArmsLive && force !== true) {
+                const armLines = wiring.perArm.map(formatArmLine);
+                const zeroArms = wiring.perArm
+                    .filter((a) => a.exposures === 0)
+                    .map((a) => `${a.label} (${a.variantKey})`);
+                const refusal = [
+                    `${APEX} Activation Refused — experiment is not wired up`,
+                    `${"═".repeat(40)}`,
+                    ``,
+                    `  Did NOT launch ${experimentId}.`,
+                    ``,
+                    `  Both arms must be producing \`experiment_exposure\` events before`,
+                    `  launch. Otherwise you'd start an experiment that silently collects`,
+                    `  no data on one or more arms.`,
+                    ``,
+                    `  Verdict: ${wiring.verdict} (${wiring.armsLive}/${wiring.totalArms} arm(s) live)`,
+                    `  Arm(s) with zero exposures: ${zeroArms.length ? zeroArms.join(", ") : "none"}`,
+                    ``,
+                    `  Per-arm exposures:`,
+                    ...armLines,
+                    ``,
+                    `  To fix: wire up and deploy the variant-serving code`,
+                    `  (useApexVariant / Apex.getVariant) so every arm records exposures,`,
+                    `  then re-run activate_experiment. Or, to override this check and`,
+                    `  launch anyway, re-run with force: true.`,
+                    ``,
+                    `${"═".repeat(40)}`,
+                ].join("\n");
+                return {
+                    content: [
+                        { type: "text", text: refusal },
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                _apex: true,
+                                _type: "activation_refused",
+                                reason: "not_wired",
+                                ...wiring,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             const exp = await apiPatch("/api/experiments", {
                 id: experimentId,
                 status: "running",
             });
+            // PATCH returns a minimal/legacy body — re-read the unified record to
+            // derive the live traffic split from the allocation weights.
+            let controlPct = 50;
+            try {
+                const unified = await apiGet(`/api/experiments/${experimentId}?unified=true`);
+                controlPct = controlPctOf(unified);
+            }
+            catch { /* fall back to 50/50 in the message */ }
+            // Surface why the wiring gate didn't block: either it couldn't be
+            // verified (best-effort) or the user explicitly forced past it.
+            const notes = [];
+            if (wiringError) {
+                notes.push(`  ⚠ Wiring could not be verified before launch (${wiringError}).`, `    Confirm both arms are recording exposures via verify_experiment_wiring.`, ``);
+            }
+            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.`, ``);
+            }
             return {
                 content: [
                     {
@@ -288,8 +686,9 @@ export const toolDefinitions = {
                             ``,
                             `  "${exp.name}" is now LIVE`,
                             `  ID: ${exp.id}`,
-                            `  Traffic is being split ${exp.trafficSplit}% / ${100 - exp.trafficSplit}%`,
+                            `  Traffic is being split ${controlPct}% / ${100 - controlPct}%`,
                             ``,
+                            ...notes,
                             `  Visitors will now see either the control or variant.`,
                             `  Results will appear in the dashboard and via get_results.`,
                             ``,
@@ -364,7 +763,7 @@ export const toolDefinitions = {
             experimentId: z.string().describe("The experiment ID to check"),
         }),
         handler: async ({ experimentId }) => {
-            const exp = await apiGet(`/api/experiments/${experimentId}`);
+            const exp = await apiGet(`/api/experiments/${experimentId}?unified=true`);
             if (!exp) {
                 return { content: [{ type: "text", text: JSON.stringify({ _apex: true, error: "Experiment not found" }) }] };
             }
@@ -437,7 +836,7 @@ export const toolDefinitions = {
                 .describe("Filter by status. Defaults to showing all except archived."),
         }),
         handler: async ({ status }) => {
-            const experiments = await apiGet("/api/experiments");
+            const experiments = await apiGet("/api/experiments?unified=true");
             const filtered = status === "all"
                 ? experiments
                 : status
@@ -446,26 +845,27 @@ export const toolDefinitions = {
             if (filtered.length === 0) {
                 return { content: [{ type: "text", text: `${APEX} No experiments found.` }] };
             }
-            const pendingGraduation = filtered.filter((e) => e.promoted && !e.graduated && !e.graduationDismissed);
+            const pendingGraduation = filtered.filter((e) => e.promoted && !e.graduated);
             const lines = filtered.map((e) => {
-                const ctrl = e.results?.control;
-                const varB = e.results?.variant_b;
-                const isPendingGrad = e.promoted && !e.graduated && !e.graduationDismissed;
+                const ctrl = e.results?.perVariant?.control;
+                const varB = e.results?.perVariant?.variant_b;
+                const isPendingGrad = !!(e.promoted && !e.graduated);
                 const statusIcon = isPendingGrad
                     ? "⬆"
                     : e.status === "running" ? "●" : e.status === "draft" ? "○" : e.status === "paused" ? "◐" : "◉";
                 const statusLabel = isPendingGrad
                     ? `${e.status}] [PENDING GRADUATION`
                     : e.status;
-                const changeSummary = isPendingGrad && e.winner && e.variants?.[e.winner]?.changes?.length
-                    ? `  Changes to graduate: ${e.variants[e.winner].changes.map((c) => `"${c.originalValue ?? c.value}" → "${c.value}"`).join(", ")}`
+                const winnerVariant = e.winner ? findVariant(e, e.winner) : undefined;
+                const changeSummary = isPendingGrad && winnerVariant?.changes?.length
+                    ? `  Changes to graduate: ${winnerVariant.changes.map((c) => `"${c.originalValue ?? c.value}" → "${c.value}"`).join(", ")}`
                     : "";
                 return [
                     `${statusIcon} ${e.name} [${statusLabel}]`,
                     `  ID: ${e.id}`,
-                    `  URL: ${e.targetUrl} | ${e.daysRunning ?? 0}d running`,
+                    `  URL: ${e.targetUrl ?? "—"} | ${daysRunningOf(e)}d running`,
                     ctrl && varB
-                        ? `  Control: ${ctrl.conversionRate}% CVR (${ctrl.visitors} visitors) | Variant: ${varB.conversionRate}% CVR (${varB.visitors} visitors)`
+                        ? `  Control: ${ctrl.conversionRate ?? 0}% CVR (${ctrl.assigned} visitors) | Variant: ${varB.conversionRate ?? 0}% CVR (${varB.assigned} visitors)`
                         : "  No results yet",
                     e.beliefId ? `  Belief: ${e.beliefId}` : "",
                     changeSummary,
@@ -486,12 +886,12 @@ export const toolDefinitions = {
             experimentId: z.string().describe("The experiment ID"),
         }),
         handler: async ({ experimentId }) => {
-            const exp = await apiGet(`/api/experiments/${experimentId}`);
+            const exp = await apiGet(`/api/experiments/${experimentId}?unified=true`);
             if (!exp) {
                 return { content: [{ type: "text", text: `${APEX} Experiment ${experimentId} not found.` }] };
             }
-            const ctrl = exp.results?.control;
-            const varB = exp.results?.variant_b;
+            const ctrl = exp.results?.perVariant?.control;
+            const varB = exp.results?.perVariant?.variant_b;
             return {
                 content: [
                     {
@@ -501,17 +901,17 @@ export const toolDefinitions = {
                             `${"═".repeat(40)}`,
                             ``,
                             `  Status:     ${exp.status}`,
-                            `  Running:    ${exp.daysRunning ?? 0} days`,
+                            `  Running:    ${daysRunningOf(exp)} days`,
                             `  Confidence: ${exp.confidence ?? 0}%`,
-                            `  URL:        ${exp.targetUrl}`,
+                            `  URL:        ${exp.targetUrl ?? "—"}`,
                             ``,
                             `  Control:`,
                             ctrl
-                                ? `    ${ctrl.visitors} visitors | ${ctrl.leads} conversions | ${ctrl.conversionRate}% CVR`
+                                ? `    ${ctrl.assigned} visitors | ${ctrl.converted} conversions | ${ctrl.conversionRate ?? 0}% CVR`
                                 : "    No data yet",
                             `  Variant B:`,
                             varB
-                                ? `    ${varB.visitors} visitors | ${varB.leads} conversions | ${varB.conversionRate}% CVR`
+                                ? `    ${varB.assigned} visitors | ${varB.converted} conversions | ${varB.conversionRate ?? 0}% CVR`
                                 : "    No data yet",
                             exp.beliefId ? `\n  Linked belief: ${exp.beliefId}` : "",
                             ``,
@@ -541,7 +941,7 @@ export const toolDefinitions = {
         handler: async ({ context }) => {
             const [beliefs, experiments] = await Promise.all([
                 apiGet("/api/beliefs"),
-                apiGet("/api/experiments"),
+                apiGet("/api/experiments?unified=true"),
             ]);
             const lowConfidence = beliefs.filter((b) => b.confidence < 0.6 && b.confidence > 0.05);
             const untested = beliefs.filter((b) => b.confidence > 0.05 && !experiments.some((e) => e.beliefId === b.id));
@@ -574,10 +974,12 @@ export const toolDefinitions = {
             }
             if (relevantExperiments.length > 0) {
                 recs.push(`**Past experiments in this area** (${relevantExperiments.length}):`, ...relevantExperiments.slice(0, 3).map((e) => {
-                    const ctrl = e.results?.control;
-                    const varB = e.results?.variant_b;
-                    const lift = ctrl && varB && ctrl.conversionRate > 0
-                        ? ((varB.conversionRate - ctrl.conversionRate) / ctrl.conversionRate * 100).toFixed(1)
+                    const ctrl = e.results?.perVariant?.control;
+                    const varB = e.results?.perVariant?.variant_b;
+                    const ctrlCvr = ctrl?.conversionRate ?? 0;
+                    const varCvr = varB?.conversionRate ?? 0;
+                    const lift = ctrl && varB && ctrlCvr > 0
+                        ? ((varCvr - ctrlCvr) / ctrlCvr * 100).toFixed(1)
                         : "N/A";
                     return `  - "${e.name}" — ${lift}% lift, ${e.confidence}% confidence`;
                 }), "");
@@ -605,7 +1007,7 @@ export const toolDefinitions = {
             winner: z.enum(["control", "variant_b"]).describe("Which variant won"),
         }),
         handler: async ({ experimentId, winner }) => {
-            const existing = await apiGet(`/api/experiments/${experimentId}`);
+            const existing = await apiGet(`/api/experiments/${experimentId}?unified=true`);
             if (existing.status !== "completed" || !existing.winner) {
                 await apiPatch(`/api/experiments`, {
                     id: experimentId,
@@ -617,10 +1019,13 @@ export const toolDefinitions = {
                 id: experimentId,
                 action: "promote",
             });
+            // PATCH responses are minimal — winner content / belief link / mode come
+            // from the unified record fetched at the top.
+            const beliefId = existing.beliefId;
             let beliefUpdate = "";
-            if (promoted.beliefId) {
+            if (beliefId) {
                 try {
-                    const result = await apiPost(`/api/beliefs/${promoted.beliefId}/update-confidence`, {
+                    const result = await apiPost(`/api/beliefs/${beliefId}/update-confidence`, {
                         experimentId,
                         outcome: winner === "variant_b" ? "confirmed" : "contradicted",
                         metricDelta: winner === "variant_b" ? 0.15 : -0.1,
@@ -631,11 +1036,11 @@ export const toolDefinitions = {
                     beliefUpdate = "Could not update assumption certainty automatically.";
                 }
             }
-            const winnerVariant = promoted.variants?.[winner];
+            const winnerVariant = findVariant(existing, winner);
             const changeSummary = winnerVariant?.changes?.length
                 ? winnerVariant.changes.map((c) => `  • ${c.type}: "${c.originalValue ?? "(unknown)"}" → "${c.value}" (${c.selector})`).join("\n")
                 : "  No DOM changes recorded.";
-            const nextStep = promoted.mode === "sdk"
+            const nextStep = winnerVariant?.mode === "sdk"
                 ? `Use graduate_experiment("${experimentId}") to get cleanup instructions for removing useApexVariant() conditionals from your code.`
                 : `Use graduate_experiment("${experimentId}") to get instructions for making these changes permanent in your source code. The Apex snippet handles serving the winner in the meantime.`;
             const output = [
@@ -829,7 +1234,7 @@ export const toolDefinitions = {
         handler: async ({ feature, targetMetric }) => {
             const [beliefs, experiments] = await Promise.all([
                 apiGet("/api/beliefs"),
-                apiGet("/api/experiments"),
+                apiGet("/api/experiments?unified=true"),
             ]);
             const keywords = feature
                 .toLowerCase()
@@ -850,10 +1255,12 @@ export const toolDefinitions = {
             const lowConfRelevant = relevantBeliefs.filter((b) => b.confidence < 0.6);
             const avgLift = relevantExperiments.length > 0
                 ? relevantExperiments.reduce((sum, e) => {
-                    const ctrl = e.results?.control;
-                    const varB = e.results?.variant_b;
-                    if (ctrl && varB && ctrl.conversionRate > 0) {
-                        return sum + ((varB.conversionRate - ctrl.conversionRate) / ctrl.conversionRate) * 100;
+                    const ctrl = e.results?.perVariant?.control;
+                    const varB = e.results?.perVariant?.variant_b;
+                    const ctrlCvr = ctrl?.conversionRate ?? 0;
+                    const varCvr = varB?.conversionRate ?? 0;
+                    if (ctrl && varB && ctrlCvr > 0) {
+                        return sum + ((varCvr - ctrlCvr) / ctrlCvr) * 100;
                     }
                     return sum;
                 }, 0) / relevantExperiments.length
@@ -874,10 +1281,12 @@ export const toolDefinitions = {
             }
             if (relevantExperiments.length > 0) {
                 lines.push(`**Historical evidence** (${relevantExperiments.length} related experiments):`, ...relevantExperiments.slice(0, 5).map((e) => {
-                    const ctrl = e.results?.control;
-                    const varB = e.results?.variant_b;
-                    const lift = ctrl && varB && ctrl.conversionRate > 0
-                        ? `${((varB.conversionRate - ctrl.conversionRate) / ctrl.conversionRate * 100).toFixed(1)}%`
+                    const ctrl = e.results?.perVariant?.control;
+                    const varB = e.results?.perVariant?.variant_b;
+                    const ctrlCvr = ctrl?.conversionRate ?? 0;
+                    const varCvr = varB?.conversionRate ?? 0;
+                    const lift = ctrl && varB && ctrlCvr > 0
+                        ? `${((varCvr - ctrlCvr) / ctrlCvr * 100).toFixed(1)}%`
                         : "N/A";
                     return `  - "${e.name}": ${lift} lift`;
                 }), avgLift !== null ? `  Average lift in this area: ${avgLift > 0 ? "+" : ""}${avgLift.toFixed(1)}%` : "", "");
@@ -1152,44 +1561,19 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             };
         },
     },
+    // `switch_workspace` is canonical; `switch_project` is the deprecated alias
+    // kept for the project→workspace rename. Both point at the same handler/
+    // schema so existing agent calls keep working. (Auth-experience fix
+    // 2026-06-13; deprecation alias formalized 2026-06-14.)
+    switch_workspace: {
+        description: "Switch the active workspace for this session. All subsequent API calls will use this workspace. After switching, Apex verifies it can read the workspace and warns if authentication or the workspace key looks wrong.",
+        schema: switchWorkspaceSchema,
+        handler: switchWorkspaceHandler,
+    },
     switch_project: {
-        description: "Switch the active workspace for this session. All subsequent API calls will use this workspace.",
-        // `projectKey` is the deprecated alias of `workspaceKey` (the
-        // project→workspace rename). Accept either for one deprecation cycle —
-        // hard-rejecting `projectKey` broke existing agent calls and diverged
-        // from the SDK, which still aliases it. (Auth-experience fix 2026-06-13.)
-        schema: z.object({
-            workspaceKey: z
-                .string()
-                .optional()
-                .describe("The workspace key to switch to"),
-            projectKey: z
-                .string()
-                .optional()
-                .describe("Deprecated alias of workspaceKey. Use workspaceKey."),
-        }),
-        handler: async (args) => {
-            const key = args.workspaceKey ?? args.projectKey;
-            if (!key) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: "Provide a workspaceKey to switch to (projectKey is accepted as a deprecated alias).",
-                        }],
-                    isError: true,
-                };
-            }
-            setActiveWorkspace(key);
-            const deprecationNote = !args.workspaceKey && args.projectKey
-                ? " (note: `projectKey` is deprecated — use `workspaceKey`.)"
-                : "";
-            return {
-                content: [{
-                        type: "text",
-                        text: `Switched to workspace: ${key}. All subsequent calls will use this workspace.${deprecationNote}`,
-                    }],
-            };
-        },
+        description: "DEPRECATED alias of switch_workspace — use switch_workspace. Switches the active workspace for this session; all subsequent API calls use it.",
+        schema: switchWorkspaceSchema,
+        handler: switchWorkspaceHandler,
     },
     list_orgs: {
         description: "List all organizations you have access to, with their workspaces. Use this to see which orgs and workspaces are available.",