@agent-native/core 0.107.2 → 0.108.0

package/dist/feature-flags/a2a-action-route.d.ts

@@ -0,0 +1,14 @@
+import type { ActionRouteAuthAdapter } from "../server/action-routes.js";
+declare const FLAG_ACTION_SCOPES: {
+    readonly "list-feature-flags": "flags:read";
+    readonly "set-feature-flag": "flags:write";
+};
+export declare function declaresFeatureFlagDelegation(token: string): boolean;
+/**
+ * Narrow opt-in adapter for fleet flag control. It owns Bearer credentials only
+ * for these two actions; malformed owned bearers reject rather than falling
+ * back to a browser cookie.
+ */
+export declare function createFeatureFlagA2AActionRouteAuth(actionName: keyof typeof FLAG_ACTION_SCOPES): ActionRouteAuthAdapter;
+export {};
+//# sourceMappingURL=a2a-action-route.d.ts.map

package/dist/feature-flags/a2a-action-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-action-route.d.ts","sourceRoot":"","sources":["../../src/feature-flags/a2a-action-route.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAEzE,QAAA,MAAM,kBAAkB;aACtB,oBAAoB,EAAE,YAAY;aAClC,kBAAkB,EAAE,aAAa;CACzB,CAAC;AAEX,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAepE;AAED;;;;GAIG;AACH,wBAAgB,mCAAmC,CACjD,UAAU,EAAE,MAAM,OAAO,kBAAkB,GAC1C,sBAAsB,CAoBxB"}

package/dist/feature-flags/a2a-action-route.js

@@ -0,0 +1,50 @@
+import { getHeader } from "h3";
+import * as jose from "jose";
+import { verifyA2ATokenWithClaims } from "../a2a-claims.js";
+const FLAG_ACTION_SCOPES = {
+    "list-feature-flags": "flags:read",
+    "set-feature-flag": "flags:write",
+};
+export function declaresFeatureFlagDelegation(token) {
+    try {
+        const raw = jose.decodeJwt(token);
+        const scopes = typeof raw.scope === "string"
+            ? raw.scope.split(/\s+/)
+            : Array.isArray(raw.scope)
+                ? raw.scope.filter((scope) => typeof scope === "string")
+                : [];
+        return scopes.some((scope) => scope.startsWith("flags:"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Narrow opt-in adapter for fleet flag control. It owns Bearer credentials only
+ * for these two actions; malformed owned bearers reject rather than falling
+ * back to a browser cookie.
+ */
+export function createFeatureFlagA2AActionRouteAuth(actionName) {
+    return {
+        async resolveCaller(event) {
+            const header = getHeader(event, "authorization");
+            if (!header?.startsWith("Bearer "))
+                return null;
+            const token = header.slice(7);
+            if (!declaresFeatureFlagDelegation(token))
+                return null;
+            const claims = await verifyA2ATokenWithClaims(token, event);
+            if (!claims || !claims.scope.includes(FLAG_ACTION_SCOPES[actionName])) {
+                throw new Error("Invalid feature flag delegation");
+            }
+            return {
+                owner: claims.email,
+                orgId: claims.orgId,
+                anonymous: false,
+                delegationJti: claims.jti,
+                delegationIssuer: claims.issuer,
+            };
+        },
+    };
+}
+//# sourceMappingURL=a2a-action-route.js.map

package/dist/feature-flags/a2a-action-route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-action-route.js","sourceRoot":"","sources":["../../src/feature-flags/a2a-action-route.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAG5D,MAAM,kBAAkB,GAAG;IACzB,oBAAoB,EAAE,YAAY;IAClC,kBAAkB,EAAE,aAAa;CACzB,CAAC;AAEX,MAAM,UAAU,6BAA6B,CAAC,KAAa;IACzD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAClC,MAAM,MAAM,GACV,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;YAC3B,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;YACxB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;gBACxB,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CACd,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CACtD;gBACH,CAAC,CAAC,EAAE,CAAC;QACX,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mCAAmC,CACjD,UAA2C;IAE3C,OAAO;QACL,KAAK,CAAC,aAAa,CAAC,KAAK;YACvB,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;YACjD,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,SAAS,CAAC;gBAAE,OAAO,IAAI,CAAC;YAChD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC9B,IAAI,CAAC,6BAA6B,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YACvD,MAAM,MAAM,GAAG,MAAM,wBAAwB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAC5D,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;gBACtE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;YACrD,CAAC;YACD,OAAO;gBACL,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,SAAS,EAAE,KAAK;gBAChB,aAAa,EAAE,MAAM,CAAC,GAAG;gBACzB,gBAAgB,EAAE,MAAM,CAAC,MAAM;aAChC,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import { getHeader } from \"h3\";\nimport * as jose from \"jose\";\n\nimport { verifyA2ATokenWithClaims } from \"../a2a-claims.js\";\nimport type { ActionRouteAuthAdapter } from \"../server/action-routes.js\";\n\nconst FLAG_ACTION_SCOPES = {\n  \"list-feature-flags\": \"flags:read\",\n  \"set-feature-flag\": \"flags:write\",\n} as const;\n\nexport function declaresFeatureFlagDelegation(token: string): boolean {\n  try {\n    const raw = jose.decodeJwt(token);\n    const scopes =\n      typeof raw.scope === \"string\"\n        ? raw.scope.split(/\\s+/)\n        : Array.isArray(raw.scope)\n          ? raw.scope.filter(\n              (scope): scope is string => typeof scope === \"string\",\n            )\n          : [];\n    return scopes.some((scope) => scope.startsWith(\"flags:\"));\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Narrow opt-in adapter for fleet flag control. It owns Bearer credentials only\n * for these two actions; malformed owned bearers reject rather than falling\n * back to a browser cookie.\n */\nexport function createFeatureFlagA2AActionRouteAuth(\n  actionName: keyof typeof FLAG_ACTION_SCOPES,\n): ActionRouteAuthAdapter {\n  return {\n    async resolveCaller(event) {\n      const header = getHeader(event, \"authorization\");\n      if (!header?.startsWith(\"Bearer \")) return null;\n      const token = header.slice(7);\n      if (!declaresFeatureFlagDelegation(token)) return null;\n      const claims = await verifyA2ATokenWithClaims(token, event);\n      if (!claims || !claims.scope.includes(FLAG_ACTION_SCOPES[actionName])) {\n        throw new Error(\"Invalid feature flag delegation\");\n      }\n      return {\n        owner: claims.email,\n        orgId: claims.orgId,\n        anonymous: false,\n        delegationJti: claims.jti,\n        delegationIssuer: claims.issuer,\n      };\n    },\n  };\n}\n"]}

package/dist/feature-flags/actions/get-feature-flags.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("../../action.js").ActionDefinition<Record<string, never>, any>;
+export default _default;
+//# sourceMappingURL=get-feature-flags.d.ts.map

package/dist/feature-flags/actions/get-feature-flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-feature-flags.d.ts","sourceRoot":"","sources":["../../../src/feature-flags/actions/get-feature-flags.ts"],"names":[],"mappings":""}

package/dist/feature-flags/actions/get-feature-flags.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { listFeatureFlags } from "../registry.js";
+import { evaluateFeatureFlag } from "../store.js";
+export default defineAction({
+    description: "Return the boolean values of every feature flag registered by this app for the current caller. Unknown or unconfigured flags always evaluate to false.",
+    schema: z.object({}),
+    http: { method: "GET" },
+    run: async (_args, ctx) => {
+        const scope = { userEmail: ctx?.userEmail, orgId: ctx?.orgId };
+        const values = Object.fromEntries(await Promise.all(listFeatureFlags().map(async ({ key }) => [
+            key,
+            await evaluateFeatureFlag(key, scope).catch(() => false),
+        ])));
+        return values;
+    },
+});
+//# sourceMappingURL=get-feature-flags.js.map

package/dist/feature-flags/actions/get-feature-flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-feature-flags.js","sourceRoot":"","sources":["../../../src/feature-flags/actions/get-feature-flags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,eAAe,YAAY,CAAC;IAC1B,WAAW,EACT,wJAAwJ;IAC1J,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;IACpB,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;IACvB,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QACxB,MAAM,KAAK,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;QAC/D,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAC/B,MAAM,OAAO,CAAC,GAAG,CACf,gBAAgB,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC;YACxC,GAAG;YACH,MAAM,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC;SACzD,CAAC,CACH,CACF,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;CACF,CAAC,CAAC","sourcesContent":["import { z } from \"zod\";\n\nimport { defineAction } from \"../../action.js\";\nimport { listFeatureFlags } from \"../registry.js\";\nimport { evaluateFeatureFlag } from \"../store.js\";\n\nexport default defineAction({\n  description:\n    \"Return the boolean values of every feature flag registered by this app for the current caller. Unknown or unconfigured flags always evaluate to false.\",\n  schema: z.object({}),\n  http: { method: \"GET\" },\n  run: async (_args, ctx) => {\n    const scope = { userEmail: ctx?.userEmail, orgId: ctx?.orgId };\n    const values = Object.fromEntries(\n      await Promise.all(\n        listFeatureFlags().map(async ({ key }) => [\n          key,\n          await evaluateFeatureFlag(key, scope).catch(() => false),\n        ]),\n      ),\n    );\n    return values;\n  },\n});\n"]}

