feat(orchestrator): variant gating + shared bootstrap extraction

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gewenyu99

src/env.ts

@@ -44,6 +44,9 @@ type RuntimeEnvKey =
   | 'POSTHOG_WIZARD_BENCHMARK_FILE'
   | 'POSTHOG_WIZARD_LOG_DIR'
   | 'POSTHOG_WIZARD_DEBUG'
+  // Dev-only feature-flag override (JSON map of flagKey -> value). No effect in
+  // published builds, where IS_PRODUCTION_BUILD is true.
+  | 'POSTHOG_WIZARD_FORCE_FLAGS'
   | 'DEBUG'
   // Agent / MCP
   | 'MCP_URL'

src/lib/agent/__tests__/variant-gating.test.ts

@@ -0,0 +1,39 @@
+import {
+  buildWizardMetadata,
+  isOrchestratorVariant,
+} from '@lib/agent/agent-interface';
+
+describe('isOrchestratorVariant', () => {
+  it('is true only when the wizard-variant flag is orchestrator', () => {
+    expect(isOrchestratorVariant({ 'wizard-variant': 'orchestrator' })).toBe(
+      true,
+    );
+  });
+
+  it('is false for other variants, a missing flag, and no flags', () => {
+    expect(isOrchestratorVariant({ 'wizard-variant': 'base' })).toBe(false);
+    expect(isOrchestratorVariant({ 'wizard-variant': 'subagents' })).toBe(
+      false,
+    );
+    expect(isOrchestratorVariant({ 'some-other-flag': 'orchestrator' })).toBe(
+      false,
+    );
+    expect(isOrchestratorVariant({})).toBe(false);
+    expect(isOrchestratorVariant()).toBe(false);
+  });
+});
+
+describe('buildWizardMetadata', () => {
+  it('selects the orchestrator variant header from the flag', () => {
+    expect(buildWizardMetadata({ 'wizard-variant': 'orchestrator' })).toEqual({
+      VARIANT: 'orchestrator',
+    });
+  });
+
+  it('falls back to the base variant for unknown or missing flags', () => {
+    expect(buildWizardMetadata({ 'wizard-variant': 'nope' })).toEqual({
+      VARIANT: 'base',
+    });
+    expect(buildWizardMetadata({})).toEqual({ VARIANT: 'base' });
+  });
+});

src/lib/agent/agent-interface.ts

@@ -363,6 +363,18 @@ export function buildWizardMetadata(
   return { ...variant };
 }
 
