@apex-inc/mcp-server 0.25.0 → 0.27.0

package/dist/tools.js

@@ -5,6 +5,8 @@ import { apiGet, apiPost, apiPatch, apiPut, apiDelete, postWithIdempotency, setA
 import { resolveExperimentHypothesis } from "./experiment-copy.js";
 import { controlGateGuidanceFor } from "./control-gate-guidance.js";
 import { getPersonLabel, lowerPerson } from "./person-label.js";
+import { notStartedExplanation, publishedExperimentLine, } from "./publish-communication-copy.js";
+import { activationLiveLine, shouldRefuseActivationWiring, } from "./activation-wiring.js";
 const APEX = "∧ Apex";
 /**
  * MOBX-006 — stable synthetic visitor id for agent-fired events.
@@ -81,28 +83,6 @@ function appUrl(path) {
     const base = process.env.APEX_URL || process.env.APEX_API_URL || "http://localhost:3001";
     return `${base.replace(/\/$/, "")}${path}`;
 }
-/**
- * Why publishing a comm with variants didn't start an experiment.
- *
- * Each of these is a missing precondition the user can actually fix, so the
- * agent is told what to do rather than that "nothing happened."
- */
-function notStartedExplanation(reason) {
-    switch (reason) {
-        case "no_host":
-            return "The variants were published but no experiment started: no published journey sends this communication, so there's no traffic to measure. Add it to a journey and publish that journey.";
-        case "no_goal":
-            return "The variants were published but no experiment started: the journey sending this communication has no goal event, so there's nothing to optimize toward. Set the journey's goal event first.";
-        case "ambiguous_host":
-            return "The variants were published but no experiment started: more than one published journey sends this communication. Re-issue publish_communication with host_journey_id.";
-        case "conflict":
-            return "The variants were published but no experiment started: another experiment already holds this communication. End it, then publish again.";
-        case "no_variants":
-            return "";
-        default:
-            return "The variants were published but the experiment could not be started. Check the communication in the dashboard.";
-    }
-}
 function journeyLink(id) {
     return appUrl(`/dashboard/communications/journeys/${id}`);
 }
@@ -1066,7 +1046,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). 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.`,
+        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 and journey_arm message tests do not need pre-activation exposures — journey traffic starts on the next send once running. Only wired web 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
@@ -1091,11 +1071,7 @@ export const toolDefinitions = {
             // 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) {
+            if (wiring && shouldRefuseActivationWiring(wiring, force)) {
                 const armLines = wiring.perArm.map(formatArmLine);
                 const zeroArms = wiring.perArm
                     .filter((a) => a.exposures === 0)
@@ -1194,9 +1170,11 @@ export const toolDefinitions = {
             // PATCH returns a minimal/legacy body — re-read the unified record to
             // derive the live traffic split from the allocation weights.
             let controlPct = 50;
+            let liveSurface = exp.surface;
             try {
                 const unified = await apiGet(`/api/experiments/${experimentId}?unified=true`);
                 controlPct = controlPctOf(unified);
+                liveSurface = unified.surface ?? liveSurface;
             }
             catch { /* fall back to 50/50 in the message */ }
             // Surface why the wiring gate didn't block: either it couldn't be
@@ -1235,7 +1213,7 @@ export const toolDefinitions = {
                             `  Traffic is being split ${controlPct}% / ${100 - controlPct}%`,
                             ``,
                             ...notes,
-                            `  Visitors will now see either the control or variant.`,
+                            `  ${activationLiveLine(liveSurface)}`,
                             `  Results will appear in the dashboard and via get_results.`,
                             ``,
                             `${"═".repeat(40)}`,
@@ -1746,7 +1724,15 @@ export const toolDefinitions = {
                     content: [
                         {
                             type: "text",
-                            text: `${APEX} Forked into a fresh draft "${forked.name}" (id: ${forked.id}). Edit it with update_experiment, then activate.`,
+                            text: [
+                                `${APEX} Forked into a fresh draft "${forked.name}" (id: ${forked.id}).`,
+                                ``,
+                                `A copy gets a new id. The page still asks the old one until you replace it.`,
+                                `  Find:    const variant = useApexVariant("${experimentId}");`,
+                                `  Replace: const variant = useApexVariant("${forked.id}");`,
+                                `Deploy that change, then activate.`,
+                                `Preview still works via _apex_exp. A normal visit shows control until the new id is shipped.`,
+                            ].join("\n"),
                         },
                     ],
                 };
@@ -2742,9 +2728,9 @@ Identical to the SDK's track() and the snippet's apex.track(). Use this to instr
 
 The Apex Spec ships two peer registries:
 
-\u2022 **App events** (\`APEX_EVENTS\`) — the canonical SDK vocabulary the customer's app fires. Names you'll commonly use here: \`page_view\`, \`product_view\`, \`add_to_cart\`, \`checkout_started\`, \`in_app_purchase\`, \`purchase_refunded\`, \`subscription_event\`, \`user_signed_up\`, \`user_signed_in\`, \`user_identified\`, \`app_open\`, \`session_start\`, \`form_submit\`, \`click\`, \`search\`, \`share\`, \`content_view\`, \`goal_conversion\`, \`email_opened\`, \`email_clicked\`, \`push_opened\`, \`in_app_message_seen\`, \`deep_link_open\`. Field names are flat snake_case (e.g. \`product_id\`, \`order_id\`, \`value\`, \`currency\`).
+\u2022 **App events** (\`APEX_EVENTS\`) — the canonical SDK vocabulary the customer's app fires. Names you'll commonly use here: \`page_view\`, \`product_view\`, \`add_to_cart\`, \`checkout_started\`, \`in_app_purchase\`, \`purchase_refunded\`, \`subscription_event\`, \`user_signed_up\`, \`user_signed_in\`, \`user_identified\`, \`app_open\`, \`session_start\`, \`form_submit\`, \`click\`, \`ui_action\`, \`search\`, \`share\`, \`content_view\`, \`goal_conversion\`, \`email_opened\`, \`email_clicked\`, \`push_opened\`, \`in_app_message_seen\`, \`deep_link_open\`. Field names are flat snake_case (e.g. \`product_id\`, \`order_id\`, \`value\`, \`currency\`). Named in-product controls (buttons, tabs, widget chrome) are \`ui_action\` with \`action\` + \`name\` + optional \`location\` — do not invent one event per button. SDK helper: \`trackUiAction({ action, name, location })\`.
 
-\u2022 **Platform events** (\`APEX_PLATFORM_EVENTS\`) — events Apex's own dashboard fires as merchants use it. Names: \`user_invitation_created\`, \`user_invitation_accepted\`, \`developer_invite_sent\`, \`integration_connected\`, \`integration_sync_completed\`, \`integration_sync_failed\`, \`experiment_launched\`, \`experiment_significant\`, \`experiment_concluded\`, \`experiment_promoted\`, \`portfolio_access_requested\`, \`portfolio_access_approved\`, \`portfolio_access_rejected\`, \`portfolio_share_accepted\`, \`subscription_upgraded\`, \`subscription_downgraded\`, \`tier_limit_approaching\`, \`anomaly_detected\`, \`weekly_digest_scheduled\`, \`cognito_verification_code\`, \`user_signup\`. Use these when an agent is acting *as* the Apex platform (admin tooling, dashboard automation), not as the customer's product.
+\u2022 **Platform events** (\`APEX_PLATFORM_EVENTS\`) — events Apex's own dashboard fires as merchants use it. Names: \`user_invitation_created\`, \`user_invitation_accepted\`, \`developer_invite_sent\`, \`integration_selected\`, \`integration_connected\`, \`setup_step_continued\`, \`integration_sync_completed\`, \`integration_sync_failed\`, \`experiment_launched\`, \`experiment_significant\`, \`experiment_concluded\`, \`experiment_promoted\`, \`portfolio_access_requested\`, \`portfolio_access_approved\`, \`portfolio_access_rejected\`, \`portfolio_share_accepted\`, \`subscription_upgraded\`, \`subscription_downgraded\`, \`tier_limit_approaching\`, \`anomaly_detected\`, \`weekly_digest_scheduled\`, \`cognito_verification_code\`, \`user_signup\`. Use these when an agent is acting *as* the Apex platform (admin tooling, dashboard automation), not as the customer's product.
 
 Custom event names are accepted (the spec is open by default), but agents should prefer canonical names from one of the two registries so the event flows directly into the catalog templates, the journey trigger system, and the conversion-goal helpers without manual wiring. The full spec lives at https://docs.apex.inc/spec.
 
@@ -2791,9 +2777,17 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             visitorId: z.string().optional().describe("Visitor ID to stitch back to a web/mobile session (apex_vid)"),
             email: z.string().optional().describe("Email to stitch by identity when no visitorId is known"),
             data: z.record(z.unknown()).optional().describe("Event payload (value, currency, order_id, …)"),
+            environment: z
+                .enum(["production", "preview", "localhost"])
+                .optional()
+                .describe("Dashboard slice only. Omit to leave Unclassified. Never use this to force Production dollars."),
+            release_channel: z
+                .string()
+                .optional()
+                .describe("Optional OS channel (testflight, app-store, xcode-debug, …). Dashboard slice only."),
             idempotencyKey: z.string().optional().describe("Stable key to prevent double-counting on retry (defaults to a fresh UUID)"),
         }),
-        handler: async ({ type, visitorId, email, data, idempotencyKey, }) => {
+        handler: async ({ type, visitorId, email, data, environment, release_channel, idempotencyKey, }) => {
             const key = idempotencyKey ??
                 (typeof globalThis.crypto?.randomUUID === "function"
                     ? globalThis.crypto.randomUUID()
@@ -2805,6 +2799,8 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                         visitorId,
                         email,
                         data,
+                        environment,
+                        release_channel,
                         timestamp: new Date().toISOString(),
                     },
                 ],
@@ -3271,6 +3267,10 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             slots: z.record(z.string()).optional().describe("Content overrides: headline, body, ctaLabel, ctaUrl. These now sync into the rendered email body (not just metadata)."),
             channels: z.array(z.string()).optional().describe("Channels: email, in_app_push, mobile_push"),
             status: z.enum(["draft", "active", "paused"]).optional().describe("Communication status"),
+            audience_bucket: z
+                .enum(["production", "beta", "dev"])
+                .optional()
+                .describe("Who this send is for. Default production. Never All or Unclassified."),
             intent: z
                 .enum(["compete", "replace"])
                 .optional()
@@ -3286,6 +3286,8 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 body.status = args.status;
             if (args.channels)
                 body.channels = args.channels;
+            if (args.audience_bucket)
+                body.audienceBucket = args.audience_bucket;
             if (args.intent)
                 body.intent = args.intent;
             if (args.confirmLiveExperiment)
@@ -3325,13 +3327,13 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     publish_communication: {
-        description: "Publish a communication's draft as the live version — this is what makes an edit reach recipients. Editing only saves a draft.\n\nIf the communication has variants, publishing STARTS the experiment that measures them against the control. That is the point of authoring a variant: a variant that is never published is measured by nothing.\n\nTwo conflicts need a decision rather than a retry. `ambiguous_experiment_host` means several published journeys send this communication, so Apex cannot tell where the experiment belongs — the candidates are returned; ask the user and re-issue with host_journey_id. `comm_already_in_experiment` means one is already running; end it first.",
+        description: "Publish a communication's draft as the live version — this is what makes an edit reach recipients. Editing only saves a draft.\n\nCompete (or publishing a letter that already has variants) creates a prefilled DRAFT experiment. It does not start the test. After the user reviews the draft, call activate_experiment to begin it. Replace publishes the letter for everyone and never creates an experiment.\n\nOptional overrides: hypothesis, belief_id, confidence, duration_days.\n\nTwo conflicts need a decision rather than a retry. `ambiguous_experiment_host` means several published journeys send this communication — the candidates are returned; ask the user and re-issue with host_journey_id. `comm_already_in_experiment` means one is already running; end it first.",
         schema: z.object({
             communicationId: z.string().describe("The communication ID to publish"),
             intent: z
                 .enum(["compete", "replace"])
                 .optional()
-                .describe('How to apply the draft when the Control is protected. "compete" = the current content keeps sending and your draft runs against it as an experiment (safe default). "replace" = your draft becomes what everyone receives, superseding any prior win. Required only when the comm won an experiment or is live in a published journey.'),
+                .describe('How to apply the draft when the Control is protected. "compete" = the current content keeps sending and your draft becomes a filled-in experiment draft (then activate_experiment). "replace" = your draft becomes what everyone receives. Required only when the comm won an experiment or is live in a published journey.'),
             confirmLiveExperiment: z
                 .boolean()
                 .optional()
@@ -3340,6 +3342,22 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 .string()
                 .optional()
                 .describe("Which published journey hosts the experiment. Only needed after a 409 ambiguous_experiment_host, using one of the returned candidate ids."),
+            hypothesis: z
+                .string()
+                .optional()
+                .describe("Override the Suggested hypothesis on the draft experiment."),
+            beliefId: z
+                .string()
+                .optional()
+                .describe("Link the draft experiment to an existing belief."),
+            confidence: z
+                .number()
+                .optional()
+                .describe("Override the prefilled confidence (percent)."),
+            durationDays: z
+                .number()
+                .optional()
+                .describe("Override the prefilled decision window in days."),
         }),
         handler: async (args) => {
             const body = {};
@@ -3349,6 +3367,14 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 body.confirmLiveExperiment = true;
             if (args.hostJourneyId)
                 body.hostJourneyId = args.hostJourneyId;
+            if (args.hypothesis)
+                body.hypothesis = args.hypothesis;
+            if (args.beliefId)
+                body.beliefId = args.beliefId;
+            if (typeof args.confidence === "number")
+                body.confidence = args.confidence;
+            if (typeof args.durationDays === "number")
+                body.durationDays = args.durationDays;
             try {
                 const data = await apiPost(`/api/communications/${args.communicationId}/publish`, body);
                 const lines = [];
@@ -3362,7 +3388,11 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                     lines.push(`${data.repinned.length} send step(s) moved to the new version.`);
                 }
                 if (data.experiment) {
-                    lines.push(`Experiment started: ${data.experiment.id}. Watch it at ${appUrl(`/dashboard/experiments/${data.experiment.id}`)}`);
+                    lines.push(publishedExperimentLine({
+                        id: data.experiment.id,
+                        status: data.experiment.status ?? "draft",
+                        url: appUrl(`/dashboard/experiments/${data.experiment.id}`),
+                    }));
                 }
                 else if (data.experimentNotStarted) {
                     lines.push(notStartedExplanation(data.experimentNotStarted));
@@ -3480,7 +3510,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     create_comm_experiment: {
-        description: "A/B test a communication's subject, body, or CTA. Creates an experiment with variants that split traffic using Thompson Sampling.",
+        description: "Legacy helper. Prefer the composer loop: edit_communication or add_communication_variant, then publish_communication (compete creates a prefilled draft), then activate_experiment to start the test. Do not teach this as the default.",
         schema: z.object({
             communicationId: z.string().describe("The communication to experiment on"),
             splitLevel: z.enum(["subject", "body", "cta", "full"]).describe("What to vary between variants"),
@@ -3963,11 +3993,20 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
     // Agent-friendly arg names (snake_case) are mapped to the REST
     // routes inside each handler.
     create_journey: {
-        description: `${APEX} — Create a blank draft journey (an unconfigured event trigger wired to an exit). Then set_journey_trigger and add_journey_step to build it, and publish_journey to launch. For e-commerce flows like cart recovery, prefer create_journey_from_template.`,
-        schema: z.object({ name: z.string().optional().describe("Journey name (default 'Untitled journey').") }),
-        handler: async ({ name }) => {
+        description: `${APEX} — Create a blank draft journey (an unconfigured event trigger wired to an exit). Then set_journey_trigger and add_journey_step to build it, and publish_journey to launch. For e-commerce flows like cart recovery, prefer create_journey_from_template. audience_bucket defaults to production (live customers). Same email on TestFlight and the store is two people — do not create a staging copy of the journey.`,
+        schema: z.object({
+            name: z.string().optional().describe("Journey name (default 'Untitled journey')."),
+            audience_bucket: z
+                .enum(["production", "beta", "dev"])
+                .optional()
+                .describe("Who this journey enrolls. Default production. Never All or Unclassified."),
+        }),
+        handler: async ({ name, audience_bucket }) => {
             try {
                 const j = await apiPost("/api/journeys/blank", { name });
+                if (audience_bucket && audience_bucket !== "production") {
+                    await apiPatch(`/api/journeys/${j.id}`, { audienceBucket: audience_bucket });
+                }
                 if (!tenantOk(j.workspaceKey))
                     return tenantMismatch();
                 return { content: [{ type: "text", text: `${APEX} Created draft journey "${j.name}" (id: ${j.id}). Open it in the browser: ${journeyLink(j.id)}\nNext: set_journey_trigger, then add_journey_step.` }] };
@@ -4223,14 +4262,21 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     create_communication: {
-        description: `${APEX} — Create a blank custom communication (draft, no send path) you can reference from a journey send step. Distinct from generate_communications, which generates pre-written messages from catalog templates; use this when you need a net-new message (e.g. a cart-recovery email not in the catalog).`,
+        description: `${APEX} — Create a blank custom communication (draft, no send path) you can reference from a journey send step. Distinct from generate_communications, which generates pre-written messages from catalog templates; use this when you need a net-new message (e.g. a cart-recovery email not in the catalog). audience_bucket defaults to production.`,
         schema: z.object({
             title: z.string().optional(),
             channels: z.array(z.enum(["email", "in_app_push", "mobile_push"])).optional(),
+            audience_bucket: z
+                .enum(["production", "beta", "dev"])
+                .optional()
+                .describe("Who this send is for. Default production. Never All or Unclassified."),
         }),
-        handler: async ({ title, channels }) => {
+        handler: async ({ title, channels, audience_bucket }) => {
             try {
                 const comm = await apiPost("/api/communications/blank", { title, channels });
+                if (audience_bucket && audience_bucket !== "production") {
+                    await apiPatch(`/api/communications/${comm.id}`, { audienceBucket: audience_bucket });
+                }
                 if (!tenantOk(comm.workspaceKey))
                     return tenantMismatch();
                 return { content: [{ type: "text", text: `${APEX} Created draft communication "${comm.title}" (id: ${comm.id}). Open it in the browser: ${appUrl(`/dashboard/communications/${comm.id}`)}\nEdit it (or edit_communication), then reference it from a journey send step.` }] };
@@ -4521,6 +4567,32 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             return { content: [{ type: "text", text }] };
         },
     },
+    list_workspace_environments: {
+        description: `${APEX} — Read the sites this workspace named as Production and Beta, plus unclassified sites Apex has seen. Name sites before you trust the Production slice. Do not invent a second workspace.`,
+        schema: z.object({}),
+        handler: async () => {
+            const json = await apiGet("/api/workspace/environments");
+            return {
+                content: [{ type: "text", text: JSON.stringify(json.data, null, 2) }],
+            };
+        },
+    },
+    set_workspace_environments: {
+        description: `${APEX} — Name Production sites (and optional Beta sites). Apex will not guess staging. / qa. / dev. Naming reclassifies events from those sites at read time.`,
+        schema: z.object({
+            production_hosts: z.array(z.string()).describe("Hostnames that are live (shop.example.com)."),
+            beta_hosts: z.array(z.string()).optional().describe("Hostnames that are testers. Never guessed from staging."),
+        }),
+        handler: async ({ production_hosts, beta_hosts, }) => {
+            const json = await apiPut("/api/workspace/environments", {
+                production_hosts,
+                beta_hosts: beta_hosts ?? [],
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(json.data, null, 2) }],
+            };
+        },
+    },
     // ─── Data Sources + unified analytics ──────────────────────────────────
     list_data_sources: {
         description: `${APEX} — List the workspace's Data Sources (the producers that send events: Website, iOS/Android apps, Backend). Shows each source's live status (live / listening / stalled / not-started). Call when the user asks "where is my data coming from?", "which sources are live?", or to audit collection coverage.`,