package/dist/feature-flags/actions/list-feature-flags.d.ts

@@ -0,0 +1,28 @@
+declare const _default: import("../../action.js").ActionDefinition<Record<string, never>, {
+    contractVersion: number;
+    status: "forbidden";
+    reason: "forbidden";
+    flags: any[];
+    canManage: boolean;
+} | {
+    contractVersion: number;
+    status: "no-definitions";
+    reason: "no-definitions";
+    flags: any[];
+    canManage: boolean;
+} | {
+    contractVersion: number;
+    status: "ready";
+    reason: "ready";
+    flags: {
+        key: string;
+        defaultValue?: false;
+        displayName?: string;
+        description?: string;
+        rules: import("../store.js").FeatureFlagRules;
+        enabledForCurrentUser: boolean;
+    }[];
+    canManage: boolean;
+}>;
+export default _default;
+//# sourceMappingURL=list-feature-flags.d.ts.map

package/dist/feature-flags/actions/list-feature-flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-feature-flags.d.ts","sourceRoot":"","sources":["../../../src/feature-flags/actions/list-feature-flags.ts"],"names":[],"mappings":";;YA0BkB,WAAW;YACX,WAAW;;;;;YAUb,gBAAgB;YAChB,gBAAgB;;;;;YAwBlB,OAAO;YACP,OAAO"}

package/dist/feature-flags/actions/list-feature-flags.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { requireFeatureFlagManager } from "../permissions.js";
+import { listFeatureFlags } from "../registry.js";
+import { evaluateFeatureFlagRules, getFeatureFlagRules } from "../store.js";
+export default defineAction({
+    description: "List this app's registered feature flags and their current rules. Organization owner/admin only (or the explicit no-org administrator).",
+    schema: z.object({}),
+    http: { method: "GET" },
+    toolCallable: false,
+    run: async (_args, ctx) => {
+        const definitions = listFeatureFlags();
+        let manager;
+        try {
+            manager = await requireFeatureFlagManager(ctx ?? {});
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                "statusCode" in error &&
+                error.statusCode === 403) {
+                return {
+                    contractVersion: 1,
+                    status: "forbidden",
+                    reason: "forbidden",
+                    flags: [],
+                    canManage: false,
+                };
+            }
+            throw error;
+        }
+        if (definitions.length === 0)
+            return {
+                contractVersion: 1,
+                status: "no-definitions",
+                reason: "no-definitions",
+                flags: [],
+                canManage: true,
+            };
+        const flags = await Promise.all(definitions.map(async (definition) => {
+            const rules = await getFeatureFlagRules(definition.key, manager);
+            return {
+                ...definition,
+                rules,
+                enabledForCurrentUser: evaluateFeatureFlagRules(definition.key, rules, {
+                    userEmail: manager.email,
+                    userKey: manager.email,
+                    orgId: manager.orgId,
+                }),
+            };
+        }));
+        return {
+            contractVersion: 1,
+            status: "ready",
+            reason: "ready",
+            flags,
+            canManage: true,
+        };
+    },
+});
+//# sourceMappingURL=list-feature-flags.js.map