+/**
+ * Whether this run uses the experimental task-queue orchestrator. Selected by the
+ * `wizard-variant` feature flag value `orchestrator`. Gating is the flag: target it
+ * to your user in PostHog, or in a dev build force it with
+ * `POSTHOG_WIZARD_FORCE_FLAGS='{"wizard-variant":"orchestrator"}'`.
+ */
+export function isOrchestratorVariant(
+  flags: Record<string, string> = {},
+): boolean {
+  return flags[WIZARD_VARIANT_FLAG_KEY] === 'orchestrator';
+}
+
 /**
  * Build env for the SDK subprocess: process.env plus ANTHROPIC_CUSTOM_HEADERS, which always
  * includes `x-posthog-use-bedrock-fallback: true` so the LLM gateway falls back to Bedrock on

src/lib/agent/agent-runner.ts

@@ -9,9 +9,11 @@
  *   - What MCP servers and package manager detector to use
  *   - What happens after the agent completes
  *
- * The pipeline itself is fixed:
- *   init → health check → settings → OAuth → [skill install] →
- *   agent init → prompt → run → errors → [postRun] → outro
+ * The pipeline runs a shared bootstrap (logging, health check, settings, OAuth,
+ * flags, MCP url), then forks. The `orchestrator` variant routes to the
+ * experimental task-queue runner. Every other variant runs the fixed linear
+ * pipeline:
+ *   [skill install] → agent init → prompt → run → errors → [postRun] → outro
  */
 
 import {
@@ -29,10 +31,12 @@ import {
   AgentErrorType,
   AgentSignals,
   buildWizardMetadata,
+  isOrchestratorVariant,
   checkAllSettingsConflicts,
   backupAndFixClaudeSettings,
   restoreClaudeSettings,
 } from './agent-interface';
+import { runOrchestrator } from '../programs/orchestrator/orchestrator-runner';
 import { getCloudUrlFromRegion } from '@utils/urls';
 import {
   evaluateWizardReadiness,
@@ -51,7 +55,7 @@ import { getSkillsBaseUrl } from '@lib/constants';
 import { runtimeEnv } from '@env';
 import { installSkillById, type InstallSkillResult } from '@lib/wizard-tools';
 import { createWizardAskBridge } from '@lib/wizard-ask-bridge';
-import type { WizardRunOptions } from '@utils/types';
+import type { WizardRunOptions, CloudRegion } from '@utils/types';
 
 import type { ProgramConfig } from '@lib/programs/program-step';
 import { assemblePrompt, type PromptContext } from './agent-prompt';
@@ -106,7 +110,7 @@ export interface ProgramRun {
   buildOutroData?: (
     session: WizardSession,
     credentials: Credentials,
-    cloudRegion: import('@utils/types').CloudRegion | undefined,
+    cloudRegion: CloudRegion | undefined,
   ) => WizardSession['outroData'];
   /**
    * Per-run cap on `wizard_ask` invocations. Defaults to 10. The 4th call
@@ -115,6 +119,23 @@ export interface ProgramRun {
   maxQuestions?: number;
 }
 
+/**
+ * Result of the shared bootstrap, consumed by both the linear and the
+ * orchestrator arm. Credentials, role, and user are already applied to the
+ * session by `bootstrapProgram`; this carries the values both arms still need.
+ */
+export interface BootstrapResult {
+  skillsBaseUrl: string;
+  projectApiKey: Credentials['projectApiKey'];
+  host: Credentials['host'];
+  accessToken: Credentials['accessToken'];
+  projectId: Credentials['projectId'];
+  cloudRegion: CloudRegion;
+  mcpUrl: string;
+  wizardFlags: Record<string, string>;
+  wizardMetadata: Record<string, string>;
+}
+
 // ── Helpers ──────────────────────────────────────────────────────────
 
 /**
@@ -170,16 +191,35 @@ export async function runAgent(
 /**
  * Run a program's agent pipeline.
  *
- * This is the single execution path for all programs — both skill-based
- * (revenue analytics) and framework-based (core integration). The
- * `ProgramRun` controls what varies between them; `programConfig` carries
- * the program-level static metadata (tool allow/disallow lists, etc.).
+ * Runs the shared bootstrap, then forks on the `wizard-variant` flag. The
+ * `orchestrator` variant routes to the experimental task-queue runner; every
+ * other variant runs the linear pipeline.
  */
 export async function runProgram(
   session: WizardSession,
   config: ProgramRun,
   programConfig: ProgramConfig,
 ): Promise<void> {
+  const boot = await bootstrapProgram(session, config, programConfig);
+
+  if (isOrchestratorVariant(boot.wizardFlags)) {
+    return runOrchestrator(session, programConfig, boot);
+  }
+
+  return runLinearProgram(session, config, programConfig, boot);
+}
+
+/**
+ * Shared setup for both arms: logging, health check, settings conflicts, OAuth
+ * and credentials, then the feature flags, variant metadata, and MCP url. Sets
+ * `session.credentials`, role, and user as a side effect. Returns the values the
+ * arms still need.
+ */
+async function bootstrapProgram(
+  session: WizardSession,
+  config: ProgramRun,
+  programConfig: ProgramConfig,
+): Promise<BootstrapResult> {
   // 1. Init logging + debug
   initLogFile();
   session.skillId = config.skillId ?? config.integrationLabel;
@@ -283,6 +323,55 @@ export async function runProgram(
 
   analytics.setGroups(groupsFromUser(user, host));
 
+  // Feature flags, variant metadata, and MCP url. Both arms need these, and the
+  // fork decision reads the flags.
+  const wizardFlags = await analytics.getAllFlagsForWizard();
+  const wizardMetadata = buildWizardMetadata(wizardFlags);
+
+  const mcpUrl = session.localMcp
+    ? 'http://localhost:8787/mcp'
+    : runtimeEnv('MCP_URL') ||
+      (cloudRegion === 'eu'
+        ? 'https://mcp-eu.posthog.com/mcp'
+        : 'https://mcp.posthog.com/mcp');
+
+  return {
+    skillsBaseUrl,
+    projectApiKey,
+    host,
+    accessToken,
+    projectId,
+    cloudRegion,
+    mcpUrl,
+    wizardFlags,
+    wizardMetadata,
+  };
+}
+
+/**
+ * The linear pipeline. Single execution path for all non-orchestrator programs,
+ * both skill-based (revenue analytics) and framework-based (core integration).
+ * The `ProgramRun` controls what varies between them; `programConfig` carries the
+ * program-level static metadata (tool allow/disallow lists, etc.).
+ */
+async function runLinearProgram(
+  session: WizardSession,
+  config: ProgramRun,
+  programConfig: ProgramConfig,
+  boot: BootstrapResult,
+): Promise<void> {
+  const {
+    skillsBaseUrl,
+    projectApiKey,
+    host,
+    accessToken,
+    projectId,
+    cloudRegion,
+    mcpUrl,
+    wizardFlags,
+    wizardMetadata,
+  } = boot;
+
   // 5. Skill install (if skillId provided)
   let skillPath: string | undefined;
   if (config.skillId) {
@@ -302,15 +391,6 @@ export async function runProgram(
 
   // 6. Initialize agent
   const spinner = getUI().spinner();
-  const wizardFlags = await analytics.getAllFlagsForWizard();
-  const wizardMetadata = buildWizardMetadata(wizardFlags);
-
-  const mcpUrl = session.localMcp
-    ? 'http://localhost:8787/mcp'
-    : runtimeEnv('MCP_URL') ||
-      (cloudRegion === 'eu'
-        ? 'https://mcp-eu.posthog.com/mcp'
-        : 'https://mcp.posthog.com/mcp');
 
   const restoreSettings = () => restoreClaudeSettings(session.installDir);
   getUI().onEnterScreen('outro', restoreSettings);

src/lib/constants.ts

@@ -147,6 +147,7 @@ export const WIZARD_TOOLS_MENU_FLAG_KEY = 'wizard-tools-menu';
 export const WIZARD_VARIANTS: Record<string, Record<string, string>> = {
   base: { VARIANT: 'base' },
   subagents: { VARIANT: 'subagents' },
+  orchestrator: { VARIANT: 'orchestrator' },
 };
 /** User-Agent for wizard HTTP requests and MCP server identification. */
 export const WIZARD_USER_AGENT = `posthog/wizard; version: ${VERSION}`;

src/lib/programs/orchestrator/orchestrator-runner.ts

@@ -0,0 +1,33 @@
+/**
+ * Experimental task-queue orchestrator runner.
+ *
+ * Branches from the linear runner when the `wizard-variant` feature flag is
+ * `orchestrator`. The shape: an orchestrator agent inspects the repo and seeds an
+ * in-memory task queue, and an executor drains it one fresh agent per task.
+ *
+ * This is the stub. It logs, emits a start event, and returns. The queue, the
+ * executor, and the seeding agent land in the following issues.
+ */
+import type { WizardSession } from '../../wizard-session';
+import type { ProgramConfig } from '../program-step';
+import type { BootstrapResult } from '../../agent/agent-runner';
+import { getUI } from '../../../ui';
+import { logToFile } from '../../../utils/debug';
+import { analytics } from '../../../utils/analytics';
+
+export function runOrchestrator(
+  session: WizardSession,
+  programConfig: ProgramConfig,
+  boot: BootstrapResult,
+): Promise<void> {
+  logToFile(
+    `[orchestrator] START program=${programConfig.id} dir=${session.installDir} variant=${boot.wizardMetadata.VARIANT}`,
+  );
+  analytics.wizardCapture('orchestrator started', {
+    program_id: programConfig.id,
+  });
+  getUI().log.info(
+    'Orchestrator variant is active. This runner is a stub for now; the queue and executor land in the following issues.',
+  );
+  return Promise.resolve();
+}

src/utils/analytics.ts

@@ -8,6 +8,33 @@ import type { WizardSession } from '@lib/wizard-session';
 import type { ApiUser } from '@lib/api';
 import { v4 as uuidv4 } from 'uuid';
 import { debug } from './debug';
+import { IS_PRODUCTION_BUILD, runtimeEnv } from '@env';
+
+/**
+ * Dev-only feature-flag override. In non-production builds,
+ * `POSTHOG_WIZARD_FORCE_FLAGS` (a JSON object of flagKey -> value) is merged over
+ * the evaluated flags, so a developer can force e.g.
+ * `{"wizard-variant":"orchestrator"}` without targeting the flag in PostHog. It
+ * has no effect in published builds, where `IS_PRODUCTION_BUILD` is true.
+ */
+function applyDevFlagOverrides(
+  flags: Record<string, string>,
+): Record<string, string> {
+  if (IS_PRODUCTION_BUILD) return flags;
+  const raw = runtimeEnv('POSTHOG_WIZARD_FORCE_FLAGS');
+  if (!raw) return flags;
+  try {
+    const overrides = JSON.parse(raw) as Record<string, unknown>;
+    const merged = { ...flags };
+    for (const [key, value] of Object.entries(overrides)) {
+      merged[key] = String(value);
+    }
+    return merged;
+  } catch (error) {
+    debug('Invalid POSTHOG_WIZARD_FORCE_FLAGS:', error);
+    return flags;
+  }
+}
 
 /**
  * Extract a standard property bag from the current session.
@@ -144,23 +171,24 @@ export class Analytics {
     if (this.activeFlags !== null) {
       return this.activeFlags;
     }
+    let out: Record<string, string> = {};
     try {
       const distinctId = this.distinctId ?? this.anonymousId;
       const result = await this.client.getAllFlagsAndPayloads(distinctId, {
         personProperties: { $app_name: this.appName },
       });
       const flags = result.featureFlags ?? {};
-      const out: Record<string, string> = {};
       for (const [key, value] of Object.entries(flags)) {
         if (value === undefined) continue;
         out[key] = typeof value === 'boolean' ? String(value) : String(value);
       }
-      this.activeFlags = out;
-      return out;
     } catch (error) {
       debug('Failed to get all feature flags:', error);
-      return {};
+      out = {};
     }
+    out = applyDevFlagOverrides(out);
+    this.activeFlags = out;
+    return out;
   }
 
   async shutdown(status: 'success' | 'error' | 'cancelled') {