@agent-native/core 0.107.2 → 0.108.0

package/corpus/core/src/localization/default-messages.ts

@@ -33,6 +33,53 @@ const messages = {
     openResourceSettings: "Open resource settings",
     backHome: "Back to home",
   },
+  featureFlags: {
+    title: "Feature flags",
+    description: "Control staged capabilities without changing a deployment.",
+    enableForMe: "Enable for me",
+    enabledForMe: "Enabled for you",
+    youHaveAccess: "You have access",
+    youDoNotHaveAccess: "You don't have access",
+    currentUserUnknown: "Your access couldn't be evaluated",
+    moreActions: "More actions for {{name}}",
+    disableForEveryone: "Disable for everyone",
+    disableForEveryoneTitle: "Disable {{name}} for everyone?",
+    disableForEveryoneDescription:
+      "This immediately removes access for every targeted person and organization. You can configure a new rollout later.",
+    editTargeting: "Edit targeting",
+    editTargetingFor: "Edit targeting for {{name}}",
+    targetingTitle: "Edit targeting — {{name}}",
+    targetingDescription:
+      "Choose who can use this capability. Changes apply immediately.",
+    noFlags: "No feature flags are registered for this app.",
+    defaultOn: "Code fallback: on",
+    defaultOff: "Code fallback: off",
+    enabledFor: "Enabled for",
+    modeLabel: "Availability",
+    emailsLabel: "People",
+    orgIdsLabel: "Organization IDs",
+    percentageLabel: "Percentage of users",
+    targetingRuleHelp:
+      "A person gets access if they match any email, organization, or percentage rule.",
+    targetingSummary: "Currently enabled for: {{audience}}.",
+    saveRules: "Save changes",
+    cancel: "Cancel",
+    inherited: "No matching targets",
+    off: "Off",
+    targeted: "Targeted",
+    everyone: "Everyone",
+    everyoneAudience: "everyone",
+    emailCount_one: "{{count}} email",
+    emailCount_other: "{{count}} emails",
+    organizationCount_one: "{{count}} organization",
+    organizationCount_other: "{{count}} organizations",
+    percentageRollout: "{{count}}% rollout",
+    lastChanged: "Last changed: {{metadata}}",
+    mutationUnverified:
+      "We couldn't verify the change to {{name}}. Reload flags before trying again.",
+    mutationUnverifiedGeneric:
+      "We couldn't verify this feature flag change. Reload flags before trying again.",
+  },
   dispatch: {
     nav: {
       chat: "Chat",

package/corpus/core/src/server/action-discovery.ts

@@ -595,6 +595,18 @@ export async function mergeCoreSharingActions(
       () => import("../sharing/actions/create-agent-resource-link.js"),
     ],
     ["upload-image", () => import("../file-upload/actions/upload-image.js")],
+    [
+      "get-feature-flags",
+      () => import("../feature-flags/actions/get-feature-flags.js"),
+    ],
+    [
+      "list-feature-flags",
+      () => import("../feature-flags/actions/list-feature-flags.js"),
+    ],
+    [
+      "set-feature-flag",
+      () => import("../feature-flags/actions/set-feature-flag.js"),
+    ],
     // Agent Jobs page — UI-only scoped reads and mutations for resource-backed
     // recurring jobs and personal automations. The agent-facing native tools
     // remain the canonical conversational surface.

package/corpus/core/src/server/action-routes.ts

@@ -9,8 +9,10 @@ import {
   getRequestURL,
 } from "h3";
 
+import { verifyA2ATokenWithClaims } from "../a2a-claims.js";
 import { isAgentActionStopError } from "../action.js";
 import type { ActionEntry } from "../agent/production-agent.js";
+import { declaresFeatureFlagDelegation } from "../feature-flags/a2a-action-route.js";
 import { resolveOrgIdForEmail } from "../org/context.js";
 import { readBody } from "../server/h3-helpers.js";
 import { EMBED_TARGET_HEADER } from "../shared/embed-auth.js";
@@ -39,6 +41,30 @@ import { runWithRequestContext } from "./request-context.js";
 
 const ROUTE_PREFIX = "/_agent-native/actions";
 
+async function resolveFeatureFlagA2ACaller(event: any, actionName: string) {
+  const required =
+    actionName === "list-feature-flags"
+      ? "flags:read"
+      : actionName === "set-feature-flag"
+        ? "flags:write"
+        : null;
+  if (!required) return null;
+  const authorization = getHeader(event, "authorization");
+  if (!authorization?.startsWith("Bearer ")) return null;
+  const token = authorization.slice(7);
+  if (!declaresFeatureFlagDelegation(token)) return null;
+  const claims = await verifyA2ATokenWithClaims(token, event);
+  if (!claims || !claims.scope.includes(required))
+    throw new Error("Invalid feature flag delegation");
+  return {
+    owner: claims.email,
+    orgId: claims.orgId,
+    anonymous: false,
+    delegationJti: claims.jti,
+    delegationIssuer: claims.issuer,
+  } as ActionRouteResolvedCaller;
+}
+
 export function parseActionSearchParams(
   searchParams: URLSearchParams,
 ): Record<string, any> {
@@ -189,6 +215,9 @@ export type ActionRouteResolvedCaller = AgentRunOwnerContext & {
    * must not leak into the token caller's request context.
    */
   orgId?: string;
+  /** Verified A2A correlation and issuer metadata for the audit row. */
+  delegationJti?: string;
+  delegationIssuer?: string;
 };
 
 export interface ActionRouteAuthAdapter {
@@ -336,10 +365,14 @@ export function mountActionRoutes(
         // through, so a live same-origin session cookie can't silently execute
         // the request as the logged-in user.
         let resolvedCaller: ActionRouteResolvedCaller | null = null;
-        if (options?.actionRouteAuth?.resolveCaller) {
+        {
           let caller: ActionRouteResolvedCaller | null;
           try {
-            caller = await options.actionRouteAuth.resolveCaller(event);
+            caller = options?.actionRouteAuth?.resolveCaller
+              ? await options.actionRouteAuth.resolveCaller(event)
+              : null;
+            if (!caller)
+              caller = await resolveFeatureFlagA2ACaller(event, name);
           } catch {
             throw createError({
               statusCode: 401,
@@ -463,14 +496,23 @@ export function mountActionRoutes(
             // userEmail / orgId mirror the request context resolved above (do
             // NOT inject a dev identity — leave undefined when unauthenticated).
             try {
-              const caller = isFrontendActionRequest(event)
-                ? "frontend"
-                : "http";
+              const caller = resolvedCaller
+                ? "a2a"
+                : isFrontendActionRequest(event)
+                  ? "frontend"
+                  : "http";
               const result = await entry.run(params, {
                 userEmail,
                 orgId: orgId ?? null,
                 caller,
                 actionName: name,
+                ...(resolvedCaller?.delegationJti
+                  ? {
+                      networkProtocol: "a2a",
+                      networkId: resolvedCaller.delegationJti,
+                      networkPeer: resolvedCaller.delegationIssuer,
+                    }
+                  : {}),
               });
 
               // Auto-refresh the UI after a successful mutating action. GET

package/corpus/core/src/server/index.ts

@@ -180,6 +180,7 @@ export { createSentryPlugin, defaultSentryPlugin } from "./sentry-plugin.js";
 // (which references "defaultOrgPlugin" from @agent-native/core/server) can
 // resolve it during the deploy build worker-entry generation.
 export { createOrgPlugin, defaultOrgPlugin } from "../org/plugin.js";
+export { createFeatureFlagsPlugin } from "../feature-flags/plugin.js";
 export {
   createContextXrayPlugin,
   defaultContextXrayPlugin,

package/corpus/core/src/settings/org-settings.ts

@@ -10,6 +10,7 @@
 
 import {
   getSetting,
+  mutateSetting,
   putSetting,
   deleteSetting,
   getAllSettings,
@@ -40,6 +41,18 @@ export async function putOrgSetting(
   return putSetting(orgKey(orgId, key), value, options);
 }
 
+/** Atomically derive and persist an org-scoped setting. */
+export async function mutateOrgSetting(
+  orgId: string,
+  key: string,
+  updater: (
+    current: Record<string, unknown> | null,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>,
+  options?: StoreWriteOptions,
+): Promise<Record<string, unknown>> {
+  return mutateSetting(orgKey(orgId, key), updater, options);
+}
+
 /** Delete an org-scoped setting. */
 export async function deleteOrgSetting(
   orgId: string,

package/corpus/core/src/settings/store.ts

@@ -128,6 +128,63 @@ export interface StoreWriteOptions {
   requestSource?: string;
 }
 
+const SETTINGS_MUTATION_ATTEMPTS = 25;
+
+/**
+ * Atomically derive and persist one setting with an optimistic raw-value CAS.
+ * This works across SQLite/libSQL and Postgres and remains safe across
+ * horizontally scaled processes where an in-memory mutex would not.
+ * The updater may run more than once after contention and must not perform
+ * external side effects.
+ */
+export async function mutateSetting(
+  key: string,
+  updater: (
+    current: Record<string, unknown> | null,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>,
+  options?: StoreWriteOptions,
+): Promise<Record<string, unknown>> {
+  await ensureTable();
+  const client = getDbExec();
+  const table = settingsTable();
+  for (let attempt = 0; attempt < SETTINGS_MUTATION_ATTEMPTS; attempt += 1) {
+    // Deliberately bypass the request cache: a failed CAS means another
+    // request committed a newer value and the next attempt must reread it.
+    const snapshot = await client.execute({
+      sql: `SELECT value FROM ${table} WHERE key = ?`,
+      args: [key],
+    });
+    const raw =
+      snapshot.rows.length === 0 ? null : (snapshot.rows[0]?.value as string);
+    const current = raw == null ? null : JSON.parse(raw);
+    const next = await updater(current);
+    const nextRaw = JSON.stringify(next);
+    const timestamp = Date.now();
+    const result =
+      raw == null
+        ? await client.execute({
+            sql: isPostgres()
+              ? `INSERT INTO ${table} (key, value, updated_at) VALUES (?, ?, ?) ON CONFLICT (key) DO NOTHING`
+              : `INSERT OR IGNORE INTO ${table} (key, value, updated_at) VALUES (?, ?, ?)`,
+            args: [key, nextRaw, timestamp],
+          })
+        : await client.execute({
+            sql: `UPDATE ${table} SET value = ?, updated_at = ? WHERE key = ? AND value = ?`,
+            args: [nextRaw, timestamp, key, raw],
+          });
+    if (result.rowsAffected === 0) continue;
+    requestSettingsCache()?.set(key, nextRaw);
+    _emitter.emit("settings", {
+      source: "settings",
+      type: "change",
+      key,
+      ...(options?.requestSource && { requestSource: options.requestSource }),
+    });
+    return JSON.parse(nextRaw);
+  }
+  throw new Error(`Setting ${key} changed too many times; retry the mutation.`);
+}
+
 export async function putSetting(
   key: string,
   value: Record<string, unknown>,

package/corpus/core/src/templates/default/.agents/skills/feature-flags/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: feature-flags
+description: >-
+  Declare, evaluate, manage, and remove framework feature flags. Use when
+  shipping a capability gradually, targeting users or organizations, or
+  replacing a compile-time rollout switch with a production-safe runtime flag.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Feature Flags
+
+A feature flag is a boolean declared in app code, evaluated locally by Core,
+and managed from the Analytics fleet control plane. Code owns whether a flag
+exists. Runtime settings own only its rollout state.
+
+Flags let an app deploy dormant code and turn it on in the real environment
+without another deployment. They are not experiments: do not add variants,
+hypotheses, conversion metrics, exposure tracking, or lifecycle states.
+
+## When to use one
+
+Use a flag for a reversible rollout of a user-facing capability whose dormant
+code is safe to deploy. Flags are useful for production dogfooding, exact-user
+or organization pilots, and deterministic percentage rollouts.
+
+Do not use a flag for authentication, authorization, secrets, audit enablement,
+SSR cache behavior, or another security boundary. Client hiding is presentation
+only; every guarded server action must evaluate the same registered flag.
+
+## Agent workflow
+
+### 1. Declare
+
+Keep definitions in a shared TypeScript module so server and client code use the
+same stable key. Flags are boolean and default-off.
+
+```ts
+import { defineFeatureFlag } from "@agent-native/core/feature-flags";
+
+export const FULL_APP_BUILDING = defineFeatureFlag({
+  key: "full-app-building",
+  displayName: "Full app building",
+  description: "Create and edit Fusion-backed applications.",
+});
+```
+
+Keys are immutable, never reused, and contain only letters, numbers, dots,
+underscores, or hyphens. Prefer a concise app-owned name. Do not create flag
+definitions or rollout rows from Analytics.
+
+### 2. Register
+
+Register app definitions from a Nitro plugin before actions are discovered.
+Do not add app-specific flags to a Core registry.
+
+```ts
+import { createFeatureFlagsPlugin } from "@agent-native/core/server";
+
+import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
+
+export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });
+```
+
+### 3. Guard server and client
+
+The server action is the enforcement boundary:
+
+```ts
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
+
+run: async (args, ctx) => {
+  if (!(await isFeatureFlagEnabled(FULL_APP_BUILDING, ctx))) {
+    throw new Error("Full app building is not enabled for this account.");
+  }
+  // guarded operation
+}
+```
+
+Use the client hook only to hide or reveal hydrated UI:
+
+```tsx
+import { useFeatureFlag } from "@agent-native/core/client";
+
+const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
+return enabled ? <FullAppOption /> : null;
+```
+
+The client hook intentionally returns false while loading or for an unknown
+flag. Never replace that fail-closed behavior with app-local bucketing or a
+compile-time fallback. Never evaluate personalized flags in the public SSR
+shell; it is shared and cached for every visitor.
+
+### 4. Verify and roll out
+
+1. Verify the off path before changing rollout state.
+2. Confirm the registered flag appears in **Analytics → Feature flags** for the
+   app and is Off by default.
+3. Use **Enable for me** for initial production dogfood.
+4. Expand to exact emails, organization IDs, or a percentage only from
+   Analytics.
+5. Confirm the client presentation and authoritative server action agree.
+
+## Management contract
+
+Core mounts three actions in registered apps:
+
+| Action | Purpose |
+| --- | --- |
+| `get-feature-flags` | Return the current caller's evaluated boolean values. |
+| `list-feature-flags` | Return definitions and rollout metadata to an authorized operator. |
+| `set-feature-flag` | Atomically turn a flag off, enable it for the operator, or replace targeting rules. |
+
+Analytics calls the app-local operator actions through narrowly scoped A2A
+delegation. Tokens require an exact audience, organization, scope, operator
+role, and audit correlation id. Management is permission-checked and audited
+by the target app. Never manage flags through generic settings routes, raw SQL,
+or per-app toggle UIs.
+
+## Rollout semantics
+
+The operator modes are **Off**, **Targeted**, and **Everyone**. Core stores them
+as `off`, `rules`, and `on`.
+
+Targeted rules combine exact normalized emails, exact organization IDs, and a
+percentage with OR semantics. Exact matches are checked first. Percentage
+buckets use Core's stable hash of the flag key and authenticated user identity;
+anonymous callers fail closed. Raising a percentage preserves the users already
+included at a lower percentage. Do not implement bucketing in app code.
+
+Unknown definitions, missing state, malformed state, storage errors, and
+evaluation errors all return the code default (`false` in v1). Explicit Off
+wins over every target; Everyone enables every authenticated caller.
+
+## Remove a flag
+
+After a rollout is permanent:
+
+1. Replace guarded branches with the chosen behavior.
+2. Delete the server and client gates.
+3. Delete the definition and registration entry.
+4. Verify the flag disappears from the Analytics fleet.
+5. Remove stale tests and rollout instructions.
+
+A permanent flag is just an if statement with a pension plan.
+
+## Verification checklist
+
+- Unknown and unregistered keys evaluate false.
+- UI hiding and server enforcement use the same registered key.
+- Exact-user, organization, deterministic percentage, Everyone, and Off paths
+  have focused tests.
+- Increasing a percentage is monotonic; anonymous percentage evaluation is off.
+- Unauthorized callers cannot list targeting details or mutate flags.
+- Mutations are atomic, read back stored state, emit refresh, and appear in the
+  audit log with the flag key.
+- Analytics represents ready, no-definition, unsupported, forbidden, legacy,
+  and unreachable directory apps honestly.
+- Future agents can find this skill from root `AGENTS.md`, and
+  `pnpm guard:workspace-skills` passes after syncing generated copies.
+
+## Related skills
+
+- **adding-a-feature** — preserve UI/action/instruction/application-state parity
+- **actions** — define and call guarded app operations
+- **audit-log** — inspect automatic action mutation history
+- **reliable-mutations** — make rollout changes atomic and provable
+- **security** — keep security controls out of feature flags

package/corpus/core/src/templates/default/AGENTS.md

@@ -158,6 +158,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 | ---------------------- | --------------------------------------------------------------------------------- |
 | `agent-native-docs`    | Before using advanced Agent Native framework APIs or generated-app features       |
 | `adding-a-feature`     | **Read first when adding ANY new feature** — the four-area parity checklist       |
+| `feature-flags`        | Before shipping a staged production rollout or replacing a compile-time switch    |
 | `real-time-sync`       | Before wiring data fetching for anything the agent can mutate (must auto-refresh) |
 | `storing-data`         | Before storing or reading any app state                                           |
 | `internationalization` | Before adding or editing visible UI copy, prompts, toasts, labels, or formatting  |

package/corpus/core/src/templates/headless/.agents/skills/feature-flags/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: feature-flags
+description: >-
+  Declare, evaluate, manage, and remove framework feature flags. Use when
+  shipping a capability gradually, targeting users or organizations, or
+  replacing a compile-time rollout switch with a production-safe runtime flag.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Feature Flags
+
+A feature flag is a boolean declared in app code, evaluated locally by Core,
+and managed from the Analytics fleet control plane. Code owns whether a flag
+exists. Runtime settings own only its rollout state.
+
+Flags let an app deploy dormant code and turn it on in the real environment
+without another deployment. They are not experiments: do not add variants,
+hypotheses, conversion metrics, exposure tracking, or lifecycle states.
+
+## When to use one
+
+Use a flag for a reversible rollout of a user-facing capability whose dormant
+code is safe to deploy. Flags are useful for production dogfooding, exact-user
+or organization pilots, and deterministic percentage rollouts.
+
+Do not use a flag for authentication, authorization, secrets, audit enablement,
+SSR cache behavior, or another security boundary. Client hiding is presentation
+only; every guarded server action must evaluate the same registered flag.
+
+## Agent workflow
+
+### 1. Declare
+
+Keep definitions in a shared TypeScript module so server and client code use the
+same stable key. Flags are boolean and default-off.
+
+```ts
+import { defineFeatureFlag } from "@agent-native/core/feature-flags";
+
+export const FULL_APP_BUILDING = defineFeatureFlag({
+  key: "full-app-building",
+  displayName: "Full app building",
+  description: "Create and edit Fusion-backed applications.",
+});
+```
+
+Keys are immutable, never reused, and contain only letters, numbers, dots,
+underscores, or hyphens. Prefer a concise app-owned name. Do not create flag
+definitions or rollout rows from Analytics.
+
+### 2. Register
+
+Register app definitions from a Nitro plugin before actions are discovered.
+Do not add app-specific flags to a Core registry.
+
+```ts
+import { createFeatureFlagsPlugin } from "@agent-native/core/server";
+
+import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
+
+export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });
+```
+
+### 3. Guard server and client
+
+The server action is the enforcement boundary:
+
+```ts
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
+
+run: async (args, ctx) => {
+  if (!(await isFeatureFlagEnabled(FULL_APP_BUILDING, ctx))) {
+    throw new Error("Full app building is not enabled for this account.");
+  }
+  // guarded operation
+}
+```
+
+Use the client hook only to hide or reveal hydrated UI:
+
+```tsx
+import { useFeatureFlag } from "@agent-native/core/client";
+
+const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
+return enabled ? <FullAppOption /> : null;
+```
+
+The client hook intentionally returns false while loading or for an unknown
+flag. Never replace that fail-closed behavior with app-local bucketing or a
+compile-time fallback. Never evaluate personalized flags in the public SSR
+shell; it is shared and cached for every visitor.
+
+### 4. Verify and roll out
+
+1. Verify the off path before changing rollout state.
+2. Confirm the registered flag appears in **Analytics → Feature flags** for the
+   app and is Off by default.
+3. Use **Enable for me** for initial production dogfood.
+4. Expand to exact emails, organization IDs, or a percentage only from
+   Analytics.
+5. Confirm the client presentation and authoritative server action agree.
+
+## Management contract
+
+Core mounts three actions in registered apps:
+
+| Action | Purpose |
+| --- | --- |
+| `get-feature-flags` | Return the current caller's evaluated boolean values. |
+| `list-feature-flags` | Return definitions and rollout metadata to an authorized operator. |
+| `set-feature-flag` | Atomically turn a flag off, enable it for the operator, or replace targeting rules. |
+
+Analytics calls the app-local operator actions through narrowly scoped A2A
+delegation. Tokens require an exact audience, organization, scope, operator
+role, and audit correlation id. Management is permission-checked and audited
+by the target app. Never manage flags through generic settings routes, raw SQL,
+or per-app toggle UIs.
+
+## Rollout semantics
+
+The operator modes are **Off**, **Targeted**, and **Everyone**. Core stores them
+as `off`, `rules`, and `on`.
+
+Targeted rules combine exact normalized emails, exact organization IDs, and a
+percentage with OR semantics. Exact matches are checked first. Percentage
+buckets use Core's stable hash of the flag key and authenticated user identity;
+anonymous callers fail closed. Raising a percentage preserves the users already
+included at a lower percentage. Do not implement bucketing in app code.
+
+Unknown definitions, missing state, malformed state, storage errors, and
+evaluation errors all return the code default (`false` in v1). Explicit Off
+wins over every target; Everyone enables every authenticated caller.
+
+## Remove a flag
+
+After a rollout is permanent:
+
+1. Replace guarded branches with the chosen behavior.
+2. Delete the server and client gates.
+3. Delete the definition and registration entry.
+4. Verify the flag disappears from the Analytics fleet.
+5. Remove stale tests and rollout instructions.
+
+A permanent flag is just an if statement with a pension plan.
+
+## Verification checklist
+
+- Unknown and unregistered keys evaluate false.
+- UI hiding and server enforcement use the same registered key.
+- Exact-user, organization, deterministic percentage, Everyone, and Off paths
+  have focused tests.
+- Increasing a percentage is monotonic; anonymous percentage evaluation is off.
+- Unauthorized callers cannot list targeting details or mutate flags.
+- Mutations are atomic, read back stored state, emit refresh, and appear in the
+  audit log with the flag key.
+- Analytics represents ready, no-definition, unsupported, forbidden, legacy,
+  and unreachable directory apps honestly.
+- Future agents can find this skill from root `AGENTS.md`, and
+  `pnpm guard:workspace-skills` passes after syncing generated copies.
+
+## Related skills
+
+- **adding-a-feature** — preserve UI/action/instruction/application-state parity
+- **actions** — define and call guarded app operations
+- **audit-log** — inspect automatic action mutation history
+- **reliable-mutations** — make rollout changes atomic and provable
+- **security** — keep security controls out of feature flags