@apex-inc/mcp-server 0.32.0 → 0.34.0

package/dist/tools/letters.js

@@ -0,0 +1,1324 @@
+import { z } from "zod";
+import { apiGet, apiPost, apiPatch, apiDelete, getActiveWorkspace, } from "../api-client.js";
+import { controlGateGuidanceFor } from "../control-gate-guidance.js";
+import { notStartedExplanation, publishedExperimentLine } from "../publish-communication-copy.js";
+import { applyAddJourneyStep } from "../add-journey-step.js";
+import { refuseLiveApexObject } from "../live-test-guard.js";
+import { APEX, errMsg, appUrl, journeyLink, tenantOk, tenantMismatch, } from "../tool-shared.js";
+export const letterTools = {
+    recommend_communications: {
+        description: "Get recommended lifecycle communications for your vertical and conversion model. Returns a prioritized list of emails and push notifications to set up.",
+        schema: z.object({}),
+        handler: async () => {
+            const data = await apiPost("/api/communications/recommend", {});
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        },
+    },
+    generate_communications: {
+        description: "Create your communication program from recommendations. Pass catalog entry IDs to generate tenant communications with pre-written copy. Each new letter wears the workspace default Theme (Title / Body / Button look is snapshotted; catalog copy is not rewritten to match). Preview with preview_communication to see theme roles vs block overrides.",
+        schema: z.object({
+            catalogEntryIds: z.array(z.string()).describe("IDs from the recommendation output to generate"),
+        }),
+        handler: async (args) => {
+            const data = await apiPost("/api/communications/generate", { catalogEntryIds: args.catalogEntryIds });
+            const count = Array.isArray(data) ? data.length : 0;
+            return { content: [{ type: "text", text: `Generated ${count} communication(s).\n\n${JSON.stringify(data, null, 2)}` }] };
+        },
+    },
+    list_communications: {
+        description: "List the workspace's communication templates (email / inbox / web push / mobile push) with the fields you need to CHOOSE one — for a journey send step, a broadcast, or a transactional send. Returns per template: title, version, status, pipeline, channels, subject, a one-line body preview so you can disambiguate similar titles without opening each one, and controlState. Pipeline is 'transactional' (bypasses opt-out — needs a recipient-initiated trigger) or 'marketing' (consent-gated). Filter by pipeline, channel, or a search string. This is the programmatic equivalent of the dashboard's communication picker.\n\ncontrolState tells you what the Control currently IS, and therefore what editing it will cost: 'winner' (won an experiment, unedited — editing needs an explicit intent), 'winner_edited' (won, then changed since), 'in_experiment' (frozen, an experiment is measuring it right now), 'no_winner' (an experiment ran and settled without one), 'none' (never experimented on). A live letter with no champion is still editable; Publish asks replace vs compete. A champion or a running test: do not edit Control — add a variant, then compete.",
+        schema: z.object({
+            pipeline: z
+                .enum(["transactional", "marketing"])
+                .optional()
+                .describe("Only return comms in this deliverability pipeline. 'transactional' bypasses marketing opt-out; 'marketing' is consent-gated."),
+            channel: z
+                .enum(["email", "inbox", "web_push", "mobile_push"])
+                .optional()
+                .describe("Only return comms that include this channel."),
+            search: z
+                .string()
+                .optional()
+                .describe("Case-insensitive match against title, subject, and body preview."),
+            includeArchived: z
+                .boolean()
+                .optional()
+                .describe("Include archived templates (default false)."),
+        }),
+        handler: async (args) => {
+            const path = args.includeArchived
+                ? "/api/communications?includeArchived=1"
+                : "/api/communications";
+            const data = await apiGet(path);
+            const raw = Array.isArray(data) ? data : [];
+            const rows = raw.map((c) => {
+                const comm = c;
+                const content = (comm.content ?? {});
+                const slots = (content.slots ?? {});
+                const commType = typeof comm.commType === "string" ? comm.commType : undefined;
+                const bodyPreview = slots.body || slots.headline || slots.paragraph_1 || "";
+                return {
+                    id: String(comm.id ?? ""),
+                    title: String(comm.title ?? "Untitled"),
+                    version: typeof comm.version === "number" ? comm.version : 1,
+                    status: String(comm.status ?? "draft"),
+                    pipeline: commType === "transactional"
+                        ? "transactional"
+                        : "marketing",
+                    channels: Array.isArray(comm.channels)
+                        ? comm.channels
+                        : ["email"],
+                    subject: typeof content.subject === "string" ? content.subject : "",
+                    bodyPreview: String(bodyPreview),
+                    controlState: typeof comm.controlState === "string" ? comm.controlState : "none",
+                    triggerEventId: typeof comm.triggerEventId === "string"
+                        ? comm.triggerEventId
+                        : "",
+                };
+            });
+            const q = (args.search ?? "").trim().toLowerCase();
+            const filtered = rows.filter((r) => {
+                if (args.pipeline && r.pipeline !== args.pipeline)
+                    return false;
+                if (args.channel && !r.channels.includes(args.channel))
+                    return false;
+                if (q &&
+                    !`${r.title} ${r.subject} ${r.bodyPreview}`.toLowerCase().includes(q)) {
+                    return false;
+                }
+                return true;
+            });
+            if (filtered.length === 0) {
+                const hint = rows.length === 0
+                    ? "No communications set up yet. Use recommend_communications to get started."
+                    : "No communications match those filters.";
+                return { content: [{ type: "text", text: hint }] };
+            }
+            const summary = filtered
+                .map((r) => {
+                const preview = r.bodyPreview
+                    ? `\n  ${r.bodyPreview.slice(0, 120)}`
+                    : "";
+                const control = r.controlState && r.controlState !== "none"
+                    ? ` — control: ${r.controlState}`
+                    : "";
+                return `• ${r.title} (v${r.version}) — ${r.pipeline} — ${r.channels.join("/")} — ${r.status}${control}\n  subject: ${r.subject || "(none)"}${preview}\n  id: ${r.id}`;
+            })
+                .join("\n\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${filtered.length} communication(s):\n\n${summary}\n\nJSON:\n${JSON.stringify(filtered, null, 2)}`,
+                    },
+                ],
+            };
+        },
+    },
+    list_communication_themes: {
+        description: "List workspace communication Themes (the look: fonts, sizes, colors, Title/Body/Button roles). A Theme is not a Template — Templates are the job (event, slots, copy). Activate a Template with no extra theme step; new emails wear the workspace default theme. Apply writes drafts only; the merchant still publishes each email.",
+        schema: z.object({}),
+        handler: async () => {
+            const json = await apiGet("/api/communications/themes");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(json, null, 2),
+                    },
+                ],
+            };
+        },
+    },
+    create_communication_theme: {
+        description: "Create a communication Theme (the look). Clone an existing theme with clone_from_id, or pass style/roles. Does not assign other emails. Tell the merchant to publish emails after applying.",
+        schema: z.object({
+            name: z.string().min(1).max(60),
+            clone_from_id: z.string().optional(),
+            style: z.record(z.string(), z.unknown()).optional(),
+            roles: z.record(z.string(), z.unknown()).optional(),
+        }),
+        handler: async (args) => {
+            const data = await apiPost("/api/communications/themes", {
+                name: args.name,
+                cloneFromId: args.clone_from_id,
+                style: args.style,
+                roles: args.roles,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        },
+    },
+    update_communication_theme: {
+        description: "Update a communication Theme's name, style tokens, or Title/Body/Button roles. Does not rewrite other emails. Use apply_communication_theme to draft the look onto chosen emails. set_default makes new activations wear this theme.",
+        schema: z.object({
+            theme_id: z.string(),
+            name: z.string().min(1).max(60).optional(),
+            style: z.record(z.string(), z.unknown()).optional(),
+            roles: z.record(z.string(), z.unknown()).optional(),
+            set_default: z.boolean().optional(),
+        }),
+        handler: async (args) => {
+            const data = await apiPatch(`/api/communications/themes/${encodeURIComponent(args.theme_id)}`, {
+                name: args.name,
+                style: args.style,
+                roles: args.roles,
+                setDefault: args.set_default,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        },
+    },
+    apply_communication_theme: {
+        description: "Apply a Theme's look onto chosen communication Templates. Default apply is draft — recipients keep the old look until the merchant publishes. apply=live uses the look on the next send. Omit comm_ids to target every template already on this theme. Never group emails by experiment catalog ids; a shop's order-updates series is the same object.",
+        schema: z.object({
+            theme_id: z.string(),
+            comm_ids: z.array(z.string()).optional(),
+            apply: z.enum(["draft", "live"]).optional(),
+        }),
+        handler: async (args) => {
+            const data = await apiPost(`/api/communications/themes/${encodeURIComponent(args.theme_id)}/apply`, { commIds: args.comm_ids, apply: args.apply });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        },
+    },
+    edit_communication: {
+        description: "Update a communication's subject, body, CTA, channels, or status. Pass the communication ID and the fields to update. For blank/builder comms, the headline/body/ctaLabel/ctaUrl slots are synced into the rendered email body — verify with preview_communication.\n\nA communication's Control is protected when it won an experiment or a published journey is sending it. Editing it then requires `intent`: \"compete\" adds your edit as a variant and measures it against the current content (nothing changes for recipients yet); \"replace\" makes your edit what everyone receives and supersedes any prior win. WHEN IN DOUBT, USE \"compete\" — it is recoverable, \"replace\" discards a measured result permanently. The server returns 409 intent_required with both options if you omit it.",
+        schema: z.object({
+            communicationId: z.string().describe("The communication ID to update"),
+            subject: z.string().optional().describe("New email subject line"),
+            slots: z.record(z.string()).optional().describe("Content overrides: headline, body, ctaLabel, ctaUrl. These now sync into the rendered email body (not just metadata)."),
+            channels: z.array(z.string()).optional().describe("Channels: email, in_app_push, mobile_push"),
+            status: z.enum(["draft", "active", "paused"]).optional().describe("Communication status"),
+            audience_bucket: z
+                .enum(["production", "beta", "dev"])
+                .optional()
+                .describe("Who this send is for. Default production. Never All or Unclassified."),
+            intent: z
+                .enum(["compete", "replace"])
+                .optional()
+                .describe('How to apply the edit when the Control is protected. "compete" = add it as a variant and run it as an experiment against the current content (safe default; the current content keeps sending). "replace" = update what everyone receives, superseding any prior win. Required only when the comm won an experiment or is live in a published journey.'),
+            confirmLiveExperiment: z
+                .boolean()
+                .optional()
+                .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;
+            if (args.channels)
+                body.channels = args.channels;
+            if (args.audience_bucket)
+                body.audienceBucket = args.audience_bucket;
+            if (args.intent)
+                body.intent = args.intent;
+            if (args.confirmLiveExperiment)
+                body.confirmLiveExperiment = true;
+            const content = {};
+            if (args.subject)
+                content.subject = args.subject;
+            if (args.slots)
+                content.slots = args.slots;
+            if (Object.keys(content).length)
+                body.content = content;
+            try {
+                const data = await apiPatch(`/api/communications/${args.communicationId}`, body);
+                // The comm may be protected without the edit being blocked (draft saves
+                // defer the question to publish). Carry the server's advisory through
+                // so the agent knows a decision is coming rather than meeting it later.
+                const advisory = typeof data?.controlAdvisory === "string"
+                    ? `\n\n${data.controlAdvisory}`
+                    : "";
+                return { content: [{ type: "text", text: `Communication updated.${advisory}\n\n${JSON.stringify(data, null, 2)}` }] };
+            }
+            catch (err) {
+                const guidance = controlGateGuidanceFor(err, {
+                    toolName: "edit_communication",
+                    communicationId: args.communicationId,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: guidance ?? `${APEX} ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    },
+    publish_communication: {
+        description: "Publish a communication's draft as the live version — this is what makes an edit reach recipients. Editing only saves a draft.\n\nCompete (or publishing a letter that already has variants) creates a prefilled DRAFT experiment. It does not start the test. After the user reviews the draft, call activate_experiment to begin it. Replace publishes the letter for everyone and never creates an experiment.\n\nOptional overrides: hypothesis, belief_id, confidence, duration_days.\n\nTwo conflicts need a decision rather than a retry. `ambiguous_experiment_host` means several published journeys send this communication — the candidates are returned; ask the user and re-issue with host_journey_id. `comm_already_in_experiment` means one is already running; end it first.",
+        schema: z.object({
+            communicationId: z.string().describe("The communication ID to publish"),
+            intent: z
+                .enum(["compete", "replace"])
+                .optional()
+                .describe('How to apply the draft when the Control is protected. "compete" = the current content keeps sending and your draft becomes a filled-in experiment draft (then activate_experiment). "replace" = your draft becomes what everyone receives. Required only when the comm won an experiment or is live in a published journey.'),
+            confirmLiveExperiment: z
+                .boolean()
+                .optional()
+                .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()
+                .describe("Which published journey hosts the experiment. Only needed after a 409 ambiguous_experiment_host, using one of the returned candidate ids."),
+            hypothesis: z
+                .string()
+                .optional()
+                .describe("Override the Suggested hypothesis on the draft experiment."),
+            beliefId: z
+                .string()
+                .optional()
+                .describe("Link the draft experiment to an existing belief."),
+            confidence: z
+                .number()
+                .optional()
+                .describe("Override the prefilled confidence (percent)."),
+            durationDays: z
+                .number()
+                .optional()
+                .describe("Override the prefilled decision window in days."),
+        }),
+        handler: async (args) => {
+            const 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;
+            if (args.confirmLiveExperiment)
+                body.confirmLiveExperiment = true;
+            if (args.hostJourneyId)
+                body.hostJourneyId = args.hostJourneyId;
+            if (args.hypothesis)
+                body.hypothesis = args.hypothesis;
+            if (args.beliefId)
+                body.beliefId = args.beliefId;
+            if (typeof args.confidence === "number")
+                body.confidence = args.confidence;
+            if (typeof args.durationDays === "number")
+                body.durationDays = args.durationDays;
+            try {
+                const data = await apiPost(`/api/communications/${args.communicationId}/publish`, body);
+                const lines = [];
+                if (data.published === false) {
+                    lines.push("Nothing to publish — no unpublished changes.");
+                }
+                else {
+                    lines.push(`Published version ${data.version ?? "?"}.`);
+                }
+                if (data.repinned?.length) {
+                    lines.push(`${data.repinned.length} send step(s) moved to the new version.`);
+                }
+                if (data.experiment) {
+                    lines.push(publishedExperimentLine({
+                        id: data.experiment.id,
+                        status: data.experiment.status ?? "draft",
+                        url: appUrl(`/dashboard/experiments/${data.experiment.id}`),
+                    }));
+                }
+                else if (data.experimentNotStarted) {
+                    lines.push(notStartedExplanation(data.experimentNotStarted));
+                }
+                return { content: [{ type: "text", text: lines.join("\n") }] };
+            }
+            catch (err) {
+                const guidance = controlGateGuidanceFor(err, {
+                    toolName: "publish_communication",
+                    communicationId: args.communicationId,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: guidance ??
+                                `${APEX} ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    },
+    preview_communication: {
+        description: "See the rendered communication with your brand and Theme applied. Returns the subject, the rendered plain-text body, Title/Body/Button roles, which blocks override the theme, and a browser preview link.",
+        schema: z.object({
+            communicationId: z.string().describe("The communication ID to preview"),
+        }),
+        handler: async (args) => {
+            const data = await apiPost(`/api/communications/${args.communicationId}/preview`, {});
+            // Strip tags from subject (preview may annotate it with a slot span).
+            const subject = (data.subject ?? "").replace(/<[^>]+>/g, "");
+            const text = (data.text ?? "").trim();
+            const link = appUrl(`/dashboard/communications/${args.communicationId}`);
+            const look = data.themeLook;
+            const roleLines = look?.roles
+                ? Object.entries(look.roles).map(([role, style]) => {
+                    const bits = [
+                        style.type,
+                        style.headingLevel,
+                        style.align,
+                        style.width,
+                    ].filter(Boolean);
+                    return `  ${role}: ${bits.join(" / ") || "(default)"}`;
+                })
+                : ["  (no role snapshot — look is whatever is baked on the blocks)"];
+            const overrideLines = look?.overrides && look.overrides.length > 0
+                ? look.overrides.map((row) => `  ${row.label}: ${row.keys.join(", ")}`)
+                : ["  (none)"];
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Subject: ${subject || "(none)"}`,
+                            ``,
+                            `Rendered body:`,
+                            text ? text : "(empty — add content via edit_communication)",
+                            ``,
+                            `Theme roles:`,
+                            ...roleLines,
+                            ``,
+                            `Block overrides:`,
+                            ...overrideLines,
+                            ``,
+                            `Open in the browser to see the full styled email: ${link}`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    add_communication_variant: {
+        description: "Add a content variant (Variant A, B, …) to a communication. Clones the current Control into a new column so you can run a content experiment. When the letter is a champion, this is how you author a challenger — do not edit Control. Does not change what recipients get until you publish. Theme look is inherited; do not set per-block align here.",
+        schema: z.object({
+            communicationId: z.string().describe("The communication to add a variant to"),
+            label: z.string().optional().describe("Optional column label (e.g. Variant A)"),
+        }),
+        handler: async (args) => {
+            const data = await apiPost(`/api/communications/${args.communicationId}/variants`, { label: args.label });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Variant added.\n\n${JSON.stringify(data, null, 2)}`,
+                    },
+                ],
+            };
+        },
+    },
+    send_test_communication: {
+        description: "Send a test email to yourself. The email will be sent to the logged-in user's email address.",
+        schema: z.object({
+            communicationId: z.string().describe("The communication ID to test"),
+        }),
+        handler: async (args) => {
+            await apiPost(`/api/communications/${args.communicationId}/test`, {});
+            return { content: [{ type: "text", text: "Test email sent! Check your inbox." }] };
+        },
+    },
+    trigger_communication: {
+        description: "Manually send a communication to a specific recipient. Use for one-off sends or testing with specific email addresses.",
+        schema: z.object({
+            communicationId: z.string().describe("The communication ID to send"),
+            recipientEmail: z.string().email().describe("Email address of the recipient"),
+            mergeData: z.record(z.string()).optional().describe("Template variables to merge (e.g. user_name, company)"),
+        }),
+        handler: async (args) => {
+            // `/send` was removed. The composer test route is the one-off send:
+            // workspace-admin, optional recipient override, mergeData substitution.
+            await apiPost(`/api/communications/${args.communicationId}/test`, {
+                recipient: args.recipientEmail,
+                mergeData: args.mergeData,
+            });
+            return { content: [{ type: "text", text: `Communication sent to ${args.recipientEmail}.` }] };
+        },
+    },
+    create_comm_experiment: {
+        description: "Legacy helper. Prefer the composer loop: edit_communication or add_communication_variant, then publish_communication (compete creates a prefilled draft), then activate_experiment to start the test. Do not teach this as the default.",
+        schema: z.object({
+            communicationId: z.string().describe("The communication to experiment on"),
+            splitLevel: z.enum(["subject", "body", "cta", "full"]).describe("What to vary between variants"),
+            funnelGoal: z.string().describe("The conversion event to optimize for (e.g. 'purchase', 'signup_complete')"),
+            variants: z.array(z.object({
+                name: z.string(),
+                bodyOverrides: z.record(z.string()).optional(),
+                subjectOverride: z.string().optional(),
+            })).describe("Variant definitions with content overrides"),
+        }),
+        handler: async (args) => {
+            const data = await apiPost("/api/communications/experiments", args);
+            return { content: [{ type: "text", text: `Experiment created.\n\n${JSON.stringify(data, null, 2)}` }] };
+        },
+    },
+    wire_audience_seed: {
+        description: `${APEX} — Wire up the events and traits a campaign audience seed depends on. Use this when the merchant says "wire up the active customers audience" or after the AudienceActivationWizard's Screen 1 hands off to Cursor. Returns the per-event/trait code snippets, the file recommendations, and fires a test event with is_test=1 so the wizard's polling loop confirms the wiring landed end-to-end. Idempotent: calling twice does NOT double-instrument; the agent should still review existing code before adding the snippet.`,
+        schema: z.object({
+            seedId: z
+                .string()
+                .describe("Audience seed id, e.g. 'aud-seed-active-customers-90d'. Returned by the seed-campaign-defaults POST endpoint and surfaced in the wizard's URL."),
+            framework: z
+                .enum(["typescript", "snippet", "python", "ruby"])
+                .optional()
+                .describe("Code style to return. Defaults to 'typescript' (the SDK's canonical surface). Use 'snippet' for script-tag installs (Shopify, WordPress, Webflow). The wizard sets this from the detected framework."),
+            fireTestEvent: z
+                .boolean()
+                .optional()
+                .describe("When true (default), fires a test event with is_test=1 for each event the seed depends on. The wizard's poll loop sees these and advances. Set to false if the agent only wants to read the snippets without writing test data."),
+        }),
+        handler: async ({ seedId, framework = "typescript", fireTestEvent = true, }) => {
+            const workspaceKey = getActiveWorkspace() || (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY);
+            if (!workspaceKey) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No active workspace. Use switch_workspace first or set APEX_WORKSPACE_KEY.",
+                        },
+                    ],
+                };
+            }
+            // Pull the seed's instrumentation requirements via the
+            // dashboard API. Single source of truth: the dashboard
+            // walks the seed's predicate the same way the
+            // AudienceBuilder does.
+            const data = await apiGet(`/api/audiences/seed-campaign-defaults/${encodeURIComponent(seedId)}/instrumentation?framework=${framework}`);
+            // Optionally fire test events so the wizard polling loop
+            // can flip into the "test received" state immediately.
+            // We fire one per event with is_test=1 so they don't
+            // pollute analytics.
+            const firedTests = [];
+            if (fireTestEvent && data.events.length > 0) {
+                for (const ev of data.events) {
+                    try {
+                        await apiPost("/api/events", {
+                            type: "custom",
+                            visitorId: "mcp-agent-wire-test",
+                            data: {
+                                eventName: ev.name,
+                                endUserId: "mcp-agent-test-user",
+                                is_test: 1,
+                                source: "mcp_wire_audience_seed",
+                            },
+                        });
+                        firedTests.push(ev.name);
+                    }
+                    catch {
+                        // Best-effort — the agent gets the snippets even if
+                        // test firing fails; the wizard's manual fire
+                        // button is still available.
+                    }
+                }
+            }
+            const snippetBlocks = [];
+            for (const ev of data.events) {
+                const props = ev.properties.length > 0
+                    ? `\nProperties (predicate cares about):\n${ev.properties
+                        .map((p) => `  - ${p.name} (${p.type}): ${p.description}`)
+                        .join("\n")}`
+                    : "";
+                snippetBlocks.push(`### Event: ${ev.name}${props}\n\n\`\`\`${framework === "typescript" ? "ts" : framework}\n${ev.sdkExample}\n\`\`\``);
+            }
+            for (const tr of data.traits) {
+                snippetBlocks.push(`### Trait: ${tr.fieldPath}\n${tr.description}\n\n\`\`\`${framework === "typescript" ? "ts" : framework}\n${tr.sdkExample}\n\`\`\``);
+            }
+            const summary = [
+                `# Wiring up "${data.seedName}"`,
+                ``,
+                `Predicate: ${data.predicateSummary}`,
+                ``,
+                `Add the following ${data.events.length} event ${data.events.length === 1 ? "call" : "calls"} and ${data.traits.length} trait ${data.traits.length === 1 ? "set" : "sets"} to the merchant's codebase. Find the right files (checkout success handler, login flow, session start) and insert the snippet, replacing placeholder properties with the merchant's actual values.`,
+                ``,
+                ...snippetBlocks,
+                ``,
+                firedTests.length > 0
+                    ? `## Test events fired\nFired test events for: ${firedTests.join(", ")}. The wizard's polling loop will see these and advance. Confirm the merchant fires REAL events from production code paths before relying on the audience.`
+                    : `## Test events\nNo test events fired (per fireTestEvent=false). Run the wizard's "Send a test event" button manually after wiring.`,
+                ``,
+                `Workspace: ${workspaceKey}`,
+            ].join("\n");
+            return { content: [{ type: "text", text: summary }] };
+        },
+    },
+    wire_audience: {
+        description: `${APEX} — Wire up the events and traits ANY audience depends on, not just starter audiences. Use this for bespoke / merchant-built audiences (e.g. 'New sign-ups in the last 14 days', 'Stalled sign-ups — no connector in 12h'). Walks the audience's predicate server-side, classifies each referenced event (auto-fired by the Apex snippet vs documented in Apex's event taxonomy vs custom merchant event), returns per-event recommendations, and optionally fires test events (is_test=1) for non-auto-fired events so the wizard's polling loop confirms wiring landed.`,
+        schema: z.object({
+            audienceId: z
+                .string()
+                .describe("Segment id (the workspace's saved group). Use list_segments first to find it. Bespoke segments carry generated ids; seed-cloned segments carry ids starting with `aud-seed-`."),
+            framework: z
+                .enum(["typescript", "snippet", "python", "ruby"])
+                .optional()
+                .describe("Code style to return. Defaults to 'typescript'. Use 'snippet' for script-tag installs (Shopify, WordPress, Webflow)."),
+            fireTestEvent: z
+                .boolean()
+                .optional()
+                .describe("When true (default), fires a test event with is_test=1 for each NON-AUTO-FIRED event the audience depends on. Auto-fired events (pageview, click, etc.) are skipped — they're already firing automatically and don't need a synthetic test."),
+        }),
+        handler: async ({ audienceId, framework = "typescript", fireTestEvent = true, }) => {
+            const workspaceKey = getActiveWorkspace() || (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY);
+            if (!workspaceKey) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No active workspace. Use switch_workspace first or set APEX_WORKSPACE_KEY.",
+                        },
+                    ],
+                };
+            }
+            const data = await apiGet(`/api/audiences/${encodeURIComponent(audienceId)}/instrumentation?framework=${framework}`);
+            // Fire test events for non-auto-fired events only. Auto-fired
+            // events are already flowing — sending a synthetic one would
+            // be misleading (and it'd fail because the merchant's snippet
+            // is what ingests pageview, not our agent).
+            const wirableEvents = data.events.filter((e) => e.category !== "auto-fired-web" &&
+                e.category !== "auto-fired-mobile");
+            const firedTests = [];
+            const skippedAutoFired = data.events
+                .filter((e) => e.category === "auto-fired-web" ||
+                e.category === "auto-fired-mobile")
+                .map((e) => e.name);
+            if (fireTestEvent && wirableEvents.length > 0) {
+                for (const ev of wirableEvents) {
+                    try {
+                        await apiPost("/api/events", {
+                            type: "custom",
+                            visitorId: "mcp-agent-wire-test",
+                            data: {
+                                eventName: ev.name,
+                                endUserId: "mcp-agent-test-user",
+                                is_test: 1,
+                                source: "mcp_wire_audience",
+                            },
+                        });
+                        firedTests.push(ev.name);
+                    }
+                    catch {
+                        // Best-effort.
+                    }
+                }
+            }
+            const sections = [];
+            sections.push(`# Wiring up "${data.audienceName}"`);
+            if (data.audienceSummary) {
+                sections.push(`\n${data.audienceSummary}`);
+            }
+            if (skippedAutoFired.length > 0) {
+                sections.push(`\n## Already automatic (no code needed)\nThe Apex web snippet / mobile SDK fires these events automatically. Just confirm the snippet/SDK is installed:`);
+                for (const name of skippedAutoFired) {
+                    sections.push(`  - ${name}`);
+                }
+            }
+            if (wirableEvents.length > 0 || data.traits.length > 0) {
+                sections.push(`\n## Code to add to the merchant's codebase`);
+                for (const ev of wirableEvents) {
+                    const props = ev.properties.length > 0
+                        ? `\nProperties (audience reads these): ${ev.properties.map((p) => p.name).join(", ")}`
+                        : "";
+                    sections.push(`\n### Event: ${ev.name} (${ev.category})\n${ev.caption}${props}\n\n\`\`\`${framework === "typescript" ? "ts" : framework}\n${ev.sdkExample}\n\`\`\``);
+                }
+                for (const tr of data.traits) {
+                    sections.push(`\n### Trait: ${tr.fieldPath}\n${tr.description}\n\n\`\`\`${framework === "typescript" ? "ts" : framework}\n${tr.sdkExample}\n\`\`\``);
+                }
+            }
+            if (firedTests.length > 0) {
+                sections.push(`\n## Test events fired\nFired test events (is_test=1) for: ${firedTests.join(", ")}. The wizard's polling loop will see these and advance. Confirm the merchant fires REAL events from production code paths before relying on the audience.`);
+            }
+            else if (wirableEvents.length === 0) {
+                sections.push(`\n## Test events\nNothing to fire — every event is auto-fired by Apex's snippet/SDK.`);
+            }
+            else {
+                sections.push(`\n## Test events\nNo test events fired (per fireTestEvent=false). Run the wizard's "Send a test event" button manually after wiring.`);
+            }
+            sections.push(`\nWorkspace: ${workspaceKey}`);
+            return { content: [{ type: "text", text: sections.join("\n") }] };
+        },
+    },
+    audit_audience_readiness: {
+        description: `${APEX} — Check whether an audience is wired up and matching users. Use this to verify your wire_audience_seed work succeeded, or to diagnose why a campaign is showing zero matches. Returns the audience predicate, current matching count, recency buckets, and which referenced events have arrived from the workspace.`,
+        schema: z.object({
+            audienceId: z
+                .string()
+                .describe("Segment id (the workspace's saved group, not the seed). Use list_segments first to find it."),
+        }),
+        handler: async ({ audienceId }) => {
+            const workspaceKey = getActiveWorkspace() || (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY);
+            if (!workspaceKey) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No active workspace. Use switch_workspace first or set APEX_WORKSPACE_KEY.",
+                        },
+                    ],
+                };
+            }
+            const [audience, preview] = await Promise.all([
+                apiGet(`/api/audiences/${encodeURIComponent(audienceId)}`),
+                apiGet(`/api/audiences/${encodeURIComponent(audienceId)}/preview`).catch(() => null),
+            ]);
+            const matchingLine = preview
+                ? `${preview.matchingCount.toLocaleString()} user${preview.matchingCount === 1 ? "" : "s"} currently match`
+                : "Couldn't compute live preview (audience may still resolve correctly at send time)";
+            const recencyLines = preview
+                ? [
+                    `  - Last 24h: ${preview.recencyBuckets.last_24h}`,
+                    `  - Last 7d:  ${preview.recencyBuckets.last_7d}`,
+                    `  - Last 30d: ${preview.recencyBuckets.last_30d}`,
+                    `  - Older:    ${preview.recencyBuckets.older}`,
+                ].join("\n")
+                : "  (no recency data)";
+            const summary = [
+                `# Audience readiness: ${audience.name}`,
+                audience.description ? `\n${audience.description}` : "",
+                `\n## Match status\n${matchingLine}`,
+                `\n## Recency buckets\n${recencyLines}`,
+                `\n## Predicate\n\`\`\`json\n${JSON.stringify(audience.predicate, null, 2)}\n\`\`\``,
+                preview && preview.matchingCount === 0
+                    ? `\n## Diagnosis\nZero matches. Most likely causes:\n  1. Events the predicate references aren't firing yet from the merchant's codebase. Run \`wire_audience_seed\` if this is a starter audience, or check the predicate's event names against your codebase.\n  2. The predicate's window (\`last_n_days\`, \`ever\`) is too narrow.\n  3. End-user identity isn't being stitched. Each \`apex.track()\` call must include \`endUserId\` in its data payload, or be preceded by an \`identify()\` call.\n`
+                    : "",
+                `\nWorkspace: ${workspaceKey}`,
+            ].join("\n");
+            return { content: [{ type: "text", text: summary }] };
+        },
+    },
+    // ─── Journey Exit Semantics — catch-up tools ────────────────────────────
+    //
+    // Wraps the journey-management + exit-rules + cart-state API
+    // surfaces shipped in `journey_exit_semantics_0b4fe496.plan.md`.
+    // Agent-friendly arg names (snake_case) are mapped to the REST
+    // routes inside each handler.,
+    create_journey: {
+        description: `${APEX} — Create a blank draft journey (an unconfigured event trigger wired to an exit). Then set_journey_trigger and add_journey_step to build it, and publish_journey to launch. For e-commerce flows like cart recovery, prefer create_journey_from_template. audience_bucket defaults to production (live customers). Same email on TestFlight and the store is two people — do not create a staging copy of the journey.`,
+        schema: z.object({
+            name: z.string().optional().describe("Journey name (default 'Untitled journey')."),
+            audience_bucket: z
+                .enum(["production", "beta", "dev"])
+                .optional()
+                .describe("Who this journey enrolls. Default production. Never All or Unclassified."),
+        }),
+        handler: async ({ name, audience_bucket }) => {
+            try {
+                const j = await apiPost("/api/journeys/blank", { name });
+                if (audience_bucket && audience_bucket !== "production") {
+                    await apiPatch(`/api/journeys/${j.id}`, { audienceBucket: audience_bucket });
+                }
+                if (!tenantOk(j.workspaceKey))
+                    return tenantMismatch();
+                return { content: [{ type: "text", text: `${APEX} Created draft journey "${j.name}" (id: ${j.id}). Open it in the browser: ${journeyLink(j.id)}\nNext: set_journey_trigger, then add_journey_step.` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
+    create_journey_from_template: {
+        description: `${APEX} — Instantiate a starter journey template (e.g. Abandoned Cart Recovery) into a fresh draft. Get the templateId from get_wiring_status (Ready-to-run templates list their id). After instantiating, review the steps, then publish_journey.`,
+        schema: z.object({ templateId: z.string().describe("Template id from get_wiring_status (e.g. 'mobile-cart-recovery').") }),
+        handler: async ({ templateId }) => {
+            try {
+                const j = await apiPost("/api/journeys/from-template", { templateId });
+                if (!tenantOk(j.workspaceKey))
+                    return tenantMismatch();
+                return { content: [{ type: "text", text: `${APEX} Instantiated "${j.name}" (id: ${j.id}) from template ${templateId}. Open it in the browser: ${journeyLink(j.id)}\nReview its steps with get_journey, then publish_journey.` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
+    list_trigger_contracts: {
+        description: `${APEX} — List the workspace's trigger contracts (the event bindings you pass to set_journey_trigger / add_journey_exit). Returns each contract's id + the event it fires on. Call this before set_journey_trigger so you use a real id instead of guessing.`,
+        schema: z.object({}),
+        handler: async () => {
+            const data = await apiGet("/api/journeys/trigger-contracts");
+            const contracts = data.contracts ?? [];
+            if (contracts.length === 0) {
+                return { content: [{ type: "text", text: `${APEX} No trigger contracts registered yet. Creating a blank journey seeds the starter set.` }] };
+            }
+            const lines = contracts.map((c) => `  • ${c.id} → ${c.eventName ?? "?"}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [`${APEX} Trigger contracts (${contracts.length})`, ...lines, ``, `Pass one of these ids as triggerContractId to set_journey_trigger.`].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    set_journey_trigger: {
+        description: `${APEX} — Set the entry trigger (the event that enrolls subjects) on a draft journey's trigger step. Pass event_name (the Apex Spec event, e.g. user_signed_up). A trig-* contract id is storage-only — prefer the Spec name.`,
+        schema: z.object({
+            journeyId: z.string(),
+            eventName: z.string().optional().describe("Apex Spec event name that enrolls subjects (e.g. user_signed_up). Preferred."),
+            triggerContractId: z.string().optional().describe("Storage id from list_trigger_contracts. Prefer event_name."),
+        }),
+        handler: async ({ journeyId, eventName, triggerContractId, }) => {
+            try {
+                const cdata = await apiGet("/api/journeys/trigger-contracts");
+                const contracts = cdata.contracts ?? [];
+                let resolvedId = triggerContractId;
+                if (eventName) {
+                    const match = contracts.find((c) => c.eventName === eventName);
+                    if (match) {
+                        resolvedId = match.id;
+                    }
+                    else {
+                        const created = await apiPost("/api/journey-triggers", {
+                            eventName,
+                            fieldMappings: { end_user_id: "endUserId" },
+                            recipientInitiated: true,
+                        });
+                        resolvedId = created.id;
+                    }
+                }
+                if (!resolvedId) {
+                    return {
+                        content: [{ type: "text", text: `${APEX} Pass event_name (preferred) or triggerContractId.` }],
+                        isError: true,
+                    };
+                }
+                if (!eventName &&
+                    contracts.length > 0 &&
+                    !contracts.some((c) => c.id === resolvedId)) {
+                    const opts = contracts
+                        .map((c) => `${c.id}${c.eventName ? ` (${c.eventName})` : ""}`)
+                        .join(", ");
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `${APEX} Unknown triggerContractId "${resolvedId}". Valid options: ${opts}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const j = await apiGet(`/api/journeys/${encodeURIComponent(journeyId)}`);
+                const steps = (j.steps ?? []).map((s) => s.type === "trigger" ? { ...s, trigger: { type: "event", triggerContractId: resolvedId } } : s);
+                const updated = await apiPatch(`/api/journeys/${encodeURIComponent(journeyId)}`, { steps });
+                if (!tenantOk(updated.workspaceKey))
+                    return tenantMismatch();
+                const label = eventName ? `${eventName} (${resolvedId})` : resolvedId;
+                return { content: [{ type: "text", text: `${APEX} Trigger set to ${label} on journey ${journeyId}. View it: ${journeyLink(journeyId)}` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
+    add_journey_step: {
+        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"]),
+            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 {
+                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);
+                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 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");
+                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,
+                    };
+                }
+                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} 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 };
+            }
+        },
+    },
+    add_journey_branch: {
+        description: `${APEX} — Insert a CONDITIONAL content branch before the exit: evaluate one condition and send a different communication to each side. Use this for true content branching (e.g. "cart value > $100 → VIP email, else standard email"). For the simpler "skip the next send if they already converted" case, use add_journey_exit instead. The condition is an attribute test (field_path + operator + value) or an event test (event_fired / event_not_fired within a window).`,
+        schema: z.object({
+            journeyId: z.string(),
+            condition: z.object({
+                kind: z.enum(["attribute", "event_fired", "event_not_fired"]),
+                field_path: z.string().optional().describe("attribute only: dotted path, e.g. 'cart.valueCents' or 'plan'."),
+                operator: z
+                    .enum(["equals", "not_equals", "greater_than", "less_than", "in", "exists", "not_exists"])
+                    .optional()
+                    .describe("attribute only."),
+                value: z
+                    .union([z.string(), z.number(), z.boolean(), z.array(z.union([z.string(), z.number(), z.boolean()]))])
+                    .optional()
+                    .describe("attribute only: the comparison value (omit for exists/not_exists)."),
+                event_name: z.string().optional().describe("event only: the canonical event, e.g. 'purchase'."),
+                window_days: z.number().optional().describe("event only: look-back window in days (omit = ever)."),
+            }),
+            whenTrueCommId: z.string().describe("Communication to send when the condition matches."),
+            whenFalseCommId: z.string().optional().describe("Communication to send when it doesn't match (omit to just continue to exit)."),
+            channels: z.array(z.enum(["email", "in_app_push", "mobile_push", "web_push"])).optional().describe("Channels for both send arms (default ['email'])."),
+        }),
+        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;
+                if (c.kind === "attribute") {
+                    if (!c.field_path || !c.operator) {
+                        return { content: [{ type: "text", text: `${APEX} An attribute condition needs field_path and operator.` }], isError: true };
+                    }
+                    predicate = {
+                        kind: "attribute",
+                        fieldPath: c.field_path,
+                        operator: c.operator,
+                        ...(c.value !== undefined ? { value: c.value } : {}),
+                    };
+                }
+                else {
+                    if (!c.event_name) {
+                        return { content: [{ type: "text", text: `${APEX} An event condition needs event_name.` }], isError: true };
+                    }
+                    predicate = {
+                        kind: c.kind,
+                        eventName: c.event_name,
+                        window: c.window_days ? { type: "last_n_days", days: c.window_days } : { type: "ever" },
+                    };
+                }
+                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 a branch.` }], isError: true };
+                }
+                const exitId = exit.id;
+                const channels = args.channels ?? ["email"];
+                const mkId = () => `step_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+                const trueId = mkId();
+                const trueStep = { id: trueId, type: "send", label: "Send (match)", commId: args.whenTrueCommId, commVersion: 1, channels, next: exitId };
+                const newSteps = [trueStep];
+                let defaultNext = exitId;
+                if (args.whenFalseCommId) {
+                    const falseId = mkId();
+                    newSteps.push({ id: falseId, type: "send", label: "Send (no match)", commId: args.whenFalseCommId, commVersion: 1, channels, next: exitId });
+                    defaultNext = falseId;
+                }
+                const branchId = mkId();
+                const branchStep = {
+                    id: branchId,
+                    type: "branch",
+                    label: "Branch",
+                    mode: "condition",
+                    conditions: [{ predicate, next: trueId }],
+                    defaultNext,
+                };
+                // Insert the branch before the exit: rewire whatever currently points
+                // to the exit so the branch sits in the linear flow. (newSteps aren't in
+                // `steps` yet, so this only matches the existing pre-exit step.)
+                const pre = steps.find((s) => s.next === exitId);
+                if (pre)
+                    pre.next = branchId;
+                steps.push(branchStep, ...newSteps);
+                const updated = await apiPatch(`/api/journeys/${encodeURIComponent(args.journeyId)}`, { steps });
+                if (!tenantOk(updated.workspaceKey))
+                    return tenantMismatch();
+                return { content: [{ type: "text", text: `${APEX} Added a conditional branch 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 };
+            }
+        },
+    },
+    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. 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, 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.
+            const warnText = (warnings) => {
+                const list = Array.isArray(warnings) ? warnings.filter((w) => w?.reason) : [];
+                if (list.length === 0)
+                    return "";
+                return (`\n\n${list.length} thing${list.length === 1 ? "" : "s"} we couldn't verify until it fires (preview with example data to check):\n` +
+                    list.map((w) => `  • ${w.reason}`).join("\n"));
+            };
+            if (!confirmLive) {
+                try {
+                    const dr = await apiPost(`${path}?dryRun=true`, {});
+                    return { content: [{ type: "text", text: `${APEX} Dry-run passed — journey ${journeyId} is valid and ready.${warnText(dr?.warnings)}\nRe-call with confirmLive:true to publish it to live customers.` }] };
+                }
+                catch (err) {
+                    // A variable-coverage block arrives here with a plain message like
+                    // "This send uses {{first_name}}, but the trigger doesn't provide it."
+                    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))
+                    return tenantMismatch();
+                return { content: [{ type: "text", text: `${APEX} Published journey ${journeyId} — it is now live on trigger events.${warnText(res?.warnings)} View it: ${journeyLink(journeyId)}` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
+    create_communication: {
+        description: `${APEX} — Create a blank custom communication (draft, no send path) you can reference from a journey send step. Distinct from generate_communications, which generates pre-written messages from catalog templates; use this when you need a net-new message (e.g. a cart-recovery email not in the catalog). audience_bucket defaults to production.`,
+        schema: z.object({
+            title: z.string().optional(),
+            channels: z.array(z.enum(["email", "in_app_push", "mobile_push"])).optional(),
+            audience_bucket: z
+                .enum(["production", "beta", "dev"])
+                .optional()
+                .describe("Who this send is for. Default production. Never All or Unclassified."),
+        }),
+        handler: async ({ title, channels, audience_bucket }) => {
+            try {
+                const comm = await apiPost("/api/communications/blank", { title, channels });
+                if (audience_bucket && audience_bucket !== "production") {
+                    await apiPatch(`/api/communications/${comm.id}`, { audienceBucket: audience_bucket });
+                }
+                if (!tenantOk(comm.workspaceKey))
+                    return tenantMismatch();
+                return { content: [{ type: "text", text: `${APEX} Created draft communication "${comm.title}" (id: ${comm.id}). Open it in the browser: ${appUrl(`/dashboard/communications/${comm.id}`)}\nEdit it (or edit_communication), then reference it from a journey send step.` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
+    list_journeys: {
+        description: `${APEX} — List every adaptive journey in the active workspace. Returns id, name, status (draft/published/paused/archived), and journey type (lifecycle/campaign). Foundation for exit-rule audit loops + journey CRUD agent flows.`,
+        schema: z.object({}),
+        handler: async () => {
+            const journeys = await apiGet("/api/journeys");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(journeys.map((j) => ({
+                            id: j.id,
+                            name: j.name,
+                            status: j.status,
+                            journey_type: j.journeyType ?? null,
+                            version: j.version,
+                            exit_rule_count: (j.exitEvents ?? []).length,
+                        })), null, 2),
+                    },
+                ],
+            };
+        },
+    },
+    get_journey: {
+        description: `${APEX} — Read the full configuration for a single journey, including steps, goal event, attribution window, and exit rules. Use after list_journeys to inspect a journey's wiring before recommending edits.`,
+        schema: z.object({
+            journeyId: z.string().describe("Journey id returned from list_journeys."),
+        }),
+        handler: async ({ journeyId }) => {
+            const journey = await apiGet(`/api/journeys/${encodeURIComponent(journeyId)}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(journey, null, 2),
+                    },
+                ],
+            };
+        },
+    },
+    // ─── Accounts (B2B-000 rollup + B2B-001 groups) ───────────────────────,
+    list_journey_exits: {
+        description: `${APEX} — Just the exit-rules block of one journey. Cheaper than get_journey for audit loops that only need to know "does this journey suppress purchase / unsubscribe?".`,
+        schema: z.object({
+            journeyId: z.string(),
+        }),
+        handler: async ({ journeyId }) => {
+            const body = await apiGet(`/api/journeys/${encodeURIComponent(journeyId)}/exit-rules`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(body.data ?? [], null, 2),
+                    },
+                ],
+            };
+        },
+    },
+    add_journey_exit: {
+        description: `${APEX} — Append a new exit rule to a journey's draft. Rule fires when the chosen trigger contract's event lands on a contact with an in-flight execution — Apex stops the execution and skips any pending sends. Re-publish required for the rule to take effect on live runs.`,
+        schema: z.object({
+            journeyId: z.string(),
+            triggerContractId: z
+                .string()
+                .describe("Trigger-contract id, e.g. trig-in-app-purchase"),
+            label: z.string().optional(),
+            enabled: z.boolean().optional().default(true),
+        }),
+        handler: async ({ journeyId, triggerContractId, label, enabled, }) => {
+            const body = await apiPost(`/api/journeys/${encodeURIComponent(journeyId)}/exit-rules`, {
+                triggerContractId,
+                ...(label !== undefined && { label }),
+                enabled: enabled !== false,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Added exit rule ${body.data.id} → ${body.data.triggerContractId}. Publish the journey for it to apply to new executions.`,
+                    },
+                ],
+            };
+        },
+    },
+    remove_journey_exit: {
+        description: `${APEX} — Remove an exit rule from a journey's draft. Re-publish required for the change to apply to live runs.`,
+        schema: z.object({
+            journeyId: z.string(),
+            ruleId: z.string(),
+        }),
+        handler: async ({ journeyId, ruleId, }) => {
+            await apiDelete(`/api/journeys/${encodeURIComponent(journeyId)}/exit-rules/${encodeURIComponent(ruleId)}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Removed exit rule ${ruleId} from journey ${journeyId}.`,
+                    },
+                ],
+            };
+        },
+    },
+    get_contact_cart: {
+        description: `${APEX} — Read the rolled-up cart state for a contact (Phase 2 of Journey Exit Semantics). Returns lines, itemCount, valueCents, and last-updated timestamp. Useful for "is this lead worth a follow-up?" agent loops.`,
+        schema: z.object({
+            contact_id: z.string(),
+        }),
+        handler: async ({ contact_id }) => {
+            const contact = await apiGet(`/api/contacts/${encodeURIComponent(contact_id)}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            contact_id: contact.id,
+                            email: contact.email ?? null,
+                            cart: contact.cart ?? null,
+                        }, null, 2),
+                    },
+                ],
+            };
+        },
+    },
+    audit_journey_exits: {
+        description: `${APEX} — Audit every published journey in the workspace for exit-rule hygiene. Flags marketing/lifecycle journeys (goalEventName=in_app_purchase) that don't have a purchase exit rule — the most common misconfiguration that produces "received the recovery push AFTER converting" complaints.`,
+        schema: z.object({}),
+        handler: async () => {
+            const journeys = await apiGet("/api/journeys");
+            const findings = [];
+            for (const j of journeys) {
+                if (j.status !== "published" && j.status !== "paused")
+                    continue;
+                const isMarketing = j.journeyType === "campaign" || j.journeyType === "lifecycle";
+                if (!isMarketing)
+                    continue;
+                const goalLooksLikePurchase = j.goalEventName === "in_app_purchase" ||
+                    j.goalEventName === "purchase";
+                if (!goalLooksLikePurchase)
+                    continue;
+                const hasPurchaseExit = (j.exitEvents ?? []).some((r) => r.enabled !== false &&
+                    (r.triggerContractId.includes("purchase") ||
+                        (r.label ?? "").toLowerCase().includes("purchase")));
+                if (!hasPurchaseExit) {
+                    findings.push({
+                        journey_id: j.id,
+                        name: j.name,
+                        recommendation: "Marketing journey with purchase goal but no purchase exit rule. Users who convert mid-journey will still receive later sends.",
+                    });
+                }
+            }
+            const text = findings.length === 0
+                ? "✓ All published marketing journeys with a purchase goal have a purchase exit rule wired."
+                : `# Exit-rule audit — ${findings.length} journey${findings.length === 1 ? "" : "s"} need attention\n\n${findings.map((f) => `- **${f.name}** (${f.journey_id}): ${f.recommendation}`).join("\n")}\n\nFix with: \`add_journey_exit\` for each journey using a purchase trigger contract.`;
+            return { content: [{ type: "text", text }] };
+        },
+    },
+    list_segments: {
+        description: `${APEX} — List the workspace's segments (saved groups of customers over your own events + traits).`,
+        schema: z.object({
+            scope: z.enum(["workspace", "org"]).optional().describe("Defaults to workspace"),
+        }),
+        handler: async (args) => {
+            const q = args.scope ? `?scope=${args.scope}` : "";
+            const data = await apiGet(`/api/segments${q}`);
+            return {
+                content: [{ type: "text", text: JSON.stringify(data ?? [], null, 2) }],
+            };
+        },
+    },
+    get_segment: {
+        description: `${APEX} — Fetch one segment by id.`,
+        schema: z.object({
+            segment_id: z.string().describe("The segment id"),
+            scope: z.enum(["workspace", "org"]).optional(),
+        }),
+        handler: async (args) => {
+            const q = args.scope ? `?scope=${args.scope}` : "";
+            const data = await apiGet(`/api/segments/${encodeURIComponent(args.segment_id)}${q}`);
+            return { content: [{ type: "text", text: JSON.stringify(data ?? null, null, 2) }] };
+        },
+    },
+    create_segment: {
+        description: `${APEX} — Create a segment from friendly "conditions" (compiled server-side) OR a raw predicate. Conditions grammar: match all|any of groups; each group match all|any of conditions; each condition is an event ({verb:"has"|"hasnt", event, window_days?}) or a trait ({attribute, op:"is"|"is_not"|"exists", value?}). This is the same grammar the dashboard chip builder speaks.`,
+        schema: z.object({
+            name: z.string().describe("Segment name"),
+            description: z.string().optional(),
+            scope: z.enum(["workspace", "org"]).optional().describe("Defaults to workspace"),
+            conditions: z
+                .object({
+                match: z.enum(["all", "any"]),
+                groups: z.array(z.object({
+                    match: z.enum(["all", "any"]),
+                    conditions: z.array(z.object({
+                        verb: z.enum(["has", "hasnt"]).optional(),
+                        event: z.string().optional(),
+                        window_days: z.number().optional(),
+                        attribute: z.string().optional(),
+                        op: z.enum(["is", "is_not", "exists"]).optional(),
+                        value: z.union([z.string(), z.number(), z.boolean()]).optional(),
+                    })),
+                })),
+            })
+                .optional()
+                .describe("Friendly conditions (preferred). Sub-keys are snake_case."),
+            predicate: z.record(z.string(), z.unknown()).optional().describe("Raw SegmentPredicate escape hatch"),
+        }),
+        handler: async (args) => {
+            const body = {
+                scope: args.scope ?? "workspace",
+                name: args.name,
+            };
+            if (args.description)
+                body.description = args.description;
+            if (args.predicate)
+                body.predicate = args.predicate;
+            else if (args.conditions)
+                body.conditions = args.conditions;
+            const data = await apiPost("/api/segments", body);
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        },
+    },
+};
+//# sourceMappingURL=letters.js.map