🤖 feat: Add PostHog experiments integration

Add backend-first PostHog feature flag evaluation for remote-controlled
experiments, starting with Post-Compaction Context.

Backend (ExperimentsService):
- Evaluate PostHog feature flags via posthog-node
- Disk cache (~/.mux/feature_flags.json) with TTL-based refresh
- Fail-closed behavior (unknown = disabled)
- Disable calls when telemetry is off

Telemetry enrichment (TelemetryService):
- setFeatureFlagVariant() adds $feature/<flagKey> to all events
- Enables variant breakdown in PostHog analytics

oRPC layer:
- experiments.getAll: Get all experiment values
- experiments.reload: Force refresh from PostHog

Frontend (ExperimentsContext):
- Fetch remote experiments on mount
- Priority: remote PostHog > local toggle > default
- Read-only UI when experiment is remote-controlled

Backend authoritative gating (WorkspaceService):
- sendMessage() resolves experiment from PostHog when enabled
- list() decides includePostCompaction based on experiment

Type consolidation:
- ExperimentValueSchema (Zod) is single source of truth
- ExperimentValue type derived via z.infer in types.ts

Bug fixes (unrelated):
- Fixed backgroundProcessManager exit race condition
- Fixed telemetry client Node.js compatibility
- Relaxed timing test threshold in authMiddleware

Change-Id: I346c924324a5f59cb3349614382dc8a5276e5e1e
Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

src/browser/components/Settings/sections/ExperimentsSection.tsx

@@ -1,5 +1,5 @@
 import React, { useCallback } from "react";
