@amplitude/wizard 1.0.0 → 1.2.0

package/LICENSE

@@ -1,6 +1,30 @@
 MIT License
 
-Copyright (c) 2025 Amplitude
+Copyright (c) 2026 Amplitude, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+MIT License
+
+Copyright (c) 2025 PostHog
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/bin.js

@@ -295,6 +295,7 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
             if (!options.installDir)
                 options.installDir = process.cwd();
             const session = await buildSessionFromOptions(options);
+            session.agent = true;
             await resolveNonInteractiveCredentials(session, options, 'agent', agentUI);
             await lazyRunWizard(options, session);
         })();
@@ -354,16 +355,18 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                     const { resolveCredentials } = await import('./src/lib/credential-resolution.js');
                     await resolveCredentials(session);
                     // Resolve org/workspace display names so /whoami shows them.
+                    // Also extracts the numeric analytics project ID for MCP event detection.
                     // Fire-and-forget so it doesn't block startup.
                     if (session.region && session.selectedOrgId) {
                         const { getStoredUser, getStoredToken } = await import('./src/utils/ampli-settings.js');
-                        const { fetchAmplitudeUser } = await import('./src/lib/api.js');
+                        const { fetchAmplitudeUser, extractProjectId } = await import('./src/lib/api.js');
                         const storedUser = getStoredUser();
                         const realUser = storedUser && storedUser.id !== 'pending' ? storedUser : null;
                         const zone = session.region;
                         const storedToken = realUser
                             ? getStoredToken(realUser.id, realUser.zone)
                             : getStoredToken(undefined, zone);
+                        logToFile(`[bin] fire-and-forget: storedToken=${storedToken ? 'found' : 'null'}`);
                         if (storedToken) {
                             fetchAmplitudeUser(storedToken.idToken, zone)
                                 .then((userInfo) => {
@@ -372,16 +375,44 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                                     session.userEmail = userInfo.email;
                                     changed = true;
                                 }
+                                if (userInfo.email) {
+                                    analytics.setDistinctId(userInfo.email);
+                                    analytics.identifyUser({
+                                        email: userInfo.email,
+                                        org_id: session.selectedOrgId ?? undefined,
+                                        org_name: session.selectedOrgName ?? undefined,
+                                        workspace_id: session.selectedWorkspaceId ?? undefined,
+                                        workspace_name: session.selectedWorkspaceName ?? undefined,
+                                        project_id: session.selectedProjectId,
+                                        project_name: session.selectedProjectName,
+                                        region: session.region,
+                                        integration: session.integration,
+                                    });
+                                }
                                 if (session.selectedOrgId) {
-                                    const org = userInfo.orgs.find((o) => o.id === session.selectedOrgId);
+                                    // Fall back to the first org if the stored ID is stale
+                                    // (e.g. session checkpoint from a different account).
+                                    const org = userInfo.orgs.find((o) => o.id === session.selectedOrgId) ?? userInfo.orgs[0];
+                                    logToFile(`[bin] fire-and-forget: orgs=${userInfo.orgs
+                                        .map((o) => o.id)
+                                        .join(',')}, looking for ${session.selectedOrgId}, using=${org?.id ?? 'none'}`);
                                     if (org) {
                                         session.selectedOrgName = org.name;
                                         changed = true;
+                                        // Fall back to the first workspace if the stored ID is stale.
                                         const ws = session.selectedWorkspaceId
-                                            ? org.workspaces.find((w) => w.id === session.selectedWorkspaceId)
-                                            : undefined;
+                                            ? org.workspaces.find((w) => w.id === session.selectedWorkspaceId) ?? org.workspaces[0]
+                                            : org.workspaces[0];
                                         if (ws) {
                                             session.selectedWorkspaceName = ws.name;
+                                            // Extract the analytics project ID from the lowest-rank environment.
+                                            const projectId = extractProjectId(ws);
+                                            logToFile(`[bin] project ID resolution: environments=${ws.environments?.length ?? 'null'}, projectId=${projectId}`);
+                                            if (projectId)
+                                                session.selectedProjectId = projectId;
+                                        }
+                                        else {
+                                            logToFile(`[bin] project ID resolution: no workspaces in org ${org.id}`);
                                         }
                                     }
                                 }
@@ -389,8 +420,8 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                                     tui.store.emitChange();
                                 }
                             })