package/dist/feature-flags/actions/list-feature-flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-feature-flags.js","sourceRoot":"","sources":["../../../src/feature-flags/actions/list-feature-flags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE5E,eAAe,YAAY,CAAC;IAC1B,WAAW,EACT,yIAAyI;IAC3I,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;IACpB,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;IACvB,YAAY,EAAE,KAAK;IACnB,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QACxB,MAAM,WAAW,GAAG,gBAAgB,EAAE,CAAC;QACvC,IAAI,OAAO,CAAC;QACZ,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,yBAAyB,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IACE,KAAK,YAAY,KAAK;gBACtB,YAAY,IAAI,KAAK;gBACpB,KAAiC,CAAC,UAAU,KAAK,GAAG,EACrD,CAAC;gBACD,OAAO;oBACL,eAAe,EAAE,CAAC;oBAClB,MAAM,EAAE,WAAoB;oBAC5B,MAAM,EAAE,WAAoB;oBAC5B,KAAK,EAAE,EAAE;oBACT,SAAS,EAAE,KAAK;iBACjB,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;QACD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;YAC1B,OAAO;gBACL,eAAe,EAAE,CAAC;gBAClB,MAAM,EAAE,gBAAyB;gBACjC,MAAM,EAAE,gBAAyB;gBACjC,KAAK,EAAE,EAAE;gBACT,SAAS,EAAE,IAAI;aAChB,CAAC;QACJ,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAC7B,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE;YACnC,MAAM,KAAK,GAAG,MAAM,mBAAmB,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YACjE,OAAO;gBACL,GAAG,UAAU;gBACb,KAAK;gBACL,qBAAqB,EAAE,wBAAwB,CAC7C,UAAU,CAAC,GAAG,EACd,KAAK,EACL;oBACE,SAAS,EAAE,OAAO,CAAC,KAAK;oBACxB,OAAO,EAAE,OAAO,CAAC,KAAK;oBACtB,KAAK,EAAE,OAAO,CAAC,KAAK;iBACrB,CACF;aACF,CAAC;QACJ,CAAC,CAAC,CACH,CAAC;QACF,OAAO;YACL,eAAe,EAAE,CAAC;YAClB,MAAM,EAAE,OAAgB;YACxB,MAAM,EAAE,OAAgB;YACxB,KAAK;YACL,SAAS,EAAE,IAAI;SAChB,CAAC;IACJ,CAAC;CACF,CAAC,CAAC","sourcesContent":["import { z } from \"zod\";\n\nimport { defineAction } from \"../../action.js\";\nimport { requireFeatureFlagManager } from \"../permissions.js\";\nimport { listFeatureFlags } from \"../registry.js\";\nimport { evaluateFeatureFlagRules, getFeatureFlagRules } from \"../store.js\";\n\nexport default defineAction({\n  description:\n    \"List this app's registered feature flags and their current rules. Organization owner/admin only (or the explicit no-org administrator).\",\n  schema: z.object({}),\n  http: { method: \"GET\" },\n  toolCallable: false,\n  run: async (_args, ctx) => {\n    const definitions = listFeatureFlags();\n    let manager;\n    try {\n      manager = await requireFeatureFlagManager(ctx ?? {});\n    } catch (error) {\n      if (\n        error instanceof Error &&\n        \"statusCode\" in error &&\n        (error as { statusCode?: number }).statusCode === 403\n      ) {\n        return {\n          contractVersion: 1,\n          status: \"forbidden\" as const,\n          reason: \"forbidden\" as const,\n          flags: [],\n          canManage: false,\n        };\n      }\n      throw error;\n    }\n    if (definitions.length === 0)\n      return {\n        contractVersion: 1,\n        status: \"no-definitions\" as const,\n        reason: \"no-definitions\" as const,\n        flags: [],\n        canManage: true,\n      };\n    const flags = await Promise.all(\n      definitions.map(async (definition) => {\n        const rules = await getFeatureFlagRules(definition.key, manager);\n        return {\n          ...definition,\n          rules,\n          enabledForCurrentUser: evaluateFeatureFlagRules(\n            definition.key,\n            rules,\n            {\n              userEmail: manager.email,\n              userKey: manager.email,\n              orgId: manager.orgId,\n            },\n          ),\n        };\n      }),\n    );\n    return {\n      contractVersion: 1,\n      status: \"ready\" as const,\n      reason: \"ready\" as const,\n      flags,\n      canManage: true,\n    };\n  },\n});\n"]}

package/dist/feature-flags/actions/set-feature-flag.d.ts

@@ -0,0 +1,26 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    operation: "enable-for-current-user";
+    key: string;
+} | {
+    operation: "off";
+    key: string;
+} | {
+    operation: "replace-rules";
+    key: string;
+    rules: {
+        mode: "off" | "on" | "rules";
+        emails?: string[];
+        orgIds?: string[];
+        percentage?: number;
+    };
+}, {
+    contractVersion: 1;
+    status: "ready";
+    key: string;
+    rules: import("../store.js").FeatureFlagRules;
+    scope: {
+        orgId: string;
+    };
+}>;
+export default _default;
+//# sourceMappingURL=set-feature-flag.d.ts.map

package/dist/feature-flags/actions/set-feature-flag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-feature-flag.d.ts","sourceRoot":"","sources":["../../../src/feature-flags/actions/set-feature-flag.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;qBAiFuB,CAAC;YACV,OAAO;;;;QAGN,KAAK"}

