@apex-inc/mcp-server 0.9.9 → 0.9.11

package/dist/tools.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { apiGet, apiPost, apiPatch, apiDelete, postWithIdempotency, setActiveWorkspace, getActiveWorkspace, setActiveOrg, getActiveOrg, getUserContext } from "./api-client.js";
+import { resolveExperimentHypothesis } from "./experiment-copy.js";
 const APEX = "∧ Apex";
 /**
  * MOBX-006 — stable synthetic visitor id for agent-fired events.
@@ -273,11 +274,13 @@ export const toolDefinitions = {
             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."),
             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("Where the experiment runs: 'web' (default) for websites and web apps, 'mobile' for native / Capacitor apps. This sets the dashboard's data-source label (Website vs iOS App) — pick 'mobile' for a Capacitor/React-Native/native app so it isn't mislabeled as a website."),
             preview: z.boolean().optional().describe("If true, returns a preview without creating. Default: true."),
         }),
         handler: async (args) => {
             const split = args.trafficSplit ?? 50;
             const mode = args.mode ?? "sdk";
+            const experimentSurface = args.surface ?? "web";
             const isPreview = args.preview !== false;
             // p1-metric — resolve the primary metric. Defaults to the form_submit
             // conversion metric; an explicit primaryMetricEvent is validated against
@@ -331,6 +334,7 @@ export const toolDefinitions = {
                     _apex: true,
                     _type: "experiment_preview",
                     name: args.name,
+                    surface: experimentSurface,
                     targetUrl: args.targetUrl,
                     targetAnchor: args.targetAnchor || null,
                     targetComponent: args.targetComponent || null,
@@ -342,7 +346,7 @@ export const toolDefinitions = {
                     beliefId: args.beliefId || null,
                     beliefStatement: args.beliefStatement || null,
                     predictionId: args.predictionId || null,
-                    _instructions: "Present this as a summary and ask the user to confirm (1), adjust (2), or cancel (3). Do NOT create the experiment until confirmed.",
+                    _instructions: "Before proposing variant copy, ground every factual claim in .apex/brand-truth.md (read it; cite the line each claim traces to; if a claim isn't backed there, ask the user instead of inventing it). Then present this as a summary and ask the user to confirm (1), adjust (2), or cancel (3). Do NOT create the experiment until confirmed.",
                 };
                 return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
             }
@@ -369,33 +373,44 @@ export const toolDefinitions = {
                 });
                 hypothesisId = h.id;
             }
+            // The API requires a non-empty hypothesis on the experiment record
+            // (validate-create rejects ""). Resolve one (explicit or derived).
+            const resolvedHypothesis = resolveExperimentHypothesis(args.hypothesisStatement, args.name, primaryMetric.label);
             const controlW = split / 100;
-            const exp = await apiPost("/api/experiments", {
-                surface: "web",
-                name: args.name,
-                targetUrl: args.targetUrl,
-                targetAnchor: args.targetAnchor,
-                createdFrom: "cursor",
-                status: "draft",
-                hypothesis: "",
-                prediction: { direction: "increase", magnitude: "" },
-                confidence: 50,
-                beliefId,
-                hypothesisId,
-                predictionId: args.predictionId,
-                primaryMetric,
-                allocation: { strategy: "hash", weights: { control: controlW, variant_b: 1 - controlW } },
-                secondaryMetrics: [],
-                guardrailMetrics: [],
-                attributionWindow: { unit: "hours", value: 24, startFrom: "first_interaction" },
-                variants: [
+            const createdAtIso = new Date().toISOString();
+            // Variants must match the experiment surface (validate-create enforces
+            // this). Web arms carry DOMChange[]; mobile arms carry a JSON payload the
+            // app reads via Apex.getVariant(). Mislabeling a Capacitor app as web is
+            // exactly the bug this fixes.
+            const variants = experimentSurface === "mobile"
+                ? [
+                    {
+                        id: "v_control",
+                        key: "control",
+                        label: "Control",
+                        surface: "mobile",
+                        createdAt: createdAtIso,
+                        description: "Original content",
+                        payload: { content: args.controlContent },
+                    },
+                    {
+                        id: "v_b",
+                        key: "variant_b",
+                        label: "Variant B",
+                        surface: "mobile",
+                        createdAt: createdAtIso,
+                        description: "Modified content",
+                        payload: { content: args.variantContent },
+                    },
+                ]
+                : [
                     {
                         id: "v_control",
                         key: "control",
                         label: "Control",
                         surface: "web",
                         mode,
-                        createdAt: new Date().toISOString(),
+                        createdAt: createdAtIso,
                         description: "Original content",
                         changes: [],
                     },
@@ -405,7 +420,7 @@ export const toolDefinitions = {
                         label: "Variant B",
                         surface: "web",
                         mode,
-                        createdAt: new Date().toISOString(),
+                        createdAt: createdAtIso,
                         description: "Modified content",
                         changes: [
                             {
@@ -416,7 +431,26 @@ export const toolDefinitions = {
                             },
                         ],
                     },
-                ],
+                ];
+            const exp = await apiPost("/api/experiments", {
+                surface: experimentSurface,
+                name: args.name,
+                targetUrl: args.targetUrl,
+                targetAnchor: args.targetAnchor,
+                createdFrom: "cursor",
+                status: "draft",
+                hypothesis: resolvedHypothesis,
+                prediction: { direction: "increase", magnitude: "" },
+                confidence: 50,
+                beliefId,
+                hypothesisId,
+                predictionId: args.predictionId,
+                primaryMetric,
+                allocation: { strategy: "hash", weights: { control: controlW, variant_b: 1 - controlW } },
+                secondaryMetrics: [],
+                guardrailMetrics: [],
+                attributionWindow: { unit: "hours", value: 24, startFrom: "first_interaction" },
+                variants,
             });
             let previewUrl = "";
             try {
@@ -428,11 +462,66 @@ export const toolDefinitions = {
                 previewUrl = vu.toString();
             }
             catch { /* non-critical */ }
