LaunchDarkly

Rule

LaunchDarkly flags are read through @agent-native/core/launchdarkly on the server and @agent-native/core/client/launchdarkly in the browser. Every read fails closed to a caller-supplied default — LaunchDarkly being unconfigured, unreachable, or slow is never an availability dependency for the caller.

LaunchDarkly vs. the built-in feature-flags skill

This repo already has its own rollout system (defineFeatureFlag, isFeatureFlagEnabled, useFeatureFlag — see the feature-flags skill), managed from the Analytics fleet control plane with no external dependency. Use that system for a flag whose definition and targeting rules should live in this codebase and be manageable from Analytics.

Use LaunchDarkly instead when the flag's definition and targeting genuinely need to live in the LaunchDarkly dashboard — for example, a flag shared with non-Agent-Native systems, or targeting rules (percentage experiments, multi-variate values, scheduled changes) beyond what the built-in system offers. Don't wire the same rollout through both systems.

Setup

Set LAUNCHDARKLY_SDK_KEY to a server-side SDK key from the agent-native LaunchDarkly project's active environment. Unset, every read falls back to its default value and LaunchDarkly is never contacted — there is no broken state to debug, only an inactive one.

No client-side ID or LaunchDarkly JS SDK is used. Browser code reads evaluated flags through the get-launchdarkly-flags action instead, so the SDK key never reaches a bundle and no LaunchDarkly network connection opens from the browser.

Server usage

import { isLaunchDarklyFlagEnabled } from "@agent-native/core/launchdarkly";

run: async (args, ctx) => {
  const enabled = await isLaunchDarklyFlagEnabled("new-checkout-flow", {
    userEmail: ctx.userEmail,
    orgId: ctx.orgId,
  });
  if (!enabled) throw new Error("New checkout flow is not enabled.");
  // guarded operation
};

For a non-boolean flag (string/number/JSON variation), use getLaunchDarklyVariation(key, actor, defaultValue) — the return type matches defaultValue's type. getAllLaunchDarklyFlags(actor) returns every flag LaunchDarkly currently evaluates for that context; prefer the single-flag functions when only a few keys matter.

actor is { userEmail?, orgId?, anonymousId? }. A signed-in caller evaluates by userEmail. A caller with neither userEmail nor anonymousId falls back to one shared "anonymous" context — every such caller gets the same variation from a percentage rollout, since LaunchDarkly buckets by context key. Pass a stable anonymousId (a device or session id) when an unauthenticated caller needs its own bucket.

Client usage

import { useLaunchDarklyFlag } from "@agent-native/core/client/launchdarkly";

function CheckoutButton() {
  const enabled = useLaunchDarklyFlag("new-checkout-flow");
  if (!enabled) return null;
  return <Button>Checkout</Button>;
}

useLaunchDarklyFlag(key, defaultValue = false) calls the mounted get-launchdarkly-flags action for the current session and requires a real session — like useFeatureFlag, it never fires for a signed-out visitor and resolves to defaultValue instead. useLaunchDarklyFlags(keys, defaultValue) evaluates several keys in one request.

get-launchdarkly-flags action

Auto-mounted for every app (like get-feature-flags) — no plugin or registration needed. Gateable per app via frameworkTools.launchDarkly (see framework-tools.ts) if an app wants to remove it from the agent's tool surface; the HTTP route stays mounted either way so useLaunchDarklyFlag keeps working.

run("get-launchdarkly-flags", { keys: ["new-checkout-flow"], defaultValue: false })
// => { flags: { "new-checkout-flow": true } }

Never do this

• Never import @agent-native/core/launchdarkly (the server module) from client/browser code — it pulls in the LaunchDarkly Node SDK. Use @agent-native/core/client/launchdarkly instead.
• Never treat a LaunchDarkly read as required for an operation to complete — every function here already fails closed; don't wrap calls in retries or turn a false/default result into a thrown error unless the flag itself is an authorization gate the caller must respect.
• Never put LAUNCHDARKLY_SDK_KEY in agent-native.config.ts or any client-visible config — it is server-only.

Related skills

• feature-flags — the framework's own rollout system; read this first to decide which system a new flag belongs in.
• configuration — how LAUNCHDARKLY_SDK_KEY resolves through getAppConfig().launchDarkly.
• secrets — why the SDK key is a plain deploy-level env var rather than a vault-backed per-user/org secret.