package/dist/feature-flags/actions/set-feature-flag.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { requireFeatureFlagManager } from "../permissions.js";
+import { getFeatureFlagDefinition } from "../registry.js";
+import { defaultFeatureFlagRules, mutateFeatureFlagRules, normalizeFeatureFlagRules, } from "../store.js";
+const rulesSchema = z.object({
+    mode: z.enum(["off", "on", "rules"]),
+    emails: z.array(z.string().email()).max(500).optional(),
+    orgIds: z.array(z.string().min(1).max(200)).max(500).optional(),
+    percentage: z.number().int().min(0).max(100).optional(),
+});
+const schema = z.discriminatedUnion("operation", [
+    z.object({
+        operation: z.literal("enable-for-current-user"),
+        key: z.string(),
+    }),
+    z.object({ operation: z.literal("off"), key: z.string() }),
+    z.object({
+        operation: z.literal("replace-rules"),
+        key: z.string(),
+        rules: rulesSchema,
+    }),
+]);
+export default defineAction({
+    description: "Atomically manage one registered feature flag: enable it for the current user, turn it off immediately for the active scope, or replace its full rules. Organization owner/admin only (or the explicit no-org administrator).",
+    schema,
+    // Keep the strict discriminated union for runtime validation, but advertise
+    // an object-shaped schema so agent tool registries can expose the action.
+    // Root-level JSON Schema unions are intentionally rejected by the agent.
+    agentInputSchema: z.object({
+        operation: z.enum(["enable-for-current-user", "off", "replace-rules"]),
+        key: z.string(),
+        rules: rulesSchema.optional(),
+    }),
+    toolCallable: false,
+    audit: {
+        target: (args, _result, meta) => ({
+            type: "feature-flag",
+            id: args.key,
+            ownerEmail: meta.userEmail,
+            visibility: meta.orgId ? "org" : "private",
+        }),
+        summary: (args) => `Feature flag ${args.key}: ${args.operation}`,
+    },
+    run: async (args, ctx) => {
+        const manager = await requireFeatureFlagManager(ctx ?? {});
+        if (!getFeatureFlagDefinition(args.key)) {
+            throw new Error(`Unknown feature flag: ${args.key}`);
+        }
+        const persistedRules = await mutateFeatureFlagRules(args.key, manager, (current) => {
+            let rules;
+            if (args.operation === "off") {
+                rules = defaultFeatureFlagRules();
+            }
+            else if (args.operation === "replace-rules") {
+                rules = normalizeFeatureFlagRules(args.rules);
+            }
+            else {
+                rules = normalizeFeatureFlagRules({
+                    ...current,
+                    // A globally-on flag already includes this user. Do not
+                    // accidentally narrow it to a one-email rollout.
+                    mode: current.mode === "on" ? "on" : "rules",
+                    emails: [...current.emails, manager.email],
+                });
+            }
+            return { ...rules, updatedAt: Date.now(), updatedBy: manager.email };
+        });
+        return {
+            contractVersion: 1,
+            status: "ready",
+            key: args.key,
+            rules: persistedRules,
+            scope: { orgId: manager.orgId },
+        };
+    },
+});
+//# sourceMappingURL=set-feature-flag.js.map

package/dist/feature-flags/actions/set-feature-flag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-feature-flag.js","sourceRoot":"","sources":["../../../src/feature-flags/actions/set-feature-flag.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\n\nimport { defineAction } from \"../../action.js\";\nimport { requireFeatureFlagManager } from \"../permissions.js\";\nimport { getFeatureFlagDefinition } from \"../registry.js\";\nimport {\n  defaultFeatureFlagRules,\n  mutateFeatureFlagRules,\n  normalizeFeatureFlagRules,\n} from \"../store.js\";\n\nconst rulesSchema = z.object({\n  mode: z.enum([\"off\", \"on\", \"rules\"]),\n  emails: z.array(z.string().email()).max(500).optional(),\n  orgIds: z.array(z.string().min(1).max(200)).max(500).optional(),\n  percentage: z.number().int().min(0).max(100).optional(),\n});\n\nconst schema = z.discriminatedUnion(\"operation\", [\n  z.object({\n    operation: z.literal(\"enable-for-current-user\"),\n    key: z.string(),\n  }),\n  z.object({ operation: z.literal(\"off\"), key: z.string() }),\n  z.object({\n    operation: z.literal(\"replace-rules\"),\n    key: z.string(),\n    rules: rulesSchema,\n  }),\n]);\n\nexport default defineAction({\n  description:\n    \"Atomically manage one registered feature flag: enable it for the current user, turn it off immediately for the active scope, or replace its full rules. Organization owner/admin only (or the explicit no-org administrator).\",\n  schema,\n  // Keep the strict discriminated union for runtime validation, but advertise\n  // an object-shaped schema so agent tool registries can expose the action.\n  // Root-level JSON Schema unions are intentionally rejected by the agent.\n  agentInputSchema: z.object({\n    operation: z.enum([\"enable-for-current-user\", \"off\", \"replace-rules\"]),\n    key: z.string(),\n    rules: rulesSchema.optional(),\n  }),\n  toolCallable: false,\n  audit: {\n    target: (args, _result, meta) => ({\n      type: \"feature-flag\",\n      id: args.key,\n      ownerEmail: meta.userEmail,\n      visibility: meta.orgId ? \"org\" : \"private\",\n    }),\n    summary: (args) => `Feature flag ${args.key}: ${args.operation}`,\n  },\n  run: async (args, ctx) => {\n    const manager = await requireFeatureFlagManager(ctx ?? {});\n    if (!getFeatureFlagDefinition(args.key)) {\n      throw new Error(`Unknown feature flag: ${args.key}`);\n    }\n\n    const persistedRules = await mutateFeatureFlagRules(\n      args.key,\n      manager,\n      (current) => {\n        let rules;\n        if (args.operation === \"off\") {\n          rules = defaultFeatureFlagRules();\n        } else if (args.operation === \"replace-rules\") {\n          rules = normalizeFeatureFlagRules(args.rules);\n        } else {\n          rules = normalizeFeatureFlagRules({\n            ...current,\n            // A globally-on flag already includes this user. Do not\n            // accidentally narrow it to a one-email rollout.\n            mode: current.mode === \"on\" ? \"on\" : \"rules\",\n            emails: [...current.emails, manager.email],\n          });\n        }\n        return { ...rules, updatedAt: Date.now(), updatedBy: manager.email };\n      },\n    );\n    return {\n      contractVersion: 1 as const,\n      status: \"ready\" as const,\n      key: args.key,\n      rules: persistedRules,\n      scope: { orgId: manager.orgId },\n    };\n  },\n});\n"]}