+            const isMobile = experimentSurface === "mobile";
+            // Grounding guidance — prepended to every recipe. The agent must write
+            // variant copy against the merchant's brand-truth file, not invent
+            // claims (the 2026-06-15 "free shipping on every order" incident, where
+            // the app actually charges $8 under $100).
+            const groundingGuidance = [
+                "GROUND THE COPY — do this BEFORE writing any variant text:",
+                "- Read .apex/brand-truth.md, .apex/brand-voice.md, and .apex/lexicon.md if they exist in the repo.",
+                "- Every factual claim in the variant copy MUST trace to a specific line in .apex/brand-truth.md. State which line each claim comes from. If a claim isn't backed there, ASK the user — do NOT invent it.",
+                "- If .apex/brand-truth.md is missing, scaffold the guardrails first (Apex → Set up Apex → Intelligence → \"Set up experiment guardrails\"), then ask the user to fill in the facts before writing copy.",
+                "",
+            ];
+            // Style/visual-change guidance — appended to every SDK recipe. The
+            // classic failure (QA 2026-06-15): a `bg-black` class collided with
+            // `bg-primary` because the codebase's cn() doesn't tailwind-merge, so
+            // both arms rendered identical and the test measured nothing.
+            const styleGuidance = [
+                "",
+                "VISUAL / STYLE CHANGES — read before editing:",
+                "- If the change is visual (color, size, layout), a variant that renders identical to control measures NOTHING. Always visually diff the two arms (screenshot both) before activating.",
+                "- Do NOT rely on a utility CLASS to override an existing one unless the codebase uses tailwind-merge. Plain className concatenation keeps BOTH classes (e.g. `bg-primary` + `bg-black`) and the original usually wins. Prefer an inline `style={{...}}` override or a class with guaranteed precedence.",
+                "- Change exactly ONE thing (the variable under test); keep everything else identical to control.",
+            ];
+            const webSteps = [
+                "IMPLEMENT THE EXPERIMENT IN CODE (web):",
+                `1. Open the target file${args.targetComponent ? ` (${args.targetComponent})` : ""}`,
+                `2. Install the hook package: npm i @apex-inc/react`,
+                `3. Add: import { useApexVariant } from "@apex-inc/react"`,
+                `4. In the component, add: const variant = useApexVariant("${exp.id}")  // fires experiment_exposure automatically`,
+                `5. Wrap the target content in a conditional (fall back to control on null/error):`,
+                `   {variant === "variant_b" ? <VARIANT_CONTENT> : <CONTROL_CONTENT>}`,
+                `6. Screenshots for the dashboard:`,
+                `   - Public web page: Apex auto-captures on create — nothing to do.`,
+                `   - localhost / auth-gated: capture BOTH arms, then call attach_experiment_asset({experimentId, variantKey, imageBase64}).`,
+                `7. Show the user the diff and ask them to preview at: ${previewUrl}`,
+                `8. After preview approval, commit and push`,
+                `9. Call track_deployment with the experiment ID and commit SHA`,
+                `10. Call verify_experiment_wiring, then activate_experiment once both arms report exposures`,
+            ];
+            const mobileSteps = [
+                "IMPLEMENT THE EXPERIMENT IN CODE (mobile / Capacitor):",
+                `1. Open the target screen${args.targetComponent ? ` (${args.targetComponent})` : ""}`,
+                `2. Install the plugin: npm i @apex-inc/capacitor-plugin`,
+                `3. Add: import { Apex } from "@apex-inc/capacitor-plugin"`,
+                `4. Resolve the variant: const { value: variant } = await Apex.getVariant({ experimentId: "${exp.id}" })  // fires experiment_exposure automatically`,
+                `5. Render conditionally (fall back to control on null/error): variant === "variant_b" ? <VARIANT> : <CONTROL>`,
+                `6. Screenshot both arms — add ONE debug-gated line on the screen that renders the variant, keyed to the resolved variant so it fires once the arm is on-screen:`,
+                `       useEffect(() => { if (variant) Apex.captureVariantScreenshot({ experimentId: "${exp.id}", variantKey: variant }); }, [variant]);`,
+                `   It is debug-gated (init Apex with debug:true) — a no-op in production, so real users are never screenshotted.`,
+                `7. Show the user the diff and a side-by-side of both arms`,
+                `8. After approval, commit and push`,
+                `9. Call track_deployment with the experiment ID and commit SHA`,
+                `10. Call verify_experiment_wiring, then activate_experiment once both arms report exposures`,
+            ];
             const recipe = {
                 _apex: true,
                 _type: "experiment_created",
                 experimentId: exp.id,
                 name: exp.name,
+                surface: experimentSurface,
                 status: exp.status,
                 mode,
                 primaryMetric: primaryMetric.key,
@@ -440,9 +529,17 @@ export const toolDefinitions = {
                 hypothesisId: hypothesisId || null,
                 predictionId: args.predictionId || null,
                 sdk: mode === "sdk" ? {
-                    hook: "useApexVariant",
-                    import: "@apex-inc/react",
-                    install: "npm i @apex-inc/react",
+                    ...(isMobile
+                        ? {
+                            method: "Apex.getVariant",
+                            import: "@apex-inc/capacitor-plugin",
+                            install: "npm i @apex-inc/capacitor-plugin",
+                        }
+                        : {
+                            hook: "useApexVariant",
+                            import: "@apex-inc/react",
+                            install: "npm i @apex-inc/react",
+                        }),
                     experimentId: exp.id,
                     targetComponent: args.targetComponent || null,
                     targetAnchor: args.targetAnchor || null,
@@ -452,25 +549,18 @@ export const toolDefinitions = {
                 previewUrl,
                 trafficSplit: { control: split, variant: 100 - split },
                 _instructions: mode === "sdk"
-                    ? [
-                        "IMPLEMENT THE EXPERIMENT IN CODE:",
-                        `1. Open the target file${args.targetComponent ? ` (${args.targetComponent})` : ""}`,
-                        `2. Install the hook package: npm i @apex-inc/react`,
-                        `3. Add: import { useApexVariant } from "@apex-inc/react"`,
-                        `4. In the component, add: const variant = useApexVariant("${exp.id}")`,
-                        `5. Wrap the target content in a conditional:`,
-                        `   {variant === "variant_b" ? <VARIANT_CONTENT> : <CONTROL_CONTENT>}`,
-                        `6. Show the user the diff and ask them to preview at: ${previewUrl}`,
-                        `7. After preview approval, commit and push`,
-                        `8. Call track_deployment with the experiment ID and commit SHA`,
-                        `9. Call activate_experiment after deployment confirms`,
-                    ].join("\n")
-                    : [
+                    ? groundingGuidance
+                        .concat(isMobile ? mobileSteps : webSteps)
+                        .concat(styleGuidance)
+                        .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.",
-                    ].join("\n"),
+                    ])
+                        .join("\n"),
             };
             return { content: [{ type: "text", text: JSON.stringify(recipe, null, 2) }] };
         },
