@apex-inc/mcp-server 0.40.0 → 0.41.1

package/dist/tools/experiments.js

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { apiGet, apiPost, apiPatch, apiDelete, getActiveWorkspace, } from "../api-client.js";
 import { resolveExperimentHypothesis } from "../experiment-copy.js";
 import { activationLiveLine, shouldRefuseActivationWiring } from "../activation-wiring.js";
+import { apexBaseUrl } from "../base-url.js";
 import { fetchLiveTestHits, formatLiveTestStop, isFileStop, isObjectStop, } from "../live-test-guard.js";
 import { hasConflictAdvisory, renderConflictAdvisory, } from "../conflict-advisory.js";
 import { APEX, controlPctOf, daysRunningOf, findVariant, formatArmLine, titleCaseEvent, assertTargetUrlForActiveWorkspace, errMsg, resolveCreateSurface, } from "../tool-shared.js";
@@ -35,7 +36,7 @@ async function createAdHoldout(args) {
     if (adSetIds.length > 20)
         return textError("An Ad holdout covers at most 20 ad sets.");
     // What the workspace has already set up for this network: the connected
-    // ad account, whether the shop agreed to hashed emails going to the
+    // ad account, whether the owner agreed to hashed emails going to the
     // network, and (Meta) whether Apex proved it can hold people back there.
     let prereqs = null;
     try {
@@ -57,7 +58,7 @@ async function createAdHoldout(args) {
     }
     else {
         if (!net.audienceAcked) {
-            blockers.push(`The shop has not yet agreed to hashed emails going to ${networkWord}. Finish the "Let Apex hold people back from your ads" setup step.`);
+            blockers.push(`The owner has not yet agreed to hashed emails going to ${networkWord}. Finish the "Let Apex hold people back from your ads" setup step.`);
         }
         if (net.attachAvailable && !net.accessProven) {
             blockers.push(`Apex has not yet proved its ${networkWord} token can put a do-not-show list on this account. The same setup step runs the two checks.`);
@@ -98,7 +99,7 @@ async function createAdHoldout(args) {
         what_is_measured: "App installs in both lanes (saw the ads vs held back). Purchases can be a secondary metric.",
         hypothesis,
         honesty: [
-            `Nothing counts until Apex confirms the do-not-show list is on every ad set${attachMode === "manual" ? ` — with manual attach the shop adds the audience as an exclusion in ${networkWord} Ads` : ""}.`,
+            `Nothing counts until Apex confirms the do-not-show list is on every ad set${attachMode === "manual" ? ` — with manual attach the owner adds the audience as an exclusion in ${networkWord} Ads` : ""}.`,
             "Results freeze if the list comes off mid-run; start a new holdout to measure again.",
             "Installs are counted for known people only (someone with an email or phone Apex can hash).",
         ],
@@ -149,7 +150,7 @@ async function createAdHoldout(args) {
                     experimentId: exp.id,
                     status: exp.status,
                     _next: [
-                        `activate_experiment({ experimentId: "${exp.id}" }) — Apex draws the held-back list and ${attachMode === "apex" ? `puts it on the ${networkWord} ad sets` : `makes the audience for the shop to add as an exclusion in ${networkWord} Ads`}.`,
+                        `activate_experiment({ experimentId: "${exp.id}" }) — Apex draws the held-back list and ${attachMode === "apex" ? `puts it on the ${networkWord} ad sets` : `makes the audience for the owner to add as an exclusion in ${networkWord} Ads`}.`,
                         `verify_ad_exclusion({ experiment_id: "${exp.id}" }) — confirm the list is on every ad set. Counting starts after the washout.`,
                         `get_results({ experimentId: "${exp.id}" }) — the two lanes, once counting.`,
                     ],
@@ -323,14 +324,14 @@ export const experimentTools = {
             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."),
-            surface: z.enum(["web", "mobile", "paid_channel"]).optional().describe("The PROPERTY the experiment runs in (not the SDK used): 'web' for a website, 'mobile' for a native / Capacitor / React-Native app, 'paid_channel' for an Ad holdout (Apex holds a share of known people back from the shop's ads on one network and measures the installs the ads actually caused — pass paid_channel too). OPTIONAL for web/mobile — 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 vs Ads)."),
+            surface: z.enum(["web", "mobile", "paid_channel"]).optional().describe("The PROPERTY the experiment runs in (not the SDK used): 'web' for a website, 'mobile' for a native / Capacitor / React-Native app, 'paid_channel' for an Ad holdout (Apex holds a share of known people back from the workspace's ads on one network and measures the installs the ads actually caused — pass paid_channel too). OPTIONAL for web/mobile — 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 vs Ads)."),
             paid_channel: z
                 .object({
                 network: z.enum(["meta", "google", "tiktok", "linkedin"]).describe("Ad network the ad sets run on. Apex attaches the do-not-show list itself on Meta only; other networks are manual attach."),
                 ad_account_id: z.string().optional().describe("The connected ad account the ad sets belong to. Omit to use the account the workspace connected for this network."),
                 ad_set_ids: z.array(z.string()).min(1).describe("Ad set ids to hold people back from (max 20). Frozen at create; changing them is a new holdout."),
                 holdout_percent: z.number().min(0.05).max(0.5).describe("Share of the known population held back, 0.05–0.5 (0.2 = one in five)."),
-                attach_mode: z.enum(["apex", "manual"]).optional().describe("'apex' = Apex puts the list on the ad sets and checks daily (Meta only). 'manual' = the shop adds the audience as an exclusion by hand; Apex checks daily and counts nothing until it is on. Defaults to 'apex' on Meta, 'manual' elsewhere."),
+                attach_mode: z.enum(["apex", "manual"]).optional().describe("'apex' = Apex puts the list on the ad sets and checks daily (Meta only). 'manual' = the owner adds the audience as an exclusion by hand; Apex checks daily and counts nothing until it is on. Defaults to 'apex' on Meta, 'manual' elsewhere."),
                 washout_days: z.number().int().min(0).max(30).optional().describe("Days after the list lands before installs count, so pre-list ad exposure washes out. Default 3."),
                 population_segment_id: z.string().optional().describe("Optional Segment id narrowing who can be drawn."),
             })
@@ -1212,8 +1213,7 @@ export const experimentTools = {
             }
             let isReachable = false;
             try {
-                const BASE_URL = process.env.APEX_URL || "http://localhost:3001";
-                const res = await fetch(`${BASE_URL}/api/experiments/${experimentId}/assign`, {
+                const res = await fetch(`${apexBaseUrl()}/api/experiments/${experimentId}/assign`, {
                     signal: AbortSignal.timeout(5000),
                 });
                 isReachable = res.ok;
@@ -1485,7 +1485,7 @@ export const experimentTools = {
                                 blocker: d.blocker ?? null,
                                 existing_belief_id: d.existingBeliefId ?? null,
                                 in_plain_words: d.suggestions.length > 0
-                                    ? `${d.suggestions.length} verdict${d.suggestions.length === 1 ? "" : "s"} worth writing down. Show the shop the sentence; they can edit it before accept_belief_suggestion writes it as one study.`
+                                    ? `${d.suggestions.length} verdict${d.suggestions.length === 1 ? "" : "s"} worth writing down. Show the owner the sentence; they can edit it before accept_belief_suggestion writes it as one study.`
                                     : d.blocker
                                         ? blockerWords[d.blocker] ?? `Not offered: ${d.blocker}.`
                                         : "Nothing worth writing down right now. Suggestions appear when an experiment settles cleanly.",
@@ -1499,10 +1499,10 @@ export const experimentTools = {
         },
     },
     accept_belief_suggestion: {
-        description: `${APEX} — Write a settled experiment's verdict down as one belief. Creates the Belief with the experiment as its supporting evidence and generatedFromExperimentId set; its evidence state starts at 'one study' and moves to 'validated' when a second test agrees. 'statement' is the shop's edit of the sentence (the numbers and evidence line stay Apex's). The gate re-runs here, so an experiment list_belief_suggestions would not offer is refused with its blocker. Writing it twice returns the existing belief. Admin only.`,
+        description: `${APEX} — Write a settled experiment's verdict down as one belief. Creates the Belief with the experiment as its supporting evidence and generatedFromExperimentId set; its evidence state starts at 'one study' and moves to 'validated' when a second test agrees. 'statement' is the workspace's edit of the sentence (the numbers and evidence line stay Apex's). The gate re-runs here, so an experiment list_belief_suggestions would not offer is refused with its blocker. Writing it twice returns the existing belief. Admin only.`,
         schema: z.object({
             experimentId: z.string().describe("The settled experiment to write down."),
-            statement: z.string().min(8).max(600).optional().describe("The shop's wording of the belief. Omit to accept Apex's sentence as written."),
+            statement: z.string().min(8).max(600).optional().describe("The owner's wording of the belief. Omit to accept Apex's sentence as written."),
         }),
         handler: async (args) => {
             const id = args.experimentId.trim();
@@ -1521,7 +1521,7 @@ export const experimentTools = {
                                 confidence: b.confidence,
                                 evidence_state: "one_study",
                                 generated_from_experiment_id: id,
-                                in_plain_words: "Written down. It is on the shop's Belief Map as one study with this experiment as the evidence. A second test that agrees moves it to validated.",
+                                in_plain_words: "Written down. It is on the workspace's Belief Map as one study with this experiment as the evidence. A second test that agrees moves it to validated.",
                             }, null, 2),
                         }],
                 };
@@ -1539,7 +1539,7 @@ export const experimentTools = {
         },
     },
     verify_ad_exclusion: {
-        description: `${APEX} — Ad holdout only (surface paid_channel). Ask Apex to check, right now, whether the do-not-show list is on every ad set the holdout covers, and record the answer. Nothing is counted until this reads "attached"; the daily check runs on its own, so call this after the list lands or after the shop attached it by hand. Rate-limited: a recent check returns the last reading instead of re-reading.`,
+        description: `${APEX} — Ad holdout only (surface paid_channel). Ask Apex to check, right now, whether the do-not-show list is on every ad set the holdout covers, and record the answer. Nothing is counted until this reads "attached"; the daily check runs on its own, so call this after the list lands or after the workspace attached it by hand. Rate-limited: a recent check returns the last reading instead of re-reading.`,
         schema: z.object({
             experimentId: z.string().describe("The Ad holdout experiment id."),
         }),
@@ -1597,11 +1597,11 @@ export const experimentTools = {
         },
     },
     attach_ad_exclusion: {
-        description: `${APEX} — Ad holdout only (surface paid_channel, Meta only). Apex puts the held-back list on the holdout's ad sets itself: exactly one exclusion added per ad set, every other targeting key (locations, age, placements, ...) left as read, then read back to confirm. Two steps, always in this order: (1) call with preview=true (default) and SHOW the shop the before/after per ad set — which ad sets get the exclusion, which already have it, which are on another account and will not be touched; (2) once the shop confirms, call with preview=false. The first real attach in a workspace needs acknowledge=true, which records the shop's standing allowance for Apex to edit ad-set targeting (say so before passing it; never pass it without the shop having seen the preview). Refuses with needs_targeting_ack when it is missing, list_not_on_network while the list is still syncing, and not for Google/TikTok/LinkedIn (there the shop adds the list in the network's tools and verify_ad_exclusion checks). Ending, pausing or archiving the holdout takes the list off again on its own. Not billed.`,
+        description: `${APEX} — Ad holdout only (surface paid_channel, Meta only). Apex puts the held-back list on the holdout's ad sets itself: exactly one exclusion added per ad set, every other targeting key (locations, age, placements, ...) left as read, then read back to confirm. Two steps, always in this order: (1) call with preview=true (default) and SHOW the workspace the before/after per ad set — which ad sets get the exclusion, which already have it, which are on another account and will not be touched; (2) once the workspace confirms, call with preview=false. The first real attach in a workspace needs acknowledge=true, which records the workspace's standing allowance for Apex to edit ad-set targeting (say so before passing it; never pass it without the workspace having seen the preview). Refuses with needs_targeting_ack when it is missing, list_not_on_network while the list is still syncing, and not for Google/TikTok/LinkedIn (there the owner adds the list in the network's tools and verify_ad_exclusion checks). Ending, pausing or archiving the holdout takes the list off again on its own. Not billed.`,
         schema: z.object({
             experimentId: z.string().describe("The Ad holdout experiment id."),
             preview: z.boolean().optional().describe("true (default): read-only — return the before/after per ad set and whether the allowance is on file. false: make the edit."),
-            acknowledge: z.boolean().optional().describe("Pass true on the first real attach in this workspace, after the shop has seen the preview and agreed that Apex may edit ad-set targeting. Recorded once per network."),
+            acknowledge: z.boolean().optional().describe("Pass true on the first real attach in this workspace, after the owner has seen the preview and agreed that Apex may edit ad-set targeting. Recorded once per network."),
         }),
         handler: async (args) => {
             const id = args.experimentId.trim();
@@ -1642,8 +1642,8 @@ export const experimentTools = {
                                     ad_sets: rows,
                                     _next: d.ready
                                         ? d.ack.present
-                                            ? `Show the shop this table. On its word, call attach_ad_exclusion({ experiment_id: "${id}", preview: false }).`
-                                            : `Show the shop this table and say: confirming allows Apex to add the held-back list as one exclusion on holdout ad sets and remove it when a holdout ends; nothing else on the ad sets is changed. On its word, call attach_ad_exclusion({ experiment_id: "${id}", preview: false, acknowledge: true }).`
+                                            ? `Show the owner this table. On their word, call attach_ad_exclusion({ experiment_id: "${id}", preview: false }).`
+                                            : `Show the owner this table and say: confirming allows Apex to add the held-back list as one exclusion on holdout ad sets and remove it when a holdout ends; nothing else on the ad sets is changed. On their word, call attach_ad_exclusion({ experiment_id: "${id}", preview: false, acknowledge: true }).`
                                         : "Fix the reason above, then preview again.",
                                 }, null, 2),
                             }],
@@ -1686,17 +1686,17 @@ export const experimentTools = {
             catch (err) {
                 const message = errMsg(err);
                 if (/needs_targeting_ack|\(409\)/.test(message)) {
-                    return textError(`Apex will not edit ad sets until the shop has allowed it. Call attach_ad_exclusion with preview=true, show the before/after, and on the shop's word call again with preview=false and acknowledge=true.`);
+                    return textError(`Apex will not edit ad sets until the owner has allowed it. Call attach_ad_exclusion with preview=true, show the before/after, and on the owner's word call again with preview=false and acknowledge=true.`);
                 }
                 if (/network_not_supported/.test(message)) {
-                    return textError("Apex attaches the list itself on Meta only. On other networks the shop adds the list in the network's own tools; verify_ad_exclusion checks it is on.");
+                    return textError("Apex attaches the list itself on Meta only. On other networks the owner adds the list in the network's own tools; verify_ad_exclusion checks it is on.");
                 }
                 return textError(`Could not attach the held-back list: ${message}`);
             }
         },
     },
     detach_ad_exclusion: {
-        description: `${APEX} — Ad holdout only (surface paid_channel, Meta only). Take Apex's exclusion back off the holdout's ad sets and delete the held-back list from Meta. Removes only what Apex added: a list the shop attached by hand is refused (not_apex_attached) and the shop removes it in Ads Manager. Ending, pausing or archiving the holdout does this on its own; call this only to undo an attach early. Admin only. Confirm with the shop first: the held-back people start seeing the ads again and the holdout stops measuring.`,
+        description: `${APEX} — Ad holdout only (surface paid_channel, Meta only). Take Apex's exclusion back off the holdout's ad sets and delete the held-back list from Meta. Removes only what Apex added: a list the owner attached by hand is refused (not_apex_attached) and the owner removes it in Ads Manager. Ending, pausing or archiving the holdout does this on its own; call this only to undo an attach early. Admin only. Confirm with the workspace first: the held-back people start seeing the ads again and the holdout stops measuring.`,
         schema: z.object({
             experimentId: z.string().describe("The Ad holdout experiment id."),
         }),
@@ -1728,7 +1728,7 @@ export const experimentTools = {
             catch (err) {
                 const message = errMsg(err);
                 if (/not_apex_attached|\(409\)/.test(message)) {
-                    return textError("Apex did not put this list on the ad sets, so it will not take it off. The shop removes the exclusion in Ads Manager.");
+                    return textError("Apex did not put this list on the ad sets, so it will not take it off. The owner removes the exclusion in Ads Manager.");
                 }
                 return textError(`Could not take the held-back list off: ${message}`);
             }