package/dist/feature-flags/index.d.ts

@@ -0,0 +1,5 @@
+export { defineFeatureFlag, defineFeatureFlags, getFeatureFlagDefinition, listFeatureFlags, registerFeatureFlags, type FeatureFlagDefinition, } from "./registry.js";
+export { defaultFeatureFlagRules, evaluateFeatureFlag, evaluateFeatureFlagRules, isFeatureFlagEnabled, getFeatureFlagRules, normalizeFeatureFlagRules, type FeatureFlagMode, type FeatureFlagRules, type FeatureFlagScope, } from "./store.js";
+export { createFeatureFlagsPlugin } from "./plugin.js";
+export { createFeatureFlagA2AActionRouteAuth } from "./a2a-action-route.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/feature-flags/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/feature-flags/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,qBAAqB,GAC3B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,mCAAmC,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/feature-flags/index.js

@@ -0,0 +1,5 @@
+export { defineFeatureFlag, defineFeatureFlags, getFeatureFlagDefinition, listFeatureFlags, registerFeatureFlags, } from "./registry.js";
+export { defaultFeatureFlagRules, evaluateFeatureFlag, evaluateFeatureFlagRules, isFeatureFlagEnabled, getFeatureFlagRules, normalizeFeatureFlagRules, } from "./store.js";
+export { createFeatureFlagsPlugin } from "./plugin.js";
+export { createFeatureFlagA2AActionRouteAuth } from "./a2a-action-route.js";
+//# sourceMappingURL=index.js.map

package/dist/feature-flags/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/feature-flags/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,gBAAgB,EAChB,oBAAoB,GAErB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,GAI1B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,mCAAmC,EAAE,MAAM,uBAAuB,CAAC","sourcesContent":["export {\n  defineFeatureFlag,\n  defineFeatureFlags,\n  getFeatureFlagDefinition,\n  listFeatureFlags,\n  registerFeatureFlags,\n  type FeatureFlagDefinition,\n} from \"./registry.js\";\nexport {\n  defaultFeatureFlagRules,\n  evaluateFeatureFlag,\n  evaluateFeatureFlagRules,\n  isFeatureFlagEnabled,\n  getFeatureFlagRules,\n  normalizeFeatureFlagRules,\n  type FeatureFlagMode,\n  type FeatureFlagRules,\n  type FeatureFlagScope,\n} from \"./store.js\";\nexport { createFeatureFlagsPlugin } from \"./plugin.js\";\nexport { createFeatureFlagA2AActionRouteAuth } from \"./a2a-action-route.js\";\n"]}

package/dist/feature-flags/permissions.d.ts

@@ -0,0 +1,13 @@
+export declare class FeatureFlagPermissionError extends Error {
+    statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+/** Require an org admin/owner, or an explicit production no-org allowlist entry. */
+export declare function requireFeatureFlagManager(scope: {
+    userEmail?: string;
+    orgId?: string | null;
+}): Promise<{
+    email: string;
+    orgId: string | null;
+}>;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/feature-flags/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/feature-flags/permissions.ts"],"names":[],"mappings":"AAGA,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,UAAU,EAAE,MAAM,CAAC;IAEnB,YAAY,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAG9C;CACF;AAWD,oFAAoF;AACpF,wBAAsB,yBAAyB,CAAC,KAAK,EAAE;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CA2BnD"}

package/dist/feature-flags/permissions.js

@@ -0,0 +1,37 @@
+import { getOrgRoleForEmail } from "../mcp/actions/service-token-access.js";
+import { canManageOrg } from "../org/permissions.js";
+export class FeatureFlagPermissionError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+    }
+}
+function productionAdminAllowlist() {
+    return new Set((process.env.AGENT_NATIVE_FEATURE_FLAG_ADMIN_EMAILS ?? "")
+        .split(",")
+        .map((email) => email.trim().toLowerCase())
+        .filter(Boolean));
+}
+/** Require an org admin/owner, or an explicit production no-org allowlist entry. */
+export async function requireFeatureFlagManager(scope) {
+    const email = scope.userEmail?.trim().toLowerCase();
+    if (!email) {
+        throw new FeatureFlagPermissionError("Sign in to manage feature flags.", 401);
+    }
+    const orgId = scope.orgId?.trim() || null;
+    if (orgId) {
+        const role = await getOrgRoleForEmail(orgId, email);
+        if (!canManageOrg(role)) {
+            throw new FeatureFlagPermissionError("Only organization owners or admins can manage feature flags.", 403);
+        }
+        return { email, orgId };
+    }
+    if (process.env.NODE_ENV !== "production")
+        return { email, orgId: null };
+    if (!productionAdminAllowlist().has(email)) {
+        throw new FeatureFlagPermissionError("Feature flag management without an organization requires an explicit admin allowlist entry.", 403);
+    }
+    return { email, orgId: null };
+}
+//# sourceMappingURL=permissions.js.map