@@ -2590,5 +2680,366 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             };
         },
     },
+    // ─── Graduation Pipeline — Engineering Links (Wave 2) ─────────────────
+    link_experiment: {
+        description: `${APEX} — Link an experiment to a GitHub pull request or issue. The link is what auto-starts the experiment when the PR merges. The convention "apex/exp_XXX" in your PR title also auto-links, but call this explicitly to be sure.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID to link"),
+            system: z
+                .enum(["github", "github-issues", "linear", "jira", "trello"])
+                .describe("Which dev tool the work item lives in (github for PRs)"),
+            kind: z.enum(["pr", "issue"]).describe("Pull request or issue/ticket"),
+            repo: z
+                .string()
+                .optional()
+                .describe('"owner/repo" slug for GitHub links'),
+            externalId: z
+                .string()
+                .describe("PR number or issue number (e.g. 482)"),
+            url: z.string().url().optional().describe("Canonical URL of the work item"),
+        }),
+        handler: async (args) => {
+            const res = await apiPost(`/api/experiments/${encodeURIComponent(args.experimentId)}/links`, {
+                system: args.system,
+                kind: args.kind,
+                repo: args.repo,
+                externalId: args.externalId,
+                url: args.url,
+            });
+            const text = res.data
+                ? `Linked experiment ${args.experimentId} to ${args.system} ${args.kind} ${args.repo ?? ""}#${args.externalId}.\n${res.data.url}`
+                : `Could not link: ${res.error ?? "unknown error"}`;
+            return { content: [{ type: "text", text }] };
+        },
+    },
+    unlink_experiment: {
+        description: `${APEX} — Remove an Engineering Link from an experiment.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+            linkId: z
+                .string()
+                .describe('The link id, or "{system}#{externalId}" (e.g. github#482)'),
+        }),
+        handler: async ({ experimentId, linkId }) => {
+            await apiDelete(`/api/experiments/${encodeURIComponent(experimentId)}/links/${encodeURIComponent(linkId)}`);
+            return {
+                content: [
+                    { type: "text", text: `Unlinked ${linkId} from experiment ${experimentId}.` },
+                ],
+            };
+        },
+    },
+    // ─── Apex Developer CLI (Wave 6.5) — IDE debugging helpers ───────────
+    apex_test_event: {
+        description: `${APEX} — Send a test event through the public ingestion endpoint and confirm it was accepted. The fastest way to verify event tracking works after installing the SDK.`,
+        schema: z.object({
+            eventName: z.string().describe("Event name, e.g. signup_completed"),
+            attributes: z.record(z.unknown()).optional().describe("Event attributes"),
+            visitorId: z.string().optional().describe("Visitor id (default a test id)"),
+        }),
+        handler: async (args) => {
+            const workspaceKey = getActiveWorkspace();
+            if (!workspaceKey) {
+                return { content: [{ type: "text", text: "No active workspace. Run /apex-login or set APEX_PROJECT_KEY." }] };
+            }
+            const visitorId = args.visitorId ?? `test-${Date.now()}`;
+            const res = await apiPost("/api/events", {
+                workspaceKey,
+                type: args.eventName,
+                visitorId,
+                timestamp: new Date().toISOString(),
+                data: { ...(args.attributes ?? {}), endUserId: visitorId },
+            });
+            const text = res.eventId
+                ? `Test event "${args.eventName}" accepted (id ${res.eventId}). It's flowing into ${workspaceKey}.`
+                : `Event rejected: ${res.error ?? "unknown error"}`;
+            return { content: [{ type: "text", text }] };
+        },
+    },
+    apex_recent_events: {
+        description: `${APEX} — List recent events for the workspace (optionally filtered by type). Use to debug SDK wiring without opening the dashboard.`,
+        schema: z.object({
+            type: z.string().optional().describe("Filter by event type"),
+            sinceMinutes: z.number().optional().describe("Lookback window in minutes (default 60)"),
+        }),
+        handler: async (args) => {
+            const qs = new URLSearchParams();
+            if (args.type)
+                qs.set("type", args.type);
+            qs.set("sinceMinutes", String(args.sinceMinutes ?? 60));
+            const res = await apiGet(`/api/events/stream?${qs.toString()}`);
+            const events = res.events ?? [];
+            if (events.length === 0) {
+                return { content: [{ type: "text", text: "No recent events in that window." }] };
+            }
+            const lines = events.slice(0, 25).map((e) => `- ${e.timestamp} ${e.type}${e.visitorId ? ` (${e.visitorId})` : ""}`);
+            return { content: [{ type: "text", text: `# Recent events\n${lines.join("\n")}` }] };
+        },
+    },
+    apex_health: {
+        description: `${APEX} — One-shot health check of every connected integration (last sync, status). Use before adding a feature that depends on a connector.`,
+        schema: z.object({}),
+        handler: async () => {
+            const connectors = await apiGet("/api/connectors");
+            const list = Array.isArray(connectors) ? connectors : [];
+            const connected = list.filter((c) => c.isConnected || c.status === "connected");
+            if (connected.length === 0) {
+                return { content: [{ type: "text", text: "No connected integrations." }] };
+            }
+            const lines = connected.map((c) => `- ${c.name ?? c.type}: ${c.status ?? "connected"}${c.lastSyncAt ? ` (last sync ${c.lastSyncAt})` : ""}`);
+            return { content: [{ type: "text", text: `# Integration health\n${lines.join("\n")}` }] };
+        },
+    },
+    apex_spec_validate: {
+        description: `${APEX} — Fetch the canonical Apex Spec event taxonomy so you can validate the track()/identify()/useApexVariant() calls in the user's files against it (ESLint-like for Apex usage). Read the user's files, find the calls, and flag event names + attributes that don't match the returned spec.`,
+        schema: z.object({}),
+        handler: async () => {
+            const spec = await apiGet("/api/spec/events");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Apex Spec (validate the user's track/identify/useApexVariant calls against this — flag unknown event names + attribute shapes):\n\n${JSON.stringify(spec, null, 2)}`,
+                    },
+                ],
+            };
+        },
+    },
+    check_workspace_readiness: {
+        description: `${APEX} — Check whether the workspace is ready for the Graduation Pipeline flow: Apex auth, GitHub App install, and (if you pass a repo) whether Apex may write to it. Run this at the top of /apex-experiment, /apex-graduate, etc., and resolve any gaps before proceeding.`,
+        schema: z.object({
+            repo: z.string().optional().describe('Current repo "owner/name" to check write opt-in for'),
+        }),
+        handler: async (args) => {
+            const apexAuthed = Boolean(getActiveWorkspace());
+            let githubAppInstalled = false;
+            let currentRepoWritable = false;
+            try {
+                const connectors = await apiGet("/api/connectors");
+                const list = Array.isArray(connectors) ? connectors : [];
+                githubAppInstalled = list.some((c) => c.type === "github" && (c.isConnected || c.status === "connected"));
+            }
+            catch { /* unauth or unreachable */ }
+            if (args.repo && githubAppInstalled) {
+                try {
+                    const auto = await apiGet("/api/graduation-pipeline/automation");
+                    currentRepoWritable = (auto.data?.writeRepos ?? []).includes(args.repo);
+                }
+                catch { /* ignore */ }
+            }
+            const readiness = {
+                apexAuthed,
+                githubAppInstalled,
+                currentRepoWritable,
+                // The agent verifies these locally (presence of @apex-inc/sdk + repo access).
+                sdkInstalled: "check-locally",
+                currentRepoAuthorized: githubAppInstalled ? "check-locally" : false,
+            };
+            return { content: [{ type: "text", text: JSON.stringify(readiness, null, 2) }] };
+        },
+    },
+    start_apex_login: {
+        description: `${APEX} — Begin the in-IDE Apex sign-in. Returns a browser URL; open it, the developer signs in (Google / GitHub / email / SSO — unchanged), and this tool polls until a workspace-scoped API key is minted. Save the returned key to your Cursor MCP config (with the developer's consent).`,
+        schema: z.object({}),
+        handler: async () => {
+            const start = await apiPost("/api/auth/cli-login/start", {});
+            const lines = [
+                `Open this URL in your browser to sign in to Apex:`,
+                start.url,
+                ``,
+                `Waiting for sign-in…`,
+            ];
+            // Poll up to ~90s.
+            for (let i = 0; i < 45; i++) {
+                await new Promise((r) => setTimeout(r, 2000));
+                try {
+                    const status = await apiGet(`/api/auth/login-status?state=${encodeURIComponent(start.state)}`);
+                    if (status.state === "logged_in" && status.apiKey) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Signed in. Save this API key to your Cursor MCP config (APEX_API_KEY) with the developer's consent:\n\n${status.apiKey}\n\nWorkspace: ${status.workspace || "(default)"}`,
+                                },
+                            ],
+                        };
+                    }
+                    if (status.state === "failed") {
+                        return { content: [{ type: "text", text: `Sign-in session expired. Re-run /apex-login.` }] };
+                    }
+                }
+                catch { /* keep polling */ }
+            }
+            return { content: [{ type: "text", text: `${lines.join("\n")}\n\nStill waiting — re-run /apex-login if you didn't finish in the browser.` }] };
+        },
+    },
+    start_integration_install: {
+        description: `${APEX} — Begin an in-IDE integration install (GitHub today; Stripe/HubSpot/etc. later). Returns a browser URL; open it, the developer completes the install, and this tool polls until it's connected. Generalized by integration type.`,
+        schema: z.object({
+            type: z.string().describe('Integration type, e.g. "github"'),
+        }),
+        handler: async ({ type }) => {
+            const start = await apiPost("/api/integrations/cli-install/start", { type });
+            for (let i = 0; i < 60; i++) {
+                await new Promise((r) => setTimeout(r, 2000));
+                try {
+                    const status = await apiGet(`/api/integrations/install-status?state=${encodeURIComponent(start.state)}`);
+                    if (status.state === "installed") {
+                        return { content: [{ type: "text", text: `${type} connected. Continuing.` }] };
+                    }
+                    if (status.state === "failed") {
+                        return { content: [{ type: "text", text: `Install session expired. Re-run the install.` }] };
+                    }
+                }
+                catch { /* keep polling */ }
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Open this URL to install ${type}:\n${start.url}\n\nI'll keep waiting — say "continue" once you've finished, or skip for now (the merge gate won't arm until it's connected).`,
+                    },
+                ],
+            };
+        },
+    },
+    create_api_key: {
+        description: `${APEX} — Create a new Apex API key for the current user. Returns the raw key once.`,
+        schema: z.object({ name: z.string().optional().describe("A label for the key") }),
+        handler: async ({ name }) => {
+            const res = await apiPost("/api/user/api-keys", {
+                name: name ?? "Cursor (Apex MCP)",
+            });
+            const text = res.rawKey
+                ? `Created API key "${name ?? "Cursor (Apex MCP)"}". Store it securely — shown once:\n${res.rawKey}`
+                : `Could not create API key.`;
+            return { content: [{ type: "text", text }] };
+        },
+    },
+    list_api_keys: {
+        description: `${APEX} — List the current user's Apex API keys (names + ids; never the secret).`,
+        schema: z.object({}),
+        handler: async () => {
+            const keys = await apiGet("/api/user/api-keys");
+            const list = Array.isArray(keys) ? keys : [];
+            if (list.length === 0)
+                return { content: [{ type: "text", text: "No API keys." }] };
+            const lines = list.map((k) => `- ${k.name} (${k.id})${k.lastUsedAt ? ` — last used ${k.lastUsedAt}` : ""}`);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+    },
+    revoke_api_key: {
+        description: `${APEX} — Revoke (delete) an Apex API key by id.`,
+        schema: z.object({ keyId: z.string().describe("The API key id to revoke") }),
+        handler: async ({ keyId }) => {
+            await apiDelete(`/api/user/api-keys/${encodeURIComponent(keyId)}`);
+            return { content: [{ type: "text", text: `Revoked API key ${keyId}.` }] };
+        },
+    },
+    gate_experiment_on_merge: {
+        description: `${APEX} — Arm a merge gate: bind an experiment to a linked PR so merging it auto-starts the test. Requires a frozen design spec (primary metric, minimum sample size, max duration, stopping rule) — this is the rigor gate that stops PR latency from changing the rules of the test. Link the PR first with link_experiment.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+            engineeringLinkId: z.string().describe("The link id of the PR (from list_engineering_links)"),
+            rampOnMerge: z.number().min(0).max(100).optional().describe("Variant traffic split applied on merge (default 50)"),
+            primaryMetric: z.string().describe("Primary metric key (must be one of the experiment's metrics)"),
+            minSampleSize: z.number().int().positive().describe("Minimum per-variant sample size (must exceed the default 10)"),
+            maxDurationDays: z.number().int().positive().describe("Max run duration in days (auto-stop)"),
+            stoppingRule: z.string().describe('Stopping rule, e.g. "bayesian-95" or "fixed-horizon"'),
+        }),
+        handler: async (args) => {
+            const res = await apiPost(`/api/experiments/${encodeURIComponent(args.experimentId)}/gate`, {
+                engineeringLinkId: args.engineeringLinkId,
+                rampOnMerge: args.rampOnMerge ?? 50,
+                designSpec: {
+                    primaryMetric: args.primaryMetric,
+                    minSampleSize: args.minSampleSize,
+                    maxDurationDays: args.maxDurationDays,
+                    stoppingRule: args.stoppingRule,
+                },
+            });
+            const text = res.data
+                ? `Merge gate armed for ${args.experimentId}. Status: ${res.data.status} (waiting on the PR to merge).`
+                : `Could not arm gate: ${res.error ?? "unknown error"}${res.code ? ` (${res.code})` : ""}`;
+            return { content: [{ type: "text", text }] };
+        },
+    },
+    open_graduation_pr: {
+        description: `${APEX} — Open an Apex-authored Graduation PR that inlines the winning variant in the merchant's repo. Requires the repo to be opted in for Apex writes (Automation Controls). The experiment must be promoted with a winner. No LLM — a deterministic, reviewable manifest + branded PR.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID (must be promoted with a winner)"),
+        }),
+        handler: async ({ experimentId }) => {
+            const res = await apiPost(`/api/experiments/${encodeURIComponent(experimentId)}/promote`, { openGraduationPr: true });
+            const url = res.data?.graduationPrUrl;
+            const text = url
+                ? `Graduation PR opened: ${url}`
+                : `Could not open graduation PR: ${res.error ?? "unknown error"}`;
+            return { content: [{ type: "text", text }] };
+        },
+    },
+    open_revert_pr: {
+        description: `${APEX} — Open a native-format Revert PR removing a losing experiment's variant. Requires the repo to be opted in for Apex writes.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+        }),
+        handler: async ({ experimentId }) => {
+            const res = await apiPost(`/api/experiments/${encodeURIComponent(experimentId)}/open-revert-pr`, {});
+            const url = res.data?.prUrl;
+            const text = url
+                ? `Revert PR opened: ${url}`
+                : `Could not open revert PR: ${res.error ?? "unknown error"}`;
+            return { content: [{ type: "text", text }] };
+        },
+    },
+    get_automation_controls: {
+        description: `${APEX} — Read the workspace's Graduation Pipeline Automation Controls (on-conclusion behavior, per-repo write allowlist, GitHub visibility, commit/branch conventions).`,
+        schema: z.object({}),
+        handler: async () => {
+            const res = await apiGet(`/api/graduation-pipeline/automation`);
+            return {
+                content: [{ type: "text", text: JSON.stringify(res.data ?? res, null, 2) }],
+            };
+        },
+    },
+    update_automation_controls: {
+        description: `${APEX} — Update the workspace's Graduation Pipeline Automation Controls. Only the fields you pass change. To let Apex open PRs to a repo, add it via writeRepos (or use the dedicated repos endpoint).`,
+        schema: z.object({
+            onWin: z.enum(["do_nothing", "notify", "auto"]).optional(),
+            onLose: z.enum(["do_nothing", "notify", "auto"]).optional(),
+            writeRepos: z.array(z.string()).optional(),
+            githubVisibility: z.enum(["full", "minimal", "off"]).optional(),
+            commitConvention: z.enum(["conventional", "none", "custom"]).optional(),
+            branchConvention: z.enum(["apex", "feature", "feat", "chore", "custom"]).optional(),
+            workingHours: z.enum(["anytime", "off_hours", "business_hours"]).optional(),
+        }),
+        handler: async (args) => {
+            const res = await apiPatch(`/api/graduation-pipeline/automation`, args);
+            return {
+                content: [{ type: "text", text: `Automation Controls updated.\n${JSON.stringify(res.data ?? res, null, 2)}` }],
+            };
+        },
+    },
+    list_engineering_links: {
+        description: `${APEX} — List the PRs and issues linked to an experiment, with their current state.`,
+        schema: z.object({
+            experimentId: z.string().describe("The experiment ID"),
+        }),
+        handler: async ({ experimentId }) => {
+            const res = await apiGet(`/api/experiments/${encodeURIComponent(experimentId)}/links`);
+            const links = res.data ?? [];
+            if (links.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No engineering links for experiment ${experimentId}.` }],
+                };
+            }
+            const lines = links.map((l) => `- ${l.system} ${l.kind} ${l.repo ?? ""}#${l.externalId}${l.state ? ` (${l.state})` : ""}${l.title ? ` — ${l.title}` : ""}\n  ${l.url}`);
+            return {
+                content: [
+                    { type: "text", text: `# Engineering links — ${experimentId}\n\n${lines.join("\n")}` },
+                ],
+            };
+        },
+    },
 };
 //# sourceMappingURL=tools.js.map