@apex-inc/mcp-server 0.34.0 → 0.35.1

package/dist/tools/experiments.js

@@ -7,6 +7,156 @@ import { activationLiveLine, shouldRefuseActivationWiring } from "../activation-
 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";
+const NETWORK_WORD = {
+    meta: "Meta",
+    google: "Google",
+    tiktok: "TikTok",
+    linkedin: "LinkedIn",
+};
+function textError(text) {
+    return { content: [{ type: "text", text: `${APEX} ${text}` }], isError: true };
+}
+async function createAdHoldout(args) {
+    if (args.surface && args.surface !== "paid_channel") {
+        return textError(`paid_channel only applies to surface "paid_channel" (got "${args.surface}").`);
+    }
+    const pc = args.paid_channel;
+    if (!pc) {
+        return textError(`An Ad holdout needs a paid_channel block: { network, ad_set_ids, holdout_percent, attach_mode? }. Use list_ad_measurement or the dashboard's Ad holdout page to find the ad set ids.`);
+    }
+    const networkWord = NETWORK_WORD[pc.network] ?? pc.network;
+    const attachMode = pc.attach_mode ?? (pc.network === "meta" ? "apex" : "manual");
+    if (attachMode === "apex" && pc.network !== "meta") {
+        return textError(`Apex can put the list on the ad sets itself on Meta only. For ${networkWord} pass attach_mode "manual".`);
+    }
+    const adSetIds = [...new Set(pc.ad_set_ids.map((s) => s.trim()).filter(Boolean))];
+    if (adSetIds.length === 0)
+        return textError("ad_set_ids must name at least one ad set.");
+    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
+    // network, and (Meta) whether Apex proved it can hold people back there.
+    let prereqs = null;
+    try {
+        const r = await apiGet(`/api/experiments/ad-holdout/prereqs?network=${encodeURIComponent(pc.network)}`);
+        prereqs = r.data;
+    }
+    catch (err) {
+        return textError(`Could not read the Ad holdout prerequisites: ${errMsg(err)}`);
+    }
+    if (!prereqs)
+        return textError("Could not read the Ad holdout prerequisites for the active workspace.");
+    if (!prereqs.enabled) {
+        return textError("Ad holdouts are not switched on for this workspace yet. Turn them on in the dashboard (Settings → Platforms) first.");
+    }
+    const net = prereqs.networks.find((n) => n.network === pc.network);
+    const blockers = [];
+    if (!net?.connected) {
+        blockers.push(`${networkWord} Ads is not connected. Run the "Pick your ad platforms" setup step (or start_integration_install) first.`);
+    }
+    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.`);
+        }
+        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.`);
+        }
+    }
+    const adAccountId = pc.ad_account_id?.trim() || net?.adAccountId;
+    if (!adAccountId) {
+        blockers.push(`No ${networkWord} ad account is known for this workspace. Pass ad_account_id or connect the account.`);
+    }
+    const known = new Set(prereqs.adSets.map((a) => a.id));
+    const unknown = known.size > 0 ? adSetIds.filter((id) => !known.has(id)) : [];
+    if (unknown.length > 0) {
+        blockers.push(`These ad set ids are not on the connected ${networkWord} account: ${unknown.join(", ")}. Known ad sets: ${prereqs.adSets.slice(0, 12).map((a) => `${a.id} (${a.name})`).join(", ")}${prereqs.adSets.length > 12 ? ", …" : ""}.`);
+    }
+    if (blockers.length > 0) {
+        return textError(`This Ad holdout cannot start yet:\n- ${blockers.join("\n- ")}`);
+    }
+    const picked = prereqs.adSets.filter((a) => adSetIds.includes(a.id));
+    const campaignNames = [...new Set(picked.map((a) => a.campaignName).filter((c) => Boolean(c)))];
+    const weeks = Math.max(1, Math.round((args.runtimeDays ?? 28) / 7));
+    const heldBack = Math.round(prereqs.population.knownPeople * pc.holdout_percent);
+    const hypothesis = args.hypothesisStatement?.trim() ||
+        `The ${networkWord} ads on ${adSetIds.length === 1 ? "this ad set" : `these ${adSetIds.length} ad sets`} cause installs that would not have happened without them.`;
+    const summary = {
+        _apex: true,
+        _type: "ad_holdout_preview",
+        name: args.name,
+        surface: "paid_channel",
+        network: networkWord,
+        ad_account_id: adAccountId,
+        ad_sets: picked.length > 0 ? picked.map((a) => ({ id: a.id, name: a.name, campaign: a.campaignName ?? null })) : adSetIds,
+        holdout_percent: pc.holdout_percent,
+        attach_mode: attachMode,
+        washout_days: pc.washout_days ?? 3,
+        runtime_days: weeks * 7,
+        known_people: prereqs.population.knownPeople,
+        people_held_back_now: heldBack,
+        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` : ""}.`,
+            "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).",
+        ],
+    };
+    if (args.preview !== false) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        ...summary,
+                        _instructions: "Present this as a summary and ask the user to confirm (1), adjust (2), or cancel (3). Do NOT create the holdout until confirmed. Then call again with preview=false, then activate_experiment to start drawing the list, and verify_ad_exclusion once the list has landed.",
+                    }, null, 2),
+                }],
+        };
+    }
+    const exp = await apiPost("/api/experiments", {
+        surface: "paid_channel",
+        name: args.name,
+        hypothesis,
+        createdFrom: "cursor",
+        status: "draft",
+        paidChannel: {
+            network: pc.network,
+            adAccountId,
+            adSetIds,
+            holdoutPercent: pc.holdout_percent,
+            attachMode,
+            washoutDays: pc.washout_days ?? 3,
+            ...(pc.population_segment_id ? { populationSegmentId: pc.population_segment_id } : {}),
+            ...(campaignNames.length > 0 ? { campaignNames } : {}),
+        },
+        decisionWindow: { unit: "days", value: weeks * 7, startFrom: "assignment" },
+        ...(args.beliefId ? { beliefId: args.beliefId } : {}),
+        ...(args.hypothesisId ? { hypothesisId: args.hypothesisId } : {}),
+        ...(args.predictionId ? { predictionId: args.predictionId } : {}),
+        prediction: {
+            direction: "increase",
+            magnitude: args.predictionMagnitude?.trim() ?? "",
+            provenance: "agent",
+        },
+    });
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    ...summary,
+                    _type: "ad_holdout_created",
+                    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`}.`,
+                        `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.`,
+                    ],
+                }, null, 2),
+            }],
+    };
+}
 export const experimentTools = {
     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.`,
@@ -154,9 +304,9 @@ export const experimentTools = {
         description: `${APEX} — Create an experiment record. Returns a structured recipe for the AI agent to implement. The agent makes the actual code changes using useApexVariant hook — Apex never generates code. Always call with preview=true first so the user sees a summary.`,
         schema: z.object({
             name: z.string().describe("Experiment name"),
-            targetUrl: z.string().describe("URL of the page to test on the ACTIVE workspace (include #anchor for section targeting). Must be a host this workspace has actually sent events from — never guess a brand domain or a sibling workspace's site."),
-            controlContent: z.string().describe("The current content that the control shows"),
-            variantContent: z.string().describe("The new content for the variant"),
+            targetUrl: z.string().optional().describe("URL of the page to test on the ACTIVE workspace (include #anchor for section targeting). Must be a host this workspace has actually sent events from — never guess a brand domain or a sibling workspace's site. Required for web and mobile; not used for surface 'paid_channel'."),
+            controlContent: z.string().optional().describe("The current content that the control shows. Required for web and mobile; not used for surface 'paid_channel'."),
+            variantContent: z.string().optional().describe("The new content for the variant. Required for web and mobile; not used for surface 'paid_channel'."),
             targetComponent: z.string().optional().describe("Component or file path where the change should be made"),
             targetAnchor: z.string().optional().describe("Section anchor/ID on the page (e.g. 'pricing', 'hero')"),
             trafficSplit: z.number().min(1).max(99).optional().describe("Percentage of traffic to control (default 50)"),
@@ -173,7 +323,19 @@ 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"]).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)."),
+            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)."),
+            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."),
+                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."),
+            })
+                .optional()
+                .describe("Ad holdout settings. Required when surface is 'paid_channel'; rejected otherwise. The primary metric is always app installs, so primaryMetricEvent is not needed."),
             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."),
@@ -181,6 +343,22 @@ export const experimentTools = {
             preview: z.boolean().optional().describe("If true, returns a preview without creating. Default: true."),
         }),
         handler: async (args) => {
+            // Mobile Measurement P3a — an Ad holdout is not a code change. No page,
+            // no control/variant copy, no recipe: Apex draws the held-back list,
+            // puts it on the ad sets, and counts installs. Branch before any of the
+            // web/mobile checks so a missing targetUrl is not an error here.
+            if (args.surface === "paid_channel" || args.paid_channel) {
+                return createAdHoldout(args);
+            }
+            if (!args.targetUrl || !args.controlContent || !args.variantContent) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `${APEX} targetUrl, controlContent and variantContent are required for a web or mobile experiment. (For an Ad holdout pass surface "paid_channel" and a paid_channel block instead.)`,
+                        }],
+                    isError: true,
+                };
+            }
             const targetCheck = await assertTargetUrlForActiveWorkspace(args.targetUrl);
             if (!targetCheck.ok) {
                 return {
@@ -477,7 +655,7 @@ export const experimentTools = {
             });
             let previewUrl = "";
             try {
-                const vu = new URL(exp.targetUrl || args.targetUrl);
+                const vu = new URL(exp.targetUrl || args.targetUrl || "");
                 vu.searchParams.set("_apex_preview", "variant_a");
                 vu.searchParams.set("_apex_exp", exp.id);
                 if (args.targetAnchor)
@@ -1248,12 +1426,307 @@ export const experimentTools = {
             };
         },
     },
+    list_belief_suggestions: {
+        description: `${APEX} — "Worth writing down": settled experiments whose verdict passes the belief gate (decisive, exclusion attached the whole window for Ad holdouts, no sample-ratio mismatch, no guardrail breach, both arms over the events floor) and have not been written down as a belief yet. Statistical only; no model in the path. Pass experimentId for one experiment and, when nothing is offered, 'blocker' says why in one word. Each row carries the sentence Apex would write and the evidence line; write one down with accept_belief_suggestion.`,
+        schema: z.object({
+            experimentId: z.string().optional().describe("One experiment. Omit for the workspace's rail (newest settled first)."),
+            max: z.number().int().min(1).max(10).optional().describe("Cap for the rail (default 5)."),
+        }),
+        handler: async (args) => {
+            const qs = new URLSearchParams();
+            if (args.experimentId?.trim())
+                qs.set("experiment_id", args.experimentId.trim());
+            if (args.max !== undefined)
+                qs.set("max", String(args.max));
+            const q = qs.toString();
+            try {
+                const r = await apiGet(`/api/experiments/belief-suggestions${q ? `?${q}` : ""}`);
+                const d = r.data;
+                const blockerWords = {
+                    not_decisive: "The result is not decisive yet; Apex does not write down a belief from a test that has not settled.",
+                    exclusion_not_attached: "The held-back list was not on every ad set for the whole window, so the held-out arm saw ads and the comparison is not clean.",
+                    results_frozen: "The exclusion came off mid-run and the results were frozen; nothing after that counts.",
+                    srm: "The arms did not split the way they were supposed to (sample-ratio mismatch), so the comparison cannot be trusted.",
+                    guardrail_breach: "A guardrail was breached. A win that broke a guardrail is not a belief.",
+                    events_floor: "One arm has too few events to say anything yet.",
+                    already_written: "This verdict is already written down as a belief.",
+                    not_found: "No experiment with that id in this workspace.",
+                };
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                _apex: true,
+                                suggestions: d.suggestions.map((s) => ({
+                                    experiment_id: s.experimentId,
+                                    experiment: s.experimentName,
+                                    surface: s.surface,
+                                    statement: s.statement,
+                                    evidence: s.evidence,
+                                    lift: s.lift,
+                                    lift_ci: s.liftCI,
+                                    window_days: s.windowDays,
+                                    people: s.n,
+                                    metric: s.metricLabel,
+                                })),
+                                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.blocker
+                                        ? blockerWords[d.blocker] ?? `Not offered: ${d.blocker}.`
+                                        : "Nothing worth writing down right now. Suggestions appear when an experiment settles cleanly.",
+                            }, null, 2),
+                        }],
+                };
+            }
+            catch (err) {
+                return textError(`Could not read the suggestions: ${errMsg(err)}`);
+            }
+        },
+    },
+    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.`,
+        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."),
+        }),
+        handler: async (args) => {
+            const id = args.experimentId.trim();
+            if (!id)
+                return textError("experimentId is required.");
+            try {
+                const r = await apiPost("/api/experiments/belief-suggestions/accept", { experimentId: id, ...(args.statement?.trim() ? { statement: args.statement.trim() } : {}) });
+                const b = r.data;
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                _apex: true,
+                                belief_id: b.id,
+                                statement: b.statement,
+                                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.",
+                            }, null, 2),
+                        }],
+                };
+            }
+            catch (err) {
+                const message = errMsg(err);
+                if (/\(409\)/.test(message)) {
+                    return textError("This verdict is already written down. list_beliefs shows it; nothing was duplicated.");
+                }
+                if (/\(422\)/.test(message)) {
+                    return textError(`Apex will not write this one down: ${message}. Run list_belief_suggestions with the experimentId to see the blocker in plain words.`);
+                }
+                return textError(`Could not write the belief: ${message}`);
+            }
+        },
+    },
+    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.`,
+        schema: z.object({
+            experimentId: z.string().describe("The Ad holdout experiment id."),
+        }),
+        handler: async (args) => {
+            const id = args.experimentId.trim();
+            if (!id)
+                return textError("experimentId is required.");
+            try {
+                const r = await apiGet(`/api/experiments/${encodeURIComponent(id)}/ad-exclusion/verify`);
+                const d = r.data;
+                const words = {
+                    attached: "The list is on every ad set. Counting starts after the washout.",
+                    pending: "The list is not on the ad sets yet.",
+                    syncing: "The network is still matching the list.",
+                    detached: "The list came off at least one ad set. Results are frozen where they stood.",
+                    contaminated: "The held-back people saw these ads. Results are frozen; start a new holdout to measure again.",
+                    too_small: "The network matched too few people to honour the list.",
+                    token_expired: "The network no longer accepts Apex's connection. Reconnect the ad account.",
+                    unverifiable: "The network does not let Apex read whether the list is on.",
+                    failed_verify: "Apex could not confirm the list is on the ad sets.",
+                };
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                _apex: true,
+                                experimentId: d.experimentId,
+                                exclusion_status: d.exclusionStatus,
+                                in_plain_words: words[d.exclusionStatus] ?? d.exclusionStatus,
+                                checked_just_now: !d.skipped,
+                                last_checked_at: d.lastVerifiedAt ?? null,
+                                confirmed_since: d.exclusionVerifiedAt ?? null,
+                                list: typeof d.uploadedCount === "number"
+                                    ? { sent: d.uploadedCount, matched: d.matchedCount ?? null }
+                                    : null,
+                                ad_sets: d.adSets ?? null,
+                                results_frozen_at: d.resultsFrozenAt ?? null,
+                                last_error: d.lastVerifyError ?? null,
+                            }, null, 2),
+                        }],
+                };
+            }
+            catch (err) {
+                const message = errMsg(err);
+                if (/\(429\)/.test(message)) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `${APEX} Apex checked this exclusion recently and will not re-read yet. Use get_results or list_experiments for the last reading, or try again in a few minutes.`,
+                            }],
+                    };
+                }
+                return textError(`Could not verify the exclusion: ${message}`);
+            }
+        },
+    },
+    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.`,
+        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."),
+        }),
+        handler: async (args) => {
+            const id = args.experimentId.trim();
+            if (!id)
+                return textError("experimentId is required.");
+            const path = `/api/experiments/${encodeURIComponent(id)}/ad-exclusion/attach`;
+            const ids = (t) => (t?.excluded_custom_audiences ?? []).map((a) => String(a.id));
+            try {
+                if (args.preview !== false) {
+                    const r = await apiGet(path);
+                    const d = r.data;
+                    const rows = d.adSets.map((a) => ({
+                        ad_set_id: a.adSetId,
+                        name: a.name ?? null,
+                        apex_will: !a.found ? "leave it (could not read it)" : !a.sameAccount ? "leave it (another ad account)" : a.alreadyPresent ? "leave it (list already on)" : "add the held-back list as one exclusion",
+                        excluded_audiences_before: ids(a.before),
+                        excluded_audiences_after: a.after ? ids(a.after) : ids(a.before),
+                        everything_else: a.found ? "unchanged" : null,
+                        note: a.message ?? null,
+                    }));
+                    const reasonWords = {
+                        no_connection: "Meta Ads is not connected with outbound access.",
+                        list_not_on_network: "The held-back list has not reached Meta yet. Activate the holdout and wait for the sync; then attach.",
+                        adsets_not_ready: "At least one ad set could not be read or is on another ad account. Apex will not touch those.",
+                    };
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    _apex: true,
+                                    experimentId: id,
+                                    preview: true,
+                                    ready: d.ready,
+                                    why_not_ready: d.reason ? reasonWords[d.reason] ?? d.reason : null,
+                                    allowance_on_file: d.ack.present,
+                                    allowance_since: d.ack.at ?? null,
+                                    held_back_list_id: d.audienceId,
+                                    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 }).`
+                                        : "Fix the reason above, then preview again.",
+                                }, null, 2),
+                            }],
+                    };
+                }
+                const r = await apiPost(path, args.acknowledge ? { acknowledge: true } : {});
+                const d = r.data;
+                const words = {
+                    attached: "The list is on every ad set and Meta confirmed it. Counting starts after the washout.",
+                    syncing: "Apex put the list on every ad set. It is checking Meta has taken it; verify_ad_exclusion reads the answer.",
+                    failed_verify: "The list is on some ad sets, not all. See the changes below and last_error.",
+                    token_expired: "Meta no longer accepts Apex's connection. Reconnect Meta Ads and attach again.",
+                };
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                _apex: true,
+                                experimentId: id,
+                                exclusion_status: d.exclusionStatus,
+                                in_plain_words: words[d.exclusionStatus] ?? d.exclusionStatus,
+                                every_ad_set_took_it: d.allSettled,
+                                apex_attached_at: d.apexAttachedAt ?? null,
+                                changes: d.changes.map((c) => ({
+                                    ad_set_id: c.adSetId,
+                                    name: c.name ?? null,
+                                    outcome: c.outcome,
+                                    excluded_audiences_before: c.before ?? null,
+                                    excluded_audiences_after: c.after ?? null,
+                                    note: c.message ?? null,
+                                })),
+                                last_error: d.lastVerifyError ?? null,
+                                _next: d.allSettled
+                                    ? `verify_ad_exclusion({ experiment_id: "${id}" }) once Meta has had a minute, or get_results after the washout.`
+                                    : "Read each change's note; a rate-limited or locked ad set can simply be attached again.",
+                            }, null, 2),
+                        }],
+                };
+            }
+            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.`);
+                }
+                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(`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.`,
+        schema: z.object({
+            experimentId: z.string().describe("The Ad holdout experiment id."),
+        }),
+        handler: async (args) => {
+            const id = args.experimentId.trim();
+            if (!id)
+                return textError("experimentId is required.");
+            try {
+                const r = await apiPost(`/api/experiments/${encodeURIComponent(id)}/ad-exclusion/detach`, {});
+                const d = r.data;
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                _apex: true,
+                                experimentId: id,
+                                every_ad_set_restored: d.ok,
+                                held_back_list_deleted: d.listDeleted,
+                                exclusion_status: d.exclusionStatus ?? null,
+                                in_plain_words: d.ok
+                                    ? "Apex took its exclusion off every ad set and deleted the held-back list. The ad sets are as they were before the holdout."
+                                    : "Apex could not take the list off every ad set. See the changes; the list stays until they are clean.",
+                                changes: d.changes.map((c) => ({ ad_set_id: c.adSetId, name: c.name ?? null, outcome: c.outcome, note: c.message ?? null })),
+                                last_error: d.lastVerifyError ?? null,
+                            }, null, 2),
+                        }],
+                };
+            }
+            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(`Could not take the held-back list off: ${message}`);
+            }
+        },
+    },
     update_experiment: {
         description: `${APEX} — Edit an EXISTING experiment. Editability is gated by lifecycle: a DRAFT (with no exposures yet) is fully editable; once it has data or is running, the pre-registration (hypothesis, metric, guardrails) and bucketing (surface, variants) freeze and edits return a clear "experiment_locked" reason. After freeze, fork_experiment instead. Use this to fix a mislabeled surface or correct a draft before launch.`,
         schema: z.object({
             experimentId: z.string().describe("The experiment id to edit."),
             name: z.string().optional().describe("Rename (cosmetic; editable anytime)."),
-            surface: z.enum(["web", "mobile"]).optional().describe("Correct the surface — editable only on a draft with 0 exposures (web↔mobile)."),
+            surface: z.enum(["web", "mobile", "paid_channel"]).optional().describe("Correct the surface — editable only on a draft with 0 exposures (web↔mobile). 'paid_channel' is accepted only when the draft already carries its Ad holdout block."),
             hypothesis: z.string().optional().describe("Edit the hypothesis — draft only (pre-registration)."),
             targetUrl: z.string().optional().describe("Retarget a DRAFT to a URL on the ACTIVE workspace. Same host rules as create_experiment."),
             predictionId: z.string().optional().describe("Attach a minted prediction id (from log_prediction) to this draft. Also stamps the prediction onto the experiment's hypothesis when that link is missing. Required before activation."),
@@ -1395,7 +1868,7 @@ export const experimentTools = {
         description: `${APEX} — Before you create or activate an experiment, check who else is live on that page. Pin a part (target_anchor) so two homepage experiments are not the same place. Whole page plus a part is one place. Different named parts: the same person can see both — say so, do not add the two lifts. Overlap: Someone could see both; Keep them apart with set_experiment_mutex, or wait. Shared conversion on the allowed mix: one experiment or wait. Pass either experimentId OR the candidate's location + primaryMetricEvent. Advisory only.`,
         schema: z.object({
             experimentId: z.string().optional().describe("Check an existing experiment by id (loads its location + metric)."),
-            surface: z.enum(["web", "mobile"]).optional(),
+            surface: z.enum(["web", "mobile", "paid_channel"]).optional(),
             targetComponent: z.string().optional().describe("Component/file the experiment changes, e.g. 'ProductCard'."),
             targetUrl: z.string().optional(),
             targetAnchor: z.string().optional(),