Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(platform): add a PostHog feature-flag backend behind the existing API (#14317)

Reinier van der Leer56a1c09f37e3
diff --git a/autogpt_platform/backend/.env.default b/autogpt_platform/backend/.env.default
index 82dcc7065b..bc18998508 100644
--- a/autogpt_platform/backend/.env.default
+++ b/autogpt_platform/backend/.env.default
@@ -259,6 +259,9 @@ SENTRY_DSN=
# Feature Flags
LAUNCH_DARKLY_SDK_KEY=
+# Which vendor answers a flag read: launchdarkly (default), posthog, or dual
+# (evaluate both, always serve LaunchDarkly here, log every disagreement).
+FEATURE_FLAG_BACKEND=launchdarkly
# Local-dev master switch: turn EVERY boolean feature flag on at once, without
# listing them. Off by default; local dev only, where LaunchDarkly is
# unconfigured and every flag is otherwise off. A per-flag FORCE_FLAG_<NAME>
@@ -352,6 +355,9 @@ ZEROBOUNCE_API_KEY=
# Get API key from https://posthog.com - Project Settings > Project API Key
POSTHOG_API_KEY=
POSTHOG_HOST=https://eu.i.posthog.com
+# Personal API key, only for local feature-flag evaluation (Settings > Personal
+# API keys, scope: feature_flag:read). Without it flag reads go over the wire.
+POSTHOG_PERSONAL_API_KEY=
# Tally Form Integration (pre-populate business understanding on signup)
TALLY_API_KEY=
diff --git a/autogpt_platform/backend/backend/api/rest_api.py b/autogpt_platform/backend/backend/api/rest_api.py
index 0bc0a93f7c..ff8db10e24 100644
--- a/autogpt_platform/backend/backend/api/rest_api.py
+++ b/autogpt_platform/backend/backend/api/rest_api.py
@@ -104,7 +104,7 @@ from backend.util.exceptions import (
NotFoundError,
PreconditionFailed,
)
-from backend.util.feature_flag import initialize_launchdarkly, shutdown_launchdarkly
+from backend.util.feature_flag import initialize_feature_flags, shutdown_feature_flags
from backend.util.service import UnhealthyServiceError
from backend.util.workspace_storage import shutdown_workspace_storage
@@ -127,13 +127,13 @@ _webhook_bot_backend = BotBackend()
@contextlib.contextmanager
-def launch_darkly_context():
+def feature_flag_context():
if settings.config.app_env != backend.util.settings.AppEnvironment.LOCAL:
- initialize_launchdarkly()
+ initialize_feature_flags()
try:
yield
finally:
- shutdown_launchdarkly()
+ shutdown_feature_flags()
else:
yield
@@ -200,7 +200,7 @@ async def lifespan_context(app: fastapi.FastAPI):
# Fail-hard: the catalog is load-bearing — a broken load stops the boot.
backend.data.llm_registry.load_catalog()
- with launch_darkly_context():
+ with feature_flag_context():
yield
try:
diff --git a/autogpt_platform/backend/backend/executor/jobstore_test.py b/autogpt_platform/backend/backend/executor/jobstore_test.py
index 018cceacae..bac1ef0697 100644
--- a/autogpt_platform/backend/backend/executor/jobstore_test.py
+++ b/autogpt_platform/backend/backend/executor/jobstore_test.py
@@ -318,7 +318,7 @@ def _scheduler_wired_to(store):
with (
patch(f"{_SCHEDULER_PATH}.BackgroundScheduler", return_value=MagicMock()),
patch(f"{_SCHEDULER_PATH}.load_dotenv"),
- patch(f"{_SCHEDULER_PATH}._init_launchdarkly_for_scheduler"),
+ patch(f"{_SCHEDULER_PATH}._init_feature_flags_for_scheduler"),
patch(f"{_SCHEDULER_PATH}.asyncio.new_event_loop", return_value=MagicMock()),
patch(f"{_SCHEDULER_PATH}.threading.Thread", return_value=MagicMock()),
patch(f"{_SCHEDULER_PATH}.create_engine", return_value=MagicMock()),
diff --git a/autogpt_platform/backend/backend/executor/scheduler.py b/autogpt_platform/backend/backend/executor/scheduler.py
index 6e674d8a58..4c80b13ad8 100644
--- a/autogpt_platform/backend/backend/executor/scheduler.py
+++ b/autogpt_platform/backend/backend/executor/scheduler.py
@@ -73,7 +73,7 @@ from backend.util.exceptions import (
NotFoundError,
UserPaywalledError,
)
-from backend.util.feature_flag import initialize_launchdarkly, shutdown_launchdarkly
+from backend.util.feature_flag import initialize_feature_flags, shutdown_feature_flags
from backend.util.logging import PrefixFilter
from backend.util.retry import func_retry
from backend.util.service import (
@@ -121,25 +121,25 @@ SCHEDULER_OPERATION_TIMEOUT_SECONDS = 300 # 5 minutes for scheduler operations
SCHEDULER_DREAM_OPERATION_TIMEOUT_SECONDS = 1800
-def _init_launchdarkly_for_scheduler() -> None:
- """Eagerly initialize LaunchDarkly unless running LOCAL.
+def _init_feature_flags_for_scheduler() -> None:
+ """Eagerly initialize the feature flag backend unless running LOCAL.
- Mirrors ``rest_api.py``'s ``launch_darkly_context``: the @expose flag
+ Mirrors ``rest_api.py``'s ``feature_flag_context``: the @expose flag
gates (e.g. ``add_nightly_batch_schedule``'s ``DREAM_PASS_ENABLED``
- check) fail closed, so evaluating them against a lazily-initialized LD
+ check) fail closed, so evaluating them against a lazily-initialized
client right after a pod restart would silently skip registrations
- until the first lazy init completed. Skipped LOCAL, where LD is
- unconfigured and flags resolve to their mock defaults.
+ until the first lazy init completed. Skipped LOCAL, where no vendor is
+ configured and flags resolve to their mock defaults.
"""
if config.app_env != AppEnvironment.LOCAL:
- initialize_launchdarkly()
+ initialize_feature_flags()
-def _shutdown_launchdarkly_for_scheduler() -> None:
- """Reverse of ``_init_launchdarkly_for_scheduler`` — only tears down the
- LD client when it was actually initialized (non-LOCAL)."""
+def _shutdown_feature_flags_for_scheduler() -> None:
+ """Reverse of ``_init_feature_flags_for_scheduler`` — only tears down the
+ client when it was actually initialized (non-LOCAL)."""
if config.app_env != AppEnvironment.LOCAL:
- shutdown_launchdarkly()
+ shutdown_feature_flags()
# The Stripe tier sweep pages through every active subscription, so it needs a
@@ -1916,7 +1916,7 @@ class Scheduler(AppService):
# Eagerly initialize LaunchDarkly before any @expose flag gate can
# run (see the helper for why lazy init would skip registrations
# after a pod restart).
- _init_launchdarkly_for_scheduler()
+ _init_feature_flags_for_scheduler()
# Initialize the event loop for async jobs
global _event_loop
@@ -2181,7 +2181,7 @@ class Scheduler(AppService):
# Reverse order of run_service: LD was initialized before the
# scheduler started, so close it after all jobs have drained.
- _shutdown_launchdarkly_for_scheduler()
+ _shutdown_feature_flags_for_scheduler()
super().cleanup()
diff --git a/autogpt_platform/backend/backend/executor/scheduler_test.py b/autogpt_platform/backend/backend/executor/scheduler_test.py
index bf146d8f3e..7faadc7e24 100644
--- a/autogpt_platform/backend/backend/executor/scheduler_test.py
+++ b/autogpt_platform/backend/backend/executor/scheduler_test.py
@@ -840,23 +840,23 @@ def test_build_trigger_unix_dow_various_cases(
# ---------------------------------------------------------------------------
-# LaunchDarkly lifecycle — the scheduler eagerly inits LD in run_service (so
-# @expose flag gates don't fail-closed right after a pod restart) and tears
-# it down in cleanup, both gated on the non-LOCAL app env. Test the gate at
-# the boundary where the LD symbols are used (the scheduler module).
+# Feature flag lifecycle — the scheduler eagerly inits the flag backend in
+# run_service (so @expose flag gates don't fail-closed right after a pod
+# restart) and tears it down in cleanup, both gated on the non-LOCAL app env.
+# Test the gate at the boundary where the symbols are used (the scheduler).
# ---------------------------------------------------------------------------
-class TestLaunchDarklyLifecycle:
+class TestFeatureFlagLifecycle:
def test_init_runs_when_app_env_not_local(self) -> None:
from backend.executor import scheduler as sched
from backend.util.settings import AppEnvironment
with (
patch.object(sched.config, "app_env", AppEnvironment.PRODUCTION),
- patch.object(sched, "initialize_launchdarkly") as init,
+ patch.object(sched, "initialize_feature_flags") as init,
):
- sched._init_launchdarkly_for_scheduler()
+ sched._init_feature_flags_for_scheduler()
init.assert_called_once()
def test_init_skipped_when_app_env_local(self) -> None:
@@ -865,9 +865,9 @@ class TestLaunchDarklyLifecycle:
with (
patch.object(sched.config, "app_env", AppEnvironment.LOCAL),
- patch.object(sched, "initialize_launchdarkly") as init,
+ patch.object(sched, "initialize_feature_flags") as init,
):
- sched._init_launchdarkly_for_scheduler()
+ sched._init_feature_flags_for_scheduler()
init.assert_not_called()
def test_shutdown_runs_when_app_env_not_local(self) -> None:
@@ -876,9 +876,9 @@ class TestLaunchDarklyLifecycle:
with (
patch.object(sched.config, "app_env", AppEnvironment.PRODUCTION),
- patch.object(sched, "shutdown_launchdarkly") as shutdown,
+ patch.object(sched, "shutdown_feature_flags") as shutdown,
):
- sched._shutdown_launchdarkly_for_scheduler()
+ sched._shutdown_feature_flags_for_scheduler()
shutdown.assert_called_once()
def test_shutdown_skipped_when_app_env_local(self) -> None:
@@ -887,9 +887,9 @@ class TestLaunchDarklyLifecycle:
with (
patch.object(sched.config, "app_env", AppEnvironment.LOCAL),
- patch.object(sched, "shutdown_launchdarkly") as shutdown,
+ patch.object(sched, "shutdown_feature_flags") as shutdown,
):
- sched._shutdown_launchdarkly_for_scheduler()
+ sched._shutdown_feature_flags_for_scheduler()
shutdown.assert_not_called()
diff --git a/autogpt_platform/backend/backend/util/feature_flag.py b/autogpt_platform/backend/backend/util/feature_flag/__init__.py
similarity index 71%
rename from autogpt_platform/backend/backend/util/feature_flag.py
rename to autogpt_platform/backend/backend/util/feature_flag/__init__.py
index fa74637d76..1721f4f2e6 100644
--- a/autogpt_platform/backend/backend/util/feature_flag.py
+++ b/autogpt_platform/backend/backend/util/feature_flag/__init__.py
@@ -1,4 +1,7 @@
+import asyncio
import contextlib
+import hashlib
+import json
import logging
import os
import uuid
@@ -14,9 +17,13 @@ from ldclient.config import Config
from typing_extensions import ParamSpec
from backend.util.cache import cached
-from backend.util.settings import AppEnvironment, Settings
+from backend.util.settings import AppEnvironment, FeatureFlagBackend, Settings
+
+from . import posthog
logger = logging.getLogger(__name__)
+# Own logger so a dual-run diff week can be queried without trawling the rest.
+mismatch_logger = logging.getLogger(f"{__name__}.mismatch")
# Load settings at module level
settings = Settings()
@@ -27,10 +34,19 @@ T = TypeVar("T")
_is_initialized = False
_init_attempted = False
+# Strong references to in-flight shadow evaluations; without them asyncio only
+# holds a weak one and the task can be collected mid-flight.
+_shadow_evaluations: set[asyncio.Task] = set()
+_shadow_evaluations_stopped = False
+MAX_CONCURRENT_SHADOW_EVALUATIONS = 100
+# Flags PostHog could not answer for, already reported once. Before phase 2
+# creates the flags that is every read; one record per flag keeps the signal.
+_unanswered_flags_reported: set[str] = set()
+
class Flag(str, Enum):
"""
- Centralized enum for all LaunchDarkly feature flags.
+ Centralized enum for all feature flags.
Add new flags here to ensure consistency across the codebase.
"""
@@ -192,6 +208,87 @@ class Flag(str, Enum):
# block schemas, and digests oversized tool results to the workspace.
+# LaunchDarkly keys whose targeting is segment membership or an individual-user
+# target — neither of which any PostHog cohort reproduces until phase 2 creates
+# one. From ld-targeting-summary.md; attribute rules (email domain, role,
+# signup date) are not listed because `_person_properties` already carries them.
+LD_UNPORTED_TARGETING = frozenset(
+ {
+ "ai-agent-execution-summary",
+ "artifacts",
+ "artifacts-page",
+ "autogpt-new-layout",
+ "AutoMod",
+ "beta-blocks",
+ "chat",
+ "chat-mode-option",
+ "chat-search",
+ "chat-sharing",
+ "copilot-bot-platforms",
+ "dream-pass-enabled",
+ "enable-platform-payment",
+ "generic-trigger-agents",
+ "graphiti-memory",
+ "new-tool-ui",
+ "nightly-copilot",
+ "SHOW_ORG_SETTINGS",
+ "task-progress-bar",
+ }
+)
+
+
+def initialize_feature_flags() -> None:
+ """Start whichever vendor(s) the configured backend reads from."""
+ global _shadow_evaluations_stopped
+ _shadow_evaluations_stopped = False
+ _unanswered_flags_reported.clear()
+ backend = settings.config.feature_flag_backend
+ if backend is not FeatureFlagBackend.POSTHOG:
+ initialize_launchdarkly()
+ if backend is not FeatureFlagBackend.LAUNCHDARKLY:
+ if not settings.secrets.posthog_personal_api_key:
+ logger.warning(
+ f"Feature flag backend is {backend.value} without "
+ "POSTHOG_PERSONAL_API_KEY: every flag read becomes a remote "
+ "/flags call instead of an in-process evaluation"
+ )
+ posthog.initialize_posthog_flags()
+
+
+def shutdown_feature_flags() -> None:
+ """Reverse of :func:`initialize_feature_flags`."""
+ _stop_shadow_evaluations()
+ backend = settings.config.feature_flag_backend
+ try:
+ if backend is not FeatureFlagBackend.POSTHOG:
+ shutdown_launchdarkly()
+ finally:
+ # `ldclient.close()` can raise; skipping PostHog teardown would leak its
+ # poller and latch `_init_attempted` against an in-process restart.
+ if backend is not FeatureFlagBackend.LAUNCHDARKLY:
+ posthog.shutdown_posthog_flags()
+
+
+def _stop_shadow_evaluations() -> None:
+ """Cancel in-flight shadow reads and refuse new ones until the next init.
+
+ A shadow read that resumed after teardown would call ``get_flag_client()``
+ again and, since shutdown clears the "did we try" gate so an in-process
+ restart works, build a fresh PostHog client with a poller thread nothing
+ closes. This is the same hazard ``shutdown_launchdarkly`` documents.
+ """
+ global _shadow_evaluations_stopped
+ _shadow_evaluations_stopped = True
+ for task in list(_shadow_evaluations):
+ task.cancel()
+ _shadow_evaluations.clear()
+
+
+def serves_launchdarkly() -> bool:
+ """Whether LaunchDarkly answers flag reads under the configured backend."""
+ return settings.config.feature_flag_backend is not FeatureFlagBackend.POSTHOG
+
+
def is_configured() -> bool:
"""Check if LaunchDarkly is configured with an SDK key."""
return bool(settings.secrets.launch_darkly_sdk_key)
@@ -244,8 +341,8 @@ def shutdown_launchdarkly() -> None:
# `initialize_launchdarkly` returns early when no SDK key is configured,
# so `ldclient.set_config` was never called and `ldclient.get()` would
# raise "set_config was not called". Callers pair init/shutdown on
- # app_env alone (see `rest_api.launch_darkly_context` and
- # `scheduler._shutdown_launchdarkly_for_scheduler`), so an unconfigured
+ # app_env alone (see `rest_api.feature_flag_context` and
+ # `scheduler._shutdown_feature_flags_for_scheduler`), so an unconfigured
# non-LOCAL deployment would otherwise raise out of service teardown and
# leave the process alive instead of exiting.
return
@@ -389,12 +486,12 @@ async def get_feature_flag_value(
which could be a boolean, string, number, or JSON object.
Args:
- flag_key: The LaunchDarkly feature flag key
+ flag_key: The feature flag key
user_id: The user ID to evaluate the flag for
- default: Default value if LaunchDarkly is unavailable or flag evaluation fails
+ default: Default value if the vendor is unavailable or evaluation fails
Returns:
- The flag value from LaunchDarkly
+ The flag value from the configured backend
"""
value, _ = await _evaluate_flag_value(
flag_key, user_id, default, attributes=attributes
@@ -409,7 +506,145 @@ async def _evaluate_flag_value(
*,
attributes: dict[str, str] | None = None,
) -> tuple[Any, bool]:
- """``(value, evaluated)`` for one raw flag read.
+ """``(value, evaluated)`` for one raw flag read, from the configured vendor.
+
+ ``evaluated`` is False whenever *default* is standing in for an answer the
+ vendor could not give.
+ """
+ context = None
+ if attributes:
+ # Layered once, so every vendor evaluates the same per-request facts.
+ user_context, context_resolved = await _fetch_user_context_status(user_id)
+ context = (_with_request_attributes(user_context, attributes), context_resolved)
+ backend = settings.config.feature_flag_backend
+ if backend is FeatureFlagBackend.POSTHOG:
+ return await _evaluate_posthog(flag_key, user_id, default, context)
+ if backend is FeatureFlagBackend.DUAL:
+ return await _evaluate_dual(flag_key, user_id, default, context)
+ return await _evaluate_launchdarkly(flag_key, user_id, default, context)
+
+
+async def _evaluate_dual(
+ flag_key: str,
+ user_id: str,
+ default: Any = None,
+ context: tuple[Context, bool] | None = None,
+) -> tuple[Any, bool]:
+ """Evaluate both vendors, serve LaunchDarkly's answer, log disagreements.
+
+ Serving LaunchDarkly is what makes the diff week free of user-visible
+ risk: PostHog's answer is only ever observed, never acted on.
+ """
+ # One lookup for both vendors: the failure path is deliberately uncached,
+ # so evaluating them independently would double its database reads.
+ context = context or await _fetch_user_context_status(user_id)
+ ld_result = await _evaluate_launchdarkly(flag_key, user_id, default, context)
+ _probe_posthog(flag_key, user_id, default, context, ld_result)
+ return ld_result
+
+
+def _probe_posthog(
+ flag_key: str,
+ user_id: str,
+ default: Any,
+ context: tuple[Context, bool],
+ ld_result: tuple[Any, bool],
+) -> None:
+ """Compare PostHog's answer to LaunchDarkly's without making a caller wait.
+
+ The shadow answer is never served, so awaiting it would only add PostHog's
+ latency to the request path — up to a 3s remote ``/flags`` call wherever
+ ``POSTHOG_PERSONAL_API_KEY`` is unset and local evaluation is off.
+ """
+ if _shadow_evaluations_stopped:
+ return
+
+ if len(_shadow_evaluations) >= MAX_CONCURRENT_SHADOW_EVALUATIONS:
+ # A slow PostHog must cost the diff week its samples, not the process
+ # its memory.
+ logger.debug(f"Shadow evaluation backlog full, skipping {flag_key}")
+ return
+
+ task = asyncio.create_task(
+ _record_mismatch(flag_key, user_id, default, context, ld_result)
+ )
+ _shadow_evaluations.add(task)
+ task.add_done_callback(_shadow_evaluations.discard)
+
+
+async def _record_mismatch(
+ flag_key: str,
+ user_id: str,
+ default: Any,
+ context: tuple[Context, bool],
+ ld_result: tuple[Any, bool],
+) -> None:
+ try:
+ ph_result = await _evaluate_posthog(flag_key, user_id, default, context)
+ except Exception as e:
+ logger.warning(f"PostHog shadow evaluation raised for {flag_key}: {e}")
+ return
+
+ if ld_result == ph_result:
+ return
+
+ ld_value, ld_evaluated = ld_result
+ ph_value, ph_evaluated = ph_result
+ if not ph_evaluated:
+ if flag_key in _unanswered_flags_reported:
+ return
+ _unanswered_flags_reported.add(flag_key)
+ mismatch_logger.warning(
+ "feature-flag mismatch: "
+ + json.dumps(
+ {
+ "flag": flag_key,
+ "user": _user_digest(user_id),
+ "launchdarkly": {"value": ld_value, "evaluated": ld_evaluated},
+ "posthog": {"value": ph_value, "evaluated": ph_evaluated},
+ # Segment and individual-user targeting has no PostHog cohort
+ # until phase 2 builds one, so these flags are expected to
+ # disagree — the diff-week report has to separate them from
+ # real divergence rather than drown in them.
+ "expected_until_cohorts_exist": flag_key in LD_UNPORTED_TARGETING,
+ },
+ default=repr,
+ sort_keys=True,
+ )
+ )
+
+
+async def _evaluate_posthog(
+ flag_key: str,
+ user_id: str,
+ default: Any = None,
+ context: tuple[Context, bool] | None = None,
+) -> tuple[Any, bool]:
+ """``(value, evaluated)`` from PostHog for one raw flag read.
+
+ A degraded context lookup makes the answer unauthoritative for the same
+ reason it does on LaunchDarkly: the flag evaluates fine, it just answers
+ for a user without the targeted attributes.
+ """
+ user_context, context_resolved = context or await _fetch_user_context_status(
+ user_id
+ )
+ value, evaluated = await posthog.evaluate_flag(
+ flag_key,
+ user_id,
+ _person_properties(user_context),
+ default,
+ )
+ return value, evaluated and context_resolved
+
+
+async def _evaluate_launchdarkly(
+ flag_key: str,
+ user_id: str,
+ default: Any = None,
+ context: tuple[Context, bool] | None = None,
+) -> tuple[Any, bool]:
+ """``(value, evaluated)`` from LaunchDarkly for one raw flag read.
``evaluated`` is False whenever *default* is standing in for an answer
LaunchDarkly could not give — no client, an uninitialised one, a failed
@@ -428,12 +663,12 @@ async def _evaluate_flag_value(
return default, False
# Get user context (role/email) from the Better Auth user table
- context, context_resolved = await _fetch_user_context_status(user_id)
- if attributes:
- context = _with_request_attributes(context, attributes)
+ user_context, context_resolved = context or await _fetch_user_context_status(
+ user_id
+ )
# Evaluate flag
- result = client.variation(flag_key, context, default)
+ result = client.variation(flag_key, user_context, default)
logger.debug(
f"Feature flag {flag_key} for user {user_id}: {result} (type: {type(result).__name__})"
@@ -449,6 +684,28 @@ async def _evaluate_flag_value(
return default, False
+def _person_properties(context: Context) -> dict[str, Any]:
+ """PostHog person properties from the shared user context.
+
+ Reads the LaunchDarkly context rather than the auth row so both vendors
+ see one cached lookup and cannot drift; ``custom.role`` is dropped
+ because PostHog targets flat properties, and ``email`` because no ported
+ rule reads it — individual targets key on the ``distinct_id``.
+ """
+ if context.anonymous:
+ return {}
+ return {
+ attribute: context.get(attribute)
+ for attribute in ("role", "email_domain", "created_at", "country")
+ if context.get(attribute) is not None
+ }
+
+
+def _user_digest(user_id: str) -> str:
+ """Short stable hash — a mismatch record must be joinable, not identifying."""
+ return hashlib.sha256(user_id.encode()).hexdigest()[:12]
+
+
_TRUTHY = ("1", "true", "yes", "on")
# Flags whose callers read a string / JSON value through
@@ -522,9 +779,9 @@ def _env_flag_override(flag_key: Flag | str) -> bool | None:
"""Return a local override for ``flag_key`` from the environment.
Set ``FORCE_FLAG_<NAME>=true|false`` (``NAME`` = flag value with
- ``-`` → ``_``, upper-cased) to bypass LaunchDarkly for a single
- flag in local dev or tests. Returns ``None`` when no override
- is configured so the caller falls through to LaunchDarkly.
+ ``-`` → ``_``, upper-cased) to bypass the flag vendor for a single
+ flag in local dev or tests. Returns ``None`` when no override is
+ configured so the caller falls through to the configured backend.
The ``NEXT_PUBLIC_FORCE_FLAG_<NAME>`` prefix is also accepted so a
single shared env var can toggle a flag across backend and
@@ -533,10 +790,10 @@ def _env_flag_override(flag_key: Flag | str) -> bool | None:
When no per-flag override is set, the ``FORCE_ALL_FLAGS`` master switch
(see :func:`_force_all_flags_enabled`) forces every boolean flag on;
- non-boolean flags are left to LaunchDarkly.
+ non-boolean flags are left to the configured backend.
Example: ``FORCE_FLAG_CHAT_MODE_OPTION=true`` forces
- ``Flag.CHAT_MODE_OPTION`` on regardless of LaunchDarkly.
+ ``Flag.CHAT_MODE_OPTION`` on regardless of the vendor's answer.
Accepts a raw flag key string as well as a :class:`Flag`, so the
``feature_flag`` decorator (which holds a raw key) shares this path.
@@ -563,7 +820,7 @@ async def is_feature_enabled(
Args:
flag_key: The Flag enum value
user_id: The user ID to evaluate the flag for
- default: Default value if LaunchDarkly is unavailable or flag evaluation fails
+ default: Default value if the vendor is unavailable or evaluation fails
Returns:
True if feature is enabled, False otherwise
@@ -615,7 +872,7 @@ def feature_flag(
Decorator for async feature flag protected endpoints.
Args:
- flag_key: The LaunchDarkly feature flag key
+ flag_key: The feature flag key
default: Default value if flag evaluation fails
Returns:
@@ -631,18 +888,18 @@ def feature_flag(
raise ValueError("user_id is required")
# A local env override (per-flag FORCE_FLAG_*, or the
- # FORCE_ALL_FLAGS master switch) wins over LaunchDarkly and
- # applies even when the client is uninitialised — the normal
- # local-dev state, where the decorator would otherwise 404.
+ # FORCE_ALL_FLAGS master switch) wins over whichever vendor is
+ # configured, and applies even when it cannot answer — the
+ # normal local-dev state, where this would otherwise 404.
override = _env_flag_override(flag_key)
if override is not None:
logger.debug(
f"Feature flag {flag_key} overridden by env: {override}"
)
is_enabled = override
- elif not get_client().is_initialized():
+ elif not _flag_backend_initialized():
logger.warning(
- "LaunchDarkly not initialized, "
+ "Feature flag backend not initialized, "
f"using default {flag_key}={repr(default)}"
)
is_enabled = default
@@ -689,8 +946,8 @@ def create_feature_flag_dependency(
Create a FastAPI dependency that checks a feature flag.
This dependency automatically extracts the user_id from the JWT token
- (if present) for proper LaunchDarkly user targeting, while still
- supporting anonymous access.
+ (if present) for proper user targeting, while still supporting
+ anonymous access.
Args:
flag_key: The Flag enum value to check
@@ -717,8 +974,8 @@ def create_feature_flag_dependency(
check_user_id = user_id or "anonymous"
# A local env override (per-flag FORCE_FLAG_*, or the FORCE_ALL_FLAGS
- # master switch) wins over LaunchDarkly and applies even when the client
- # is unconfigured — the normal local-dev state, where this dependency
+ # master switch) wins over whichever vendor is configured, and applies
+ # even when none is — the normal local-dev state, where this dependency
# would otherwise 404.
override = _env_flag_override(flag_key)
if override is not None:
@@ -727,19 +984,20 @@ def create_feature_flag_dependency(
raise HTTPException(status_code=404, detail="Feature not available")
return
- if not is_configured():
+ if not _flag_backend_configured():
logger.debug(
- f"LaunchDarkly not configured, using default {flag_key.value}={default}"
+ "Feature flag backend not configured, using default "
+ f"{flag_key.value}={default}"
)
if not default:
raise HTTPException(status_code=404, detail="Feature not available")
return
try:
- client = get_client()
- if not client.is_initialized():
+ if not _flag_backend_initialized():
logger.debug(
- f"LaunchDarkly not initialized, using default {flag_key.value}={default}"
+ "Feature flag backend not initialized, using default "
+ f"{flag_key.value}={default}"
)
if not default:
raise HTTPException(status_code=404, detail="Feature not available")
@@ -755,13 +1013,28 @@ def create_feature_flag_dependency(
raise
except Exception as e:
logger.warning(
- f"LaunchDarkly error for flag {flag_key.value}: {e}, using default={default}"
+ f"Feature flag error for {flag_key.value}: {e}, using default={default}"
)
raise HTTPException(status_code=500, detail="Failed to check feature flag")
return check_feature_flag
+def _flag_backend_configured() -> bool:
+ """Whether the configured backend has the credentials a read needs."""
+ # Dual serves LaunchDarkly's answer, so LaunchDarkly is what gates a route.
+ if serves_launchdarkly():
+ return is_configured()
+ return posthog.is_configured()
+
+
+def _flag_backend_initialized() -> bool:
+ """Whether the configured backend can answer right now."""
+ if serves_launchdarkly():
+ return get_client().is_initialized()
+ return posthog.get_flag_client() is not None
+
+
@contextlib.contextmanager
def mock_flag_variation(flag_key: str, return_value: Any):
"""Context manager for testing feature flags."""
diff --git a/autogpt_platform/backend/backend/util/feature_flag/backends_test.py b/autogpt_platform/backend/backend/util/feature_flag/backends_test.py
new file mode 100644
index 0000000000..c978b13cdf
--- /dev/null
+++ b/autogpt_platform/backend/backend/util/feature_flag/backends_test.py
@@ -0,0 +1,791 @@
+"""Backend selection: launchdarkly (default), posthog, and the dual diff run."""
+
+import asyncio
+import json
+import logging
+import os
+import uuid
+
+import pytest
+from fastapi import HTTPException
+from ldclient import Context, LDClient
+from ldclient.config import Config as LDConfig
+from ldclient.integrations.test_data import TestData
+from posthog import Posthog
+
+import backend.util.feature_flag as ff
+import backend.util.feature_flag.posthog as ph
+from backend.util.feature_flag import (
+ Flag,
+ evaluate_feature_flag,
+ feature_flag,
+ is_feature_enabled,
+)
+from backend.util.settings import AppEnvironment, Config, FeatureFlagBackend
+
+
[email protected](autouse=True)
+async def no_leaked_shadow_evaluations():
+ """A dual probe left pending would surface inside the NEXT test's caplog."""
+ yield
+ await drain_shadow_evaluations()
+
+
[email protected](autouse=True)
+def no_unanswered_flags_reported():
+ ff._unanswered_flags_reported.clear()
+ yield
+ ff._unanswered_flags_reported.clear()
+
+
[email protected](autouse=True)
+def no_env_override(monkeypatch: pytest.MonkeyPatch):
+ """`.env` may force flags; pin every flag under test to the vendors."""
+ for name in list(os.environ):
+ if name.startswith(_FORCE_PREFIXES):
+ monkeypatch.delenv(name)
+
+
+_FORCE_PREFIXES = (
+ "FORCE_FLAG_",
+ "NEXT_PUBLIC_FORCE_FLAG_",
+ "FORCE_ALL_FLAGS",
+ "NEXT_PUBLIC_FORCE_ALL_FLAGS",
+)
+
+
+def ld_client(mocker):
+ client = mocker.Mock(spec=LDClient)
+ mocker.patch("backend.util.feature_flag.ldclient.get", return_value=client)
+ client.is_initialized.return_value = True
+ return client
+
+
+def user_context(mocker):
+ """A resolved context, so `authoritative` turns purely on evaluation."""
+ context = Context.builder("u-1").kind("user").anonymous(False).build()
+ return mocker.patch(
+ "backend.util.feature_flag._fetch_user_context_status",
+ return_value=(context, True),
+ )
+
+
+def _mismatch_record(message: str) -> dict:
+ """The log formatter wraps the message in ANSI colour codes."""
+ return json.loads(message[message.index("{") : message.rindex("}") + 1])
+
+
+async def drain_shadow_evaluations() -> None:
+ """Dual reports off the caller's path, so a test has to wait for it."""
+ while ff._shadow_evaluations:
+ await asyncio.gather(*list(ff._shadow_evaluations))
+
+
+def use_backend(mocker, backend: FeatureFlagBackend):
+ mocker.patch.object(ff.settings.config, "feature_flag_backend", backend)
+
+
+def stub_posthog(mocker, *, value, payload=None):
+ """Stand in for a PostHog evaluation snapshot for one flag."""
+ snapshot = mocker.Mock()
+ snapshot.get_flag.return_value = value
+ snapshot.get_flag_payload.return_value = payload
+ client = mocker.Mock()
+ client.evaluate_flags.return_value = snapshot
+ mocker.patch.object(ph, "get_flag_client", return_value=client)
+ return client
+
+
+class TestDefaultBackendIsUnchanged:
+ """Phase 1 is a no-op until the setting is flipped."""
+
+ def test_the_default_is_launchdarkly(self):
+ assert (
+ ff.settings.config.feature_flag_backend is FeatureFlagBackend.LAUNCHDARKLY
+ )
+
+ @pytest.mark.asyncio
+ async def test_the_default_never_touches_posthog(
+ self, mocker, ld_client, user_context
+ ):
+ posthog = mocker.patch.object(ph, "evaluate_flag")
+ ld_client.variation.return_value = True
+
+ assert await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1") == (True, True)
+ ld_client.variation.assert_called_once()
+ posthog.assert_not_called()
+
+ @pytest.mark.asyncio
+ async def test_the_default_reads_launchdarkly_for_raw_values(
+ self, ld_client, user_context
+ ):
+ ld_client.variation.return_value = {"daily": 5}
+
+ assert await ff.get_feature_flag_value("copilot-cost-limits", "system") == {
+ "daily": 5
+ }
+
+ def test_lifecycle_starts_only_launchdarkly(self, mocker):
+ launchdarkly = mocker.patch.object(ff, "initialize_launchdarkly")
+ posthog = mocker.patch.object(ph, "initialize_posthog_flags")
+
+ ff.initialize_feature_flags()
+
+ launchdarkly.assert_called_once()
+ posthog.assert_not_called()
+
+ def test_readiness_asks_only_launchdarkly(self, mocker, ld_client):
+ posthog = mocker.patch.object(ph, "is_configured")
+
+ ff._flag_backend_initialized()
+
+ ld_client.is_initialized.assert_called_once()
+ posthog.assert_not_called()
+
+
+class TestAnUnknownBackendValue:
+ """Settings is built at import of every module that reads a flag, so a
+ rejected value is a boot crash rather than a misconfigured flag read."""
+
+ def test_a_typo_falls_back_to_launchdarkly(self, monkeypatch):
+ monkeypatch.setenv("FEATURE_FLAG_BACKEND", "posthogg")
+ assert Config().feature_flag_backend is FeatureFlagBackend.LAUNCHDARKLY
+
+ def test_the_value_is_case_insensitive(self, monkeypatch):
+ monkeypatch.setenv("FEATURE_FLAG_BACKEND", "PostHog")
+ assert Config().feature_flag_backend is FeatureFlagBackend.POSTHOG
+
+
+class TestPostHogBackend:
+ @pytest.mark.asyncio
+ async def test_an_enabled_flag_is_authoritative(self, mocker, user_context):
+ use_backend(mocker, FeatureFlagBackend.POSTHOG)
+ stub_posthog(mocker, value=True)
+
+ assert await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1") == (True, True)
+
+ @pytest.mark.asyncio
+ async def test_a_conclusive_off_is_authoritative(self, mocker, user_context):
+ """The distinction LaunchDarkly had to infer: PostHog reports it."""
+ use_backend(mocker, FeatureFlagBackend.POSTHOG)
+ stub_posthog(mocker, value=False)
+
+ assert await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1") == (False, True)
+
+ @pytest.mark.asyncio
+ async def test_an_unresolved_flag_is_not(self, mocker, user_context):
+ use_backend(mocker, FeatureFlagBackend.POSTHOG)
+ stub_posthog(mocker, value=None)
+
+ assert await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1") == (False, False)
+
+ @pytest.mark.asyncio
+ async def test_an_unconfigured_client_is_not(self, mocker, user_context):
+ use_backend(mocker, FeatureFlagBackend.POSTHOG)
+ mocker.patch.object(ph, "get_flag_client", return_value=None)
+
+ assert await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1") == (False, False)
+
+ @pytest.mark.asyncio
+ async def test_an_evaluation_that_raises_is_not(self, mocker, user_context):
+ use_backend(mocker, FeatureFlagBackend.POSTHOG)
+ client = stub_posthog(mocker, value=True)
+ client.evaluate_flags.side_effect = Exception("evaluation exploded")
+
+ assert await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1") == (False, False)
+
+ @pytest.mark.asyncio
+ async def test_a_degraded_user_context_is_not(self, mocker):
+ use_backend(mocker, FeatureFlagBackend.POSTHOG)
+ stub_posthog(mocker, value=True)
+ mocker.patch(
+ "backend.util.feature_flag._fetch_user_context_status",
+ return_value=(Context.create("u-1"), False),
+ )
+
+ assert await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1") == (True, False)
+
+ @pytest.mark.asyncio
+ async def test_a_payload_flag_returns_its_payload(self, mocker, user_context):
+ """The JSON-valued flags: a payload stands in for LD's variation value."""
+ use_backend(mocker, FeatureFlagBackend.POSTHOG)
+ stub_posthog(mocker, value=True, payload={"daily": 5, "weekly": 20})
+
+ value = await ff.get_feature_flag_value("copilot-cost-limits", "system")
+
+ assert value == {"daily": 5, "weekly": 20}
+
+ @pytest.mark.asyncio
+ async def test_a_non_boolean_value_is_not_authoritative(self, mocker, user_context):
+ use_backend(mocker, FeatureFlagBackend.POSTHOG)
+ stub_posthog(mocker, value=True, payload={"some": "object"})
+
+ assert await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1") == (False, False)
+
+ @pytest.mark.asyncio
+ async def test_targeting_attributes_are_passed_as_person_properties(self, mocker):
+ """Every attribute an LD rule targets on has to reach PostHog, or the
+ flag silently evaluates against a user without them — and nothing
+ more: the raw email is not one of them."""
+ use_backend(mocker, FeatureFlagBackend.POSTHOG)
+ client = stub_posthog(mocker, value=True)
+ context = (
+ Context.builder("u-1")
+ .kind("user")
+ .anonymous(False)
+ .set("role", "admin")
+ .set("custom", {"role": "admin"})
+ .set("email", "[email protected]")
+ .set("email_domain", "agpt.co")
+ .set("created_at", "2026-05-07T12:00:00+00:00")
+ .build()
+ )
+ mocker.patch(
+ "backend.util.feature_flag._fetch_user_context_status",
+ return_value=(context, True),
+ )
+
+ await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1")
+
+ _, kwargs = client.evaluate_flags.call_args
+ assert kwargs["person_properties"] == {
+ "role": "admin",
+ "email_domain": "agpt.co",
+ "created_at": "2026-05-07T12:00:00+00:00",
+ }
+
+ @pytest.mark.asyncio
+ async def test_an_anonymous_context_carries_no_person_properties(self, mocker):
+ """The `"system"`-keyed config flags have no user to describe."""
+ use_backend(mocker, FeatureFlagBackend.POSTHOG)
+ client = stub_posthog(mocker, value=True, payload={"TIER": 1.5})
+
+ await ff.get_feature_flag_value("copilot-tier-multipliers", "system")
+
+ args, kwargs = client.evaluate_flags.call_args
+ assert args[0] == "system"
+ assert kwargs["person_properties"] is None
+
+ def test_lifecycle_starts_only_posthog(self, mocker):
+ use_backend(mocker, FeatureFlagBackend.POSTHOG)
+ launchdarkly = mocker.patch.object(ff, "initialize_launchdarkly")
+ posthog = mocker.patch.object(ph, "initialize_posthog_flags")
+
+ ff.initialize_feature_flags()
+
+ posthog.assert_called_once()
+ launchdarkly.assert_not_called()
+
+ def test_readiness_follows_the_posthog_client(self, mocker):
+ use_backend(mocker, FeatureFlagBackend.POSTHOG)
+ mocker.patch.object(ph, "get_flag_client", return_value=None)
+ assert ff._flag_backend_initialized() is False
+
+ mocker.patch.object(ph, "get_flag_client", return_value=mocker.Mock())
+ assert ff._flag_backend_initialized() is True
+
+
+class TestDualBackend:
+ @pytest.mark.asyncio
+ async def test_launchdarkly_answers_even_when_posthog_disagrees(
+ self, mocker, ld_client, user_context
+ ):
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ ld_client.variation.return_value = True
+ stub_posthog(mocker, value=False)
+
+ assert await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1") == (True, True)
+
+ @pytest.mark.asyncio
+ async def test_a_disagreement_is_logged_as_a_structured_record(
+ self, mocker, ld_client, user_context, caplog
+ ):
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ ld_client.variation.return_value = True
+ stub_posthog(mocker, value=False)
+ user_id = str(uuid.uuid4())
+
+ with caplog.at_level(
+ logging.WARNING, logger="backend.util.feature_flag.mismatch"
+ ):
+ await evaluate_feature_flag(Flag.HIRE_EXPERTS, user_id)
+ await drain_shadow_evaluations()
+
+ [message] = [
+ record.getMessage()
+ for record in caplog.records
+ if record.name == "backend.util.feature_flag.mismatch"
+ ]
+ record = _mismatch_record(message)
+ assert record["flag"] == Flag.HIRE_EXPERTS.value
+ assert record["launchdarkly"] == {"value": True, "evaluated": True}
+ assert record["posthog"] == {"value": False, "evaluated": True}
+ assert user_id not in message
+ assert record["user"] == ff._user_digest(user_id)
+
+ @pytest.mark.asyncio
+ async def test_agreement_logs_nothing(
+ self, mocker, ld_client, user_context, caplog
+ ):
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ ld_client.variation.return_value = True
+ stub_posthog(mocker, value=True)
+
+ with caplog.at_level(
+ logging.WARNING, logger="backend.util.feature_flag.mismatch"
+ ):
+ await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1")
+ await drain_shadow_evaluations()
+
+ assert not [
+ r for r in caplog.records if r.name == "backend.util.feature_flag.mismatch"
+ ]
+
+ @pytest.mark.asyncio
+ async def test_an_authoritativeness_difference_is_a_mismatch(
+ self, mocker, ld_client, user_context, caplog
+ ):
+ """Both say "off", but only one of them knows it — that is the
+ difference the diff week exists to find."""
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ ld_client.variation.return_value = False
+ stub_posthog(mocker, value=None)
+
+ with caplog.at_level(
+ logging.WARNING, logger="backend.util.feature_flag.mismatch"
+ ):
+ result = await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1")
+ await drain_shadow_evaluations()
+
+ assert result == (False, True)
+ [message] = [
+ r.getMessage()
+ for r in caplog.records
+ if r.name == "backend.util.feature_flag.mismatch"
+ ]
+ assert _mismatch_record(message)["posthog"] == {
+ "value": False,
+ "evaluated": False,
+ }
+
+ @pytest.mark.asyncio
+ async def test_an_unanswered_flag_is_reported_once_per_flag(
+ self, mocker, ld_client, user_context, caplog
+ ):
+ """Before phase 2 creates the flags PostHog answers nothing, so every
+ read would otherwise log the same record."""
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ ld_client.variation.return_value = True
+ stub_posthog(mocker, value=None)
+
+ with caplog.at_level(
+ logging.WARNING, logger="backend.util.feature_flag.mismatch"
+ ):
+ for _ in range(3):
+ await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1")
+ await evaluate_feature_flag(Flag.CHAT_MODE_OPTION, "u-1")
+ await drain_shadow_evaluations()
+
+ flags = [
+ _mismatch_record(r.getMessage())["flag"]
+ for r in caplog.records
+ if r.name == "backend.util.feature_flag.mismatch"
+ ]
+ assert sorted(flags) == sorted(
+ [Flag.HIRE_EXPERTS.value, Flag.CHAT_MODE_OPTION.value]
+ )
+
+ @pytest.mark.asyncio
+ async def test_an_answered_disagreement_is_reported_every_time(
+ self, mocker, ld_client, user_context, caplog
+ ):
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ ld_client.variation.return_value = True
+ stub_posthog(mocker, value=False)
+
+ with caplog.at_level(
+ logging.WARNING, logger="backend.util.feature_flag.mismatch"
+ ):
+ for _ in range(3):
+ await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1")
+ await drain_shadow_evaluations()
+
+ assert (
+ len(
+ [
+ r
+ for r in caplog.records
+ if r.name == "backend.util.feature_flag.mismatch"
+ ]
+ )
+ == 3
+ )
+
+ @pytest.mark.asyncio
+ async def test_a_posthog_failure_cannot_break_the_read(
+ self, mocker, ld_client, user_context
+ ):
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ ld_client.variation.return_value = True
+ mocker.patch.object(ph, "evaluate_flag", side_effect=Exception("boom"))
+
+ assert await is_feature_enabled(Flag.HIRE_EXPERTS, "u-1") is True
+ await drain_shadow_evaluations()
+
+ @pytest.mark.asyncio
+ async def test_an_unserializable_value_still_logs(
+ self, mocker, ld_client, user_context, caplog
+ ):
+ """A mismatch record must never be the thing that raises."""
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ ld_client.variation.return_value = object()
+ stub_posthog(mocker, value=True)
+
+ with caplog.at_level(
+ logging.WARNING, logger="backend.util.feature_flag.mismatch"
+ ):
+ await ff.get_feature_flag_value("copilot-cost-limits", "u-1")
+ await drain_shadow_evaluations()
+
+ assert [
+ r for r in caplog.records if r.name == "backend.util.feature_flag.mismatch"
+ ]
+
+ def test_lifecycle_starts_both(self, mocker):
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ launchdarkly = mocker.patch.object(ff, "initialize_launchdarkly")
+ posthog = mocker.patch.object(ph, "initialize_posthog_flags")
+
+ ff.initialize_feature_flags()
+
+ launchdarkly.assert_called_once()
+ posthog.assert_called_once()
+
+ def test_readiness_follows_launchdarkly(self, mocker, ld_client):
+ """Dual serves LaunchDarkly, so LaunchDarkly is what gates a route."""
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ ld_client.is_initialized.return_value = False
+
+ assert ff._flag_backend_initialized() is False
+
+
+class TestDualStaysOffTheRequestPath:
+ """The shadow answer is discarded, so nobody may wait for it."""
+
+ @pytest.mark.asyncio
+ async def test_the_caller_does_not_wait_for_posthog(
+ self, mocker, ld_client, user_context
+ ):
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ ld_client.variation.return_value = True
+ posthog_started = asyncio.Event()
+
+ async def slow_posthog(*args, **kwargs):
+ posthog_started.set()
+ await asyncio.sleep(30)
+ return False, True
+
+ mocker.patch.object(ph, "evaluate_flag", side_effect=slow_posthog)
+
+ result = await asyncio.wait_for(
+ evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1"), timeout=5
+ )
+
+ assert result == (True, True)
+ await posthog_started.wait()
+ for task in list(ff._shadow_evaluations):
+ task.cancel()
+
+ @pytest.mark.asyncio
+ async def test_both_vendors_share_one_context_lookup(self, mocker, ld_client):
+ """The failed-lookup path is deliberately uncached, so evaluating the
+ two vendors independently would double its database reads."""
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ ld_client.variation.return_value = True
+ stub_posthog(mocker, value=True)
+ lookup = mocker.patch(
+ "backend.util.feature_flag._fetch_user_context_status",
+ return_value=(Context.create("u-1"), False),
+ )
+
+ await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1")
+ await drain_shadow_evaluations()
+
+ lookup.assert_called_once_with("u-1")
+
+ @pytest.mark.asyncio
+ async def test_a_probe_backlog_is_bounded(self, mocker, ld_client, user_context):
+ """A slow PostHog costs the diff week its samples, not the process
+ its memory."""
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ ld_client.variation.return_value = True
+ mocker.patch.object(ff, "MAX_CONCURRENT_SHADOW_EVALUATIONS", 2)
+
+ async def never_finishes(*args, **kwargs):
+ await asyncio.sleep(30)
+ return False, True
+
+ mocker.patch.object(ph, "evaluate_flag", side_effect=never_finishes)
+
+ for _ in range(5):
+ await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1")
+
+ assert len(ff._shadow_evaluations) == 2
+ for task in list(ff._shadow_evaluations):
+ task.cancel()
+
+ @pytest.mark.asyncio
+ async def test_segment_targeted_flags_are_marked_as_expected(
+ self, mocker, ld_client, user_context, caplog
+ ):
+ """Until phase 2 builds the cohorts these disagree by construction, and
+ the diff-week report has to be able to set them aside."""
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ ld_client.variation.return_value = True
+ stub_posthog(mocker, value=False)
+
+ with caplog.at_level(
+ logging.WARNING, logger="backend.util.feature_flag.mismatch"
+ ):
+ await evaluate_feature_flag(Flag.GRAPHITI_MEMORY, "u-1")
+ await drain_shadow_evaluations()
+
+ [message] = [
+ r.getMessage()
+ for r in caplog.records
+ if r.name == "backend.util.feature_flag.mismatch"
+ ]
+ assert _mismatch_record(message)["expected_until_cohorts_exist"] is True
+
+
+class TestShutdownStopsShadowEvaluations:
+ """A shadow read that outlives teardown rebuilds the client it just closed:
+ shutdown clears the "did we try" gate so an in-process restart works, and
+ ``get_flag_client()`` then constructs a fresh one with a poller thread
+ nothing will close."""
+
+ @pytest.fixture(autouse=True)
+ def restart_after(self):
+ yield
+ ff._shadow_evaluations_stopped = False
+
+ @pytest.mark.asyncio
+ async def test_shutdown_cancels_the_in_flight_reads(
+ self, mocker, ld_client, user_context
+ ):
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ mocker.patch.object(ff, "shutdown_launchdarkly")
+ mocker.patch.object(ph, "shutdown_posthog_flags")
+ ld_client.variation.return_value = True
+
+ async def never_finishes(*args, **kwargs):
+ await asyncio.sleep(30)
+ return False, True
+
+ mocker.patch.object(ph, "evaluate_flag", side_effect=never_finishes)
+ await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1")
+ assert len(ff._shadow_evaluations) == 1
+
+ ff.shutdown_feature_flags()
+
+ assert ff._shadow_evaluations == set()
+
+ @pytest.mark.asyncio
+ async def test_a_read_during_teardown_starts_no_new_client(
+ self, mocker, ld_client, user_context
+ ):
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ mocker.patch.object(ff, "shutdown_launchdarkly")
+ mocker.patch.object(ph, "shutdown_posthog_flags")
+ ld_client.variation.return_value = True
+ get_client = mocker.patch.object(ph, "get_flag_client")
+
+ ff.shutdown_feature_flags()
+ assert await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1") == (True, True)
+ await drain_shadow_evaluations()
+
+ get_client.assert_not_called()
+
+ def test_a_restart_resumes_shadow_evaluation(self, mocker):
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ mocker.patch.object(ff, "shutdown_launchdarkly")
+ mocker.patch.object(ff, "initialize_launchdarkly")
+ mocker.patch.object(ph, "shutdown_posthog_flags")
+ mocker.patch.object(ph, "initialize_posthog_flags")
+
+ ff.shutdown_feature_flags()
+ ff.initialize_feature_flags()
+
+ assert ff._shadow_evaluations_stopped is False
+
+ def test_a_failed_launchdarkly_teardown_still_closes_posthog(self, mocker):
+ use_backend(mocker, FeatureFlagBackend.DUAL)
+ mocker.patch.object(
+ ff, "shutdown_launchdarkly", side_effect=RuntimeError("ld teardown")
+ )
+ posthog_shutdown = mocker.patch.object(ph, "shutdown_posthog_flags")
+
+ with pytest.raises(RuntimeError, match="ld teardown"):
+ ff.shutdown_feature_flags()
+
+ posthog_shutdown.assert_called_once()
+
+
+class TestForcedFlagsInEveryBackend:
+ @pytest.mark.parametrize("backend", list(FeatureFlagBackend))
+ @pytest.mark.asyncio
+ async def test_an_env_override_answers_without_any_vendor(
+ self, mocker, monkeypatch: pytest.MonkeyPatch, backend
+ ):
+ use_backend(mocker, backend)
+ mocker.patch.object(
+ ff, "get_client", side_effect=Exception("set_config was not called")
+ )
+ posthog = mocker.patch.object(ph, "evaluate_flag")
+ monkeypatch.setenv("FORCE_FLAG_HIRE_EXPERTS", "true")
+
+ assert await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1") == (True, True)
+ posthog.assert_not_called()
+
+ @pytest.mark.asyncio
+ async def test_force_all_opens_the_route_gates_under_posthog(
+ self, mocker, monkeypatch: pytest.MonkeyPatch
+ ):
+ """The local override sits above the vendor choice, on every gate.
+
+ Both gates consult it ahead of the "vendor cannot answer" bail-out, so
+ selecting PostHog must not put a developer's switch back behind one.
+ """
+ use_backend(mocker, FeatureFlagBackend.POSTHOG)
+ mocker.patch.object(ff.settings.config, "app_env", AppEnvironment.LOCAL)
+ mocker.patch.object(ff, "_force_all_logged", True)
+ mocker.patch.object(ph, "is_configured", return_value=False)
+ mocker.patch.object(ph, "get_flag_client", return_value=None)
+ monkeypatch.setenv("FORCE_ALL_FLAGS", "true")
+
+ assert await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1") == (True, True)
+ await ff.create_feature_flag_dependency(Flag.HIRE_EXPERTS)("u-1")
+ assert await _gated_route()(user_id="u-1") == "served"
+
+ @pytest.mark.asyncio
+ async def test_posthog_answers_the_gates_again_without_the_switch(
+ self, mocker, monkeypatch: pytest.MonkeyPatch
+ ):
+ use_backend(mocker, FeatureFlagBackend.POSTHOG)
+ mocker.patch.object(ff.settings.config, "app_env", AppEnvironment.LOCAL)
+ monkeypatch.delenv("FORCE_ALL_FLAGS", raising=False)
+ monkeypatch.delenv("NEXT_PUBLIC_FORCE_ALL_FLAGS", raising=False)
+ mocker.patch.object(ph, "is_configured", return_value=True)
+ stub_posthog(mocker, value=True)
+
+ assert await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1") == (True, True)
+ await ff.create_feature_flag_dependency(Flag.HIRE_EXPERTS)("u-1")
+ assert await _gated_route()(user_id="u-1") == "served"
+
+ stub_posthog(mocker, value=False)
+ assert await evaluate_feature_flag(Flag.HIRE_EXPERTS, "u-1") == (False, True)
+ with pytest.raises(HTTPException) as off:
+ await ff.create_feature_flag_dependency(Flag.HIRE_EXPERTS)("u-1")
+ assert off.value.status_code == 404
+
+
+class TestTheCountryRuleInEveryBackend:
+ """The trial's country targeting, through each vendor's real evaluator."""
+
+ @pytest.mark.asyncio
+ @pytest.mark.parametrize("backend", list(FeatureFlagBackend))
+ @pytest.mark.parametrize(
+ "country,offered", [("US", True), ("BR", True), ("IN", False), (None, False)]
+ )
+ async def test_the_country_decides_the_offer(
+ self, mocker, backend, country, offered
+ ):
+ use_backend(mocker, backend)
+ mocker.patch(
+ "backend.util.feature_flag._fetch_user_context_status",
+ return_value=(Context.builder("u-1").kind("user").build(), True),
+ )
+ ld = _launchdarkly_serving_all_but_india()
+ mocker.patch("backend.util.feature_flag.ldclient.get", return_value=ld)
+ posthog_client = _posthog_serving_all_but_india()
+ mocker.patch.object(ph, "get_flag_client", return_value=posthog_client)
+ try:
+ value = await ff.get_feature_flag_value(
+ _TRIAL_FLAG,
+ "u-1",
+ None,
+ attributes={"country": country} if country else None,
+ )
+ await drain_shadow_evaluations()
+ finally:
+ ld.close()
+ posthog_client.shutdown()
+ assert (value == {"version": "v1"}) is offered
+
+
+_TRIAL_FLAG = "card-required-trial-offer"
+
+
+def _launchdarkly_serving_all_but_india() -> LDClient:
+ td = TestData.data_source()
+ td.update(
+ td.flag(_TRIAL_FLAG)
+ .variations({"enabled": False}, {"version": "v1"})
+ .fallthrough_variation(0)
+ .if_not_match("country", "IN")
+ .then_return(1)
+ )
+ return LDClient(LDConfig("sdk-test", update_processor_class=td, send_events=False))
+
+
+def _posthog_serving_all_but_india() -> Posthog:
+ """What the sync script ports that LaunchDarkly rule to, evaluated locally."""
+ client = Posthog("phc-test", secret_key="phx-test", enable_local_evaluation=False)
+ client.feature_flags = [
+ {
+ "id": 1,
+ "key": _TRIAL_FLAG,
+ "active": True,
+ "filters": {
+ "groups": [
+ {
+ "properties": [
+ {
+ "key": "country",
+ "type": "person",
+ "operator": "is_set",
+ "value": "is_set",
+ },
+ {
+ "key": "country",
+ "type": "person",
+ "operator": "is_not",
+ "value": ["IN"],
+ },
+ ],
+ "rollout_percentage": 100,
+ }
+ ],
+ "payloads": {"true": json.dumps({"version": "v1"})},
+ },
+ }
+ ]
+ # A person without a country is inconclusive locally; keep the fallback offline.
+ client._get_flags_decision = _no_remote_flags
+ return client
+
+
+def _no_remote_flags(*args, **kwargs):
+ raise ConnectionError("remote /flags is unavailable in tests")
+
+
+def _gated_route():
+ """A route behind the decorator, which holds a raw flag key rather than a Flag."""
+
+ @feature_flag(Flag.HIRE_EXPERTS.value)
+ async def route(user_id: str) -> str:
+ return "served"
+
+ return route
diff --git a/autogpt_platform/backend/backend/util/feature_flag_test.py b/autogpt_platform/backend/backend/util/feature_flag/feature_flag_test.py
similarity index 99%
rename from autogpt_platform/backend/backend/util/feature_flag_test.py
rename to autogpt_platform/backend/backend/util/feature_flag/feature_flag_test.py
index ebdb97bcf6..3b57d14d79 100644
--- a/autogpt_platform/backend/backend/util/feature_flag_test.py
+++ b/autogpt_platform/backend/backend/util/feature_flag/feature_flag_test.py
@@ -10,6 +10,7 @@ from ldclient import Context, LDClient
from ldclient.config import Config
from ldclient.integrations.test_data import TestData
+import backend
import backend.util.feature_flag as feature_flag_module
from backend.util.feature_flag import (
_NON_BOOLEAN_FLAG_VALUES,
@@ -192,7 +193,7 @@ def _flags_read_via_get_feature_flag_value() -> set[str]:
a non-literal (``feature_flag``'s own raw-string key) are skipped —
there is no flag identity to check there.
"""
- backend_root = Path(feature_flag_module.__file__).parent.parent
+ backend_root = Path(backend.__file__).parent
found: set[str] = set()
for path in backend_root.rglob("*.py"):
if path.name.endswith("_test.py"):
diff --git a/autogpt_platform/backend/backend/util/feature_flag/posthog.py b/autogpt_platform/backend/backend/util/feature_flag/posthog.py
new file mode 100644
index 0000000000..b6ee306548
--- /dev/null
+++ b/autogpt_platform/backend/backend/util/feature_flag/posthog.py
@@ -0,0 +1,157 @@
+"""PostHog-backed feature flag evaluation.
+
+Takes plain data rather than importing ``backend.util.feature_flag``: that
+module dispatches to this one, so a back-import would be a cycle.
+"""
+
+import asyncio
+import functools
+import logging
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+from posthog import Posthog
+
+from backend.util.settings import Settings
+
+logger = logging.getLogger(__name__)
+
+settings = Settings()
+
+# Without the personal key every read is a remote /flags call; on the default
+# executor a burst of those starves every other `asyncio.to_thread` caller.
+FLAG_READ_WORKERS = 8
+_read_executor = ThreadPoolExecutor(
+ max_workers=FLAG_READ_WORKERS, thread_name_prefix="posthog-flags"
+)
+
+_client: Posthog | None = None
+# The executor evaluates flags from two event loops on two threads; a second
+# client built by a racing first read would leak its poller thread.
+_client_lock = threading.Lock()
+_init_attempted = False
+_shut_down = False
+
+
+def is_configured() -> bool:
+ """Whether PostHog has the project key a flag read needs."""
+ return bool(settings.secrets.posthog_api_key)
+
+
+async def evaluate_flag(
+ flag_key: str,
+ distinct_id: str,
+ person_properties: dict[str, Any] | None = None,
+ default: Any = None,
+) -> tuple[Any, bool]:
+ """``(value, evaluated)`` for one raw flag read.
+
+ ``evaluated`` is False whenever *default* is standing in for an answer
+ PostHog could not give. Unlike LaunchDarkly this needs no inference:
+ ``get_flag`` returns ``None`` exactly when the flag was not resolved, and
+ ``False`` when it conclusively matched no release condition.
+
+ A flag carrying a payload resolves to that payload, mirroring how the
+ JSON-valued LaunchDarkly flags return their variation value.
+ """
+ client = get_flag_client()
+ if client is None:
+ logger.debug(f"PostHog not configured, using default={default} for {flag_key}")
+ return default, False
+
+ try:
+ # evaluate_flags does network I/O whenever the local-evaluation poller
+ # has no definition for the flag, so it cannot run on the event loop.
+ snapshot = await asyncio.get_running_loop().run_in_executor(
+ _read_executor,
+ functools.partial(
+ client.evaluate_flags,
+ distinct_id,
+ person_properties=person_properties or None,
+ flag_keys=[flag_key],
+ ),
+ )
+ except Exception as e:
+ logger.warning(
+ f"PostHog flag evaluation failed for {flag_key}: {e}, using default={default}"
+ )
+ return default, False
+
+ value = snapshot.get_flag(flag_key)
+ if value is None:
+ logger.debug(f"PostHog returned no answer for {flag_key}, using {default}")
+ return default, False
+
+ # A conclusive "off" is the answer. Serving a payload here instead would
+ # turn it into a non-boolean, which every caller reads as "could not
+ # evaluate" — the one distinction this evaluator exists to preserve.
+ if value is False:
+ return False, True
+
+ payload = snapshot.get_flag_payload(flag_key)
+ return (payload if payload is not None else value), True
+
+
+def initialize_posthog_flags() -> None:
+ """Build the flag client eagerly so its definition poller is warm."""
+ global _shut_down
+ _shut_down = False
+ get_flag_client()
+
+
+def shutdown_posthog_flags() -> None:
+ global _client, _init_attempted, _shut_down
+ with _client_lock:
+ client = _client
+ _client = None
+ # Clear the "did we try" gate even when no client was built, or an
+ # unconfigured first attempt latches it shut for the life of the process.
+ _init_attempted = False
+ # A shadow read runs in a worker thread that outlives the cancelled
+ # task, so refuse to rebuild here: that client's poller would have no closer.
+ _shut_down = True
+ if client is None:
+ return
+
+ client.shutdown()
+ logger.info("PostHog feature flag client closed successfully")
+
+
+def get_flag_client() -> Posthog | None:
+ """The flag client singleton, or None when PostHog is unconfigured.
+
+ Separate from ``copilot.tracking``'s analytics client because only this
+ one carries the personal API key that enables local evaluation, and
+ shutting one down must not silence the other.
+ """
+ global _client, _init_attempted
+ if _client is not None or _init_attempted or _shut_down:
+ return _client
+
+ with _client_lock:
+ if _client is not None or _init_attempted or _shut_down:
+ return _client
+ return _build_client()
+
+
+def _build_client() -> Posthog | None:
+ global _client, _init_attempted
+ if not is_configured():
+ _init_attempted = True
+ logger.warning("PostHog API key not configured; flag reads will not resolve")
+ return None
+
+ personal_api_key = settings.secrets.posthog_personal_api_key
+ _client = Posthog(
+ settings.secrets.posthog_api_key,
+ host=settings.secrets.posthog_host,
+ personal_api_key=personal_api_key or None,
+ enable_local_evaluation=bool(personal_api_key),
+ )
+ _init_attempted = True
+ logger.info(
+ "PostHog feature flag client initialized "
+ f"(local evaluation: {'on' if personal_api_key else 'off'})"
+ )
+ return _client
diff --git a/autogpt_platform/backend/backend/util/feature_flag/posthog_test.py b/autogpt_platform/backend/backend/util/feature_flag/posthog_test.py
new file mode 100644
index 0000000000..73299c781a
--- /dev/null
+++ b/autogpt_platform/backend/backend/util/feature_flag/posthog_test.py
@@ -0,0 +1,286 @@
+"""The PostHog evaluator itself — client lifecycle and the raw read."""
+
+import asyncio
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+
+import pytest
+
+import backend.util.feature_flag.posthog as ph
+
+
[email protected](autouse=True)
+def fresh_client(mocker):
+ """The singleton is module state; each test starts without one."""
+ mocker.patch.object(ph, "_client", None)
+ mocker.patch.object(ph, "_init_attempted", False)
+ mocker.patch.object(ph, "_shut_down", False)
+
+
+def configure(mocker, *, api_key="phc_test", personal_api_key=""):
+ mocker.patch.object(ph.settings.secrets, "posthog_api_key", api_key)
+ mocker.patch.object(
+ ph.settings.secrets, "posthog_personal_api_key", personal_api_key
+ )
+
+
+def snapshot(mocker, *, value, payload=None):
+ result = mocker.Mock()
+ result.get_flag.return_value = value
+ result.get_flag_payload.return_value = payload
+ return result
+
+
+class TestClientConstruction:
+ def test_no_project_key_means_no_client(self, mocker):
+ configure(mocker, api_key="")
+ assert ph.get_flag_client() is None
+
+ def test_the_personal_key_turns_on_local_evaluation(self, mocker):
+ configure(mocker, personal_api_key="phx_personal")
+ posthog = mocker.patch.object(ph, "Posthog")
+
+ ph.get_flag_client()
+
+ _, kwargs = posthog.call_args
+ assert kwargs["personal_api_key"] == "phx_personal"
+ assert kwargs["enable_local_evaluation"] is True
+
+ def test_without_it_evaluation_stays_remote(self, mocker):
+ configure(mocker)
+ posthog = mocker.patch.object(ph, "Posthog")
+
+ ph.get_flag_client()
+
+ _, kwargs = posthog.call_args
+ assert kwargs["personal_api_key"] is None
+ assert kwargs["enable_local_evaluation"] is False
+
+ def test_the_client_is_built_once(self, mocker):
+ configure(mocker)
+ posthog = mocker.patch.object(ph, "Posthog")
+
+ ph.get_flag_client()
+ ph.get_flag_client()
+
+ posthog.assert_called_once()
+
+ def test_concurrent_first_reads_build_one_client(self, mocker):
+ """The executor reads flags from two loops on two threads; a second
+ client would leak a poller thread nothing closes."""
+ configure(mocker)
+
+ def slow_construction(*args, **kwargs):
+ time.sleep(0.05)
+ return mocker.Mock()
+
+ posthog = mocker.patch.object(ph, "Posthog", side_effect=slow_construction)
+ start = threading.Barrier(8)
+
+ def first_read():
+ start.wait()
+ return ph.get_flag_client()
+
+ with ThreadPoolExecutor(max_workers=8) as pool:
+ clients = list(pool.map(lambda _: first_read(), range(8)))
+
+ posthog.assert_called_once()
+ assert all(client is clients[0] for client in clients)
+
+ def test_an_unconfigured_deployment_does_not_retry_forever(self, mocker):
+ """Same reason LaunchDarkly gates on "did we try": a warning and a
+ construction attempt per flag read on deployments shipping without
+ PostHog."""
+ configure(mocker, api_key="")
+ warn = mocker.patch.object(ph.logger, "warning")
+
+ ph.get_flag_client()
+ ph.get_flag_client()
+
+ assert warn.call_count == 1
+
+ def test_shutdown_releases_the_singleton(self, mocker):
+ configure(mocker)
+ client = mocker.patch.object(ph, "Posthog").return_value
+
+ ph.get_flag_client()
+ ph.shutdown_posthog_flags()
+
+ client.shutdown.assert_called_once()
+ assert ph._client is None
+
+ def test_shutdown_without_a_client_is_a_no_op(self, mocker):
+ ph.shutdown_posthog_flags()
+
+ def test_the_client_can_be_rebuilt_after_shutdown(self, mocker):
+ """An in-process restart — SpinTestServer spins the app repeatedly —
+ must not leave every flag read answering with its default forever."""
+ configure(mocker)
+ posthog = mocker.patch.object(ph, "Posthog")
+
+ ph.get_flag_client()
+ ph.shutdown_posthog_flags()
+ ph.initialize_posthog_flags()
+
+ assert ph.get_flag_client() is not None
+ assert posthog.call_count == 2
+
+ def test_a_late_read_after_shutdown_does_not_rebuild(self, mocker):
+ """A shadow read runs in a worker thread that outlives the cancelled
+ task; a client built there would start a poller nothing closes."""
+ configure(mocker)
+ posthog = mocker.patch.object(ph, "Posthog")
+
+ ph.get_flag_client()
+ ph.shutdown_posthog_flags()
+
+ assert ph.get_flag_client() is None
+ assert posthog.call_count == 1
+
+ def test_an_unconfigured_first_attempt_does_not_latch_the_gate(self, mocker):
+ """Shutdown clears "did we try" even though it built no client, or
+ credentials arriving later in the process can never be picked up."""
+ configure(mocker, api_key="")
+ mocker.patch.object(ph, "Posthog")
+ assert ph.get_flag_client() is None
+
+ ph.shutdown_posthog_flags()
+ configure(mocker)
+ ph.initialize_posthog_flags()
+
+ assert ph.get_flag_client() is not None
+
+
+class TestRawRead:
+ @pytest.mark.asyncio
+ async def test_an_unconfigured_client_returns_the_default(self, mocker):
+ mocker.patch.object(ph, "get_flag_client", return_value=None)
+
+ assert await ph.evaluate_flag("hire-experts", "u-1", default=True) == (
+ True,
+ False,
+ )
+
+ @pytest.mark.asyncio
+ async def test_a_resolved_flag_is_evaluated(self, mocker):
+ client = mocker.Mock()
+ client.evaluate_flags.return_value = snapshot(mocker, value=False)
+ mocker.patch.object(ph, "get_flag_client", return_value=client)
+
+ assert await ph.evaluate_flag("hire-experts", "u-1") == (False, True)
+
+ @pytest.mark.asyncio
+ async def test_an_unresolved_flag_is_not(self, mocker):
+ client = mocker.Mock()
+ client.evaluate_flags.return_value = snapshot(mocker, value=None)
+ mocker.patch.object(ph, "get_flag_client", return_value=client)
+
+ assert await ph.evaluate_flag("hire-experts", "u-1", default=True) == (
+ True,
+ False,
+ )
+
+ @pytest.mark.asyncio
+ async def test_a_payload_wins_over_the_flag_value(self, mocker):
+ client = mocker.Mock()
+ client.evaluate_flags.return_value = snapshot(
+ mocker, value=True, payload={"daily": 5}
+ )
+ mocker.patch.object(ph, "get_flag_client", return_value=client)
+
+ assert await ph.evaluate_flag("copilot-cost-limits", "system") == (
+ {"daily": 5},
+ True,
+ )
+
+ @pytest.mark.asyncio
+ async def test_a_conclusive_off_wins_over_a_stale_payload(self, mocker):
+ """Serving the payload here would make an authoritative "off" read as
+ a non-boolean, i.e. as "could not evaluate"."""
+ client = mocker.Mock()
+ client.evaluate_flags.return_value = snapshot(
+ mocker, value=False, payload={"daily": 5}
+ )
+ mocker.patch.object(ph, "get_flag_client", return_value=client)
+
+ assert await ph.evaluate_flag("hire-experts", "u-1") == (False, True)
+
+ @pytest.mark.asyncio
+ async def test_a_variant_key_is_returned_as_the_value(self, mocker):
+ client = mocker.Mock()
+ client.evaluate_flags.return_value = snapshot(mocker, value="control")
+ mocker.patch.object(ph, "get_flag_client", return_value=client)
+
+ assert await ph.evaluate_flag("stripe-product-id-topup", "u-1") == (
+ "control",
+ True,
+ )
+
+ @pytest.mark.asyncio
+ async def test_the_read_is_scoped_to_one_flag(self, mocker):
+ client = mocker.Mock()
+ client.evaluate_flags.return_value = snapshot(mocker, value=True)
+ mocker.patch.object(ph, "get_flag_client", return_value=client)
+
+ await ph.evaluate_flag("hire-experts", "u-1", {"role": "admin"})
+
+ args, kwargs = client.evaluate_flags.call_args
+ assert args[0] == "u-1"
+ assert kwargs["flag_keys"] == ["hire-experts"]
+ assert kwargs["person_properties"] == {"role": "admin"}
+
+ @pytest.mark.asyncio
+ async def test_a_failed_evaluation_returns_the_default(self, mocker):
+ client = mocker.Mock()
+ client.evaluate_flags.side_effect = Exception("connection refused")
+ mocker.patch.object(ph, "get_flag_client", return_value=client)
+
+ assert await ph.evaluate_flag("hire-experts", "u-1", default=True) == (
+ True,
+ False,
+ )
+
+ def test_blocked_reads_leave_the_default_executor_free(self, mocker):
+ """Remote reads that hang must not starve other ``to_thread`` work."""
+ release = threading.Event()
+ entered = 0
+ lock = threading.Lock()
+
+ def blocking_read(*args, **kwargs):
+ nonlocal entered
+ with lock:
+ entered += 1
+ release.wait(10)
+ return snapshot(mocker, value=True)
+
+ client = mocker.Mock()
+ client.evaluate_flags.side_effect = blocking_read
+ mocker.patch.object(ph, "get_flag_client", return_value=client)
+
+ async def scenario():
+ loop = asyncio.get_running_loop()
+ loop.set_default_executor(
+ ThreadPoolExecutor(max_workers=ph.FLAG_READ_WORKERS)
+ )
+ reads = [
+ asyncio.create_task(ph.evaluate_flag("hire-experts", f"u-{i}"))
+ for i in range(ph.FLAG_READ_WORKERS + 1)
+ ]
+ try:
+ deadline = time.monotonic() + 5
+ while entered < ph.FLAG_READ_WORKERS:
+ assert time.monotonic() < deadline
+ await asyncio.sleep(0.01)
+ return await asyncio.wait_for(asyncio.to_thread(lambda: "probe"), 2)
+ finally:
+ release.set()
+ await asyncio.gather(*reads)
+ await loop.shutdown_default_executor()
+
+ # A private loop, so swapping its default executor touches no other test.
+ loop = asyncio.new_event_loop()
+ try:
+ assert loop.run_until_complete(scenario()) == "probe"
+ finally:
+ loop.close()
diff --git a/autogpt_platform/backend/backend/util/metrics.py b/autogpt_platform/backend/backend/util/metrics.py
index 8a24b6057b..ee5eb51b1d 100644
--- a/autogpt_platform/backend/backend/util/metrics.py
+++ b/autogpt_platform/backend/backend/util/metrics.py
@@ -267,7 +267,13 @@ def sentry_init():
sentry_dsn = settings.secrets.sentry_dsn
integrations = []
- if feature_flag.is_configured() and LaunchDarklyIntegration is not None:
+ # Only wire the LaunchDarkly inspector where LaunchDarkly actually answers
+ # flag reads; in posthog mode this would build a client nothing else uses.
+ if (
+ feature_flag.serves_launchdarkly()
+ and feature_flag.is_configured()
+ and LaunchDarklyIntegration is not None
+ ):
try:
integrations.append(LaunchDarklyIntegration(feature_flag.get_client()))
except DidNotEnable as e:
diff --git a/autogpt_platform/backend/backend/util/settings.py b/autogpt_platform/backend/backend/util/settings.py
index c5ee9f49fc..6db5487ff3 100644
--- a/autogpt_platform/backend/backend/util/settings.py
+++ b/autogpt_platform/backend/backend/util/settings.py
@@ -1,4 +1,5 @@
import json
+import logging
import os
import re
from enum import Enum
@@ -21,6 +22,8 @@ from pydantic_settings import (
from backend.util.data import get_data_path
+logger = logging.getLogger(__name__)
+
T = TypeVar("T", bound=BaseSettings)
_SERVICE_NAME = "MainProcess"
@@ -46,6 +49,20 @@ class BehaveAs(str, Enum):
CLOUD = "cloud"
+class FeatureFlagBackend(str, Enum):
+ """Which vendor answers a feature flag read.
+
+ ``DUAL`` evaluates both and serves LaunchDarkly's answer, so a
+ disagreement is measurable before the switch. The backend always serves
+ LaunchDarkly in this mode; the frontend falls back to PostHog where
+ LaunchDarkly is not configured, because there its answer never arrives.
+ """
+
+ LAUNCHDARKLY = "launchdarkly"
+ POSTHOG = "posthog"
+ DUAL = "dual"
+
+
class UpdateTrackingModel(BaseModel, Generic[T]):
_updated_fields: Set[str] = PrivateAttr(default_factory=set)
@@ -726,6 +743,32 @@ class Config(UpdateTrackingModel["Config"], BaseSettings):
description="The name of the app environment: local or dev or prod",
)
+ feature_flag_backend: FeatureFlagBackend = Field(
+ default=FeatureFlagBackend.LAUNCHDARKLY,
+ description="Which vendor answers feature flag reads: launchdarkly "
+ "(default), posthog, or dual (evaluate both, serve LaunchDarkly, log "
+ "every disagreement).",
+ )
+
+ @field_validator("feature_flag_backend", mode="before")
+ @classmethod
+ def _default_unknown_flag_backend(cls, v):
+ """A typo here must not stop the process from booting.
+
+ Settings is built at import of every module that reads a flag, so a
+ rejected value is a boot crash rather than a misconfigured flag read.
+ """
+ if not isinstance(v, str):
+ return v
+ try:
+ return FeatureFlagBackend(v.strip().lower())
+ except ValueError:
+ logger.warning(
+ f"Unknown FEATURE_FLAG_BACKEND {v!r}, "
+ f"falling back to {FeatureFlagBackend.LAUNCHDARKLY.value}"
+ )
+ return FeatureFlagBackend.LAUNCHDARKLY
+
behave_as: BehaveAs = Field(
default=BehaveAs.LOCAL,
description="What environment to behave as: local or cloud",
@@ -1115,6 +1158,11 @@ class Secrets(UpdateTrackingModel["Secrets"], BaseSettings):
posthog_host: str = Field(
default="https://eu.i.posthog.com", description="PostHog host URL"
)
+ posthog_personal_api_key: str = Field(
+ default="",
+ description="PostHog personal API key. Only used for local feature-flag "
+ "evaluation; without it flag reads fall back to a remote /flags call.",
+ )
# Add more secret fields as needed
model_config = SettingsConfigDict(
diff --git a/autogpt_platform/frontend/.env.default b/autogpt_platform/frontend/.env.default
index 160df2732e..3b182dfc3c 100644
--- a/autogpt_platform/frontend/.env.default
+++ b/autogpt_platform/frontend/.env.default
@@ -57,6 +57,11 @@ NEXT_PUBLIC_BEHAVE_AS=LOCAL
# Feature flags
NEXT_PUBLIC_LAUNCHDARKLY_ENABLED=false
NEXT_PUBLIC_LAUNCHDARKLY_CLIENT_ID=687ab1372f497809b131e06e
+# Which vendor answers a flag read: launchdarkly (default), posthog, or dual
+# (read both, report every disagreement, and serve LaunchDarkly when it is
+# configured — otherwise PostHog, since LaunchDarkly's answer never arrives
+# without its provider).
+NEXT_PUBLIC_FEATURE_FLAG_BACKEND=launchdarkly
# Local-dev master switch: turn EVERY boolean feature flag on at once, without
# listing them. Off by default. A per-flag NEXT_PUBLIC_FORCE_FLAG_<NAME> still
# wins, so one flag can be excluded with =false; array/JSON flags keep their
diff --git a/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/__tests__/brain-dump.test.tsx b/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/__tests__/brain-dump.test.tsx
index 1d11426330..e065cf9570 100644
--- a/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/__tests__/brain-dump.test.tsx
+++ b/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/__tests__/brain-dump.test.tsx
@@ -168,11 +168,9 @@ vi.mock("@/services/feature-flags/use-get-flag", () => ({
HIRE_EXPERTS: "hire-experts",
},
useGetFlag: (flag: string) => mockFlags[flag] ?? false,
-}));
-
-vi.mock("launchdarkly-react-client-sdk", () => ({
- useLDClient: () => ({
- waitForInitialization: () => Promise.resolve(),
+ useFlagStatus: (flag: string) => ({
+ enabled: mockFlags[flag] ?? false,
+ ready: true,
}),
}));
diff --git a/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/__tests__/page.test.tsx b/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/__tests__/page.test.tsx
index a7579eeb47..a0aa0ca7bb 100644
--- a/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/__tests__/page.test.tsx
+++ b/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/__tests__/page.test.tsx
@@ -114,15 +114,21 @@ vi.mock("@/services/feature-flags/use-get-flag", () => ({
ONBOARDING_EXPERT_TEAM: "ONBOARDING_EXPERT_TEAM",
HIRE_EXPERTS: "HIRE_EXPERTS",
},
- useGetFlag: (flag: string) => {
- if (flag === "ENABLE_PLATFORM_PAYMENT") return mockFlagValue;
- if (flag === "ONBOARDING_EXPERT_TEAM") return mockExpertTeamEnabled;
- if (flag === "HIRE_EXPERTS") return mockHireExpertsEnabled;
- if (flag === "ONBOARDING_BRAIN_DUMP") return mockBrainDumpEnabled;
- return false;
- },
+ useGetFlag: (flag: string) => resolveFlag(flag),
+ useFlagStatus: (flag: string) => ({
+ enabled: resolveFlag(flag),
+ ready: true,
+ }),
}));
+function resolveFlag(flag: string) {
+ if (flag === "ENABLE_PLATFORM_PAYMENT") return mockFlagValue;
+ if (flag === "ONBOARDING_EXPERT_TEAM") return mockExpertTeamEnabled;
+ if (flag === "HIRE_EXPERTS") return mockHireExpertsEnabled;
+ if (flag === "ONBOARDING_BRAIN_DUMP") return mockBrainDumpEnabled;
+ return false;
+}
+
// The brain dump step is the real one when its flag is on; the page tests
// only care which slot it occupies.
vi.mock("../steps/BrainDumpStep/BrainDumpStep", () => ({
diff --git a/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/useOnboardingPage.ts b/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/useOnboardingPage.ts
index 3ea72f8c76..818f4499e7 100644
--- a/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/useOnboardingPage.ts
+++ b/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/useOnboardingPage.ts
@@ -10,16 +10,17 @@ import { useAuth } from "@/lib/auth/hooks/useAuth";
import { trackAdsConversion } from "@/services/analytics/google-ads";
import { environment } from "@/services/environment";
import { useTrialCheckoutReturn } from "@/services/trials/useTrialCheckoutReturn";
-import { Flag, useGetFlag } from "@/services/feature-flags/use-get-flag";
-import { useLDClient } from "launchdarkly-react-client-sdk";
+import {
+ Flag,
+ useFlagStatus,
+ useGetFlag,
+} from "@/services/feature-flags/use-get-flag";
import { useRouter, useSearchParams } from "next/navigation";
import { useEffect, useRef, useState } from "react";
import { accountDisplayName, normalizeOnboardingProfile } from "./helpers";
import { buildStepLayout, Step, useOnboardingWizardStore } from "./store";
import { onboardingStepKey, trackOnboardingStep } from "./tracking";
-const LD_INIT_TIMEOUT_SECONDS = 5;
-
// SessionStorage ceiling for the wizard. The backend's `completedSteps`
// only records ONBOARDING_COMPLETE at the very end (the 5 in-wizard steps
// aren't tracked individually), so resume / fast-forward guardrails are
@@ -59,35 +60,18 @@ export function useOnboardingPage() {
const goToStep = useOnboardingWizardStore((s) => s.goToStep);
const setSteps = useOnboardingWizardStore((s) => s.setSteps);
- // Wait for LaunchDarkly before initialising the wizard from the URL.
+ // Wait for the flag vendor before initialising the wizard from the URL.
// Without this, the init effect runs against the default flag value
// (false) on first render and clamps e.g. ?step=5 down to step 1; once
// the flag resolves to true, the hasInitialized guard blocks re-init
// and the user is stuck on step 1.
- const ldClient = useLDClient();
- const ldEnabled = environment.areFeatureFlagsEnabled();
- const [areFlagsReady, setAreFlagsReady] = useState(!ldEnabled);
- useEffect(() => {
- if (!ldEnabled || !ldClient || areFlagsReady) return;
- let cancelled = false;
- // Use the same 5s timeout as LDProvider so the wizard never hangs
- // when LaunchDarkly is unreachable; on timeout we fall back to the
- // default flag values that useGetFlag already returns.
- ldClient
- .waitForInitialization(LD_INIT_TIMEOUT_SECONDS)
- .catch(() => undefined)
- .finally(() => {
- if (!cancelled) setAreFlagsReady(true);
- });
- return () => {
- cancelled = true;
- };
- }, [ldClient, ldEnabled, areFlagsReady]);
-
- // Snapshot the flag once LaunchDarkly resolves so an admin toggling
+ //
+ // Snapshot the value once it resolves so an admin toggling
// ENABLE_PLATFORM_PAYMENT mid-session can't shuffle steps under a user
// who is already inside the wizard.
- const livePaymentEnabled = useGetFlag(Flag.ENABLE_PLATFORM_PAYMENT);
+ const { enabled: livePaymentEnabled, ready: areFlagsReady } = useFlagStatus(
+ Flag.ENABLE_PLATFORM_PAYMENT,
+ );
const paymentEnabledSnapshot = useRef<boolean | null>(null);
if (paymentEnabledSnapshot.current === null && areFlagsReady) {
paymentEnabledSnapshot.current = livePaymentEnabled;
diff --git a/autogpt_platform/frontend/src/app/(platform)/settings/memory/page.tsx b/autogpt_platform/frontend/src/app/(platform)/settings/memory/page.tsx
index 0c0edc0c48..d47640d598 100644
--- a/autogpt_platform/frontend/src/app/(platform)/settings/memory/page.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/settings/memory/page.tsx
@@ -2,6 +2,7 @@
import { Text } from "@/components/atoms/Text/Text";
import { ErrorCard } from "@/components/molecules/ErrorCard/ErrorCard";
+import { Flag } from "@/services/feature-flags/use-get-flag";
import { withFeatureFlag } from "@/services/feature-flags/with-feature-flag";
import { useEffect } from "react";
@@ -102,4 +103,4 @@ function SettingsMemoryPage() {
);
}
-export default withFeatureFlag(SettingsMemoryPage, "graphiti-memory");
+export default withFeatureFlag(SettingsMemoryPage, Flag.GRAPHITI_MEMORY);
diff --git a/autogpt_platform/frontend/src/providers/posthog/__tests__/posthog-user-tracker.test.tsx b/autogpt_platform/frontend/src/providers/posthog/__tests__/posthog-user-tracker.test.tsx
new file mode 100644
index 0000000000..920bf95267
--- /dev/null
+++ b/autogpt_platform/frontend/src/providers/posthog/__tests__/posthog-user-tracker.test.tsx
@@ -0,0 +1,75 @@
+import { render } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const posthog = vi.hoisted(() => ({
+ identify: vi.fn(),
+ setPersonPropertiesForFlags: vi.fn(),
+}));
+const flags = vi.hoisted(() => ({ usesPostHog: false }));
+
+vi.mock("posthog-js", () => ({ default: posthog }));
+
+vi.mock("@/lib/auth/hooks/useAuth", () => ({
+ useAuth: () => ({
+ isUserLoading: false,
+ user: {
+ id: "user-1",
+ email: "[email protected]",
+ role: "authenticated",
+ created_at: "2026-05-08T12:00:00Z",
+ user_metadata: { name: "Ada" },
+ },
+ }),
+}));
+
+vi.mock("@/services/environment", () => ({
+ environment: { isPostHogEnabled: () => true },
+}));
+
+vi.mock("@/services/feature-flags/flag-backend", () => ({
+ usesPostHog: () => flags.usesPostHog,
+}));
+
+describe("PostHogUserTracker", () => {
+ beforeEach(() => {
+ posthog.identify.mockClear();
+ posthog.setPersonPropertiesForFlags.mockClear();
+ });
+
+ it.each([false, true])(
+ "identifies with the analytics properties only (PostHog flags: %s)",
+ async (usesPostHog) => {
+ flags.usesPostHog = usesPostHog;
+ const { PostHogUserTracker } = await import("../posthog-provider");
+
+ render(<PostHogUserTracker />);
+
+ expect(posthog.identify).toHaveBeenCalledWith("user-1", {
+ email: "[email protected]",
+ name: "Ada",
+ });
+ },
+ );
+
+ it("hands the targeting attributes to flag evaluation alone", async () => {
+ flags.usesPostHog = true;
+ const { PostHogUserTracker } = await import("../posthog-provider");
+
+ render(<PostHogUserTracker />);
+
+ expect(posthog.setPersonPropertiesForFlags).toHaveBeenCalledWith({
+ email_domain: "example.com",
+ role: "authenticated",
+ created_at: "2026-05-08T12:00:00Z",
+ });
+ });
+
+ it("leaves flag properties alone while LaunchDarkly answers flags", async () => {
+ flags.usesPostHog = false;
+ const { PostHogUserTracker } = await import("../posthog-provider");
+
+ render(<PostHogUserTracker />);
+
+ expect(posthog.setPersonPropertiesForFlags).not.toHaveBeenCalled();
+ });
+});
diff --git a/autogpt_platform/frontend/src/providers/posthog/posthog-provider.tsx b/autogpt_platform/frontend/src/providers/posthog/posthog-provider.tsx
index 3c0ff6a328..b422f33582 100644
--- a/autogpt_platform/frontend/src/providers/posthog/posthog-provider.tsx
+++ b/autogpt_platform/frontend/src/providers/posthog/posthog-provider.tsx
@@ -6,6 +6,8 @@ import {
getAnonymousID,
} from "@/services/analytics/anonymous-id";
import { environment } from "@/services/environment";
+import { usesPostHog } from "@/services/feature-flags/flag-backend";
+import { buildFlagPersonProperties } from "@/services/feature-flags/helpers";
import { PostHogProvider as PHProvider } from "@posthog/react";
import { usePathname, useSearchParams } from "next/navigation";
import posthog from "posthog-js";
@@ -54,6 +56,11 @@ export function PostHogUserTracker() {
if (user) {
if (previousUserIdRef.current !== user.id) {
+ // Flag-only properties ride on /flags and are never stored on the
+ // person profile, so identify stays exactly what analytics sends.
+ if (usesPostHog()) {
+ posthog.setPersonPropertiesForFlags(buildFlagPersonProperties(user));
+ }
posthog.identify(user.id, {
email: user.email,
...(user.user_metadata?.name && { name: user.user_metadata.name }),
diff --git a/autogpt_platform/frontend/src/services/feature-flags/FeatureFlagPage.tsx b/autogpt_platform/frontend/src/services/feature-flags/FeatureFlagPage.tsx
index eef0691de2..f7d49e805f 100644
--- a/autogpt_platform/frontend/src/services/feature-flags/FeatureFlagPage.tsx
+++ b/autogpt_platform/frontend/src/services/feature-flags/FeatureFlagPage.tsx
@@ -1,57 +1,28 @@
"use client";
import { LoadingSpinner } from "@/components/atoms/LoadingSpinner/LoadingSpinner";
-import { useLDClient } from "launchdarkly-react-client-sdk";
import { useRouter } from "next/navigation";
-import { ReactNode, useEffect, useState } from "react";
-import { environment } from "../environment";
-import { Flag, useGetFlag } from "./use-get-flag";
+import { ReactNode, useEffect } from "react";
+import { Flag, useFlagStatus } from "./use-get-flag";
-interface FeatureFlagRedirectProps {
+interface Props {
flag: Flag;
whenDisabled: string;
children: ReactNode;
}
-export function FeatureFlagPage({
- flag,
- whenDisabled,
- children,
-}: FeatureFlagRedirectProps) {
- const [isLoading, setIsLoading] = useState(true);
+export function FeatureFlagPage({ flag, whenDisabled, children }: Props) {
const router = useRouter();
- const flagValue = useGetFlag(flag);
- const ldClient = useLDClient();
- const ldEnabled = environment.areFeatureFlagsEnabled();
- const ldReady = Boolean(ldClient);
- const flagEnabled = Boolean(flagValue);
+ const { enabled, ready } = useFlagStatus(flag);
+ const flagEnabled = Boolean(enabled);
useEffect(() => {
- const initialize = async () => {
- if (!ldEnabled) {
- router.replace(whenDisabled);
- setIsLoading(false);
- return;
- }
+ if (ready && !flagEnabled) {
+ router.replace(whenDisabled);
+ }
+ }, [ready, flagEnabled, router, whenDisabled]);
- // Wait for LaunchDarkly to initialize when enabled to prevent race conditions
- if (ldEnabled && !ldReady) return;
-
- try {
- await ldClient?.waitForInitialization();
- if (!flagEnabled) router.replace(whenDisabled);
- } catch (error) {
- console.error(error);
- router.replace(whenDisabled);
- } finally {
- setIsLoading(false);
- }
- };
-
- initialize();
- }, [ldReady, flagEnabled]);
-
- return isLoading || !flagEnabled ? (
+ return !ready || !flagEnabled ? (
<LoadingSpinner size="large" cover />
) : (
<>{children}</>
diff --git a/autogpt_platform/frontend/src/services/feature-flags/FeatureFlagRedirect.tsx b/autogpt_platform/frontend/src/services/feature-flags/FeatureFlagRedirect.tsx
index b843b5567c..c2b1f9fb1b 100644
--- a/autogpt_platform/frontend/src/services/feature-flags/FeatureFlagRedirect.tsx
+++ b/autogpt_platform/frontend/src/services/feature-flags/FeatureFlagRedirect.tsx
@@ -1,13 +1,11 @@
"use client";
import { LoadingSpinner } from "@/components/atoms/LoadingSpinner/LoadingSpinner";
-import { useLDClient } from "launchdarkly-react-client-sdk";
import { useRouter } from "next/navigation";
import { useEffect } from "react";
-import { environment } from "../environment";
-import { Flag, useGetFlag } from "./use-get-flag";
+import { Flag, useFlagStatus } from "./use-get-flag";
-interface FeatureFlagRedirectProps {
+interface Props {
flag: Flag;
whenEnabled: string;
whenDisabled: string;
@@ -17,35 +15,15 @@ export function FeatureFlagRedirect({
flag,
whenEnabled,
whenDisabled,
-}: FeatureFlagRedirectProps) {
+}: Props) {
const router = useRouter();
- const flagValue = useGetFlag(flag);
- const ldEnabled = environment.areFeatureFlagsEnabled();
- const ldClient = useLDClient();
- const ldReady = Boolean(ldClient);
- const flagEnabled = Boolean(flagValue);
+ const { enabled, ready } = useFlagStatus(flag);
+ const flagEnabled = Boolean(enabled);
useEffect(() => {
- const initialize = async () => {
- if (!ldEnabled) {
- router.replace(whenDisabled);
- return;
- }
-
- // Wait for LaunchDarkly to initialize when enabled to prevent race conditions
- if (ldEnabled && !ldReady) return;
-
- try {
- await ldClient?.waitForInitialization();
- router.replace(flagEnabled ? whenEnabled : whenDisabled);
- } catch (error) {
- console.error(error);
- router.replace(whenDisabled);
- }
- };
-
- initialize();
- }, [ldReady, flagEnabled]);
+ if (!ready) return;
+ router.replace(flagEnabled ? whenEnabled : whenDisabled);
+ }, [ready, flagEnabled, router, whenEnabled, whenDisabled]);
return <LoadingSpinner size="large" cover />;
}
diff --git a/autogpt_platform/frontend/src/services/feature-flags/__tests__/flag-backends.test.tsx b/autogpt_platform/frontend/src/services/feature-flags/__tests__/flag-backends.test.tsx
new file mode 100644
index 0000000000..41756582a0
--- /dev/null
+++ b/autogpt_platform/frontend/src/services/feature-flags/__tests__/flag-backends.test.tsx
@@ -0,0 +1,386 @@
+import { renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const launchDarkly = vi.hoisted(() => ({
+ flags: {} as Record<string, unknown>,
+}));
+const postHog = vi.hoisted(() => ({
+ enabled: vi.fn(),
+ payload: vi.fn(),
+ capture: vi.fn(),
+ // Whether /flags has answered live this page load, and how.
+ loaded: true,
+ errorsLoading: false,
+}));
+const postHogClient = vi.hoisted(() => ({
+ capture: (...args: unknown[]) => postHog.capture(...args),
+ featureFlags: {
+ get hasLoadedFlags() {
+ return postHog.loaded && !postHog.errorsLoading;
+ },
+ },
+ onFeatureFlags: (
+ callback: (
+ flags: string[],
+ variants: Record<string, unknown>,
+ context?: { errorsLoading?: boolean },
+ ) => void,
+ ) => {
+ if (postHog.loaded) {
+ callback([], {}, { errorsLoading: postHog.errorsLoading });
+ }
+ return () => {};
+ },
+}));
+
+vi.mock("launchdarkly-react-client-sdk", () => ({
+ useFlags: () => launchDarkly.flags,
+}));
+
+vi.mock("@posthog/react", () => ({
+ useFeatureFlagEnabled: (flag: string) => postHog.enabled(flag),
+ useFeatureFlagPayload: (flag: string) => postHog.payload(flag),
+ usePostHog: () => postHogClient,
+}));
+
+vi.mock("@/app/(platform)/marketplace/components/HeroSection/helpers", () => ({
+ DEFAULT_SEARCH_TERMS: [],
+}));
+
+const env = vi.hoisted(() => ({ launchDarklyEnabled: true }));
+
+vi.mock("@/services/environment", () => ({
+ environment: { areFeatureFlagsEnabled: () => env.launchDarklyEnabled },
+}));
+
+const HIRE_EXPERTS = "hire-experts";
+
+describe("launchdarkly is the default backend", () => {
+ it("reads the LaunchDarkly value and never touches PostHog", async () => {
+ const { Flag, useGetFlag } = await loadWithBackend(undefined);
+ launchDarkly.flags = { [HIRE_EXPERTS]: true };
+
+ const { result } = renderHook(() => useGetFlag(Flag.HIRE_EXPERTS));
+
+ expect(result.current).toBe(true);
+ expect(postHog.enabled).not.toHaveBeenCalled();
+ expect(postHog.payload).not.toHaveBeenCalled();
+ });
+
+ it("reports a flag LaunchDarkly has not answered for as not ready", async () => {
+ const { Flag, useFlagStatus } = await loadWithBackend(undefined);
+ launchDarkly.flags = {};
+
+ const { result } = renderHook(() => useFlagStatus(Flag.HIRE_EXPERTS));
+
+ expect(result.current).toEqual({
+ enabled: false,
+ ready: false,
+ answered: false,
+ });
+ });
+});
+
+describe("posthog backend", () => {
+ it("serves an enabled flag", async () => {
+ const { Flag, useFlagStatus } = await loadWithBackend("posthog");
+ postHog.enabled.mockReturnValue(true);
+
+ const { result } = renderHook(() => useFlagStatus(Flag.HIRE_EXPERTS));
+
+ expect(result.current).toEqual({
+ enabled: true,
+ ready: true,
+ answered: true,
+ });
+ });
+
+ it("distinguishes a conclusive off from no answer yet", async () => {
+ const { Flag, useFlagStatus } = await loadWithBackend("posthog");
+ postHog.enabled.mockReturnValue(false);
+ const off = renderHook(() => useFlagStatus(Flag.HIRE_EXPERTS));
+ expect(off.result.current).toEqual({
+ enabled: false,
+ ready: true,
+ answered: true,
+ });
+
+ postHog.loaded = false;
+ const unanswered = renderHook(() => useFlagStatus(Flag.HIRE_EXPERTS));
+ expect(unanswered.result.current).toEqual({
+ enabled: false,
+ ready: false,
+ answered: false,
+ });
+ });
+
+ it("does not call a persisted snapshot an answer before /flags runs", async () => {
+ const { Flag, useFlagStatus } = await loadWithBackend("posthog");
+ postHog.loaded = false;
+ postHog.enabled.mockReturnValue(true);
+
+ const { result } = renderHook(() => useFlagStatus(Flag.HIRE_EXPERTS));
+
+ expect(result.current.answered).toBe(false);
+ });
+
+ it("does not call a failed /flags load an answer", async () => {
+ const { Flag, useFlagStatus } = await loadWithBackend("posthog");
+ postHog.errorsLoading = true;
+
+ const { result } = renderHook(() => useFlagStatus(Flag.HIRE_EXPERTS));
+
+ expect(result.current.answered).toBe(false);
+ });
+
+ it("answers a flag PostHog has never heard of with its default", async () => {
+ const { Flag, useFlagStatus } = await loadWithBackend("posthog");
+ postHog.enabled.mockReturnValue(undefined);
+
+ const { result } = renderHook(() => useFlagStatus(Flag.HIRE_EXPERTS));
+
+ expect(result.current).toEqual({
+ enabled: false,
+ ready: true,
+ answered: true,
+ });
+ });
+
+ it("serves an explicit off over a payload, as the backend does", async () => {
+ const { Flag, useGetFlag } = await loadWithBackend("posthog");
+ postHog.enabled.mockReturnValue(false);
+ postHog.payload.mockReturnValue({ slack: true });
+
+ const { result } = renderHook(() => useGetFlag(Flag.COPILOT_BOT_PLATFORMS));
+
+ expect(result.current).toEqual({});
+ });
+
+ it("returns a payload for the JSON-valued flags", async () => {
+ const { Flag, useGetFlag } = await loadWithBackend("posthog");
+ postHog.enabled.mockReturnValue(true);
+ postHog.payload.mockReturnValue({ slack: false });
+
+ const { result } = renderHook(() => useGetFlag(Flag.COPILOT_BOT_PLATFORMS));
+
+ expect(result.current).toEqual({ slack: false });
+ });
+
+ it("still honours a forced flag", async () => {
+ const { Flag, useGetFlag } = await loadWithBackend("posthog");
+ process.env.NEXT_PUBLIC_FORCE_FLAG_HIRE_EXPERTS = "true";
+ postHog.enabled.mockReturnValue(false);
+
+ const { result } = renderHook(() => useGetFlag(Flag.HIRE_EXPERTS));
+
+ expect(result.current).toBe(true);
+ });
+
+ it("honours the force-all switch, and serves PostHog again without it", async () => {
+ // The local override has to sit above the vendor choice, not inside the
+ // LaunchDarkly path: force-all is how a developer opens a gate locally,
+ // and picking posthog must not silently take that away.
+ process.env.NEXT_PUBLIC_FORCE_ALL_FLAGS = "true";
+ const forced = await loadWithBackend("posthog");
+ postHog.enabled.mockReturnValue(false);
+ expect(
+ renderHook(() => forced.useFlagStatus(forced.Flag.HIRE_EXPERTS)).result
+ .current,
+ ).toEqual({ enabled: true, ready: true, answered: true });
+
+ delete process.env.NEXT_PUBLIC_FORCE_ALL_FLAGS;
+ const unforced = await loadWithBackend("posthog");
+ expect(
+ renderHook(() => unforced.useFlagStatus(unforced.Flag.HIRE_EXPERTS))
+ .result.current,
+ ).toEqual({ enabled: false, ready: true, answered: true });
+ });
+});
+
+describe("dual backend", () => {
+ it("serves LaunchDarkly's answer when the two disagree", async () => {
+ const { Flag, useGetFlag } = await loadWithBackend("dual");
+ launchDarkly.flags = { [HIRE_EXPERTS]: true };
+ postHog.enabled.mockReturnValue(false);
+
+ const { result } = renderHook(() => useGetFlag(Flag.HIRE_EXPERTS));
+
+ expect(result.current).toBe(true);
+ });
+
+ it("reports the disagreement to PostHog and the console", async () => {
+ const { Flag, useGetFlag } = await loadWithBackend("dual");
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ launchDarkly.flags = { [HIRE_EXPERTS]: true };
+ postHog.enabled.mockReturnValue(false);
+
+ renderHook(() => useGetFlag(Flag.HIRE_EXPERTS));
+
+ expect(postHog.capture).toHaveBeenCalledWith("feature_flag_mismatch", {
+ flag: HIRE_EXPERTS,
+ launchdarkly: { value: true, resolved: true },
+ posthog: { value: false, resolved: true },
+ });
+ expect(warn).toHaveBeenCalled();
+ });
+
+ it("stays quiet when the two agree", async () => {
+ const { Flag, useGetFlag } = await loadWithBackend("dual");
+ launchDarkly.flags = { [HIRE_EXPERTS]: true };
+ postHog.enabled.mockReturnValue(true);
+
+ renderHook(() => useGetFlag(Flag.HIRE_EXPERTS));
+
+ expect(postHog.capture).not.toHaveBeenCalled();
+ });
+
+ it("stays quiet when a JSON flag differs only in key order", async () => {
+ const { Flag, useGetFlag } = await loadWithBackend("dual");
+ launchDarkly.flags = {
+ [Flag.COPILOT_BOT_PLATFORMS]: { slack: true, discord: false },
+ };
+ postHog.enabled.mockReturnValue(true);
+ postHog.payload.mockReturnValue({ discord: false, slack: true });
+
+ renderHook(() => useGetFlag(Flag.COPILOT_BOT_PLATFORMS));
+
+ expect(postHog.capture).not.toHaveBeenCalled();
+ });
+
+ it("reports a JSON flag whose values really differ", async () => {
+ const { Flag, useGetFlag } = await loadWithBackend("dual");
+ vi.spyOn(console, "warn").mockImplementation(() => {});
+ launchDarkly.flags = {
+ [Flag.COPILOT_BOT_PLATFORMS]: { slack: true, discord: false },
+ };
+ postHog.enabled.mockReturnValue(true);
+ postHog.payload.mockReturnValue({ discord: true, slack: true });
+
+ renderHook(() => useGetFlag(Flag.COPILOT_BOT_PLATFORMS));
+
+ expect(postHog.capture).toHaveBeenCalledTimes(1);
+ });
+
+ it("reports a flag LaunchDarkly has and PostHog has never heard of", async () => {
+ const { Flag, useGetFlag } = await loadWithBackend("dual");
+ vi.spyOn(console, "warn").mockImplementation(() => {});
+ launchDarkly.flags = { [HIRE_EXPERTS]: true };
+ postHog.enabled.mockReturnValue(undefined);
+
+ renderHook(() => useGetFlag(Flag.HIRE_EXPERTS));
+
+ expect(postHog.capture).toHaveBeenCalledWith("feature_flag_mismatch", {
+ flag: HIRE_EXPERTS,
+ launchdarkly: { value: true, resolved: true },
+ posthog: { value: null, resolved: true },
+ });
+ });
+
+ it("stays quiet while only one vendor has answered", async () => {
+ // The two never resolve on the same render, so comparing before both
+ // have answered reports the load order rather than a disagreement.
+ const { Flag, useGetFlag } = await loadWithBackend("dual");
+ vi.spyOn(console, "warn").mockImplementation(() => {});
+ launchDarkly.flags = {};
+ postHog.enabled.mockReturnValue(true);
+
+ const { rerender } = renderHook(() => useGetFlag(Flag.HIRE_EXPERTS));
+ rerender();
+ expect(postHog.capture).not.toHaveBeenCalled();
+
+ launchDarkly.flags = { [HIRE_EXPERTS]: true };
+ postHog.loaded = false;
+ const pending = renderHook(() => useGetFlag(Flag.HIRE_EXPERTS));
+ pending.rerender();
+
+ expect(postHog.capture).not.toHaveBeenCalled();
+ });
+
+ it("reports once LaunchDarkly catches up and still disagrees", async () => {
+ const { Flag, useGetFlag } = await loadWithBackend("dual");
+ vi.spyOn(console, "warn").mockImplementation(() => {});
+ postHog.enabled.mockReturnValue(true);
+ const { rerender } = renderHook(() => useGetFlag(Flag.HIRE_EXPERTS));
+ expect(postHog.capture).not.toHaveBeenCalled();
+
+ launchDarkly.flags = { [HIRE_EXPERTS]: false };
+ rerender();
+
+ expect(postHog.capture).toHaveBeenCalledTimes(1);
+ });
+
+ it("serves PostHog when LaunchDarkly is not configured", async () => {
+ // Dual must degrade to whichever vendor can actually answer: with no
+ // LDProvider mounted, LaunchDarkly's empty flag set never resolves.
+ env.launchDarklyEnabled = false;
+ const { Flag, useFlagStatus } = await loadWithBackend("dual");
+ launchDarkly.flags = {};
+ postHog.enabled.mockReturnValue(true);
+
+ const { result } = renderHook(() => useFlagStatus(Flag.HIRE_EXPERTS));
+
+ expect(result.current).toEqual({
+ enabled: true,
+ ready: true,
+ answered: true,
+ });
+ });
+
+ it("does not report a disagreement when only one vendor is configured", async () => {
+ env.launchDarklyEnabled = false;
+ const { Flag, useGetFlag } = await loadWithBackend("dual");
+ postHog.enabled.mockReturnValue(true);
+
+ renderHook(() => useGetFlag(Flag.HIRE_EXPERTS));
+
+ expect(postHog.capture).not.toHaveBeenCalled();
+ });
+});
+
+describe("posthog flags follow the provider's gate", () => {
+ it("falls back to defaults outside cloud, where no PostHogProvider mounts", async () => {
+ process.env.NEXT_PUBLIC_BEHAVE_AS = "LOCAL";
+ const { Flag, useFlagStatus } = await loadWithBackend("posthog");
+ postHog.enabled.mockReturnValue(true);
+
+ const { result } = renderHook(() => useFlagStatus(Flag.HIRE_EXPERTS));
+
+ expect(result.current).toEqual({
+ enabled: false,
+ ready: true,
+ answered: true,
+ });
+ });
+});
+
+beforeEach(() => {
+ launchDarkly.flags = {};
+ postHog.enabled.mockReturnValue(undefined);
+ postHog.payload.mockReturnValue(undefined);
+ postHog.capture.mockClear();
+ postHog.loaded = true;
+ postHog.errorsLoading = false;
+ Object.keys(process.env)
+ .filter((key) => key.startsWith("NEXT_PUBLIC_FORCE_FLAG_"))
+ .forEach((key) => delete process.env[key]);
+ delete process.env.NEXT_PUBLIC_FORCE_ALL_FLAGS;
+ env.launchDarklyEnabled = true;
+ process.env.NEXT_PUBLIC_BEHAVE_AS = "CLOUD";
+ process.env.NEXT_PUBLIC_POSTHOG_KEY = "phc_test";
+ process.env.NEXT_PUBLIC_POSTHOG_HOST = "https://eu.i.posthog.com";
+});
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+// The backend is read once at module load, so each case needs a fresh import.
+async function loadWithBackend(backend: string | undefined) {
+ if (backend === undefined) {
+ delete process.env.NEXT_PUBLIC_FEATURE_FLAG_BACKEND;
+ } else {
+ process.env.NEXT_PUBLIC_FEATURE_FLAG_BACKEND = backend;
+ }
+ vi.resetModules();
+ return import("../use-get-flag");
+}
diff --git a/autogpt_platform/frontend/src/services/feature-flags/__tests__/flag-source-mocking.test.tsx b/autogpt_platform/frontend/src/services/feature-flags/__tests__/flag-source-mocking.test.tsx
new file mode 100644
index 0000000000..30e4fe64a9
--- /dev/null
+++ b/autogpt_platform/frontend/src/services/feature-flags/__tests__/flag-source-mocking.test.tsx
@@ -0,0 +1,44 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { Flag, useFlagStatus, useGetFlag } from "../use-get-flag";
+
+// Phase 2 replaces 75 `vi.mock("launchdarkly-react-client-sdk")` blocks with
+// this one, vendor-independent, seam. This test is what keeps it a seam.
+const source = vi.hoisted(() => ({
+ results: {} as Record<string, { value: unknown; resolved: boolean }>,
+}));
+
+vi.mock("../flag-source", () => ({
+ useFlagSource: (key: string) =>
+ source.results[key] ?? { value: undefined, resolved: false },
+}));
+
+vi.mock("@/app/(platform)/marketplace/components/HeroSection/helpers", () => ({
+ DEFAULT_SEARCH_TERMS: [],
+}));
+
+vi.mock("@/services/environment", () => ({
+ environment: { areFeatureFlagsEnabled: () => true },
+}));
+
+describe("mocking the flag source controls every flag hook", () => {
+ it("drives useGetFlag without mocking any vendor SDK", () => {
+ source.results = { "hire-experts": { value: true, resolved: true } };
+
+ const { result } = renderHook(() => useGetFlag(Flag.HIRE_EXPERTS));
+
+ expect(result.current).toBe(true);
+ });
+
+ it("drives useFlagStatus, including the not-answered-yet case", () => {
+ source.results = {};
+
+ const { result } = renderHook(() => useFlagStatus(Flag.HIRE_EXPERTS));
+
+ expect(result.current).toEqual({
+ enabled: false,
+ ready: false,
+ answered: false,
+ });
+ });
+});
diff --git a/autogpt_platform/frontend/src/services/feature-flags/__tests__/flag-value-shape.test.ts b/autogpt_platform/frontend/src/services/feature-flags/__tests__/flag-value-shape.test.ts
new file mode 100644
index 0000000000..67d651e88e
--- /dev/null
+++ b/autogpt_platform/frontend/src/services/feature-flags/__tests__/flag-value-shape.test.ts
@@ -0,0 +1,55 @@
+import { DEFAULT_SEARCH_TERMS } from "@/app/(platform)/marketplace/components/HeroSection/helpers";
+import { describe, expect, it } from "vitest";
+import { Flag, resolveFlagValue } from "../use-get-flag";
+
+// PostHog answers a flag with no payload as a bare boolean, which for a
+// JSON-valued flag would otherwise reach consumers that call `.map` on it.
+describe("resolveFlagValue", () => {
+ it("falls back when an array flag is answered with a boolean", () => {
+ expect(resolveFlagValue(Flag.MARKETPLACE_SEARCH_TERMS, true)).toEqual(
+ DEFAULT_SEARCH_TERMS,
+ );
+ });
+
+ it("falls back when an array flag is answered with an object", () => {
+ expect(resolveFlagValue(Flag.MARKETPLACE_SEARCH_TERMS, { a: 1 })).toEqual(
+ DEFAULT_SEARCH_TERMS,
+ );
+ });
+
+ it("keeps a real array value for an array flag", () => {
+ expect(resolveFlagValue(Flag.MARKETPLACE_SEARCH_TERMS, ["a", "b"])).toEqual(
+ ["a", "b"],
+ );
+ });
+
+ it("falls back when an object flag is answered with a boolean", () => {
+ expect(resolveFlagValue(Flag.COPILOT_BOT_PLATFORMS, true)).toEqual({});
+ });
+
+ it("falls back when an object flag is answered with an array", () => {
+ expect(resolveFlagValue(Flag.COPILOT_BOT_PLATFORMS, [])).toEqual({});
+ });
+
+ it("keeps a real object value for an object flag", () => {
+ expect(
+ resolveFlagValue(Flag.COPILOT_BOT_PLATFORMS, { discord: true }),
+ ).toEqual({ discord: true });
+ });
+
+ it("keeps a boolean for a boolean flag, both ways", () => {
+ expect(resolveFlagValue(Flag.ENABLE_PLATFORM_PAYMENT, true)).toBe(true);
+ expect(resolveFlagValue(Flag.ENABLE_PLATFORM_PAYMENT, false)).toBe(false);
+ });
+
+ it("falls back when a boolean flag is answered with a string", () => {
+ expect(resolveFlagValue(Flag.ENABLE_PLATFORM_PAYMENT, "on")).toBe(false);
+ });
+
+ it("falls back on null and undefined", () => {
+ expect(resolveFlagValue(Flag.ENABLE_PLATFORM_PAYMENT, null)).toBe(false);
+ expect(resolveFlagValue(Flag.ENABLE_PLATFORM_PAYMENT, undefined)).toBe(
+ false,
+ );
+ });
+});
diff --git a/autogpt_platform/frontend/src/services/feature-flags/__tests__/helpers.test.ts b/autogpt_platform/frontend/src/services/feature-flags/__tests__/helpers.test.ts
index 7ca023cbd1..927d4e7c23 100644
--- a/autogpt_platform/frontend/src/services/feature-flags/__tests__/helpers.test.ts
+++ b/autogpt_platform/frontend/src/services/feature-flags/__tests__/helpers.test.ts
@@ -1,6 +1,6 @@
import type { User } from "@/lib/auth/types";
import { describe, expect, it } from "vitest";
-import { buildLDContext } from "../helpers";
+import { buildFlagPersonProperties, buildLDContext } from "../helpers";
function userFixture(overrides: Partial<User> = {}): User {
return {
@@ -101,3 +101,21 @@ describe("buildLDContext", () => {
expect("email_domain" in ctx && ctx.email_domain).toBe("sub.example.com");
});
});
+
+describe("buildFlagPersonProperties", () => {
+ it("carries the attributes the ported rules target on, never the raw email", () => {
+ expect(buildFlagPersonProperties(userFixture())).toEqual({
+ email_domain: "example.com",
+ role: "authenticated",
+ created_at: "2026-05-08T12:00:00Z",
+ });
+ });
+
+ it("omits what the session does not carry", () => {
+ const properties = buildFlagPersonProperties(
+ userFixture({ role: undefined, created_at: undefined }),
+ );
+
+ expect(properties).toEqual({ email_domain: "example.com" });
+ });
+});
diff --git a/autogpt_platform/frontend/src/services/feature-flags/__tests__/with-feature-flag.test.tsx b/autogpt_platform/frontend/src/services/feature-flags/__tests__/with-feature-flag.test.tsx
index 3ccdbe8c4a..7ef8d59d9c 100644
--- a/autogpt_platform/frontend/src/services/feature-flags/__tests__/with-feature-flag.test.tsx
+++ b/autogpt_platform/frontend/src/services/feature-flags/__tests__/with-feature-flag.test.tsx
@@ -1,10 +1,19 @@
-import { render, screen, waitFor } from "@testing-library/react";
+import { act, render, screen, waitFor } from "@testing-library/react";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
+import { Flag } from "../use-get-flag";
+import { withFeatureFlag } from "../with-feature-flag";
+
+// Reading through the seam is the point of this test: in posthog mode no
+// LDProvider is mounted, so a component reading the LaunchDarkly SDK directly
+// waits on an empty flag set forever.
+const source = vi.hoisted(() => ({
+ results: {} as Record<string, { value: unknown; resolved: boolean }>,
+}));
const router = vi.hoisted(() => ({ push: vi.fn() }));
-vi.mock("launchdarkly-react-client-sdk", () => ({
- useFlags: () => ({}),
+vi.mock("../flag-source", () => ({
+ useFlagSource: (key: string) =>
+ source.results[key] ?? { value: undefined, resolved: false },
}));
vi.mock("next/navigation", () => ({
@@ -16,7 +25,7 @@ vi.mock("@/app/(platform)/marketplace/components/HeroSection/helpers", () => ({
}));
vi.mock("@/services/environment", () => ({
- environment: { areFeatureFlagsEnabled: () => false },
+ environment: { areFeatureFlagsEnabled: () => true },
}));
const FORCE_ALL = "NEXT_PUBLIC_FORCE_ALL_FLAGS";
@@ -26,13 +35,63 @@ function Gated() {
return <div>gated content</div>;
}
+const Wrapped = withFeatureFlag(Gated, Flag.GRAPHITI_MEMORY);
+
+describe("withFeatureFlag reads through the flag seam", () => {
+ it("renders the page once the vendor answers true", () => {
+ source.results = { "graphiti-memory": { value: true, resolved: true } };
+
+ render(<Wrapped />);
+
+ expect(screen.getByText("gated content")).toBeDefined();
+ expect(router.push).not.toHaveBeenCalled();
+ });
+
+ it("sends the user to 404 once the vendor answers false", () => {
+ source.results = { "graphiti-memory": { value: false, resolved: true } };
+
+ render(<Wrapped />);
+
+ expect(screen.queryByText("gated content")).toBeNull();
+ expect(router.push).toHaveBeenCalledWith("/404");
+ });
+
+ it("keeps waiting, without redirecting, past the resolution timeout", () => {
+ // A user who has the flag must not land on /404 because the vendor is
+ // slow or ad-blocked; only an answer may move them.
+ vi.useFakeTimers();
+ try {
+ source.results = {};
+
+ render(<Wrapped />);
+ act(() => {
+ vi.advanceTimersByTime(10_000);
+ });
+
+ expect(screen.queryByText("gated content")).toBeNull();
+ expect(router.push).not.toHaveBeenCalled();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it("waits, without redirecting, while the answer is outstanding", () => {
+ source.results = {};
+
+ render(<Wrapped />);
+
+ expect(screen.queryByText("gated content")).toBeNull();
+ expect(router.push).not.toHaveBeenCalled();
+ });
+});
+
// `isForceAllFlags` is read once at module load, so each case sets the env
// first, drops the module cache, and imports the HOC fresh.
async function renderGated() {
vi.resetModules();
- const { withFeatureFlag } = await import("../with-feature-flag");
- const { Flag } = await import("../use-get-flag");
- const Page = withFeatureFlag(Gated, Flag.GRAPHITI_MEMORY);
+ const { withFeatureFlag: freshHOC } = await import("../with-feature-flag");
+ const { Flag: FreshFlag } = await import("../use-get-flag");
+ const Page = freshHOC(Gated, FreshFlag.GRAPHITI_MEMORY);
return render(<Page />);
}
@@ -68,7 +127,7 @@ describe("withFeatureFlag env override", () => {
expect(screen.queryByText("gated content")).toBeNull();
});
- it("keeps the spinner while LaunchDarkly has not answered and nothing is forced", async () => {
+ it("keeps the spinner while the vendor has not answered and nothing is forced", async () => {
const { container } = await renderGated();
expect(container.querySelector(".animate-spin")).not.toBeNull();
@@ -76,3 +135,12 @@ describe("withFeatureFlag env override", () => {
expect(router.push).not.toHaveBeenCalled();
});
});
+
+beforeEach(() => {
+ source.results = {};
+ router.push.mockClear();
+});
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
diff --git a/autogpt_platform/frontend/src/services/feature-flags/backends/dual.ts b/autogpt_platform/frontend/src/services/feature-flags/backends/dual.ts
new file mode 100644
index 0000000000..d501fa1aae
--- /dev/null
+++ b/autogpt_platform/frontend/src/services/feature-flags/backends/dual.ts
@@ -0,0 +1,59 @@
+"use client";
+
+import { environment } from "@/services/environment";
+import { usePostHog } from "@posthog/react";
+import isEqual from "lodash/isEqual";
+import { useEffect } from "react";
+import { isPostHogFlagsEnabled } from "../flag-backend";
+import type { FlagSourceResult } from "../flag-source";
+import { useLaunchDarklyFlag } from "./launchdarkly";
+import { usePostHogFlag } from "./posthog";
+
+export function useDualFlag(key: string): FlagSourceResult {
+ const launchDarkly = useLaunchDarklyFlag(key);
+ const postHog = usePostHogFlag(key);
+ // LaunchDarkly is what dual serves, but only when it is actually configured:
+ // with no LDProvider mounted its answer is an empty set that never resolves.
+ const serveLaunchDarkly = environment.areFeatureFlagsEnabled();
+
+ useReportMismatch(key, launchDarkly, postHog, serveLaunchDarkly);
+
+ return serveLaunchDarkly ? launchDarkly : postHog;
+}
+
+function useReportMismatch(
+ key: string,
+ launchDarkly: FlagSourceResult,
+ postHog: FlagSourceResult,
+ bothConfigured: boolean,
+) {
+ const posthog = usePostHog();
+ const record = JSON.stringify({
+ flag: key,
+ launchdarkly: {
+ value: launchDarkly.value,
+ resolved: launchDarkly.resolved,
+ },
+ // `null`, not `undefined`: a flag PostHog has never heard of must still
+ // appear in the record rather than vanish from the JSON.
+ posthog: { value: postHog.value ?? null, resolved: postHog.resolved },
+ });
+ // The two vendors never answer on the same render — LaunchDarkly fetches
+ // over the network, PostHog reads its bootstrapped snapshot — so comparing
+ // before both have resolved reports the load order, not a disagreement.
+ const comparable =
+ bothConfigured &&
+ isPostHogFlagsEnabled() &&
+ launchDarkly.resolved &&
+ postHog.resolved;
+ // Key-order-insensitive, like the backend's dict comparison: the vendors
+ // need not serialise a JSON flag's keys in the same order.
+ const agree = isEqual(launchDarkly.value, postHog.value);
+
+ useEffect(() => {
+ if (!comparable || agree) return;
+ const mismatch = JSON.parse(record);
+ console.warn("feature-flag mismatch", mismatch);
+ posthog?.capture("feature_flag_mismatch", mismatch);
+ }, [comparable, agree, record, posthog]);
+}
diff --git a/autogpt_platform/frontend/src/services/feature-flags/backends/launchdarkly.ts b/autogpt_platform/frontend/src/services/feature-flags/backends/launchdarkly.ts
new file mode 100644
index 0000000000..8e91487bd4
--- /dev/null
+++ b/autogpt_platform/frontend/src/services/feature-flags/backends/launchdarkly.ts
@@ -0,0 +1,10 @@
+"use client";
+
+import { useFlags } from "launchdarkly-react-client-sdk";
+import type { FlagSourceResult } from "../flag-source";
+
+export function useLaunchDarklyFlag(key: string): FlagSourceResult {
+ const currentFlags = useFlags<Record<string, unknown>>();
+
+ return { value: currentFlags[key], resolved: key in currentFlags };
+}
diff --git a/autogpt_platform/frontend/src/services/feature-flags/backends/posthog.ts b/autogpt_platform/frontend/src/services/feature-flags/backends/posthog.ts
new file mode 100644
index 0000000000..06b8349408
--- /dev/null
+++ b/autogpt_platform/frontend/src/services/feature-flags/backends/posthog.ts
@@ -0,0 +1,45 @@
+"use client";
+
+import {
+ useFeatureFlagEnabled,
+ useFeatureFlagPayload,
+ usePostHog,
+} from "@posthog/react";
+import { useEffect, useState } from "react";
+import type { FlagSourceResult } from "../flag-source";
+
+export function usePostHogFlag(key: string): FlagSourceResult {
+ const enabled = useFeatureFlagEnabled(key);
+ const payload = useFeatureFlagPayload(key);
+ // Not `enabled !== undefined`: posthog-js serves its persisted snapshot
+ // before /flags runs, and answers `undefined` for a flag it has never heard of.
+ const resolved = useFlagsLoaded();
+
+ // An explicit off wins over a payload, as on the backend.
+ if (enabled === false) {
+ return { value: false, resolved };
+ }
+
+ // A payload stands in for the JSON-valued LaunchDarkly variations; a plain
+ // release toggle carries none and answers with the boolean.
+ if (payload !== undefined && payload !== null) {
+ return { value: payload, resolved };
+ }
+
+ return { value: enabled, resolved };
+}
+
+function useFlagsLoaded() {
+ const posthog = usePostHog();
+ const [loaded, setLoaded] = useState(
+ () => posthog?.featureFlags?.hasLoadedFlags ?? false,
+ );
+
+ useEffect(() => {
+ return posthog?.onFeatureFlags((_flags, _variants, context) => {
+ if (!context?.errorsLoading) setLoaded(true);
+ });
+ }, [posthog]);
+
+ return loaded;
+}
diff --git a/autogpt_platform/frontend/src/services/feature-flags/feature-flag-provider.tsx b/autogpt_platform/frontend/src/services/feature-flags/feature-flag-provider.tsx
index 43e7c37d3f..95acff35ca 100644
--- a/autogpt_platform/frontend/src/services/feature-flags/feature-flag-provider.tsx
+++ b/autogpt_platform/frontend/src/services/feature-flags/feature-flag-provider.tsx
@@ -9,11 +9,12 @@ import { useMemo } from "react";
import { getAnonymousID } from "../analytics/anonymous-id";
import { environment } from "../environment";
import { LD_INIT_TIMEOUT_SECONDS } from "./constants";
+import { usesLaunchDarkly } from "./flag-backend";
import { buildLDContext } from "./helpers";
export function LaunchDarklyProvider({ children }: { children: ReactNode }) {
const { user, isUserLoading } = useAuth();
- const envEnabled = environment.areFeatureFlagsEnabled();
+ const envEnabled = usesLaunchDarkly() && environment.areFeatureFlagsEnabled();
const clientId = environment.getLaunchDarklyClientId();
const context = useMemo(() => {
diff --git a/autogpt_platform/frontend/src/services/feature-flags/flag-backend.ts b/autogpt_platform/frontend/src/services/feature-flags/flag-backend.ts
new file mode 100644
index 0000000000..4d075d1939
--- /dev/null
+++ b/autogpt_platform/frontend/src/services/feature-flags/flag-backend.ts
@@ -0,0 +1,31 @@
+export type FlagBackend = "launchdarkly" | "posthog" | "dual";
+
+// Read as a literal so Next/Turbopack inlines it into the client bundle; a
+// dynamic ``process.env[name]`` lookup is always empty in the browser.
+const configured = process.env.NEXT_PUBLIC_FEATURE_FLAG_BACKEND;
+
+export const FLAG_BACKEND: FlagBackend =
+ configured === "posthog" || configured === "dual"
+ ? configured
+ : "launchdarkly";
+
+export function usesLaunchDarkly() {
+ return FLAG_BACKEND !== "posthog";
+}
+
+export function usesPostHog() {
+ return FLAG_BACKEND !== "launchdarkly";
+}
+
+// Mirrors ``environment.isPostHogEnabled`` — including its cloud check, since
+// that is what gates the PostHogProvider: claiming flags are enabled where no
+// provider mounts is how a route ends up waiting on an answer that never comes.
+// Deliberately not routed through ``environment`` itself: this module is
+// imported by the flag hooks, which 75 test files render with a stubbed one.
+export function isPostHogFlagsEnabled() {
+ return Boolean(
+ process.env.NEXT_PUBLIC_BEHAVE_AS === "CLOUD" &&
+ process.env.NEXT_PUBLIC_POSTHOG_KEY &&
+ process.env.NEXT_PUBLIC_POSTHOG_HOST,
+ );
+}
diff --git a/autogpt_platform/frontend/src/services/feature-flags/flag-source.ts b/autogpt_platform/frontend/src/services/feature-flags/flag-source.ts
new file mode 100644
index 0000000000..71b611d360
--- /dev/null
+++ b/autogpt_platform/frontend/src/services/feature-flags/flag-source.ts
@@ -0,0 +1,28 @@
+"use client";
+
+import { useDualFlag } from "./backends/dual";
+import { useLaunchDarklyFlag } from "./backends/launchdarkly";
+import { usePostHogFlag } from "./backends/posthog";
+import { FLAG_BACKEND } from "./flag-backend";
+
+export interface FlagSourceResult {
+ value: unknown;
+ // Whether the vendor actually answered, as opposed to not having answered
+ // yet. Callers that gate a route must not treat "no answer" as "off".
+ resolved: boolean;
+}
+
+// The one seam every flag read passes through, and the only thing a test has
+// to mock to control flags regardless of which vendor is configured.
+export function useFlagSource(key: string): FlagSourceResult {
+ return useSelectedFlagSource(key);
+}
+
+// Picked at module load, not per render: the backend is a build-time constant,
+// so the hooks a component calls stay stable for the life of the app.
+const useSelectedFlagSource =
+ FLAG_BACKEND === "posthog"
+ ? usePostHogFlag
+ : FLAG_BACKEND === "dual"
+ ? useDualFlag
+ : useLaunchDarklyFlag;
diff --git a/autogpt_platform/frontend/src/services/feature-flags/helpers.ts b/autogpt_platform/frontend/src/services/feature-flags/helpers.ts
index fc5c081bb6..15d4dea0dd 100644
--- a/autogpt_platform/frontend/src/services/feature-flags/helpers.ts
+++ b/autogpt_platform/frontend/src/services/feature-flags/helpers.ts
@@ -31,6 +31,19 @@ export interface LDMultiContext {
export type LDContext = LDUserContext | LDMultiContext;
+// The attributes the ported flag targeting rules match on, in the flat shape
+// PostHog person properties take. No raw email: no rule reads it, and
+// individual targets key on the distinct id.
+export function buildFlagPersonProperties(user: User): Record<string, string> {
+ return {
+ ...(user.email && {
+ email_domain: user.email.split("@").at(-1) ?? "",
+ }),
+ ...(user.role && { role: user.role }),
+ ...(user.created_at && { created_at: user.created_at }),
+ };
+}
+
// The `user` context mirrors the backend's
// (feature_flag.py:_fetch_user_context_data), so rules on that kind evaluate
// identically on both sides. The `device` context below is client-only.
diff --git a/autogpt_platform/frontend/src/services/feature-flags/use-get-flag.ts b/autogpt_platform/frontend/src/services/feature-flags/use-get-flag.ts
index 2794b0e64a..b2ee3c5eb9 100644
--- a/autogpt_platform/frontend/src/services/feature-flags/use-get-flag.ts
+++ b/autogpt_platform/frontend/src/services/feature-flags/use-get-flag.ts
@@ -2,8 +2,9 @@
import { DEFAULT_SEARCH_TERMS } from "@/app/(platform)/marketplace/components/HeroSection/helpers";
import { environment } from "@/services/environment";
-import { useFlags } from "launchdarkly-react-client-sdk";
import { useEffect, useState } from "react";
+import { FLAG_BACKEND, isPostHogFlagsEnabled } from "./flag-backend";
+import { useFlagSource } from "./flag-source";
export enum Flag {
MARKETPLACE_SEARCH_TERMS = "marketplace-search-terms",
@@ -202,9 +203,8 @@ export function envFlagOverride<T extends Flag>(
}
export function useGetFlag<T extends Flag>(flag: T): FlagValues[T] {
- const currentFlags = useFlags<FlagValues>();
- const flagValue = currentFlags[flag];
- const areFlagsEnabled = environment.areFeatureFlagsEnabled();
+ const { value } = useFlagSource(flag);
+ const areFlagsEnabled = areFeatureFlagsEnabled();
const override = envFlagOverride(flag);
if (override !== undefined) {
@@ -215,24 +215,25 @@ export function useGetFlag<T extends Flag>(flag: T): FlagValues[T] {
return defaultFlags[flag];
}
- return flagValue ?? defaultFlags[flag];
+ return resolveFlagValue(flag, value);
}
const FLAG_RESOLUTION_TIMEOUT_MS = 5000;
/**
- * Same as ``useGetFlag`` but also surfaces whether LaunchDarkly has
+ * Same as ``useGetFlag`` but also surfaces whether the flag vendor has
* actually answered for this flag. Callers that gate a whole route on a
* flag should branch on ``ready`` first — short-circuiting to
- * ``notFound()`` before LD responds 404s users that actually have the
- * flag on. Falls back to "ready" after ``FLAG_RESOLUTION_TIMEOUT_MS`` so
- * a flag key that LD never registers doesn't spin forever.
+ * ``notFound()`` before the vendor responds 404s users that actually have
+ * the flag on. Falls back to "ready" after ``FLAG_RESOLUTION_TIMEOUT_MS``
+ * so an unregistered flag key doesn't spin forever; ``answered`` stays
+ * false then, for callers that must not act on a timeout.
*/
export function useFlagStatus<T extends Flag>(
flag: T,
-): { enabled: FlagValues[T]; ready: boolean } {
- const currentFlags = useFlags<FlagValues>();
- const areFlagsEnabled = environment.areFeatureFlagsEnabled();
+): { enabled: FlagValues[T]; ready: boolean; answered: boolean } {
+ const { value, resolved } = useFlagSource(flag);
+ const areFlagsEnabled = areFeatureFlagsEnabled();
const override = envFlagOverride(flag);
const [timedOut, setTimedOut] = useState(false);
@@ -245,15 +246,52 @@ export function useFlagStatus<T extends Flag>(
}, []);
if (override !== undefined) {
- return { enabled: override, ready: true };
+ return { enabled: override, ready: true, answered: true };
}
if (!areFlagsEnabled || isPwMockEnabled) {
- return { enabled: defaultFlags[flag], ready: true };
+ return { enabled: defaultFlags[flag], ready: true, answered: true };
}
- const ldResponded = flag in currentFlags;
return {
- enabled: (currentFlags[flag] ?? defaultFlags[flag]) as FlagValues[T],
- ready: ldResponded || timedOut,
+ enabled: resolveFlagValue(flag, value),
+ ready: resolved || timedOut,
+ answered: resolved,
};
}
+
+// PostHog answers a flag with no payload as a bare boolean, so a JSON-valued
+// flag can arrive as `true` and reach a consumer that calls `.map` on it.
+// `typeof` alone can't separate an array from an object; both are "object".
+export function resolveFlagValue<T extends Flag>(
+ flag: T,
+ value: unknown,
+): FlagValues[T] {
+ const fallback = defaultFlags[flag];
+
+ if (value === undefined || value === null) return fallback;
+
+ if (Array.isArray(fallback)) {
+ return (Array.isArray(value) ? value : fallback) as FlagValues[T];
+ }
+
+ if (fallback !== null && typeof fallback === "object") {
+ const isPlainObject = typeof value === "object" && !Array.isArray(value);
+ return (isPlainObject ? value : fallback) as FlagValues[T];
+ }
+
+ return (typeof value === typeof fallback ? value : fallback) as FlagValues[T];
+}
+
+// ``environment.areFeatureFlagsEnabled`` only knows about LaunchDarkly, and
+// deliberately stays that way — it is what the provider and the flag test
+// mocks stub. This is the same question asked of whichever vendor is configured.
+function areFeatureFlagsEnabled() {
+ switch (FLAG_BACKEND) {
+ case "posthog":
+ return isPostHogFlagsEnabled();
+ case "dual":
+ return environment.areFeatureFlagsEnabled() || isPostHogFlagsEnabled();
+ default:
+ return environment.areFeatureFlagsEnabled();
+ }
+}
diff --git a/autogpt_platform/frontend/src/services/feature-flags/with-feature-flag.tsx b/autogpt_platform/frontend/src/services/feature-flags/with-feature-flag.tsx
index e7ec683333..b70ee9504c 100644
--- a/autogpt_platform/frontend/src/services/feature-flags/with-feature-flag.tsx
+++ b/autogpt_platform/frontend/src/services/feature-flags/with-feature-flag.tsx
@@ -1,40 +1,26 @@
"use client";
-import { useFlags } from "launchdarkly-react-client-sdk";
import { useRouter } from "next/navigation";
-import { useEffect, useState } from "react";
-import { envFlagOverride, Flag } from "./use-get-flag";
+import { useEffect } from "react";
+import { Flag, useFlagStatus } from "./use-get-flag";
-export function withFeatureFlag<P extends object>(
+export function withFeatureFlag<P extends object, T extends Flag>(
WrappedComponent: React.ComponentType<P>,
- flagKey: string,
+ flag: T,
) {
return function FeatureFlaggedComponent(props: P) {
- const flags = useFlags();
+ const { enabled, answered } = useFlagStatus(flag);
const router = useRouter();
- // The local env override (per-flag NEXT_PUBLIC_FORCE_FLAG_*, or the
- // NEXT_PUBLIC_FORCE_ALL_FLAGS master switch) wins over LaunchDarkly, so a
- // page gated by this HOC respects force-all like the useGetFlag hook does.
- const override = envFlagOverride(flagKey as Flag);
- const isEnabled = override !== undefined ? override : flags[flagKey];
-
- const [hasFlagLoaded, setHasFlagLoaded] = useState(override !== undefined);
-
- useEffect(() => {
- if (override !== undefined || (flags && flagKey in flags)) {
- setHasFlagLoaded(true);
- }
- }, [flags, override]);
-
+ // Navigating on the 5s timeout would send a user who has the flag to
+ // /404 whenever the vendor is slow or blocked, so only an answer moves.
useEffect(() => {
- if (hasFlagLoaded && !isEnabled) {
+ if (answered && !enabled) {
router.push("/404");
}
- }, [hasFlagLoaded, isEnabled, router]);
+ }, [answered, enabled, router]);
- // Show loading state until flags loaded
- if (!hasFlagLoaded) {
+ if (!answered) {
return (
<div className="flex min-h-screen items-center justify-center">
<div className="h-8 w-8 animate-spin rounded-full border-4 border-primary border-t-transparent" />
@@ -42,12 +28,10 @@ export function withFeatureFlag<P extends object>(
);
}
- // If flag is loaded but false, return null (will redirect)
- if (!isEnabled) {
+ if (!enabled) {
return null;
}
- // Flag is loaded and true, show component
return <WrappedComponent {...props} />;
};
}