Merge remote-tracking branch 'origin/main' into e2e-control-plane

Author: gewenyu99

CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [2.30.0](https://github.com/PostHog/wizard/compare/v2.29.0...v2.30.0) (2026-06-23)
+
+
+### Features
+
+* Track steps progression for Wizard. ([#718](https://github.com/PostHog/wizard/issues/718)) ([896f190](https://github.com/PostHog/wizard/commit/896f190d6ddc73f2c7d5381f53f01bc001698116))
+
+## [2.29.0](https://github.com/PostHog/wizard/compare/v2.28.1...v2.29.0) (2026-06-23)
+
+
+### Features
+
+* agentic detection for source-map upload flow ([#689](https://github.com/PostHog/wizard/issues/689)) ([940bf67](https://github.com/PostHog/wizard/commit/940bf6791e80b54eb4964baa41b88f0e6742ca9e))
+* detect more data warehouse sources in onboarding ([#711](https://github.com/PostHog/wizard/issues/711)) ([b206169](https://github.com/PostHog/wizard/commit/b20616915158813f41ee7c9f0c0abc15386ea532))
+
+
+### Bug Fixes
+
+* **analytics:** tag every event with program_id ([#714](https://github.com/PostHog/wizard/issues/714)) ([4db5a0f](https://github.com/PostHog/wizard/commit/4db5a0f7aa84a4daa86e70789f592adc6c5563d3))
+* **self-driving:** Rename "canonical" scouts to "built-in" in self-driving prompt ([#717](https://github.com/PostHog/wizard/issues/717)) ([e99450e](https://github.com/PostHog/wizard/commit/e99450e82951f1a5237f7fd75e9ebe9d981152e8))
+
+## [2.28.1](https://github.com/PostHog/wizard/compare/v2.28.0...v2.28.1) (2026-06-23)
+
+
+### Bug Fixes
+
+* **self-driving:** Differentiate the source vs scout tips, rename "fleet" to "troop" ([#712](https://github.com/PostHog/wizard/issues/712)) ([edacabc](https://github.com/PostHog/wizard/commit/edacabc57660f1f4944a0c1cecdfa52f5f88986a))
+
+## [2.28.0](https://github.com/PostHog/wizard/compare/v2.27.0...v2.28.0) (2026-06-23)
+
+
+### Features
+
+* **signals:** Add limits on scouts. ([#707](https://github.com/PostHog/wizard/issues/707)) ([06307d9](https://github.com/PostHog/wizard/commit/06307d9b03018a73f5716adf056eef592804eb60))
+
 ## [2.27.0](https://github.com/PostHog/wizard/compare/v2.26.0...v2.27.0) (2026-06-22)
 
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/wizard",
-  "version": "2.27.0",
+  "version": "2.30.0",
   "homepage": "https://github.com/PostHog/wizard",
   "repository": "https://github.com/PostHog/wizard",
   "description": "The PostHog wizard helps you to configure your project",

src/lib/agent/agent-interface.ts

@@ -17,6 +17,7 @@ import {
   WIZARD_VARIANTS,
   WIZARD_ORCHESTRATOR_FLAG_KEY,
   WIZARD_USER_AGENT,
+  DEFAULT_AGENT_MODEL,
 } from '@lib/constants';
 import {
   type AdditionalFeature,
@@ -133,6 +134,11 @@ export type AgentConfig = {
   wizardMetadata?: Record<string, string>;
   /** Program identifier — selects the model for that program. */
   integrationLabel?: string;
+  /**
+   * Override the agent model for this run. Defaults to DEFAULT_AGENT_MODEL.
+   * Use for cheap mechanical runs (e.g. source-map detection on HAIKU_MODEL).
+   */
+  modelOverride?: string;
   /** Bridge that drives the `wizard_ask` overlay. Omit in non-interactive hosts. */
   askBridge?: import('@lib/wizard-ask-bridge').WizardAskBridge;
   /** Per-run cap on `wizard_ask` invocations. Defaults to 10. */
@@ -547,15 +553,16 @@ export async function initializeAgent(
   logToFile('Install directory:', options.installDir);
 
   try {
-    // Configure LLM gateway environment variables (inherited by SDK subprocess)
+    // Configure model routing (inherited by the SDK subprocess). All model
+    // calls route through the PostHog LLM gateway, authed with the user's
+    // OAuth token.
+    // Disable experimental betas (like input_examples) the gateway doesn't support.
+    process.env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = 'true';
     const gatewayUrl = getLlmGatewayUrlFromHost(config.posthogApiHost);
     process.env.ANTHROPIC_BASE_URL = gatewayUrl;
     process.env.ANTHROPIC_AUTH_TOKEN = config.posthogApiKey;
     // Use CLAUDE_CODE_OAUTH_TOKEN to override any stored /login credentials
     process.env.CLAUDE_CODE_OAUTH_TOKEN = config.posthogApiKey;
-    // Disable experimental betas (like input_examples) that the LLM gateway doesn't support
-    process.env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = 'true';
-
     logToFile('Configured LLM gateway:', gatewayUrl);
     logToFile(
       'API key prefix:',
@@ -603,7 +610,7 @@ export async function initializeAgent(
 
     // Bare model IDs (no `anthropic/` prefix) so the LLM gateway's Bedrock
     // fallback can match map_to_bedrock_model()'s strict lookup.
-    const model = 'claude-sonnet-4-6';
+    const model = config.modelOverride ?? DEFAULT_AGENT_MODEL;
 
     const agentRunConfig: AgentRunConfig = {
       workingDirectory: config.workingDirectory,
@@ -677,6 +684,11 @@ export async function runAgent(
     errorMessage?: string;
     additionalFeatureQueue?: readonly AdditionalFeature[];
     abortCases?: readonly AbortCaseMatcher[];
+    /**
+     * Emit a `wizard: step` event on each agent task transition. Threaded from
+     * `ProgramRun.trackStepProgress`; defaults off for every other caller.
+     */
+    emitStepEvents?: boolean;
     /** Request the end-of-run reflection remark. Defaults to true. */
     requestRemark?: boolean;
     /**
@@ -695,6 +707,7 @@ export async function runAgent(
     successMessage = 'PostHog integration complete',
     errorMessage = 'Integration failed',
     abortCases = [],
+    emitStepEvents = false,
   } = config ?? {};
 
   logToFile('Starting agent run');
@@ -905,7 +918,8 @@ export async function runAgent(
         },
         env: {
           ...process.env,
-          // Prevent user's Anthropic API key from overriding the wizard's OAuth token
+          // Drop any shell ANTHROPIC_API_KEY so it can't override the wizard's
+          // OAuth gateway token.
           ANTHROPIC_API_KEY: undefined,
           // Defer MCP tool schemas to avoid bloating the system prompt.
           // The posthog-wizard MCP exposes many query tools with large schemas;
@@ -921,6 +935,7 @@ export async function runAgent(
           // disables tool search deferral and re-inflates the system prompt by
           // ~113k tokens (the reason ENABLE_TOOL_SEARCH=auto:0 is set above).
           MCP_CONNECTION_NONBLOCKING: '0',
+          // PostHog gateway headers: Bedrock fallback + property/flag tags.
           ANTHROPIC_CUSTOM_HEADERS: buildAgentEnv(
             agentConfig.wizardMetadata ?? {},
             agentConfig.wizardFlags ?? {},
@@ -1014,6 +1029,7 @@ export async function runAgent(
         receivedSuccessResult,
         tasks,
         isOrchestratorEnabled(agentConfig.wizardFlags ?? {}),
+        emitStepEvents,
       );
 
       // [ABORT] detection: the skill emits "[ABORT] <reason>" when it
@@ -1246,6 +1262,8 @@ type TaskEntry = { content: string; status: string; activeForm?: string };
 interface TaskStore {
   tasks: Map<string, TaskEntry>;
   sync: () => void;
+  /** When true, emit a `wizard: step` event on each status transition. */
+  emitStepEvents?: boolean;
 }
 
 interface ToolUseBlock {
@@ -1285,6 +1303,36 @@ function handleTaskUpdate(block: ToolUseBlock, store: TaskStore): void {
   if (input.status === 'deleted') {
     store.tasks.delete(input.taskId);
   } else {
+    // Per-step drop-off signal for programs that opt in via `trackStepProgress`
+    // (threaded here as `emitStepEvents`). Emit `wizard: step` on each real
+    // status transition so analytics can see how far a run got — even a silent
+    // step (no wizard_ask) that dies mid-run surfaces as its last `in_progress`
+    // with no matching `completed`. Generic: the step name is whatever the
+    // agent set; the `command` tag already identifies the program.
+    if (
+      store.emitStepEvents &&
+      input.status &&
+      input.status !== existing.status &&
+      (input.status === 'in_progress' || input.status === 'completed')
+    ) {
+      const keys = [...store.tasks.keys()];
+      analytics.wizardCapture('step', {
+        // The task's display label lives on `activeForm` (what the TUI renders,
+        // e.g. "Checking access"); `content`/`subject` are typically empty on a
+        // status-only TaskUpdate. Prefer the stored entry, then the update, so
+        // the name is never null. Named `step_name` (not `step`): a bare
+        // `properties.step` doesn't resolve in HogQL — `step_name` queries
+        // cleanly, like `step_index` / `step_count`.
+        step_name:
+          existing.activeForm ??
+          input.activeForm ??
+          existing.content ??
+          input.subject,
+        status: input.status,
+        step_index: keys.indexOf(input.taskId),
+        step_count: keys.length,
+      });
+    }
     store.tasks.set(input.taskId, {
       content: input.subject ?? existing.content,
       status: input.status ?? existing.status,
@@ -1368,6 +1416,9 @@ function handleSDKMessage(
   // The orchestrator owns the TUI task panel (it renders its queue). Suppress the
   // agent's own TaskCreate/TaskUpdate rendering so it does not clobber the queue.
   suppressTaskRender = false,
+  // Opt-in per-step analytics, threaded from runAgent's `emitStepEvents`
+  // (ProgramRun.trackStepProgress). Off for every program that doesn't opt in.
+  emitStepEvents = false,
 ): void {
   // Map preserves insertion order (the order the agent created the tasks).
   // Within that, group by status: completed first, then in_progress, then
@@ -1453,6 +1504,7 @@ function handleSDKMessage(
             dispatchTaskToolUse(block as ToolUseBlock, {
               tasks,
               sync: syncTasks,
+              emitStepEvents,
             });
           }
 

src/lib/agent/mcp-prompt-streaming.ts

@@ -194,11 +194,12 @@ export async function* runMcpPromptViaSdk(args: {
   // before its query() call. Without these the SDK tries to
   // authenticate directly against Anthropic and 401s with "Invalid
   // authentication credentials".
+  process.env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = 'true';
+  // Route through the PostHog LLM gateway, authed with the user's OAuth token.
   const gatewayUrl = getLlmGatewayUrlFromHost(credentials.host);
   process.env.ANTHROPIC_BASE_URL = gatewayUrl;
   process.env.ANTHROPIC_AUTH_TOKEN = credentials.accessToken;
   process.env.CLAUDE_CODE_OAUTH_TOKEN = credentials.accessToken;
-  process.env.CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = 'true';
   logToFile(
     `[runMcpPromptViaSdk] gatewayUrl=${gatewayUrl} tokenPrefix=${
       credentials.accessToken
@@ -315,10 +316,8 @@ export async function* runMcpPromptViaSdk(args: {
         allowedTools: ['mcp__posthog-wizard__*'],
         env: {
           ...process.env,
-          // Without this the SDK picks up a user's personal
-          // ANTHROPIC_API_KEY from their shell and silently bypasses
-          // the PostHog LLM gateway — defeats quota tracking and the
-          // OAuth flow even though our other env vars are correct.
+          // Drop any shell ANTHROPIC_API_KEY so it can't silently bypass the
+          // PostHog LLM gateway and defeat quota tracking and the OAuth flow.
           ANTHROPIC_API_KEY: undefined,
           // Defer MCP tool schemas to avoid bloating the system prompt.
           // posthog-wizard exposes many query tools with large schemas;

src/lib/agent/runner/linear.ts

@@ -163,6 +163,7 @@ export async function runLinearProgram(
       errorMessage: config.errorMessage ?? `${config.integrationLabel} failed`,
       additionalFeatureQueue: config.additionalFeatureQueue ?? [],
       abortCases: config.abortCases,
+      emitStepEvents: config.trackStepProgress ?? false,
     },
     middleware,
   );

src/lib/agent/runner/shared/bootstrap.ts

@@ -210,6 +210,22 @@ export async function bootstrapProgram(
   await getUI().waitForAiOptIn();
   logToFile('[agent-runner] AI opt-in gate cleared');
 
+  // Park for any interactive step the user must complete AFTER authenticating
+  // but BEFORE the agent runs — e.g. the source-maps project picker, which
+  // needs credentials to scan and writes its choice to frameworkContext that
+  // the run prompt reads. Generic: await every gated step between auth and run.
+  const authIndex = programConfig.steps.findIndex((s) => s.screenId === 'auth');
+  const runIndex = programConfig.steps.findIndex((s) => s.screenId === 'run');
+  if (authIndex !== -1 && runIndex > authIndex) {
+    for (const step of programConfig.steps.slice(authIndex + 1, runIndex)) {
+      if (step.gate) {
+        logToFile(`[agent-runner] awaiting post-auth gate: ${step.id}`);
+        await getUI().waitForGate(step.id);
+        logToFile(`[agent-runner] post-auth gate cleared: ${step.id}`);
+      }
+    }
+  }
+
   // Feature flags, variant metadata, and MCP url. Both arms need these, and the
   // fork decision reads the flags.
   const wizardFlags = await analytics.getAllFlagsForWizard();

src/lib/agent/runner/shared/types.ts

@@ -79,6 +79,14 @@ export interface ProgramRun {
    * key in the browser) before they can answer.
    */
   askTimeoutMs?: number;
+  /**
+   * Emit a `wizard: step` analytics event on each agent task-list transition
+   * (in_progress / completed) so this program can build a step-level drop-off
+   * funnel — including silent steps that ask the user nothing. The step name is
+   * whatever the agent set on the task. Defaults to off, so no other program's
+   * analytics change; opt in per program.
+   */
+  trackStepProgress?: boolean;
 }
 
 /**

src/lib/constants.ts

@@ -4,6 +4,20 @@
 
 import { VERSION } from './version';
 
+// ── Models ──────────────────────────────────────────────────────────
+
+/**
+ * Default model for agent runs. Bare model IDs (no `anthropic/` prefix) so the
+ * LLM gateway's Bedrock fallback can match map_to_bedrock_model().
+ */
+export const DEFAULT_AGENT_MODEL = 'claude-sonnet-4-6';
+
+/**
+ * Cheaper, faster model for mechanical agent work (e.g. repo classification
+ * during source-map detection). Passed via AgentConfig.modelOverride.
+ */
+export const HAIKU_MODEL = 'claude-haiku-4-5-20251001';
+
 // ── Integration / CLI ───────────────────────────────────────────────
 
 /**

src/lib/detection/__tests__/agentic.test.ts

@@ -0,0 +1,78 @@
+import { coerceAgenticReport, manifestGlob } from '@lib/detection/agentic';
+
+const TARGETS = ['nextjs', 'node', 'vite'];
+
+describe('manifestGlob', () => {
+  it('is one brace-expansion glob covering JS, Python, Ruby, PHP and native manifests', () => {
+    const glob = manifestGlob();
+    expect(glob.startsWith('**/{')).toBe(true);
+    expect(glob.endsWith('}')).toBe(true);
+    for (const name of [
+      'package.json',
+      'pnpm-workspace.yaml',
+      'requirements.txt',
+      'Gemfile',
+      'composer.json',
+      'Cargo.toml',
+      'go.mod',
+      'build.gradle',
+      'pubspec.yaml',
+    ]) {
+      expect(glob).toContain(name);
+    }
+  });
+});
+
+describe('coerceAgenticReport', () => {
+  it('keeps a targetId that is in the valid set', () => {
+    const report = coerceAgenticReport(
+      {
+        repoType: 'single',
+        projects: [
+          {
+            path: '.',
+            framework: 'Next.js',
+            targetId: 'nextjs',
+            hasPostHog: true,
+          },
+        ],
+      },
+      TARGETS,
+    );
+
+    expect(report.repoType).toBe('single');
+    expect(report.projects[0].targetId).toBe('nextjs');
+    expect(report.projects[0].hasPostHog).toBe(true);
+  });
+
+  it('clamps an unknown targetId to null', () => {
+    const report = coerceAgenticReport(
+      {
+        repoType: 'monorepo',
+        projects: [
+          {
+            path: 'apps/api',
+            framework: 'Rust',
+            targetId: 'rocket',
+            hasPostHog: true,
+          },
+        ],
+      },
+      TARGETS,
+    );
+
+    expect(report.projects[0].targetId).toBeNull();
+  });
+
+  it('defaults malformed fields and an absent projects array', () => {
+    expect(coerceAgenticReport({}, TARGETS).projects).toEqual([]);
+    expect(coerceAgenticReport(null, TARGETS).projects).toEqual([]);
+
+    const report = coerceAgenticReport({ projects: [{}] }, TARGETS);
+    const p = report.projects[0];
+    expect(p.path).toBe('.');
+    expect(p.framework).toBe('Unknown');
+    expect(p.targetId).toBeNull();
+    expect(p.hasPostHog).toBe(false);
+  });
+});