@apex-inc/mcp-server 0.28.0 → 0.29.0

package/dist/tools.js

@@ -10,6 +10,7 @@ import { notStartedExplanation, publishedExperimentLine, } from "./publish-commu
 import { activationLiveLine, shouldRefuseActivationWiring, } from "./activation-wiring.js";
 import { milestoneWriteBody, preflightAdoptionMilestone, } from "./adoption-compose.js";
 import { applyAddJourneyStep } from "./add-journey-step.js";
+import { fetchLiveTestHits, formatLiveTestStop, isFileStop, isObjectStop, refuseLiveApexObject, } from "./live-test-guard.js";
 const APEX = "Apex";
 /**
  * MOBX-006 — stable synthetic visitor id for agent-fired events.
@@ -1868,6 +1869,99 @@ export const toolDefinitions = {
             }
         },
     },
+    check_live_tests: {
+        description: `${APEX} — Before you edit a page, commit, or push, call this even if the user did not mention experiments. Also call it before you change a letter, Adaptive Journey, or Milestone. If something live is on those files or ids, stop and ask. Do not edit. Do not commit.`,
+        schema: z.object({
+            file_paths: z
+                .array(z.string())
+                .optional()
+                .describe("Repo-relative paths you are about to edit or commit. Full file is read locally when content is omitted."),
+            file_contents: z
+                .array(z.object({
+                path: z.string(),
+                content: z.string().describe("Full file at HEAD, not the diff hunk."),
+            }))
+                .optional(),
+            urls: z
+                .array(z.string())
+                .optional()
+                .describe("Page URLs you are about to change. URL-only hits are a warning, not a stop."),
+            communication_ids: z
+                .array(z.string())
+                .optional()
+                .describe("Letters you are about to edit or publish."),
+            journey_ids: z
+                .array(z.string())
+                .optional()
+                .describe("Adaptive Journeys you are about to change or publish."),
+            milestone_ids: z
+                .array(z.string())
+                .optional()
+                .describe("Milestones you are about to change or delete."),
+        }),
+        handler: async (args) => {
+            try {
+                const byPath = new Map();
+                for (const row of args.file_contents ?? []) {
+                    if (row?.path)
+                        byPath.set(row.path, { path: row.path, content: row.content });
+                }
+                for (const raw of args.file_paths ?? []) {
+                    if (!raw || byPath.has(raw))
+                        continue;
+                    const abs = raw.startsWith("/") ? raw : join(process.cwd(), raw);
+                    byPath.set(raw, {
+                        path: raw,
+                        content: existsSync(abs) ? readFileSync(abs, "utf8") : undefined,
+                    });
+                }
+                const files = [...byPath.values()];
+                const hits = await fetchLiveTestHits({
+                    files,
+                    urls: args.urls,
+                    communicationIds: args.communication_ids,
+                    journeyIds: args.journey_ids,
+                    milestoneIds: args.milestone_ids,
+                    includePublishedJourneys: (args.journey_ids ?? []).length > 0,
+                });
+                const stopping = hits.filter((h) => isFileStop(h) || isObjectStop(h));
+                if (stopping.length === 0) {
+                    if (hits.length === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `${APEX} Nothing live is on those files or ids. You can edit and commit.`,
+                                },
+                            ],
+                        };
+                    }
+                    const soft = hits
+                        .map((h) => `${h.name} (${h.status}, ${h.confidence}: ${h.reason})`)
+                        .join("; ");
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `${APEX} Soft warning only — not a stop: ${soft}. If you turn a paused test back on, this is the page.`,
+                            },
+                        ],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: formatLiveTestStop(stopping),
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
     set_experiment_mutex: {
         description: `${APEX} — Put two experiments in a mutual-exclusion group: no visitor is ever assigned to both, so they run concurrently with partitioned traffic (the scientifically clean way to run two experiments that touch the same surface). Bidirectional. Pass mode:"remove" to unlink. Safe on running experiments — only affects future assignments.`,
         schema: z.object({
@@ -3368,9 +3462,17 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             confirmLiveExperiment: z
                 .boolean()
                 .optional()
-                .describe("Edit a communication that is the treatment in a RUNNING experiment. This marks that experiment invalid and excludes its result from the belief graph. Only pass true when the user has explicitly accepted losing the experiment."),
+                .describe("Edit a communication that is the treatment in a RUNNING experiment. Marks the numbers untrustworthy: we will not call a winner and we will not learn from mixed counts. Only pass true when they picked an out."),
         }),
         handler: async (args) => {
+            const guard = await refuseLiveApexObject({
+                communicationIds: [args.communicationId],
+                confirmed: args.confirmLiveExperiment === true,
+                purpose: "draft",
+            });
+            if (guard.stop) {
+                return { content: [{ type: "text", text: guard.text }] };
+            }
             const body = {};
             if (args.status)
                 body.status = args.status;
@@ -3427,7 +3529,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             confirmLiveExperiment: z
                 .boolean()
                 .optional()
-                .describe("Publish over a communication that is the treatment in a RUNNING experiment. Marks that experiment invalid and excludes its result from the belief graph. Only pass true when the user has explicitly accepted losing the experiment."),
+                .describe("Publish over a communication that is the treatment in a RUNNING experiment. Marks the numbers untrustworthy: we will not call a winner and we will not learn from mixed counts. Only pass true when they picked an out."),
             hostJourneyId: z
                 .string()
                 .optional()
@@ -3450,6 +3552,14 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 .describe("Override the prefilled decision window in days."),
         }),
         handler: async (args) => {
+            const guard = await refuseLiveApexObject({
+                communicationIds: [args.communicationId],
+                confirmed: args.confirmLiveExperiment === true,
+                purpose: "publish",
+            });
+            if (guard.stop) {
+                return { content: [{ type: "text", text: guard.text }] };
+            }
             const body = {};
             if (args.intent)
                 body.intent = args.intent;
@@ -4220,6 +4330,13 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         }),
         handler: async (args) => {
             try {
+                const guard = await refuseLiveApexObject({
+                    journeyIds: [args.journeyId],
+                    purpose: "draft",
+                });
+                if (guard.stop) {
+                    return { content: [{ type: "text", text: guard.text }] };
+                }
                 const j = await apiGet(`/api/journeys/${encodeURIComponent(args.journeyId)}`);
                 const newId = `step_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
                 const applied = applyAddJourneyStep(j.steps ?? [], args, newId);
@@ -4246,6 +4363,14 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         }),
         handler: async (args) => {
             try {
+                const guard = await refuseLiveApexObject({
+                    journeyIds: [args.journeyId],
+                    communicationIds: [args.commId],
+                    purpose: "draft",
+                });
+                if (guard.stop) {
+                    return { content: [{ type: "text", text: guard.text }] };
+                }
                 const j = await apiGet(`/api/journeys/${encodeURIComponent(args.journeyId)}`);
                 const steps = [...(j.steps ?? [])];
                 const sends = steps.filter((s) => s.type === "send");
@@ -4306,6 +4431,14 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         }),
         handler: async (args) => {
             try {
+                const guard = await refuseLiveApexObject({
+                    journeyIds: [args.journeyId],
+                    communicationIds: [args.whenTrueCommId, args.whenFalseCommId].filter((id) => Boolean(id)),
+                    purpose: "draft",
+                });
+                if (guard.stop) {
+                    return { content: [{ type: "text", text: guard.text }] };
+                }
                 const c = args.condition;
                 // Build the predicate leaf (AudiencePredicate is a bare leaf here).
                 let predicate;
@@ -4375,12 +4508,16 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     publish_journey: {
-        description: `${APEX} — Publish a draft journey so it runs on live trigger events. SAFETY: defaults to a dry-run (validation only) — pass confirmLive:true to actually publish to real customers. Email sends require a verified sender domain or publish is blocked.`,
+        description: `${APEX} — Publish a draft journey so it runs on live trigger events. SAFETY: defaults to a dry-run (validation only) — pass confirmLive:true to actually publish to real customers. Email sends require a verified sender domain or publish is blocked. If this path is already live or a test is measuring it, stop and ask. Do not pass confirmTreatmentChange unless they picked an out.`,
         schema: z.object({
             journeyId: z.string(),
             confirmLive: z.boolean().optional().describe("Set true to publish for real. Omitted/false = dry-run validation only."),
+            confirmTreatmentChange: z
+                .boolean()
+                .optional()
+                .describe("Publish anyway when this path is live or a test is measuring it. Only pass true after they picked an out."),
         }),
-        handler: async ({ journeyId, confirmLive }) => {
+        handler: async ({ journeyId, confirmLive, confirmTreatmentChange, }) => {
             const path = `/api/journeys/${encodeURIComponent(journeyId)}/publish`;
             // Non-blocking coverage warnings ("we couldn't verify these until the
             // journey fires") — surfaced so an agent can preview before publishing.
@@ -4402,6 +4539,15 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                     return { content: [{ type: "text", text: `${APEX} Dry-run found a problem before publishing: ${errMsg(err)}\nIf a variable won't resolve, map it to a field the trigger provides or remove it, then preview with example data.` }], isError: true };
                 }
             }
+            const guard = await refuseLiveApexObject({
+                journeyIds: [journeyId],
+                includePublishedJourneys: true,
+                confirmed: confirmTreatmentChange === true,
+                purpose: "publish",
+            });
+            if (guard.stop) {
+                return { content: [{ type: "text", text: guard.text }] };
+            }
             try {
                 const res = await apiPost(path, {});
                 if (!tenantOk(res.workspaceKey))
@@ -5482,12 +5628,12 @@ _Suggest the next step the user should tackle based on what's incomplete in the
         },
     },
     create_adoption_milestone: {
-        description: `${APEX} — Create an adoption milestone. "Adopted" is one event or one trait. Default enroll_mode is "future" (only people who sign up after this is created). Use enroll_mode="all" to include everyone already here. gap_hours wins over gap_days. Starts OFF unless active=true.`,
+        description: `${APEX} — Create an adoption milestone. "Adopted" is one event or one trait. Omit adopted_when_kind to create the milestone before its finishing moment is chosen, then set it later with update_adoption_milestone; a milestone with no moment counts nobody, mails nobody, and cannot be turned on. Default enroll_mode is "future" (only people who sign up after this is created). Use enroll_mode="all" to include everyone already here. gap_hours wins over gap_days. Starts OFF unless active=true.`,
         schema: z.object({
             name: z.string().describe("Human label, e.g. 'Ran first report'"),
             featureKey: z.string().describe("Stable feature key, e.g. 'reporting'"),
             actionLabel: z.string().optional().describe("Sentence verb: hasn't {action_label}. Never the raw event key."),
-            adoptedWhenKind: z.enum(["event", "trait"]).describe("How adoption is detected"),
+            adoptedWhenKind: z.enum(["event", "trait"]).optional().describe("How adoption is detected. Omit to decide the finishing moment later; the milestone stays inert until it is set."),
             eventName: z.string().optional().describe("event kind: the event whose firing means adopted"),
             traitPath: z.string().optional().describe("trait kind: dotted trait path, e.g. 'plan'"),
             traitValue: z.string().optional().describe("trait kind: value to match (equals)"),
@@ -5499,10 +5645,14 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             gapKind: z.enum(["days_since_signup", "event_not_fired"]).optional().describe("Anchor. Default days_since_signup. event_not_fired needs since_event_name."),
             sinceEventName: z.string().optional().describe("event_not_fired: the event the wait starts from."),
             enrollMode: z.enum(["all", "future"]).optional().describe("future (default) = only people who sign up from now on. all = historical roster too."),
+            finishWhen: z.enum(["this_person", "anyone_here"]).optional().describe("this_person (default) = only that person finishes. anyone_here = first person on the same Account finishes it for the company. Event finishes only."),
             active: z.boolean().optional().describe("Turn the milestone on. Default false."),
         }),
         handler: async (args) => {
             const warnings = await preflightAdoptionMilestone(args);
+            if (!args.adoptedWhenKind) {
+                warnings.push("No finishing moment set. This milestone counts nobody and cannot be turned on until update_adoption_milestone sets adopted_when_kind.");
+            }
             const body = milestoneWriteBody({
                 ...args,
                 enrollMode: args.enrollMode ?? "future",
@@ -5519,11 +5669,16 @@ _Suggest the next step the user should tackle based on what's incomplete in the
         },
     },
     update_adoption_milestone: {
-        description: `${APEX} — Update an adoption milestone (name, priority, active, gap days/hours, enroll mode, nudge or celebration journey).`,
+        description: `${APEX} — Update an adoption milestone (finishing moment, name, priority, active, gap days/hours, enroll mode, who finishing counts, nudge journey). Pass adopted_when_kind plus event_name or trait_path to set the finishing moment on a milestone created without one. active=true is REFUSED while there is no moment, because nobody could ever finish it and everyone would stay late forever. Changing the moment resets the lift window. If the Milestone is ON, changing what "finished" means stops and asks — do not pass confirmLiveMilestone unless they picked an out. A Milestone keeps BOTH letters on its one Adaptive Journey: the Celebration is a Send on the finish arm, not a second journey. finish_when=anyone_here on a live event Milestone backfills leftover Nudges for Accounts that already have a doer.`,
         schema: z.object({
             milestoneId: z.string(),
             name: z.string().optional(),
             actionLabel: z.string().optional().describe("Sentence verb: hasn't {action_label}."),
+            adoptedWhenKind: z.enum(["event", "trait"]).optional().describe("Set the finishing moment. Changing it resets the lift window."),
+            eventName: z.string().optional().describe("event kind: the event whose firing means adopted"),
+            traitPath: z.string().optional().describe("trait kind: dotted trait path, e.g. 'plan'"),
+            traitValue: z.string().optional().describe("trait kind: value to match (equals)"),
+            traitOp: z.enum(["equals", "not_equals", "exists"]).optional().describe("trait kind: comparison. Default equals."),
             priority: z.number().optional(),
             order: z.number().optional().describe("0-based sequence order. Prefer reorder_adoption_milestones to sequence the whole set."),
             active: z.boolean().optional(),
@@ -5532,10 +5687,34 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             gapKind: z.enum(["days_since_signup", "event_not_fired"]).optional(),
             sinceEventName: z.string().optional(),
             enrollMode: z.enum(["all", "future"]).optional(),
+            finishWhen: z.enum(["this_person", "anyone_here"]).optional().describe("this_person = only that person. anyone_here = first person on the Account. Event finishes only."),
             nudgeJourneyId: z.string().optional(),
-            celebrationJourneyId: z.string().optional(),
+            confirmLiveMilestone: z
+                .boolean()
+                .optional()
+                .describe("Change an ON Milestone anyway. Only pass true after they picked an out."),
         }),
         handler: async (args) => {
+            const changesWhatCounts = args.adoptedWhenKind !== undefined ||
+                args.eventName !== undefined ||
+                args.traitPath !== undefined ||
+                args.gapDays !== undefined ||
+                args.gapHours !== undefined ||
+                args.gapKind !== undefined ||
+                args.active !== undefined ||
+                args.enrollMode !== undefined ||
+                args.finishWhen !== undefined ||
+                args.nudgeJourneyId !== undefined;
+            if (changesWhatCounts) {
+                const guard = await refuseLiveApexObject({
+                    milestoneIds: [args.milestoneId],
+                    confirmed: args.confirmLiveMilestone === true,
+                    purpose: "milestone",
+                });
+                if (guard.stop) {
+                    return { content: [{ type: "text", text: guard.text }] };
+                }
+            }
             const updates = milestoneWriteBody(args);
             if (args.gapDays === undefined && args.gapHours === undefined && args.gapKind === undefined && args.sinceEventName === undefined) {
                 delete updates.gapPolicy;
@@ -5547,9 +5726,23 @@ _Suggest the next step the user should tackle based on what's incomplete in the
         },
     },
     delete_adoption_milestone: {
-        description: `${APEX} — Delete an adoption milestone.`,
-        schema: z.object({ milestoneId: z.string() }),
-        handler: async ({ milestoneId }) => {
+        description: `${APEX} — Delete an adoption milestone. If it is on, stop and ask. Do not pass confirmLiveMilestone unless they picked an out.`,
+        schema: z.object({
+            milestoneId: z.string(),
+            confirmLiveMilestone: z
+                .boolean()
+                .optional()
+                .describe("Delete an ON Milestone anyway. Only pass true after they picked an out."),
+        }),
+        handler: async ({ milestoneId, confirmLiveMilestone, }) => {
+            const guard = await refuseLiveApexObject({
+                milestoneIds: [milestoneId],
+                confirmed: confirmLiveMilestone === true,
+                purpose: "milestone",
+            });
+            if (guard.stop) {
+                return { content: [{ type: "text", text: guard.text }] };
+            }
             await apiDelete(`/api/adoption/milestones/${encodeURIComponent(milestoneId)}`);
             return { content: [{ type: "text", text: `Deleted milestone ${milestoneId}.` }] };
         },
@@ -5579,6 +5772,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             gapKind: z.enum(["days_since_signup", "event_not_fired"]).optional(),
             sinceEventName: z.string().optional(),
             enrollMode: z.enum(["all", "future"]).optional().describe("future (default) = only people who sign up from now on."),
+            finishWhen: z.enum(["this_person", "anyone_here"]).optional().describe("this_person (default) = only that person finishes. anyone_here = first person on the same Account. Event finishes only."),
             active: z.boolean().optional().describe("Turn the milestone on. Default false."),
             scaffold: z.enum(["both", "celebration", "nudge", "none"]).optional().describe("Which letters to include. Default both."),
             journeyName: z.string().optional().describe("Name for the Adaptive Journey. Default is the Milestone name."),
@@ -5658,7 +5852,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
         },
     },
     attach_adoption_milestone_still: {
-        description: `${APEX} — Attach a still of the empty screen (not_yet) or the finished screen (done) to a Milestone. Same two pictures the shop uploads. Pass imageBase64 or a public url. A Milestone is NOT a Target.`,
+        description: `${APEX} — Attach a still of the empty screen (not_yet) or the finished screen (done) to a Milestone. Same two pictures the shop uploads. Pass imageBase64 or a public url. For a signed-in product page, capture on their machine with \`npx @apex-inc/mcp-server screenshot --milestone … --state not_yet|done --url … --storage-state <login file>\` — do not use hosted recapture. A Milestone is NOT a Target.`,
         schema: z.object({
             milestoneId: z.string().describe("The Milestone to attach the still to"),
             state: z.enum(["not_yet", "done"]).describe("not_yet = empty screen; done = finished screen"),
@@ -5702,7 +5896,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
         },
     },
     recapture_adoption_milestone_stills: {
-        description: `${APEX} — Capture the Not yet and Done stills from public pages on a named workspace host. Not localhost. A login wall fails honestly and writes nothing — attach a still yourself. Same two pictures the shop uploads.`,
+        description: `${APEX} — Capture the Not yet and Done stills from public pages on a named workspace host. Not localhost. A login wall fails honestly and writes nothing. For a signed-in product page, sit it on their machine: \`npx @apex-inc/mcp-server screenshot --milestone … --storage-state <login file>\`. Same two pictures the shop uploads.`,
         schema: z.object({
             milestoneId: z.string().describe("The Milestone to capture stills for"),
             notYetUrl: z.string().url().optional().describe("Public https URL of the empty screen."),
@@ -5788,8 +5982,27 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             };
         },
     },
+    get_adoption_account_progress: {
+        description: `${APEX} — One Account's Path: which Milestones this company has finished, who did them, and how many people are Not yet / Started / Done. account_id is the company id from identify({ account: { id } }). Never includes holdout.`,
+        schema: z.object({
+            account_id: z
+                .string()
+                .describe("The Account id (identify account.id or the Apex acct_ id)"),
+        }),
+        handler: async ({ account_id }) => {
+            const data = await apiGet(`/api/adoption/progress?account_id=${encodeURIComponent(account_id)}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(data?.data ?? {}, null, 2),
+                    },
+                ],
+            };
+        },
+    },
     get_adoption_user_progress: {
-        description: `${APEX} — One user's adoption progress across milestones (status + timestamps). Answers "where is this user stuck?". Returns status/timestamps ONLY — never email, name, or holdout membership (holdout is withheld to keep the experiment unbiased). end_user_id must be a valid user id, not an email.`,
+        description: `${APEX} — One person's Path (Not yet / Started / Done) across every active Milestone. Includes finish_when and inherited when Anyone here finished for their company. Never email, name, or holdout. end_user_id must be a valid user id, not an email.`,
         schema: z.object({
             end_user_id: z
                 .string()