package/dist/feature-flags/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/feature-flags/permissions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IACnD,UAAU,CAAS;IAEnB,YAAY,OAAe,EAAE,UAAkB;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,SAAS,wBAAwB;IAC/B,OAAO,IAAI,GAAG,CACZ,CAAC,OAAO,CAAC,GAAG,CAAC,sCAAsC,IAAI,EAAE,CAAC;SACvD,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;SAC1C,MAAM,CAAC,OAAO,CAAC,CACnB,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,KAG/C;IACC,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,0BAA0B,CAClC,kCAAkC,EAClC,GAAG,CACJ,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;IAC1C,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,IAAI,GAAG,MAAM,kBAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACpD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,0BAA0B,CAClC,8DAA8D,EAC9D,GAAG,CACJ,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC1B,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzE,IAAI,CAAC,wBAAwB,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,0BAA0B,CAClC,6FAA6F,EAC7F,GAAG,CACJ,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAChC,CAAC","sourcesContent":["import { getOrgRoleForEmail } from \"../mcp/actions/service-token-access.js\";\nimport { canManageOrg } from \"../org/permissions.js\";\n\nexport class FeatureFlagPermissionError extends Error {\n  statusCode: number;\n\n  constructor(message: string, statusCode: number) {\n    super(message);\n    this.statusCode = statusCode;\n  }\n}\n\nfunction productionAdminAllowlist(): Set<string> {\n  return new Set(\n    (process.env.AGENT_NATIVE_FEATURE_FLAG_ADMIN_EMAILS ?? \"\")\n      .split(\",\")\n      .map((email) => email.trim().toLowerCase())\n      .filter(Boolean),\n  );\n}\n\n/** Require an org admin/owner, or an explicit production no-org allowlist entry. */\nexport async function requireFeatureFlagManager(scope: {\n  userEmail?: string;\n  orgId?: string | null;\n}): Promise<{ email: string; orgId: string | null }> {\n  const email = scope.userEmail?.trim().toLowerCase();\n  if (!email) {\n    throw new FeatureFlagPermissionError(\n      \"Sign in to manage feature flags.\",\n      401,\n    );\n  }\n  const orgId = scope.orgId?.trim() || null;\n  if (orgId) {\n    const role = await getOrgRoleForEmail(orgId, email);\n    if (!canManageOrg(role)) {\n      throw new FeatureFlagPermissionError(\n        \"Only organization owners or admins can manage feature flags.\",\n        403,\n      );\n    }\n    return { email, orgId };\n  }\n  if (process.env.NODE_ENV !== \"production\") return { email, orgId: null };\n  if (!productionAdminAllowlist().has(email)) {\n    throw new FeatureFlagPermissionError(\n      \"Feature flag management without an organization requires an explicit admin allowlist entry.\",\n      403,\n    );\n  }\n  return { email, orgId: null };\n}\n"]}

package/dist/feature-flags/plugin.d.ts

@@ -0,0 +1,17 @@
+import { type FeatureFlagDefinition } from "./registry.js";
+type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
+/** A tiny startup plugin for app-local, explicit feature-flag registration. */
+export declare function createFeatureFlagsPlugin(options: {
+    flags: readonly FeatureFlagDefinition[];
+    /**
+     * One-time compatibility bridge for apps that previously stored global
+     * booleans together in a single settings object. Only legacy `true` values
+     * are copied, and an explicit rule in the new store always wins.
+     */
+    legacyBooleanSetting?: {
+        settingKey: string;
+        flagKeys: readonly string[];
+    };
+}): NitroPluginDef;
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/feature-flags/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/feature-flags/plugin.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,eAAe,CAAC;AAGvB,KAAK,cAAc,GAAG,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE9D,+EAA+E;AAC/E,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAChD,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACxC;;;;OAIG;IACH,oBAAoB,CAAC,EAAE;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;KAC7B,CAAC;CACH,GAAG,cAAc,CAsBjB"}

package/dist/feature-flags/plugin.js

@@ -0,0 +1,29 @@
+import { getSetting } from "../settings/store.js";
+import { registerFeatureFlags, } from "./registry.js";
+import { mutateFeatureFlagRules } from "./store.js";
+/** A tiny startup plugin for app-local, explicit feature-flag registration. */
+export function createFeatureFlagsPlugin(options) {
+    return async () => {
+        registerFeatureFlags(options.flags);
+        if (!options.legacyBooleanSetting)
+            return;
+        const legacy = await getSetting(options.legacyBooleanSetting.settingKey);
+        if (!legacy)
+            return;
+        await Promise.all(options.legacyBooleanSetting.flagKeys.map(async (key) => {
+            if (legacy[key] !== true)
+                return;
+            await mutateFeatureFlagRules(key, {}, (current) => {
+                if (current.updatedAt !== null)
+                    return current;
+                return {
+                    ...current,
+                    mode: "on",
+                    updatedAt: Date.now(),
+                    updatedBy: "legacy-settings-migration",
+                };
+            });
+        }));
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/feature-flags/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/feature-flags/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EACL,oBAAoB,GAErB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAIpD,+EAA+E;AAC/E,MAAM,UAAU,wBAAwB,CAAC,OAWxC;IACC,OAAO,KAAK,IAAI,EAAE;QAChB,oBAAoB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,OAAO,CAAC,oBAAoB;YAAE,OAAO;QAE1C,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC;QACzE,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,MAAM,OAAO,CAAC,GAAG,CACf,OAAO,CAAC,oBAAoB,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YACtD,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI;gBAAE,OAAO;YACjC,MAAM,sBAAsB,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,EAAE;gBAChD,IAAI,OAAO,CAAC,SAAS,KAAK,IAAI;oBAAE,OAAO,OAAO,CAAC;gBAC/C,OAAO;oBACL,GAAG,OAAO;oBACV,IAAI,EAAE,IAAI;oBACV,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;oBACrB,SAAS,EAAE,2BAA2B;iBACvC,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CACH,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import { getSetting } from \"../settings/store.js\";\nimport {\n  registerFeatureFlags,\n  type FeatureFlagDefinition,\n} from \"./registry.js\";\nimport { mutateFeatureFlagRules } from \"./store.js\";\n\ntype NitroPluginDef = (nitroApp: any) => void | Promise<void>;\n\n/** A tiny startup plugin for app-local, explicit feature-flag registration. */\nexport function createFeatureFlagsPlugin(options: {\n  flags: readonly FeatureFlagDefinition[];\n  /**\n   * One-time compatibility bridge for apps that previously stored global\n   * booleans together in a single settings object. Only legacy `true` values\n   * are copied, and an explicit rule in the new store always wins.\n   */\n  legacyBooleanSetting?: {\n    settingKey: string;\n    flagKeys: readonly string[];\n  };\n}): NitroPluginDef {\n  return async () => {\n    registerFeatureFlags(options.flags);\n    if (!options.legacyBooleanSetting) return;\n\n    const legacy = await getSetting(options.legacyBooleanSetting.settingKey);\n    if (!legacy) return;\n    await Promise.all(\n      options.legacyBooleanSetting.flagKeys.map(async (key) => {\n        if (legacy[key] !== true) return;\n        await mutateFeatureFlagRules(key, {}, (current) => {\n          if (current.updatedAt !== null) return current;\n          return {\n            ...current,\n            mode: \"on\",\n            updatedAt: Date.now(),\n            updatedBy: \"legacy-settings-migration\",\n          };\n        });\n      }),\n    );\n  };\n}\n"]}

