@apex-inc/mcp-server 0.27.4 → 0.28.0

package/dist/tools.js

@@ -9,6 +9,7 @@ import { getPersonLabel, lowerPerson } from "./person-label.js";
 import { notStartedExplanation, publishedExperimentLine, } from "./publish-communication-copy.js";
 import { activationLiveLine, shouldRefuseActivationWiring, } from "./activation-wiring.js";
 import { milestoneWriteBody, preflightAdoptionMilestone, } from "./adoption-compose.js";
+import { applyAddJourneyStep } from "./add-journey-step.js";
 const APEX = "Apex";
 /**
  * MOBX-006 — stable synthetic visitor id for agent-fired events.
@@ -4204,40 +4205,77 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     add_journey_step: {
-        description: `${APEX} — Append a wait or send step to a draft journey (inserted just before the exit; linear flows). 'wait' delays (ISO-8601 duration, e.g. P1D = 24h); 'send' fires a communication on the given channels. Call repeatedly to build trigger → wait → send → exit.`,
+        description: `${APEX} — Append a Wait or Send to a draft Adaptive Journey. Prefer compose_adoption_milestone for a Milestone (one Wait until they finish, letters already on the arms). Wait mode duration (ISO, e.g. P1D) or until_event (trigger_contract_id + deadline_iso). Send arm event|deadline puts the letter on that Wait arm. Do not add_journey_step send on a compose-built path — use set_journey_send to point the existing Send.`,
         schema: z.object({
             journeyId: z.string(),
             kind: z.enum(["wait", "send"]),
-            durationIso: z.string().optional().describe("wait only: ISO-8601 duration, e.g. 'P1D' (1 day), 'PT2H' (2 hours)."),
+            mode: z.enum(["duration", "until_event"]).optional().describe("wait only. Default duration."),
+            durationIso: z.string().optional().describe("wait duration: ISO-8601, e.g. 'P1D' (1 day), 'PT2H' (2 hours)."),
+            triggerContractId: z.string().optional().describe("wait until_event: the done-event trigger contract."),
+            deadlineIso: z.string().optional().describe("wait until_event: hours or days as ISO-8601, e.g. 'PT1H', 'P3D'."),
             commId: z.string().optional().describe("send only: the communication id to fire (create_communication or an existing comm)."),
             commVersion: z.number().optional().describe("send only: pinned comm version (default 1)."),
             channels: z.array(z.enum(["email", "in_app_push", "mobile_push", "web_push"])).optional().describe("send only: channels to fire (default ['email']). Use the SAME tokens as create_communication (email, in_app_push, mobile_push) so a comm's channels map cleanly onto the send step; web_push is send-only."),
+            arm: z.enum(["event", "deadline"]).optional().describe("send only: put this Send on the until_event Wait's event or deadline arm."),
         }),
         handler: async (args) => {
             try {
-                if (args.kind === "send" && !args.commId) {
-                    return { content: [{ type: "text", text: `${APEX} A send step needs commId.` }], isError: true };
+                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);
+                if (!applied.ok) {
+                    return { content: [{ type: "text", text: `${APEX} ${applied.error}` }], isError: true };
                 }
+                const updated = await apiPatch(`/api/journeys/${encodeURIComponent(args.journeyId)}`, { steps: applied.steps });
+                if (!tenantOk(updated.workspaceKey))
+                    return tenantMismatch();
+                return { content: [{ type: "text", text: `${APEX} Added ${args.kind} step ${applied.stepId} to journey ${args.journeyId}. Watch it update in the browser: ${journeyLink(args.journeyId)}` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
+    set_journey_send: {
+        description: `${APEX} — Point a draft journey's send step at a communication. Use after create_communication + edit_communication so the letter on the journey is yours, not the shared starter template. If the journey has one send, that send is updated. If it has several, pass step_id.`,
+        schema: z.object({
+            journeyId: z.string(),
+            commId: z.string().describe("The communication id from create_communication."),
+            stepId: z.string().optional().describe("Required when the journey has more than one send."),
+            commVersion: z.number().optional().describe("Pinned comm version. Default 1."),
+        }),
+        handler: async (args) => {
+            try {
                 const j = await apiGet(`/api/journeys/${encodeURIComponent(args.journeyId)}`);
                 const steps = [...(j.steps ?? [])];
-                const exit = steps.find((s) => s.type === "exit");
-                if (!exit) {
-                    return { content: [{ type: "text", text: `${APEX} Journey has no exit step; cannot insert.` }], isError: true };
+                const sends = steps.filter((s) => s.type === "send");
+                const target = args.stepId
+                    ? sends.find((s) => s.id === args.stepId)
+                    : sends.length === 1
+                        ? sends[0]
+                        : undefined;
+                if (!target) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: sends.length === 0
+                                    ? `${APEX} This journey has no send step. Use add_journey_step kind=send.`
+                                    : `${APEX} This journey has ${sends.length} send steps. Pass step_id (${sends.map((s) => s.id).join(", ")}).`,
+                            }],
+                        isError: true,
+                    };
                 }
-                const exitId = exit.id;
-                const newId = `step_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
-                const newStep = args.kind === "wait"
-                    ? { id: newId, type: "wait", label: "Wait", mode: "duration", duration: args.durationIso ?? "P1D", next: exitId }
-                    : { id: newId, type: "send", label: "Send", commId: args.commId, commVersion: args.commVersion ?? 1, channels: args.channels ?? ["email"], next: exitId };
-                // Insert before the exit: rewire whatever currently points to exit.
-                const pre = steps.find((s) => s.next === exitId);
-                if (pre)
-                    pre.next = newId;
-                steps.push(newStep);
+                target.commId = args.commId;
+                target.commVersion = args.commVersion ?? 1;
                 const updated = await apiPatch(`/api/journeys/${encodeURIComponent(args.journeyId)}`, { steps });
                 if (!tenantOk(updated.workspaceKey))
                     return tenantMismatch();
-                return { content: [{ type: "text", text: `${APEX} Added ${args.kind} step to journey ${args.journeyId}. Watch it update in the browser: ${journeyLink(args.journeyId)}` }] };
+                return {
+                    content: [{
+                            type: "text",
+                            text: `${APEX} Send step ${String(target.id)} now uses ${args.commId}. View it: ${journeyLink(args.journeyId)}`,
+                        }],
+                };
             }
             catch (err) {
                 return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
@@ -5448,6 +5486,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
         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"),
             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'"),
@@ -5484,6 +5523,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
         schema: z.object({
             milestoneId: z.string(),
             name: z.string().optional(),
+            actionLabel: z.string().optional().describe("Sentence verb: hasn't {action_label}."),
             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(),
@@ -5515,10 +5555,11 @@ _Suggest the next step the user should tackle based on what's incomplete in the
         },
     },
     compose_adoption_milestone: {
-        description: `${APEX} — Create an adoption milestone AND scaffold its journey legs in ONE call. scaffold="both" (default, recommended) creates the nudge (hasn't adopted within the gap) AND the celebration. New milestones default to enroll_mode="future" so a short clock does not mail the historical roster. gap_hours wins over gap_days. Journeys are drafts — preview the letter, then publish_journey. Returns the milestone, journey ids, and honesty warnings. A milestone is NOT a goal.`,
+        description: `${APEX} — Create a Milestone and stamp ONE Adaptive Journey (Trigger → Wait until they finish → Celebration and/or Nudge). scaffold="both" (default) includes both letters; "nudge" / "celebration" one letter; "none" is just-track. Unique Communication per Send — never reuse the shared catalog letters. New milestones default to enroll_mode="future". Journeys are drafts — preview, then publish_journey. A Milestone is NOT a Target.`,
         schema: z.object({
             name: z.string().describe("Human label, e.g. 'Started first experiment'"),
             featureKey: z.string().describe("Stable feature key, e.g. 'experiments'"),
+            actionLabel: z.string().optional().describe("Sentence verb: hasn't {action_label}."),
             adoptedWhenKind: z.enum(["event", "trait"]).describe("How adoption is detected"),
             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'"),
@@ -5526,19 +5567,33 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             traitOp: z.enum(["equals", "not_equals", "exists"]).optional(),
             priority: z.number().optional().describe("Lower is nudged first. Default 100."),
             order: z.number().optional().describe("0-based sequence order."),
-            gapDays: z.number().optional().describe("Nudge window in days. Ignored when gap_hours is set. Default 3."),
-            gapHours: z.number().optional().describe("Nudge window in hours. Use for same-day QA. 0 = right away."),
+            gapDays: z.number().optional().describe("First Nudge window in days. Ignored when gap_hours or nudge_clocks is set. Default 3."),
+            gapHours: z.number().optional().describe("First Nudge window in hours. 0 = right away."),
+            nudgeClocks: z
+                .array(z.object({
+                hours: z.number().optional(),
+                days: z.number().optional(),
+            }))
+                .optional()
+                .describe("Each clock is N hours or N days. First is the Wait deadline; later are extra Nudges."),
             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."),
             active: z.boolean().optional().describe("Turn the milestone on. Default false."),
-            scaffold: z.enum(["both", "celebration", "nudge", "none"]).optional().describe("Which legs to scaffold. Default both."),
-            journeyName: z.string().optional().describe("Name for a single scaffolded journey. Ignored for scaffold='both'."),
+            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."),
+            saveNotYetSegment: z.boolean().optional().describe("Save the live not-yet rule as a Segment."),
+            saveDoneSegment: z.boolean().optional().describe("Save the live done rule as a Segment."),
         }),
         handler: async (args) => {
             const warnings = await preflightAdoptionMilestone(args);
+            const firstClock = args.nudgeClocks?.[0];
             const created = await apiPost("/api/adoption/milestones", milestoneWriteBody({
                 ...args,
+                ...(firstClock?.hours !== undefined ? { gapHours: firstClock.hours } : {}),
+                ...(firstClock?.days !== undefined && firstClock.hours === undefined
+                    ? { gapDays: firstClock.days }
+                    : {}),
                 enrollMode: args.enrollMode ?? "future",
                 active: args.active ?? false,
                 priority: args.priority ?? 100,
@@ -5547,37 +5602,54 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             if (!milestoneId) {
                 return { content: [{ type: "text", text: JSON.stringify(created, null, 2) }] };
             }
+            const persistSegments = async () => {
+                if (!args.saveNotYetSegment && !args.saveDoneSegment) {
+                    return created.data?.milestone;
+                }
+                const patched = await apiPatch(`/api/adoption/milestones/${encodeURIComponent(milestoneId)}`, {
+                    saveNotYetSegment: args.saveNotYetSegment === true,
+                    saveDoneSegment: args.saveDoneSegment === true,
+                });
+                return patched.data?.milestone ?? created.data?.milestone;
+            };
             const scaffold = args.scaffold ?? "both";
             if (scaffold === "none") {
+                const milestone = await persistSegments();
                 return {
-                    content: [{ type: "text", text: JSON.stringify({ milestone: created.data?.milestone, journeyId: null, nudgeJourneyId: null, celebrationJourneyId: null, warnings }, null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify({
+                                milestone,
+                                journey_id: null,
+                                nudge_journey_id: null,
+                                celebration_journey_id: null,
+                                sends: [],
+                                warnings,
+                            }, null, 2) }],
                 };
             }
-            const scaffoldLeg = async (templateId, name) => {
-                const journey = await apiPost("/api/journeys/from-template", {
-                    templateId,
-                    milestoneId,
-                    ...(name ? { name } : {}),
-                });
-                return journey?.id ?? null;
-            };
-            const wantsNudge = scaffold === "nudge" || scaffold === "both";
-            const wantsCelebration = scaffold === "celebration" || scaffold === "both";
-            // Single-leg scaffolds honor journeyName; "both" lets each leg default.
-            const legName = scaffold === "both" ? undefined : args.journeyName;
-            const nudgeJourneyId = wantsNudge ? await scaffoldLeg("adoption-nudge", legName) : null;
-            const celebrationJourneyId = wantsCelebration
-                ? await scaffoldLeg("adoption-celebration", legName)
-                : null;
+            const journey = await apiPost("/api/journeys/from-template", {
+                templateId: "adoption-nudge",
+                milestoneId,
+                scaffold,
+                name: args.journeyName ?? args.name,
+                ...(args.nudgeClocks ? { nudgeClocks: args.nudgeClocks } : {}),
+            });
+            const journeyId = journey?.id ?? null;
+            const sends = (journey?.sends ?? []).map((s) => ({
+                role: s.role,
+                step_id: s.stepId,
+                comm_id: s.commId,
+            }));
+            const milestone = await persistSegments();
             return {
                 content: [
                     {
                         type: "text",
                         text: JSON.stringify({
-                            milestone: created.data?.milestone,
-                            journeyId: nudgeJourneyId ?? celebrationJourneyId,
-                            nudgeJourneyId,
-                            celebrationJourneyId,
+                            milestone,
+                            journey_id: journeyId,
+                            nudge_journey_id: journeyId,
+                            celebration_journey_id: null,
+                            sends,
                             warnings,
                         }, null, 2),
                     },
@@ -5585,6 +5657,115 @@ _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.`,
+        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"),
+            imageBase64: z.string().optional().describe("Base64-encoded PNG/JPEG."),
+            url: z.string().url().optional().describe("Already-hosted public image URL."),
+            viewport: z.enum(["desktop", "tablet", "mobile"]).optional(),
+            format: z.enum(["png", "jpeg"]).optional(),
+            label: z.string().optional(),
+        }),
+        handler: async (args) => {
+            if (!args.imageBase64 && !args.url) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Provide either imageBase64 or url.",
+                        }],
+                    isError: true,
+                };
+            }
+            const res = await apiPost(`/api/adoption/milestones/${encodeURIComponent(args.milestoneId)}/assets`, {
+                state: args.state,
+                source: args.imageBase64 ? "agent" : "upload",
+                viewport: args.viewport ?? "desktop",
+                imageBase64: args.imageBase64,
+                url: args.url,
+                format: args.format ?? "png",
+                label: args.label,
+            });
+            const asset = res.data;
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            id: asset.id,
+                            state: asset.state,
+                            url: asset.url,
+                            milestone_id: args.milestoneId,
+                        }, null, 2),
+                    }],
+            };
+        },
+    },
+    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.`,
+        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."),
+            doneUrl: z.string().url().optional().describe("Public https URL of the finished screen."),
+        }),
+        handler: async (args) => {
+            if (!args.notYetUrl && !args.doneUrl) {
+                return {
+                    content: [{ type: "text", text: "Name a public page for Not yet or Done." }],
+                    isError: true,
+                };
+            }
+            try {
+                const res = await apiPost(`/api/adoption/milestones/${encodeURIComponent(args.milestoneId)}/recapture`, {
+                    notYetUrl: args.notYetUrl,
+                    doneUrl: args.doneUrl,
+                });
+                if (res.error) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: res.error,
+                            }],
+                        isError: true,
+                    };
+                }
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                captured: res.data?.captured ?? [],
+                                failed: res.data?.failed ?? [],
+                                milestone_id: args.milestoneId,
+                            }, null, 2),
+                        }],
+                };
+            }
+            catch {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "We couldn’t open that page from Apex. It may need a sign-in. Attach a still yourself.",
+                        }],
+                    isError: true,
+                };
+            }
+        },
+    },
+    list_adoption_milestone_stills: {
+        description: `${APEX} — List the Not yet and Done stills attached to a Milestone. Empty means they have not attached one yet.`,
+        schema: z.object({
+            milestoneId: z.string().describe("The Milestone to list stills for"),
+        }),
+        handler: async ({ milestoneId }) => {
+            const res = await apiGet(`/api/adoption/milestones/${encodeURIComponent(milestoneId)}/assets`);
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify(res.data ?? [], null, 2),
+                    }],
+            };
+        },
+    },
     reorder_adoption_milestones: {
         description: `${APEX} — Set the sequence order of adoption milestones in one call. Pass the milestone ids in the desired order; each gets order = its index. Ordering the full set unlocks the "Path" funnel in the account view (a step-by-step drop-off chart that is only honest over an explicitly-ordered set).`,
         schema: z.object({