-                                .catch(() => {
-                                // Non-fatal — /whoami will just show (none)
+                                .catch((err) => {
+                                logToFile(`[bin] fire-and-forget fetchAmplitudeUser failed: ${err instanceof Error ? err.message : String(err)}`);
                             });
                         }
                     }
@@ -429,7 +460,7 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                 const { analytics } = await import('./src/utils/analytics.js');
                 analytics.applyOptOut();
                 const { FRAMEWORK_REGISTRY } = await import('./src/lib/registry.js');
-                const { detectIntegration } = await import('./src/run.js');
+                const { detectAllFrameworks } = await import('./src/run.js');
                 const installDir = session.installDir ?? process.cwd();
                 // Verbose startup diagnostics — always written to the log file;
                 // visible in the RunScreen "Logs" tab.
@@ -515,6 +546,8 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                         });
                         // Populate user email for /whoami display
                         session.userEmail = userInfo.email;
+                        analytics.setDistinctId(userInfo.email);
+                        analytics.identifyUser({ email: userInfo.email });
                         // Signal AuthScreen — triggers org/workspace/API key pickers
                         tui.store.setOAuthComplete({
                             accessToken: auth.accessToken,
@@ -532,11 +565,13 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
                 })();
                 // ── Framework detection ────────────────────────────────
                 // Runs concurrently with auth while AuthScreen shows.