package/dist/feature-flags/registry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * App-owned feature-flag definitions. Core intentionally starts with an empty
+ * registry: a flag key is part of an app's stable contract, not framework
+ * configuration that Core should guess at.
+ */
+export interface FeatureFlagDefinition {
+    key: string;
+    /** Boolean flags are always default-off; explicit in operator metadata. */
+    defaultValue?: false;
+    displayName?: string;
+    description?: string;
+}
+/** Define one app-local feature flag for registration at server startup. */
+export declare function defineFeatureFlag(definition: FeatureFlagDefinition): FeatureFlagDefinition;
+/** Define a small app-owned feature-flag registry. */
+export declare function defineFeatureFlags(definitions: readonly FeatureFlagDefinition[]): readonly FeatureFlagDefinition[];
+/** Register definitions once at Nitro startup. Re-registering identical data is safe for HMR. */
+export declare function registerFeatureFlags(definitions: readonly FeatureFlagDefinition[]): void;
+export declare function listFeatureFlags(): readonly FeatureFlagDefinition[];
+export declare function getFeatureFlagDefinition(key: string): FeatureFlagDefinition | null;
+/** Test-only registry reset; not exported from package entrypoints. */
+export declare function _resetFeatureFlagRegistryForTests(): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/feature-flags/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/feature-flags/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAyBD,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,qBAAqB,GAChC,qBAAqB,CAEvB;AAED,sDAAsD;AACtD,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,SAAS,qBAAqB,EAAE,GAC5C,SAAS,qBAAqB,EAAE,CAYlC;AAED,iGAAiG;AACjG,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,SAAS,qBAAqB,EAAE,GAC5C,IAAI,CAiBN;AAED,wBAAgB,gBAAgB,IAAI,SAAS,qBAAqB,EAAE,CAEnE;AAED,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,GACV,qBAAqB,GAAG,IAAI,CAE9B;AAED,uEAAuE;AACvE,wBAAgB,iCAAiC,IAAI,IAAI,CAExD"}

package/dist/feature-flags/registry.js

@@ -0,0 +1,59 @@
+const registry = new Map();
+function normalizeDefinition(definition) {
+    const key = definition.key.trim();
+    if (!/^[A-Za-z][A-Za-z0-9._-]{0,63}$/.test(key)) {
+        throw new Error("Feature flag keys must be stable strings containing only letters, numbers, dots, underscores, or hyphens (1-64 characters).");
+    }
+    return {
+        key,
+        defaultValue: false,
+        ...(definition.displayName?.trim() && {
+            displayName: definition.displayName.trim(),
+        }),
+        ...(definition.description?.trim() && {
+            description: definition.description.trim(),
+        }),
+    };
+}
+/** Define one app-local feature flag for registration at server startup. */
+export function defineFeatureFlag(definition) {
+    return Object.freeze(normalizeDefinition(definition));
+}
+/** Define a small app-owned feature-flag registry. */
+export function defineFeatureFlags(definitions) {
+    const seen = new Set();
+    return Object.freeze(definitions.map((definition) => {
+        const normalized = defineFeatureFlag(definition);
+        if (seen.has(normalized.key)) {
+            throw new Error(`Duplicate feature flag key: ${normalized.key}`);
+        }
+        seen.add(normalized.key);
+        return normalized;
+    }));
+}
+/** Register definitions once at Nitro startup. Re-registering identical data is safe for HMR. */
+export function registerFeatureFlags(definitions) {
+    for (const rawDefinition of definitions) {
+        const definition = defineFeatureFlag(rawDefinition);
+        const existing = registry.get(definition.key);
+        if (!existing) {
+            registry.set(definition.key, definition);
+            continue;
+        }
+        if (existing.displayName !== definition.displayName ||
+            existing.description !== definition.description) {
+            throw new Error(`Feature flag ${definition.key} was registered with conflicting metadata.`);
+        }
+    }
+}
+export function listFeatureFlags() {
+    return [...registry.values()].sort((a, b) => a.key.localeCompare(b.key));
+}
+export function getFeatureFlagDefinition(key) {
+    return registry.get(key) ?? null;
+}
+/** Test-only registry reset; not exported from package entrypoints. */
+export function _resetFeatureFlagRegistryForTests() {
+    registry.clear();
+}
+//# sourceMappingURL=registry.js.map