-import { useExperiment } from "@/browser/contexts/ExperimentsContext";
+import { useExperiment, useRemoteExperimentValue } from "@/browser/contexts/ExperimentsContext";
 import {
   getExperimentList,
   EXPERIMENT_IDS,
@@ -17,24 +17,36 @@ interface ExperimentRowProps {
 
 function ExperimentRow(props: ExperimentRowProps) {
   const [enabled, setEnabled] = useExperiment(props.experimentId);
+  const remote = useRemoteExperimentValue(props.experimentId);
+  const isRemoteControlled = remote ? remote.source !== "disabled" : false;
   const { onToggle } = props;
 
   const handleToggle = useCallback(
     (value: boolean) => {
+      if (isRemoteControlled) {
+        return;
+      }
+
       setEnabled(value);
       onToggle?.(value);
     },
-    [setEnabled, onToggle]
+    [isRemoteControlled, setEnabled, onToggle]
   );
 
   return (
     <div className="flex items-center justify-between py-3">
       <div className="flex-1 pr-4">
         <div className="text-foreground text-sm font-medium">{props.name}</div>
         <div className="text-muted mt-0.5 text-xs">{props.description}</div>
+        {isRemoteControlled ? (
+          <div className="text-muted mt-0.5 text-xs">
+            PostHog: {remote?.value ?? "loading"} ({remote?.source})
+          </div>
+        ) : null}
       </div>
       <Switch
         checked={enabled}
+        disabled={isRemoteControlled}
         onCheckedChange={handleToggle}
         aria-label={`Toggle ${props.name}`}
       />

src/browser/contexts/ExperimentsContext.tsx

@@ -1,11 +1,20 @@
-import React, { createContext, useContext, useSyncExternalStore, useCallback } from "react";
+import React, {
+  createContext,
+  useContext,
+  useSyncExternalStore,
+  useCallback,
+  useEffect,
+  useState,
+} from "react";
 import {
   type ExperimentId,
   EXPERIMENTS,
   getExperimentKey,
   getExperimentList,
 } from "@/common/constants/experiments";
 import { getStorageChangeEvent } from "@/common/constants/events";
+import type { ExperimentValue } from "@/common/orpc/types";
+import { useAPI } from "@/browser/contexts/API";
 
 /**
  * Subscribe to experiment changes for a specific experiment ID.
@@ -48,6 +57,15 @@ function getExperimentSnapshot(experimentId: ExperimentId): boolean {
 /**
  * Set experiment state to localStorage and dispatch sync event.
  */
+
+function getRemoteExperimentEnabled(value: string | boolean): boolean {
+  if (typeof value === "boolean") {
+    return value;
+  }
+
+  // For now, our PostHog experiment uses control/test variants.
+  return value === "test";
+}
 function setExperimentState(experimentId: ExperimentId, enabled: boolean): void {
   const key = getExperimentKey(experimentId);
 
@@ -70,6 +88,8 @@ function setExperimentState(experimentId: ExperimentId, enabled: boolean): void
  */
 interface ExperimentsContextValue {
   setExperiment: (experimentId: ExperimentId, enabled: boolean) => void;
+  remoteExperiments: Partial<Record<ExperimentId, ExperimentValue>> | null;
+  reloadRemoteExperiments: () => Promise<void>;
 }
 
 const ExperimentsContext = createContext<ExperimentsContextValue | null>(null);
@@ -83,8 +103,48 @@ export function ExperimentsProvider(props: { children: React.ReactNode }) {
     setExperimentState(experimentId, enabled);
   }, []);
 
+  const apiState = useAPI();
+  const [remoteExperiments, setRemoteExperiments] = useState<Partial<
+    Record<ExperimentId, ExperimentValue>
+  > | null>(null);
+
+  const loadRemoteExperiments = useCallback(async () => {
+    if (apiState.status !== "connected" || !apiState.api) {
+      setRemoteExperiments(null);
+      return;
+    }
+
+    try {
+      const result = await apiState.api.experiments.getAll();
+      setRemoteExperiments(result as Partial<Record<ExperimentId, ExperimentValue>>);
+    } catch {
+      setRemoteExperiments(null);
+    }
+  }, [apiState.status, apiState.api]);
+
+  const reloadRemoteExperiments = useCallback(async () => {
+    if (apiState.status !== "connected" || !apiState.api) {
+      setRemoteExperiments(null);
+      return;
+    }
+
+    try {
+      await apiState.api.experiments.reload();
+    } catch {
+      // Best effort
+    }
+
+    await loadRemoteExperiments();
+  }, [apiState.status, apiState.api, loadRemoteExperiments]);
+
+  useEffect(() => {
+    void loadRemoteExperiments();
+  }, [loadRemoteExperiments]);
+
   return (
-    <ExperimentsContext.Provider value={{ setExperiment }}>
+    <ExperimentsContext.Provider
+      value={{ setExperiment, remoteExperiments, reloadRemoteExperiments }}
+    >
       {props.children}
     </ExperimentsContext.Provider>
   );
@@ -106,7 +166,16 @@ export function useExperimentValue(experimentId: ExperimentId): boolean {
 
   const getSnapshot = useCallback(() => getExperimentSnapshot(experimentId), [experimentId]);
 
-  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const localEnabled = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+  const context = useContext(ExperimentsContext);
+  const remote = context?.remoteExperiments?.[experimentId];
+
+  if (remote && remote.source !== "disabled" && remote.value !== null) {
+    return getRemoteExperimentEnabled(remote.value);
+  }
+
+  return localEnabled;
 }
 
 /**
@@ -115,6 +184,11 @@ export function useExperimentValue(experimentId: ExperimentId): boolean {
  *
  * @returns Function to set experiment state
  */
+
+export function useRemoteExperimentValue(experimentId: ExperimentId): ExperimentValue | null {
+  const context = useContext(ExperimentsContext);
+  return context?.remoteExperiments?.[experimentId] ?? null;
+}
 export function useSetExperiment(): (experimentId: ExperimentId, enabled: boolean) => void {
   const context = useContext(ExperimentsContext);
   if (!context) {
@@ -149,6 +223,8 @@ export function useExperiment(experimentId: ExperimentId): [boolean, (enabled: b
  */
 export function useAllExperiments(): Record<ExperimentId, boolean> {
   const experiments = getExperimentList();
+  const context = useContext(ExperimentsContext);
+  const remoteExperiments = context?.remoteExperiments;
 
   // Subscribe to all experiments
   const subscribe = useCallback(
@@ -164,8 +240,21 @@ export function useAllExperiments(): Record<ExperimentId, boolean> {
     for (const exp of experiments) {
       result[exp.id] = getExperimentSnapshot(exp.id);
     }
+
+    if (remoteExperiments) {
+      for (const [experimentId, remote] of Object.entries(remoteExperiments) as Array<
+        [ExperimentId, ExperimentValue]
+      >) {
+        if (!remote || remote.source === "disabled" || remote.value === null) {
+          continue;
+        }
+
+        result[experimentId] = getRemoteExperimentEnabled(remote.value);
+      }
+    }
+
     return result as Record<ExperimentId, boolean>;
-  }, [experiments]);
+  }, [experiments, remoteExperiments]);
 
   return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 }

src/cli/cli.test.ts

@@ -70,6 +70,7 @@ async function createTestServer(authToken?: string): Promise<TestServerHandle> {
     serverService: services.serverService,
     mcpConfigService: services.mcpConfigService,
     mcpServerManager: services.mcpServerManager,
+    experimentsService: services.experimentsService,
     menuEventService: services.menuEventService,
     voiceService: services.voiceService,
     telemetryService: services.telemetryService,

src/cli/server.test.ts

@@ -74,6 +74,7 @@ async function createTestServer(): Promise<TestServerHandle> {
     mcpConfigService: services.mcpConfigService,
     mcpServerManager: services.mcpServerManager,
     menuEventService: services.menuEventService,
+    experimentsService: services.experimentsService,
     voiceService: services.voiceService,
     telemetryService: services.telemetryService,
     sessionUsageService: services.sessionUsageService,

src/cli/server.ts

@@ -92,6 +92,7 @@ const mockWindow: BrowserWindow = {
     mcpServerManager: serviceContainer.mcpServerManager,
     voiceService: serviceContainer.voiceService,
     telemetryService: serviceContainer.telemetryService,
+    experimentsService: serviceContainer.experimentsService,
     sessionUsageService: serviceContainer.sessionUsageService,
   };
 

src/common/orpc/schemas.ts

@@ -111,6 +111,8 @@ export {
   ProvidersConfigMapSchema,
   server,
   splashScreens,
+  experiments,
+  ExperimentValueSchema,
   telemetry,
   TelemetryEventSchema,
   terminal,

src/common/orpc/schemas/api.ts

@@ -26,6 +26,22 @@ import {
   WorkspaceMCPOverridesSchema,
 } from "./mcp";
 
+// Experiments
+export const ExperimentValueSchema = z.object({
+  value: z.union([z.string(), z.boolean(), z.null()]),
+  source: z.enum(["posthog", "cache", "disabled"]),
+});
+
+export const experiments = {
+  getAll: {
+    input: z.void(),
+    output: z.record(z.string(), ExperimentValueSchema),
+  },
+  reload: {
+    input: z.void(),
+    output: z.void(),
+  },
+};
 // Re-export telemetry schemas
 export { telemetry, TelemetryEventSchema } from "./telemetry";
 

src/common/orpc/types.ts

@@ -34,6 +34,9 @@ export type FrontendWorkspaceMetadataSchemaType = z.infer<
   typeof schemas.FrontendWorkspaceMetadataSchema
 >;
 
+// Experiment types (single source of truth - derived from schemas)
+export type ExperimentValue = z.infer<typeof schemas.ExperimentValueSchema>;
+
 // Type guards for common chat message variants
 export function isCaughtUpMessage(msg: WorkspaceChatMessage): msg is CaughtUpMessage {
   return (msg as { type?: string }).type === "caught-up";

src/desktop/main.ts

@@ -338,6 +338,7 @@ async function loadServices(): Promise<void> {
     menuEventService: services.menuEventService,
     voiceService: services.voiceService,
     telemetryService: services.telemetryService,
+    experimentsService: services.experimentsService,
     sessionUsageService: services.sessionUsageService,
   };
 

src/node/orpc/context.ts

@@ -13,6 +13,7 @@ import type { ServerService } from "@/node/services/serverService";
 import type { MenuEventService } from "@/node/services/menuEventService";
 import type { VoiceService } from "@/node/services/voiceService";
 import type { MCPConfigService } from "@/node/services/mcpConfigService";
+import type { ExperimentsService } from "@/node/services/experimentsService";
 import type { MCPServerManager } from "@/node/services/mcpServerManager";
 import type { TelemetryService } from "@/node/services/telemetryService";
 import type { SessionUsageService } from "@/node/services/sessionUsageService";
@@ -34,6 +35,7 @@ export interface ORPCContext {
   mcpConfigService: MCPConfigService;
   mcpServerManager: MCPServerManager;
   telemetryService: TelemetryService;
+  experimentsService: ExperimentsService;
   sessionUsageService: SessionUsageService;
   headers?: IncomingHttpHeaders;
 }