+                // Each detector has its own per-framework timeout internally,
+                // so no outer timeout is needed.
                 const detectionTask = (async () => {
-                    const detectedIntegration = await Promise.race([
-                        detectIntegration(installDir),
-                        new Promise((resolve) => setTimeout(() => resolve(undefined), DETECTION_TIMEOUT_MS)),
-                    ]);
+                    const results = await detectAllFrameworks(installDir);
+                    // Store full results on session for diagnostics
+                    session.detectionResults = results;
+                    const detectedIntegration = results.find((r) => r.detected)?.integration;
                     if (detectedIntegration) {
                         const config = FRAMEWORK_REGISTRY[detectedIntegration];
                         // Run gatherContext for the friendly variant label
@@ -903,6 +938,7 @@ void (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
             if (storedToken) {
                 session.credentials = {
                     accessToken: storedToken.accessToken,
+                    idToken: storedToken.idToken,
                     projectApiKey: '',
                     host: getHostFromRegion(zone),
                     projectId: 0,

package/dist/src/frameworks/javascript-node/javascript-node-wizard-agent.js

@@ -2,8 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JAVASCRIPT_NODE_AGENT_CONFIG = void 0;
 const constants_1 = require("../../lib/constants");
+const package_json_1 = require("../../utils/package-json");
 const setup_utils_1 = require("../../utils/setup-utils");
 const package_manager_detection_1 = require("../../lib/package-manager-detection");
+const utils_1 = require("../javascript-web/utils");
 exports.JAVASCRIPT_NODE_AGENT_CONFIG = {
     metadata: {
         name: 'Node.js',
@@ -19,7 +21,15 @@ exports.JAVASCRIPT_NODE_AGENT_CONFIG = {
         detectPackageManager: package_manager_detection_1.detectNodePackageManagers,
         detect: async (options) => {
             const packageJson = await (0, setup_utils_1.tryGetPackageJson)(options);
-            return !!packageJson;
+            if (!packageJson)
+                return false;
+            // Don't claim projects that belong to a specific framework
+            for (const frameworkPkg of utils_1.FRAMEWORK_PACKAGES) {
+                if ((0, package_json_1.hasPackageInstalled)(frameworkPkg, packageJson)) {
+                    return false;
+                }
+            }
+            return true;
         },
     },
     environment: {

package/dist/src/frameworks/react-router/react-router-wizard-agent.js

@@ -7,6 +7,36 @@ const package_json_1 = require("../../utils/package-json");
 const setup_utils_1 = require("../../utils/setup-utils");
 const ui_1 = require("../../ui");
 const utils_1 = require("./utils");
+const REACT_ROUTER_MINIMUM_VERSION = '6.0.0';
+const TANSTACK_MINIMUM_VERSION = '1.0.0';
+// Priority matches gatherContext: TanStack Start > TanStack Router > react-router
+function getReactRouterVersionCheckInfo(packageJson) {
+    const tanstackStartVersion = (0, package_json_1.getPackageVersion)('@tanstack/react-start', packageJson);
+    if (tanstackStartVersion) {
+        return {
+            version: tanstackStartVersion,
+            minimumVersion: TANSTACK_MINIMUM_VERSION,
+            packageDisplayName: 'TanStack Start',
+        };
+    }
+    const tanstackRouterVersion = (0, package_json_1.getPackageVersion)('@tanstack/react-router', packageJson);
+    if (tanstackRouterVersion) {
+        return {
+            version: tanstackRouterVersion,
+            minimumVersion: TANSTACK_MINIMUM_VERSION,
+            packageDisplayName: 'TanStack Router',
+        };
+    }
+    const reactRouterVersion = (0, package_json_1.getPackageVersion)('react-router', packageJson);
+    if (reactRouterVersion) {
+        return {
+            version: reactRouterVersion,
+            minimumVersion: REACT_ROUTER_MINIMUM_VERSION,
+            packageDisplayName: 'React Router',
+        };
+    }
+    return {};
+}
 exports.REACT_ROUTER_AGENT_CONFIG = {
     metadata: {
         name: 'React Router',
@@ -14,6 +44,19 @@ exports.REACT_ROUTER_AGENT_CONFIG = {
         docsUrl: 'https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2',
         unsupportedVersionDocsUrl: 'https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2',
         gatherContext: async (options) => {
+            const packageJson = await (0, setup_utils_1.tryGetPackageJson)(options);
+            // TanStack Start / TanStack Router share the same browser SDK setup
+            if (packageJson &&
+                (0, package_json_1.hasPackageInstalled)('@tanstack/react-start', packageJson)) {
+                (0, ui_1.getUI)().setDetectedFramework('TanStack Start');
+                return { routerMode: utils_1.ReactRouterMode.V7_FRAMEWORK };
+            }
+            if (packageJson &&
+                (0, package_json_1.hasPackageInstalled)('@tanstack/react-router', packageJson)) {
+                (0, ui_1.getUI)().setDetectedFramework('TanStack Router');
+                return {};
+            }
+            // Standard React Router detection
             const routerMode = await (0, utils_1.getReactRouterMode)(options);
             if (routerMode) {
                 (0, ui_1.getUI)().setDetectedFramework(`React Router ${(0, utils_1.getReactRouterModeName)(routerMode)}`);
@@ -25,20 +68,34 @@ exports.REACT_ROUTER_AGENT_CONFIG = {
     detection: {
         packageName: 'react-router',
         packageDisplayName: 'React Router',
-        getVersion: (packageJson) => (0, package_json_1.getPackageVersion)('react-router', packageJson),
+        getVersion: (packageJson) => {
+            const pkg = packageJson;
+            // Priority matches gatherContext: TanStack Start > TanStack Router > react-router
+            return ((0, package_json_1.getPackageVersion)('@tanstack/react-start', pkg) ??
+                (0, package_json_1.getPackageVersion)('@tanstack/react-router', pkg) ??
+                (0, package_json_1.getPackageVersion)('react-router', pkg));
+        },
         getVersionBucket: utils_1.getReactRouterVersionBucket,
-        minimumVersion: '6.0.0',
+        minimumVersion: REACT_ROUTER_MINIMUM_VERSION,
         getInstalledVersion: async (options) => {
             const packageJson = await (0, setup_utils_1.tryGetPackageJson)(options);
-            return packageJson
-                ? (0, package_json_1.getPackageVersion)('react-router', packageJson)
-                : undefined;
+            if (!packageJson)
+                return undefined;
+            return getReactRouterVersionCheckInfo(packageJson).version;
+        },
+        getVersionCheckInfo: async (options) => {
+            const packageJson = await (0, setup_utils_1.tryGetPackageJson)(options);
+            if (!packageJson)
+                return {};
+            return getReactRouterVersionCheckInfo(packageJson);
         },
         detect: async (options) => {
             const packageJson = await (0, setup_utils_1.tryGetPackageJson)(options);
-            return packageJson
-                ? (0, package_json_1.hasPackageInstalled)('react-router', packageJson)
-                : false;
+            if (!packageJson)
+                return false;
+            return ((0, package_json_1.hasPackageInstalled)('react-router', packageJson) ||
+                (0, package_json_1.hasPackageInstalled)('@tanstack/react-router', packageJson) ||
+                (0, package_json_1.hasPackageInstalled)('@tanstack/react-start', packageJson));
         },
         detectPackageManager: package_manager_detection_1.detectNodePackageManagers,
     },

package/dist/src/frameworks/vue/vue-wizard-agent.js

@@ -25,7 +25,12 @@ exports.VUE_AGENT_CONFIG = {
         },
         detect: async (options) => {
             const packageJson = await (0, setup_utils_1.tryGetPackageJson)(options);
-            return packageJson ? (0, package_json_1.hasPackageInstalled)('vue', packageJson) : false;
+            if (!packageJson)
+                return false;
+            // Nuxt projects have both 'vue' and 'nuxt' — don't claim them
+            if ((0, package_json_1.hasPackageInstalled)('nuxt', packageJson))
+                return false;
+            return (0, package_json_1.hasPackageInstalled)('vue', packageJson);
         },
         detectPackageManager: package_manager_detection_1.detectNodePackageManagers,
     },

package/dist/src/lib/agent-interface.js

@@ -799,6 +799,9 @@ async function runAgent(agentConfig, prompt, options, spinner, config, middlewar
     // Event plan file watcher — cleaned up in finally block
     let eventPlanWatcher;
     let eventPlanInterval;
+    // Dashboard file watcher — cleaned up in finally block
+    let dashboardWatcher;
+    let dashboardInterval;
     try {
         // Tools needed for the wizard:
         // - File operations: Read, Write, Edit
@@ -861,6 +864,46 @@ async function runAgent(agentConfig, prompt, options, spinner, config, middlewar
                 }
             }, 1000);
         }
+        // Watch for .amplitude-dashboard.json written by the agent after dashboard creation.
+        // Parses the dashboard URL and forwards it to the UI so ChecklistScreen can
+        // surface a direct link without requiring any further user action.
+        // workingDirectory is the CLI install dir (process.cwd() or --install-dir),
+        // not untrusted network input. The filename is a hardcoded constant.
+        const dashboardFilePath = path_1.default.join(agentConfig.workingDirectory, '.amplitude-dashboard.json'); // nosemgrep
+        const dashboardFileSchema = zod_1.z.object({
+            dashboardUrl: zod_1.z.string().url(),
+        });
+        const readDashboardFile = () => {
+            try {
+                const content = fs.readFileSync(dashboardFilePath, 'utf-8');
+                const result = dashboardFileSchema.safeParse(JSON.parse(content));
+                if (result.success) {
+                    (0, ui_1.getUI)().setDashboardUrl(result.data.dashboardUrl);
+                }
+            }
+            catch {
+                // File doesn't exist or isn't valid JSON yet
+            }
+        };
+        try {
+            dashboardWatcher = fs.watch(dashboardFilePath, () => readDashboardFile());
+            readDashboardFile();
+        }
+        catch {
+            // File doesn't exist yet — poll until it appears
+            dashboardInterval = setInterval(() => {
+                try {
+                    fs.accessSync(dashboardFilePath);
+                    readDashboardFile();
+                    clearInterval(dashboardInterval);
+                    dashboardInterval = undefined;
+                    dashboardWatcher = fs.watch(dashboardFilePath, () => readDashboardFile());
+                }
+                catch {
+                    // Still waiting
+                }
+            }, 1000);
+        }
         // Retry loop: if the agent stalls (no message for the configured timeout), abort
         // and re-run with a fresh AbortController and prompt stream. Up to MAX_RETRIES.
         const MAX_RETRIES = 3;
@@ -1151,6 +1194,9 @@ async function runAgent(agentConfig, prompt, options, spinner, config, middlewar
         eventPlanWatcher?.close();
         if (eventPlanInterval)
             clearInterval(eventPlanInterval);
+        dashboardWatcher?.close();
+        if (dashboardInterval)
+            clearInterval(dashboardInterval);
     }
 }
 /**

package/dist/src/lib/agent-runner.js

@@ -1,37 +1,4 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runAgentWizard = runAgentWizard;
 const framework_config_1 = require("./framework-config");
@@ -42,7 +9,7 @@ const ui_1 = require("../ui");
 const agent_interface_1 = require("./agent-interface");
 const urls_1 = require("../utils/urls");
 const constants_js_1 = require("./constants.js");
-const semver = __importStar(require("semver"));
+const version_check_1 = require("./version-check");
 const debug_1 = require("../utils/debug");
 const benchmark_1 = require("./middleware/benchmark");
 const wizard_abort_1 = require("../utils/wizard-abort");
@@ -76,19 +43,23 @@ async function runAgentWizard(config, session) {
         (0, debug_1.enableDebugLogs)();
     }
     // Version check
-    if (config.detection.minimumVersion && config.detection.getInstalledVersion) {
-        const version = await config.detection.getInstalledVersion(sessionToOptions(session));
-        (0, debug_1.logToFile)(`[runAgentWizard] detected version: ${version}`);
-        if (version) {
-            const coerced = semver.coerce(version);
-            if (coerced && semver.lt(coerced, config.detection.minimumVersion)) {
-                (0, debug_1.logToFile)(`[runAgentWizard] version ${version} is less than minimum required ${config.detection.minimumVersion}`);
-                const docsUrl = config.metadata.unsupportedVersionDocsUrl ?? config.metadata.docsUrl;
-                (0, debug_1.logToFile)(`[runAgentWizard] directing user to manual setup guide: ${docsUrl}`);
-                (0, ui_1.getUI)().cancel(`The wizard requires ${config.metadata.name} ${config.detection.minimumVersion} or later, but found version ${version}. Upgrade your ${config.metadata.name} version to use the wizard, or follow the manual setup guide.`, { docsUrl });
-                (0, debug_1.logToFile)('[runAgentWizard] cancel displayed to user');
-                return;
-            }
+    if (config.detection.getInstalledVersion ||
+        config.detection.getVersionCheckInfo) {
+        const versionCheckInfo = await (0, version_check_1.getVersionCheckInfo)(config.detection, sessionToOptions(session));
+        (0, debug_1.logToFile)(`[runAgentWizard] detected version: ${versionCheckInfo.version}`);
+        const versionWarning = (0, version_check_1.getVersionWarning)(versionCheckInfo, {
+            coerceVersion: true,
+        });
+        if (versionWarning) {
+            (0, debug_1.logToFile)(`[runAgentWizard] ${versionWarning}`);
+            const docsUrl = config.metadata.unsupportedVersionDocsUrl ?? config.metadata.docsUrl;
+            (0, debug_1.logToFile)(`[runAgentWizard] directing user to manual setup guide: ${docsUrl}`);
+            const minimumVersion = versionCheckInfo.minimumVersion ?? config.detection.minimumVersion;
+            const packageDisplayName = versionCheckInfo.packageDisplayName ?? config.metadata.name;
+            const version = versionCheckInfo.version ?? 'unknown';
+            (0, ui_1.getUI)().cancel(`The wizard requires ${packageDisplayName} ${minimumVersion} or later, but found version ${version}. Upgrade your ${packageDisplayName} version to use the wizard, or follow the manual setup guide.`, { docsUrl });
+            (0, debug_1.logToFile)('[runAgentWizard] cancel displayed to user');
+            return;
         }
     }
     // Setup phase — informational only, no prompts
@@ -112,12 +83,14 @@ async function runAgentWizard(config, session) {
     if (usesPackageJson) {
         packageJson = await (0, setup_utils_1.tryGetPackageJson)({ installDir: session.installDir });
         if (packageJson) {
-            // Log warning if package not installed, but continue (agent handles it)
-            const { hasPackageInstalled } = await import('../utils/package-json.js');
-            if (!hasPackageInstalled(config.detection.packageName, packageJson)) {
+            frameworkVersion = config.detection.getVersion(packageJson);
+            // Log warning if package not found, but continue (agent handles it).
+            // Uses getVersion() rather than checking packageName directly so
+            // frameworks that match multiple packages (e.g. React Router +
+            // TanStack) don't trigger false "not installed" warnings.
+            if (!frameworkVersion) {
                 (0, ui_1.getUI)().log.warn(`${config.detection.packageDisplayName} does not seem to be installed. Continuing anyway — the agent will handle it.`);
             }
-            frameworkVersion = config.detection.getVersion(packageJson);
         }
         else {
             (0, ui_1.getUI)().log.warn('Could not find package.json. Continuing anyway — the agent will handle it.');
@@ -310,6 +283,11 @@ async function runAgentWizard(config, session) {
         });
     }
     // MCP installation is handled by McpScreen — no prompt here
+    // Data ingestion check — agent mode only (not CI).
+    // Poll via MCP until events arrive, then emit a structured result event.
+    if (session.agent) {
+        await pollForDataIngestion(session, accessToken, cloudRegion);
+    }
     // Build outro data and store it for OutroScreen
     const continueUrl = session.signup
         ? constants_js_1.OUTBOUND_URLS.products(cloudRegion)
@@ -332,6 +310,89 @@ async function runAgentWizard(config, session) {
     (0, ui_1.getUI)().outro(`Successfully installed Amplitude!`);
     await analytics_1.analytics.shutdown('success');
 }
+/**
+ * Poll the Amplitude MCP server for event ingestion in agent mode.
+ *
+ * Emits structured NDJSON events via the AgentUI:
+ *   - `status` events every poll cycle while waiting
+ *   - `result` event when events are detected (includes event names)
+ *   - `log` warning if the timeout is reached without detecting events
+ *
+ * Skipped silently if no project ID can be resolved (e.g. --api-key flow).
+ *
+ * @param session    - wizard session (must have session.agent === true)
+ * @param accessToken - OAuth access token for MCP Bearer auth
+ * @param cloudRegion - us | eu, used to resolve project ID lazily if needed
+ */
+async function pollForDataIngestion(session, accessToken, cloudRegion) {
+    const { fetchHasAnyEventsMcp, fetchAmplitudeUser } = await import('../lib/api.js');
+    const { logToFile } = await import('../utils/debug.js');
+    const POLL_INTERVAL_MS = 30_000;
+    // Allow override for testing; default 30 minutes.
+    const MAX_WAIT_MS = Number(process.env.DATA_INGESTION_TIMEOUT_MS) || 30 * 60 * 1000;
+    // Resolve the numeric analytics project ID.
+    // It is set by resolveEnvironmentSelection for the environment-picker path,
+    // and by the fire-and-forget in bin.ts for the TUI path.
+    // If still missing, try a single fetchAmplitudeUser call.
+    let projectId = session.selectedProjectId ?? null;
+    if (!projectId) {
+        try {
+            const userInfo = await fetchAmplitudeUser(accessToken, cloudRegion);
+            const org = session.selectedOrgId
+                ? userInfo.orgs.find((o) => o.id === session.selectedOrgId)
+                : userInfo.orgs[0];
+            const ws = org && session.selectedWorkspaceId
+                ? org.workspaces.find((w) => w.id === session.selectedWorkspaceId)
+                : org?.workspaces[0];
+            projectId =
+                ws?.environments
+                    ?.slice()
+                    .sort((a, b) => a.rank - b.rank)
+                    .find((e) => e.app?.id)?.app?.id ?? null;
+            if (projectId)
+                session.selectedProjectId = projectId;
+        }
+        catch (err) {
+            logToFile(`[pollForDataIngestion] could not resolve projectId: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (!projectId) {
+        logToFile('[pollForDataIngestion] no projectId — skipping ingestion check');
+        return;
+    }
+    const ui = (0, ui_1.getUI)();
+    ui.pushStatus('Waiting for events — run your app and trigger some actions');
+    const deadline = Date.now() + MAX_WAIT_MS;
+    let pollCount = 0;
+    while (Date.now() < deadline) {
+        pollCount++;
+        logToFile(`[pollForDataIngestion] poll #${pollCount} projectId=${projectId}`);
+        try {
+            const result = await fetchHasAnyEventsMcp(accessToken, projectId);
+            if (result.hasEvents) {
+                logToFile(`[pollForDataIngestion] events detected: ${result.activeEventNames.join(', ')}`);
+                // Emit a structured result event so callers can act on it.
+                ui.setEventIngestionDetected(result.activeEventNames);
+                ui.log.success(`Events detected: ${result.activeEventNames.length > 0
+                    ? result.activeEventNames.join(', ')
+                    : '(events flowing)'}`);
+                session.dataIngestionConfirmed = true;
+                return;
+            }
+        }
+        catch (err) {
+            logToFile(`[pollForDataIngestion] poll error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Wait before the next poll, but bail early if deadline passed.
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, Math.min(POLL_INTERVAL_MS, remaining)));
+    }
+    logToFile('[pollForDataIngestion] timeout reached without detecting events');
+    ui.log.warn('No events detected within the timeout window. ' +
+        'Run your app to send events, then check your Amplitude dashboard.');
+}
 /**
  * Build the integration prompt for the agent.
  */

package/dist/src/lib/api.d.ts

@@ -16,6 +16,14 @@ export type AmplitudeOrg = {
         }> | null;
     }>;
 };
+/** Shared workspace type for environment helpers. */
+export type AmplitudeWorkspace = AmplitudeOrg['workspaces'][number];
+/**
+ * Extract the primary analytics project ID from a workspace.
+ * Picks the lowest-rank environment that has an app ID.
+ * Returns null if no such environment exists.
+ */
+export declare function extractProjectId(ws: AmplitudeWorkspace): string | null;
 export type AmplitudeUserInfo = {
     id: string;
     firstName: string;
@@ -72,6 +80,33 @@ export type AmplitudeSource = {
 };
 /** Fetches sources for a specific branch version. */
 export declare function fetchSources(idToken: string, zone: AmplitudeZone, orgId: string, workspaceId: string, branchId: string, versionId: string): Promise<AmplitudeSource[]>;
+export interface McpUser {
+    /** Amplitude's internal ID (always present) */
+    amplitudeId: string;
+    /** App-assigned user ID if setUserId() was called, otherwise null */
+    userId: string | null;
+}
+export interface McpEventsResult {
+    hasEvents: boolean;
+    /** Kept for API compatibility — always empty (query_dataset was removed from MCP server) */
+    csvRows: unknown[][];
+    /** Active event names from get_events (isActive=true), up to 10 */
+    activeEventNames: string[];
+    /** Recent users who fired events, up to 5 */
+    activeUsers: McpUser[];
+}
+/**
+ * Checks whether the project has received any events via the Amplitude MCP server.
+ * Uses get_users with `_all` as the primary signal (userCount > 0 → events exist),
+ * then fetches get_events for display names.
+ *
+ * Falls back to a Claude agent with the Amplitude MCP configured if the direct
+ * HTTP call fails, so the check survives MCP API drift.
+ *
+ * Requires the numeric analytics project ID (from workspace.environments[].app.id),
+ * not the workspace UUID. Returns false on any error so callers can fall through.
+ */
+export declare function fetchHasAnyEventsMcp(accessToken: string, projectId: string): Promise<McpEventsResult>;
 export type ProjectActivationStatus = {
     /** SDK/snippet has been installed (default event tracking source detected) */
     hasDetSource: boolean;