package/dist/feature-flags/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/feature-flags/registry.ts"],"names":[],"mappings":"AAaA,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAiC,CAAC;AAE1D,SAAS,mBAAmB,CAC1B,UAAiC;IAEjC,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IAClC,IAAI,CAAC,gCAAgC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CACb,6HAA6H,CAC9H,CAAC;IACJ,CAAC;IACD,OAAO;QACL,GAAG;QACH,YAAY,EAAE,KAAK;QACnB,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI;YACpC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE;SAC3C,CAAC;QACF,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI;YACpC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE;SAC3C,CAAC;KACH,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,iBAAiB,CAC/B,UAAiC;IAEjC,OAAO,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,kBAAkB,CAChC,WAA6C;IAE7C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,MAAM,CAAC,MAAM,CAClB,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE;QAC7B,MAAM,UAAU,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;QACjD,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,+BAA+B,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QACzB,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC,CACH,CAAC;AACJ,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,oBAAoB,CAClC,WAA6C;IAE7C,KAAK,MAAM,aAAa,IAAI,WAAW,EAAE,CAAC;QACxC,MAAM,UAAU,GAAG,iBAAiB,CAAC,aAAa,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QAC9C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;YACzC,SAAS;QACX,CAAC;QACD,IACE,QAAQ,CAAC,WAAW,KAAK,UAAU,CAAC,WAAW;YAC/C,QAAQ,CAAC,WAAW,KAAK,UAAU,CAAC,WAAW,EAC/C,CAAC;YACD,MAAM,IAAI,KAAK,CACb,gBAAgB,UAAU,CAAC,GAAG,4CAA4C,CAC3E,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,GAAW;IAEX,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;AACnC,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,iCAAiC;IAC/C,QAAQ,CAAC,KAAK,EAAE,CAAC;AACnB,CAAC","sourcesContent":["/**\n * App-owned feature-flag definitions. Core intentionally starts with an empty\n * registry: a flag key is part of an app's stable contract, not framework\n * configuration that Core should guess at.\n */\nexport interface FeatureFlagDefinition {\n  key: string;\n  /** Boolean flags are always default-off; explicit in operator metadata. */\n  defaultValue?: false;\n  displayName?: string;\n  description?: string;\n}\n\nconst registry = new Map<string, FeatureFlagDefinition>();\n\nfunction normalizeDefinition(\n  definition: FeatureFlagDefinition,\n): FeatureFlagDefinition {\n  const key = definition.key.trim();\n  if (!/^[A-Za-z][A-Za-z0-9._-]{0,63}$/.test(key)) {\n    throw new Error(\n      \"Feature flag keys must be stable strings containing only letters, numbers, dots, underscores, or hyphens (1-64 characters).\",\n    );\n  }\n  return {\n    key,\n    defaultValue: false,\n    ...(definition.displayName?.trim() && {\n      displayName: definition.displayName.trim(),\n    }),\n    ...(definition.description?.trim() && {\n      description: definition.description.trim(),\n    }),\n  };\n}\n\n/** Define one app-local feature flag for registration at server startup. */\nexport function defineFeatureFlag(\n  definition: FeatureFlagDefinition,\n): FeatureFlagDefinition {\n  return Object.freeze(normalizeDefinition(definition));\n}\n\n/** Define a small app-owned feature-flag registry. */\nexport function defineFeatureFlags(\n  definitions: readonly FeatureFlagDefinition[],\n): readonly FeatureFlagDefinition[] {\n  const seen = new Set<string>();\n  return Object.freeze(\n    definitions.map((definition) => {\n      const normalized = defineFeatureFlag(definition);\n      if (seen.has(normalized.key)) {\n        throw new Error(`Duplicate feature flag key: ${normalized.key}`);\n      }\n      seen.add(normalized.key);\n      return normalized;\n    }),\n  );\n}\n\n/** Register definitions once at Nitro startup. Re-registering identical data is safe for HMR. */\nexport function registerFeatureFlags(\n  definitions: readonly FeatureFlagDefinition[],\n): void {\n  for (const rawDefinition of definitions) {\n    const definition = defineFeatureFlag(rawDefinition);\n    const existing = registry.get(definition.key);\n    if (!existing) {\n      registry.set(definition.key, definition);\n      continue;\n    }\n    if (\n      existing.displayName !== definition.displayName ||\n      existing.description !== definition.description\n    ) {\n      throw new Error(\n        `Feature flag ${definition.key} was registered with conflicting metadata.`,\n      );\n    }\n  }\n}\n\nexport function listFeatureFlags(): readonly FeatureFlagDefinition[] {\n  return [...registry.values()].sort((a, b) => a.key.localeCompare(b.key));\n}\n\nexport function getFeatureFlagDefinition(\n  key: string,\n): FeatureFlagDefinition | null {\n  return registry.get(key) ?? null;\n}\n\n/** Test-only registry reset; not exported from package entrypoints. */\nexport function _resetFeatureFlagRegistryForTests(): void {\n  registry.clear();\n}\n"]}

package/dist/feature-flags/store.d.ts

@@ -0,0 +1,31 @@
+import { type FeatureFlagDefinition } from "./registry.js";
+export type FeatureFlagMode = "off" | "on" | "rules";
+export interface FeatureFlagRules {
+    version: 1;
+    mode: FeatureFlagMode;
+    emails: string[];
+    orgIds: string[];
+    percentage: number;
+    updatedAt: number | null;
+    updatedBy: string | null;
+}
+export interface FeatureFlagScope {
+    userEmail?: string;
+    /** Canonical authenticated identity. V1 callers use normalized email. */
+    userKey?: string;
+    orgId?: string | null;
+}
+export declare const FEATURE_FLAG_SETTINGS_PREFIX = "feature-flag:";
+export declare function defaultFeatureFlagRules(): FeatureFlagRules;
+export declare function normalizeFeatureFlagRules(value: unknown): FeatureFlagRules;
+export declare function getFeatureFlagRules(key: string, scope: Pick<FeatureFlagScope, "orgId">): Promise<FeatureFlagRules>;
+/**
+ * Atomically derive one flag's scoped rules. An org's first override starts
+ * from the global fallback, then becomes independently CAS-protected.
+ */
+export declare function mutateFeatureFlagRules(key: string, scope: Pick<FeatureFlagScope, "orgId">, updater: (current: FeatureFlagRules) => FeatureFlagRules | Promise<FeatureFlagRules>): Promise<FeatureFlagRules>;
+export declare function evaluateFeatureFlagRules(key: string, rules: FeatureFlagRules, scope: FeatureFlagScope): boolean;
+export declare function evaluateFeatureFlag(key: string, scope?: FeatureFlagScope): Promise<boolean>;
+/** Ergonomic app-action guard. Accepts either a registered definition or its key. */
+export declare function isFeatureFlagEnabled(flag: string | FeatureFlagDefinition, scope?: FeatureFlagScope): Promise<boolean>;
+//# sourceMappingURL=store.d.ts.map