@apex-inc/mcp-server 0.9.14 → 0.11.0

package/dist/tools.js

@@ -51,6 +51,28 @@ function titleCaseEvent(event) {
         .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
         .join(" ");
 }
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Tenant echo (council CISO): never report a mutation as successful for a record
+ * outside the active workspace (guards a leaked/cross-workspace key).
+ */
+function tenantOk(workspaceKey) {
+    const active = getActiveWorkspace();
+    return !active || !workspaceKey || workspaceKey === active;
+}
+function tenantMismatch() {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `${APEX} Refusing to confirm: the affected record belongs to a different workspace.`,
+            },
+        ],
+        isError: true,
+    };
+}
 /**
  * Shared schema + handler for `switch_workspace` (canonical) and its
  * deprecated alias `switch_project`. Both register against the same handler
@@ -299,7 +321,13 @@ export const toolDefinitions = {
             beliefStatement: z.string().optional().describe("If you don't have a beliefId, pass the assumption statement and Apex will create the belief (and a hypothesis) and link them to this experiment."),
             beliefConfidence: z.number().min(0).max(100).optional().describe("Confidence (0-100%) for the belief created from beliefStatement. Defaults to 50."),
             hypothesisStatement: z.string().optional().describe("Optional hypothesis statement to record alongside a belief created from beliefStatement."),
-            primaryMetricEvent: z.string().optional().describe("Canonical event name the experiment optimizes, e.g. 'add_to_cart', 'checkout_completed', 'form_submit'. Validated against the workspace event spec."),
+            primaryMetricEvent: z.string().optional().describe("Canonical event name the experiment optimizes, e.g. 'add_to_cart', 'checkout_completed', 'form_submit'. Validated against the workspace event spec. Prefer an OUTCOME event (purchase/signup) over a proxy (email_open) — use list_metrics to see which are DETECTED with volume."),
+            primaryMetricType: z.enum(["rate", "count", "revenue", "duration"]).optional().describe("How the goal is measured. 'rate' (default) = did it happen. 'revenue'/'duration' = a continuous value summed per subject (set primaryMetricValueProperty). Use 'revenue' for Stripe/purchase-value goals."),
+            primaryMetricValueProperty: z.string().optional().describe("For revenue/duration goals: the event property to sum, e.g. 'value'. Defaults to 'value'."),
+            guardrailEvent: z.string().optional().describe("Canonical protective event for an EXTRA guardrail that must not regress (e.g. 'purchase_refunded', 'app_uninstall', 'js_error'). Apex already auto-protects revenue/refunds/errors by default — only pass this to add a test-specific harm signal. Use list_metrics({role:'guardrail'}) to see what's firing. Choose one ORTHOGONAL to the primary goal."),
+            guardrailType: z.enum(["rate", "revenue", "duration"]).optional().describe("How the guardrail is measured. 'rate' (default) = how often the harm event fires. 'revenue' = sum a value (e.g. refund $)."),
+            guardrailThreshold: z.number().optional().describe("Harm margin for the guardrail, RELATIVE (0.25 = flag a >25% rise). Defaults to 0.25."),
+            predictionMagnitude: z.string().optional().describe("Your committed prediction of the effect, e.g. '10% lift'. Recorded with 'agent' provenance and used for calibration. Required before the experiment can be ACTIVATED."),
             mode: z.enum(["sdk", "snippet"]).optional().describe("Experiment mode: 'sdk' for code-level (default via MCP), 'snippet' for runtime DOM"),
             surface: z.enum(["web", "mobile"]).optional().describe("The PROPERTY the experiment runs in (not the SDK used): 'web' (default) for a website, 'mobile' for a native / Capacitor / React-Native app. If the repo is a mobile app (has capacitor.config.* or @apex-inc/capacitor-plugin), set 'mobile' for ALL its experiments — even ones resolved via useApexVariant in the web layer — so they group under the app, not a website. This sets the dashboard data-source label (Website vs Mobile app)."),
             dataSourceId: z.string().optional().describe("Optional explicit Data Source (property) id this experiment runs in, e.g. 'ds_website' or 'ds_ios'. Usually inferred from surface; pass it to bind to a specific registered source. Tenant-validated server-side."),
@@ -349,13 +377,18 @@ export const toolDefinitions = {
                         isError: true,
                     };
                 }
+                const metricType = args.primaryMetricType ?? "rate";
+                const isValue = metricType === "revenue" || metricType === "duration";
+                const valueProperty = args.primaryMetricValueProperty ?? "value";
                 primaryMetric = {
-                    key: `${event}_rate`,
-                    label: `${titleCaseEvent(event)} rate`,
-                    type: "rate",
-                    unit: "%",
+                    key: `${event}_${metricType}`,
+                    label: `${titleCaseEvent(event)} ${metricType}`,
+                    type: metricType,
+                    unit: metricType === "revenue" ? "USD" : metricType === "duration" ? "s" : "%",
                     direction: "increase",
-                    source: { kind: "event", eventType: event },
+                    source: isValue
+                        ? { kind: "event", eventType: event, property: valueProperty }
+                        : { kind: "event", eventType: event },
                 };
             }
             if (isPreview) {
@@ -471,7 +504,14 @@ export const toolDefinitions = {
                 ...(args.dataSourceId ? { dataSourceId: args.dataSourceId } : {}),
                 ...(args.randomizationUnit ? { randomizationUnit: args.randomizationUnit } : {}),
                 hypothesis: resolvedHypothesis,
-                prediction: { direction: "increase", magnitude: "" },
+                // Agent-authored: tagged "agent" provenance so calibration attributes it
+                // correctly. When the agent supplies predictionMagnitude it satisfies the
+                // activation gate; an empty magnitude leaves the gate asking for one.
+                prediction: {
+                    direction: "increase",
+                    magnitude: args.predictionMagnitude?.trim() ?? "",
+                    provenance: "agent",
+                },
                 confidence: 50,
                 beliefId,
                 hypothesisId,
@@ -479,7 +519,31 @@ export const toolDefinitions = {
                 primaryMetric,
                 allocation: { strategy: "hash", weights: { control: controlW, variant_b: 1 - controlW } },
                 secondaryMetrics: [],
-                guardrailMetrics: [],
+                // Explicit EXTRA guardrail when the agent named one (orthogonal to the
+                // goal). When omitted, the server auto-attaches the conversion-model
+                // vital signs ("protected by default").
+                ...(args.guardrailEvent
+                    ? {
+                        guardrailMetrics: [
+                            (() => {
+                                const gType = args.guardrailType ?? "rate";
+                                const isValue = gType === "revenue" || gType === "duration";
+                                return {
+                                    key: `${args.guardrailEvent}_${gType}`,
+                                    label: `${titleCaseEvent(args.guardrailEvent)} ${gType === "rate" ? "rate" : gType}`,
+                                    type: gType,
+                                    unit: gType === "revenue" ? "USD" : gType === "duration" ? "s" : "%",
+                                    direction: "decrease",
+                                    source: isValue
+                                        ? { kind: "event", eventType: args.guardrailEvent, property: "value" }
+                                        : { kind: "event", eventType: args.guardrailEvent },
+                                    guardrailThreshold: args.guardrailThreshold ?? 0.25,
+                                    thresholdKind: "relative",
+                                };
+                            })(),
+                        ],
+                    }
+                    : {}),
                 attributionWindow: { unit: "hours", value: 24, startFrom: "first_interaction" },
                 variants,
             });
@@ -547,6 +611,19 @@ export const toolDefinitions = {
                 `9. Call track_deployment with the experiment ID and commit SHA`,
                 `10. Call verify_experiment_wiring, then activate_experiment once both arms report exposures`,
             ];
+            // Autonomous-agent activation policy (Phase 6): the experiment is created
+            // as a DRAFT. Activating it spends metered usage and exposes real users,
+            // so an agent must NOT auto-activate — surface the cost and get explicit
+            // human approval first. The server's activation gate also independently
+            // requires the full spine (measurable goal + guardrail + prediction).
+            const activationPolicy = [
+                "",
+                "ACTIVATION POLICY — do not auto-activate:",
+                "- This experiment is a DRAFT. It is NOT collecting data yet.",
+                "- Activating meters usage (one billable event per variant assignment) and shows variants to real users.",
+                "- Before calling activate_experiment, tell the user the expected metered volume and get their explicit go-ahead.",
+                "- Activation also requires a measurable primary goal, a guardrail, and a committed prediction (the server enforces this). If you didn't pass predictionMagnitude, add one first.",
+            ];
             const recipe = {
                 _apex: true,
                 _type: "experiment_created",
@@ -583,14 +660,15 @@ export const toolDefinitions = {
                     ? groundingGuidance
                         .concat(isMobile ? mobileSteps : webSteps)
                         .concat(styleGuidance)
+                        .concat(activationPolicy)
                         .join("\n")
                     : groundingGuidance
                         .concat([
                         "SNIPPET MODE — no code changes needed.",
                         "The experiment will be applied via the Apex snippet at runtime.",
                         `Preview: ${previewUrl}`,
-                        "Ask the user to activate when ready.",
                     ])
+                        .concat(activationPolicy)
                         .join("\n"),
             };
             return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
@@ -1051,6 +1129,270 @@ export const toolDefinitions = {
             };
         },
     },
+    list_beliefs: {
+        description: `${APEX} — List the workspace's beliefs (the assumptions experiments test). Shows confidence, validation state, and AI-generated provenance so you can LINK an existing belief instead of minting a duplicate.`,
+        schema: z.object({
+            query: z
+                .string()
+                .optional()
+                .describe("Filter beliefs by a keyword in the statement"),
+        }),
+        handler: async ({ query }) => {
+            const beliefs = await apiGet("/api/beliefs");
+            const q = query?.toLowerCase().trim();
+            const filtered = q
+                ? beliefs.filter((b) => b.statement.toLowerCase().includes(q))
+                : beliefs;
+            if (filtered.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No beliefs${q ? ` matching "${query}"` : ""} yet. You can generate one from a hypothesis when creating an experiment.`,
+                        },
+                    ],
+                };
+            }
+            const lines = filtered
+                .slice(0, 50)
+                .map((b) => {
+                const tags = [
+                    `${Math.round(b.confidence * 100)}% confidence`,
+                    b.validationState === "unvalidated" ? "unvalidated" : null,
+                    b.generatedFromExperimentId ? "AI-generated" : null,
+                ]
+                    .filter(Boolean)
+                    .join(", ");
+                return `  • [${b.id}] ${b.statement} (${tags})`;
+            })
+                .join("\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Beliefs (${filtered.length})`,
+                            `${"═".repeat(40)}`,
+                            lines,
+                            ``,
+                            `Link one to a new experiment with its id, or generate a fresh belief from your hypothesis.`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    list_metrics: {
+        description: `${APEX} — List the canonical metric/goal catalog for this workspace: typed metrics (rate/revenue/duration) with whether each is DETECTED (firing, with volume) and its outcome tier. Use this to pick a measurable OUTCOME goal (purchase/signup) over a proxy (email_open) before create_experiment, or role:'guardrail' to see protective harm signals.`,
+        schema: z.object({
+            onlyMeasurable: z
+                .boolean()
+                .optional()
+                .describe("Only return metrics the engine can estimate today (default true)."),
+            role: z
+                .enum(["goal", "guardrail"])
+                .optional()
+                .describe("Filter to goal metrics (optimize) or guardrail metrics (protect against harm)."),
+        }),
+        handler: async ({ onlyMeasurable, role }) => {
+            const res = await apiGet(role ? `/api/metrics/catalog?role=${role}` : "/api/metrics/catalog");
+            const all = res.data ?? [];
+            const list = (onlyMeasurable === false ? all : all.filter((m) => m.measurable)).slice(0, 60);
+            if (list.length === 0) {
+                return {
+                    content: [{ type: "text", text: `${APEX} No metrics in the catalog yet.` }],
+                };
+            }
+            const lines = list
+                .map((m) => {
+                const tags = [
+                    m.type,
+                    m.outcomeTier === "proximal" ? "proxy" : m.outcomeTier,
+                    m.wired === "detected"
+                        ? `DETECTED${m.trailingVolume ? ` (${m.trailingVolume})` : ""}`
+                        : "not firing",
+                    m.measurable ? null : "not measurable",
+                ]
+                    .filter(Boolean)
+                    .join(", ");
+                return `  • ${m.key} — ${m.label} (${tags})`;
+            })
+                .join("\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Metric catalog (${list.length})`,
+                            `${"═".repeat(40)}`,
+                            lines,
+                            ``,
+                            `Prefer a DETECTED outcome metric. Pass its event to create_experiment as primaryMetricEvent (+ primaryMetricType 'revenue' for value goals).`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
+    update_experiment: {
+        description: `${APEX} — Edit an EXISTING experiment. Editability is gated by lifecycle: a DRAFT (with no exposures yet) is fully editable; once it has data or is running, the pre-registration (hypothesis, metric, guardrails) and bucketing (surface, variants) freeze and edits return a clear "experiment_locked" reason. After freeze, fork_experiment instead. Use this to fix a mislabeled surface or correct a draft before launch.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment id to edit."),
+            name: z.string().optional().describe("Rename (cosmetic; editable anytime)."),
+            surface: z.enum(["web", "mobile"]).optional().describe("Correct the surface — editable only on a draft with 0 exposures (web↔mobile)."),
+            hypothesis: z.string().optional().describe("Edit the hypothesis — draft only (pre-registration)."),
+            primaryMetricEvent: z.string().optional().describe("Change the primary metric's canonical event — draft only."),
+            primaryMetricType: z.enum(["rate", "count", "revenue", "duration"]).optional(),
+            guardrailEvent: z.string().optional().describe("Replace the guardrail with this canonical protective event — draft only."),
+        }),
+        handler: async (args) => {
+            const body = { id: args.experimentId };
+            if (args.name !== undefined)
+                body.name = args.name;
+            if (args.surface !== undefined)
+                body.surface = args.surface;
+            if (args.hypothesis !== undefined)
+                body.hypothesis = args.hypothesis;
+            if (args.primaryMetricEvent) {
+                const t = args.primaryMetricType ?? "rate";
+                const isValue = t === "revenue" || t === "duration";
+                body.primaryMetric = {
+                    key: `${args.primaryMetricEvent}_${t}`,
+                    label: titleCaseEvent(args.primaryMetricEvent),
+                    type: t,
+                    unit: t === "revenue" ? "USD" : t === "duration" ? "s" : "%",
+                    direction: "increase",
+                    source: isValue
+                        ? { kind: "event", eventType: args.primaryMetricEvent, property: "value" }
+                        : { kind: "event", eventType: args.primaryMetricEvent },
+                };
+            }
+            if (args.guardrailEvent) {
+                body.guardrailMetrics = [
+                    {
+                        key: `${args.guardrailEvent}_rate`,
+                        label: `${titleCaseEvent(args.guardrailEvent)} rate`,
+                        type: "rate",
+                        unit: "%",
+                        direction: "decrease",
+                        source: { kind: "event", eventType: args.guardrailEvent },
+                        guardrailThreshold: 0.25,
+                        thresholdKind: "relative",
+                    },
+                ];
+            }
+            try {
+                const updated = await apiPatch("/api/experiments", body);
+                // Tenant echo: never report success for a record outside the active workspace.
+                const active = getActiveWorkspace();
+                if (active && updated.workspaceKey && updated.workspaceKey !== active) {
+                    return {
+                        content: [{ type: "text", text: `${APEX} Refusing to confirm: the updated record belongs to a different workspace.` }],
+                        isError: true,
+                    };
+                }
+                const applied = Object.keys(body).filter((k) => k !== "id");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} Updated "${updated.name}" (${updated.surface}, ${updated.status}). Applied: ${applied.join(", ") || "nothing"}.`,
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                // Surface the lock reason verbatim (409 experiment_locked etc.).
+                return {
+                    content: [{ type: "text", text: `${APEX} ${err instanceof Error ? err.message : String(err)}` }],
+                    isError: true,
+                };
+            }
+        },
+    },
+    fork_experiment: {
+        description: `${APEX} — Duplicate a frozen experiment's design into a fresh editable DRAFT. Use this after update_experiment reports "experiment_locked" (running or has exposures). The fork carries NO data (no results, assignments, or winner) and records its lineage; edit it freely, then activate.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment id to fork."),
+        }),
+        handler: async ({ experimentId }) => {
+            try {
+                const forked = await apiPost(`/api/experiments/${encodeURIComponent(experimentId)}/fork`, {});
+                const active = getActiveWorkspace();
+                if (active && forked.workspaceKey && forked.workspaceKey !== active) {
+                    return {
+                        content: [{ type: "text", text: `${APEX} Refusing to confirm: the fork belongs to a different workspace.` }],
+                        isError: true,
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} Forked into a fresh draft "${forked.name}" (id: ${forked.id}). Edit it with update_experiment, then activate.`,
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: `${APEX} ${err instanceof Error ? err.message : String(err)}` }],
+                    isError: true,
+                };
+            }
+        },
+    },
+    get_growth_reality: {
+        description: `${APEX} — "Is our growth real?" Per goal, the cumulative lift of everything Apex did (journeys + experiments) vs a persistent do-nothing global holdout, with a 95% CI. The honest, holdout-gated answer to "would this have happened anyway?" Forward-only; goals still collecting are flagged, not faked.`,
+        schema: z.object({
+            days: z
+                .union([z.number(), z.literal("all")])
+                .optional()
+                .describe("Trailing window in days, or 'all' for since-inception (default)."),
+        }),
+        handler: async ({ days }) => {
+            const q = days && days !== "all" ? `?days=${days}` : "?days=all";
+            const res = await apiGet(`/api/growth/reality${q}`);
+            const goals = res.data?.goals ?? [];
+            if (goals.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${APEX} No growth-reality data yet. Counting is forward-only from when the global holdout went live — check back once exposed + holdout cohorts are flowing.`,
+                        },
+                    ],
+                };
+            }
+            const pctFmt = (v) => v == null ? "—" : `${v > 0 ? "+" : ""}${(v * 100).toFixed(1)}%`;
+            const lines = goals.map((g) => {
+                if (!g.isDecisive) {
+                    return `  • ${g.goalName}: COLLECTING (directional ${pctFmt(g.lift)}, since ${g.collectingSince || "—"})`;
+                }
+                const ci = g.liftCI
+                    ? ` [${pctFmt(g.liftCI.lower)}, ${pctFmt(g.liftCI.upper)}]`
+                    : "";
+                const rev = typeof g.incrementalRevenue === "number"
+                    ? ` · ~$${Math.round(g.incrementalRevenue).toLocaleString()} incremental`
+                    : "";
+                return `  • ${g.goalName}: ${pctFmt(g.lift)} vs holdout${ci} — DECISIVE${rev}`;
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `${APEX} Is our growth real? (vs ${res.data?.holdoutPct ?? 5}% do-nothing holdout)`,
+                            `${"═".repeat(40)}`,
+                            ...lines,
+                            ``,
+                            `Decisive = both cohorts cleared the minimum size AND the CI excludes zero. Everything else is directional, not proven.`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        },
+    },
     suggest_experiment: {
         description: `${APEX} — Get smart experiment suggestions based on context. Analyzes your assumptions, past experiments, and confidence gaps to recommend what to test next.`,
         schema: z.object({
@@ -2326,6 +2668,143 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
     // 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.`,
+        schema: z.object({ name: z.string().optional().describe("Journey name (default 'Untitled journey').") }),
+        handler: async ({ name }) => {
+            try {
+                const j = await apiPost("/api/journeys/blank", { name });
+                if (!tenantOk(j.workspaceKey))
+                    return tenantMismatch();
+                return { content: [{ type: "text", text: `${APEX} Created draft journey "${j.name}" (id: ${j.id}). Next: 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}. Review its steps with get_journey, then publish_journey.` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
+    set_journey_trigger: {
+        description: `${APEX} — Set the entry trigger (the event that enrolls subjects) on a draft journey's trigger step. Pass a triggerContractId (a blank journey seeds the starter contracts; get_journey shows the current value).`,
+        schema: z.object({
+            journeyId: z.string(),
+            triggerContractId: z.string().describe("The trigger contract id (event binding) to enroll on."),
+        }),
+        handler: async ({ journeyId, triggerContractId }) => {
+            try {
+                const j = await apiGet(`/api/journeys/${encodeURIComponent(journeyId)}`);
+                const steps = (j.steps ?? []).map((s) => s.type === "trigger" ? { ...s, trigger: { type: "event", triggerContractId } } : s);
+                const updated = await apiPatch(`/api/journeys/${encodeURIComponent(journeyId)}`, { steps });
+                if (!tenantOk(updated.workspaceKey))
+                    return tenantMismatch();
+                return { content: [{ type: "text", text: `${APEX} Trigger set to contract ${triggerContractId} on journey ${journeyId}.` }] };
+            }
+            catch (err) {
+                return { content: [{ type: "text", text: `${APEX} ${errMsg(err)}` }], isError: true };
+            }
+        },
+    },
+    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.`,
+        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)."),
+            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", "mobile_push", "web_push"])).optional().describe("send only: channels to fire (default ['email'])."),
+        }),
+        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 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 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);
+                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}.` }] };
+            }
+            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.`,
+        schema: z.object({
+            journeyId: z.string(),
+            confirmLive: z.boolean().optional().describe("Set true to publish for real. Omitted/false = dry-run validation only."),
+        }),
+        handler: async ({ journeyId, confirmLive }) => {
+            const path = `/api/journeys/${encodeURIComponent(journeyId)}/publish`;
+            if (!confirmLive) {
+                try {
+                    await apiPost(`${path}?dryRun=true`, {});
+                    return { content: [{ type: "text", text: `${APEX} Dry-run passed — journey ${journeyId} is valid and ready. Re-call with confirmLive:true to publish it to live customers.` }] };
+                }
+                catch (err) {
+                    return { content: [{ type: "text", text: `${APEX} Dry-run found a problem before publishing: ${errMsg(err)}` }], isError: true };
+                }
+            }
+            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.` }] };
+            }
+            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).`,
+        schema: z.object({
+            title: z.string().optional(),
+            channels: z.array(z.enum(["email", "in_app_push", "mobile_push"])).optional(),
+        }),
+        handler: async ({ title, channels }) => {
+            try {
+                const comm = await apiPost("/api/communications/blank", { title, channels });
+                if (!tenantOk(comm.workspaceKey))
+                    return tenantMismatch();
+                return { content: [{ type: "text", text: `${APEX} Created draft communication "${comm.title}" (id: ${comm.id}). Edit it with 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({}),
@@ -2635,8 +3114,8 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             const readyTemplates = d.templates.filter((t) => t.ready);
             const blockedTemplates = d.templates.filter((t) => !t.ready);
             const templateLines = [
-                ...readyTemplates.map((t) => `- ✅ ${t.title} (${t.templateKind}) — Ready to run`),
-                ...blockedTemplates.slice(0, 10).map((t) => `- ⏳ ${t.title} (${t.templateKind}) — needs ${[...t.missingEvents, ...t.missingTraits].join(", ") || "?"}`),
+                ...readyTemplates.map((t) => `- ✅ ${t.title} (${t.templateKind}, id: ${t.templateId}) — Ready to run${t.templateKind === "journey" ? ` → create_journey_from_template({ templateId: "${t.templateId}" })` : ""}`),
+                ...blockedTemplates.slice(0, 10).map((t) => `- ⏳ ${t.title} (${t.templateKind}, id: ${t.templateId}) — needs ${[...t.missingEvents, ...t.missingTraits].join(", ") || "?"}`),
             ];
             const milestones = [
                 d.milestones.firstEventAt ? `First event: ${d.milestones.firstEventAt}` : "First event: not yet",