@agent-native/core 0.164.1 → 0.164.3

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 8442
+- template files: 8445

package/corpus/templates/analytics/app/components/agents/FeatureFlagsFleetPanel.tsx

@@ -9,7 +9,7 @@ import {
 } from "@agent-native/core/client/hooks";
 import { useT } from "@agent-native/core/client/i18n";
 import { IconRefresh } from "@tabler/icons-react";
-import { useQueryClient } from "@tanstack/react-query";
+import { type QueryClient, useQueryClient } from "@tanstack/react-query";
 
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -40,6 +40,51 @@ export interface FlagDirectory {
   apps?: FlagApp[];
 }
 
+interface VerifiedFlagMutation {
+  contractVersion: 3;
+  status: "verified";
+  key: string;
+  rules: FeatureFlagMetadata["rules"];
+  enabledForCurrentUser: boolean;
+}
+
+export function reconcileVerifiedFleetMutation(
+  value: unknown,
+  targetAppId: string,
+  verified: VerifiedFlagMutation,
+): FlagDirectory {
+  const data = asDirectory(value);
+  return {
+    ...data,
+    apps: data.apps?.map((app) =>
+      appId(app) !== targetAppId
+        ? app
+        : {
+            ...app,
+            flags: app.flags?.map((flag) =>
+              flag.key === verified.key
+                ? {
+                    ...flag,
+                    rules: verified.rules,
+                    enabledForCurrentUser: verified.enabledForCurrentUser,
+                  }
+                : flag,
+            ),
+          },
+    ),
+  };
+}
+
+export function recoverFleetMutationFailure(
+  client: QueryClient,
+  context?: { previous: unknown; key: readonly unknown[] },
+) {
+  if (context) client.setQueryData(context.key, context.previous);
+  void client.invalidateQueries({
+    queryKey: ["action", "list-workspace-feature-flags"],
+  });
+}
+
 function asDirectory(value: unknown): FlagDirectory {
   return value && typeof value === "object" ? (value as FlagDirectory) : {};
 }
@@ -76,9 +121,10 @@ export function FeatureFlagsFleetPanel() {
     { retry: false },
   );
   const mutation = useActionMutation<
-    unknown,
+    VerifiedFlagMutation | unknown,
     { appId: string } & SetFeatureFlagInput
   >("set-workspace-feature-flag", {
+    skipActionQueryInvalidation: true,
     onMutate: async (input) => {
       await client.cancelQueries({
         queryKey: ["action", "list-workspace-feature-flags"],
@@ -119,13 +165,25 @@ export function FeatureFlagsFleetPanel() {
       });
       return { previous, key };
     },
-    onError: (_error, _input, context: any) => {
-      if (context) client.setQueryData(context.key, context.previous);
+    onError: (_error, _input, context: any) =>
+      recoverFleetMutationFailure(client, context),
+    onSuccess: (result, input, context: any) => {
+      if (
+        !result ||
+        typeof result !== "object" ||
+        (result as Partial<VerifiedFlagMutation>).contractVersion !== 3 ||
+        (result as Partial<VerifiedFlagMutation>).status !== "verified"
+      ) {
+        void client.invalidateQueries({
+          queryKey: ["action", "list-workspace-feature-flags"],
+        });
+        return;
+      }
+      const verified = result as VerifiedFlagMutation;
+      client.setQueryData(context.key, (old: unknown) =>
+        reconcileVerifiedFleetMutation(old, input.appId, verified),
+      );
     },
-    onSettled: () =>
-      void client.invalidateQueries({
-        queryKey: ["action", "list-workspace-feature-flags"],
-      }),
   });
   const directory = asDirectory(flags.data);
   const apps = directory.apps ?? [];
@@ -134,7 +192,11 @@ export function FeatureFlagsFleetPanel() {
     return (
       <StatusState
         title={t("agents.flagsUnavailable")}
-        detail={flags.error?.message || t("agents.flagsUnreachable")}
+        detail={
+          mutation.error?.message ||
+          flags.error?.message ||
+          t("agents.flagsUnreachable")
+        }
         onRetry={() => void flags.refetch()}
       />
     );
@@ -179,22 +241,19 @@ export function FeatureFlagsFleetPanel() {
           </div>
           {isReady(app) ? (
             <div className="p-4">
+              {mutation.variables?.appId === appId(app) && mutation.error ? (
+                <p className="mb-3 text-sm text-destructive">
+                  {mutation.error.message}
+                </p>
+              ) : null}
               <FeatureFlagsEditor
                 flags={(app.flags ?? []).filter(
                   (flag): flag is FeatureFlagMetadata =>
                     !!flag.rules && typeof flag.defaultValue === "boolean",
                 )}
                 isPending={mutation.isPending}
-                error={
-                  mutation.variables?.appId === appId(app)
-                    ? mutation.error
-                    : null
-                }
-                errorFlagKey={
-                  mutation.variables?.appId === appId(app)
-                    ? mutation.variables.key
-                    : null
-                }
+                error={null}
+                errorFlagKey={null}
                 showHeader={false}
                 onMutate={(input) =>
                   mutation.mutate(qualifyFleetMutation(appId(app), input))

package/corpus/templates/analytics/app/lib/use-auto-focus-select.ts

@@ -1,9 +1,9 @@
 import { useEffect, useRef, type RefObject } from "react";
 
-/** Focus an input and select its existing value after the next paint. */
-export function useAutoFocusSelect<T extends HTMLInputElement>(
-  enabled: boolean,
-): RefObject<T | null> {
+/** Focus an input/textarea and select its existing value after the next paint. */
+export function useAutoFocusSelect<
+  T extends HTMLInputElement | HTMLTextAreaElement,
+>(enabled: boolean): RefObject<T | null> {
   const inputRef = useRef<T | null>(null);
 
   useEffect(() => {

package/corpus/templates/analytics/app/pages/adhoc/explorer-dashboard/index.tsx

@@ -93,6 +93,7 @@ import {
   resourceCanManage,
   type ResourceAccess,
 } from "@/lib/resource-access";
+import { useAutoFocusSelect } from "@/lib/use-auto-focus-select";
 
 import { DashboardSkeleton } from "../DashboardSkeleton";
 import { DashboardChartCard } from "./ChartCard";
@@ -206,6 +207,7 @@ export default function ExplorerDashboardPage() {
   );
   const [editingName, setEditingName] = useState(false);
   const [nameInput, setNameInput] = useState("");
+  const nameInputRef = useAutoFocusSelect<HTMLInputElement>(editingName);
   const [addChartOpen, setAddChartOpen] = useState(false);
   const [loaded, setLoaded] = useState(false);
   const [confirmDeleteOpen, setConfirmDeleteOpen] = useState(false);
@@ -635,6 +637,7 @@ export default function ExplorerDashboardPage() {
           ) : null}
           {editingName && canEdit ? (
             <Input
+              ref={nameInputRef}
               value={nameInput}
               onChange={(e) => setNameInput(e.target.value)}
               onBlur={handleSaveName}

package/corpus/templates/analytics/app/pages/adhoc/sql-dashboard/index.tsx

@@ -129,6 +129,7 @@ import {
   resourceCanManage,
   type ResourceAccess,
 } from "@/lib/resource-access";
+import { useAutoFocusSelect } from "@/lib/use-auto-focus-select";
 
 import BlankDashboard from "../BlankDashboard";
 import { DashboardSkeleton } from "../DashboardSkeleton";
@@ -598,8 +599,11 @@ function SqlDashboardPageContent({
   );
   const [editingName, setEditingName] = useState(false);
   const [nameInput, setNameInput] = useState("");
+  const nameInputRef = useAutoFocusSelect<HTMLInputElement>(editingName);
   const [editingDescription, setEditingDescription] = useState(false);
   const [descriptionInput, setDescriptionInput] = useState("");
+  const descriptionInputRef =
+    useAutoFocusSelect<HTMLTextAreaElement>(editingDescription);
   const [loaded, setLoaded] = useState(false);
   const [confirmDeleteOpen, setConfirmDeleteOpen] = useState(false);
   const [openDeleteAfterMenuClose, setOpenDeleteAfterMenuClose] =
@@ -1734,6 +1738,7 @@ function SqlDashboardPageContent({
       <div className="flex min-w-0 items-center gap-2">
         {editingName && canEdit ? (
           <Input
+            ref={nameInputRef}
             value={nameInput}
             onChange={(e) => setNameInput(e.target.value)}
             onBlur={handleSaveName}
@@ -2159,6 +2164,7 @@ function SqlDashboardPageContent({
       {/* Description (click to edit) */}
       {editingDescription && canEdit ? (
         <Textarea
+          ref={descriptionInputRef}
           value={descriptionInput}
           onChange={(e) => setDescriptionInput(e.target.value)}
           onBlur={handleSaveDescription}

package/corpus/templates/analytics/app/routes/_index.tsx

@@ -1,3 +1,4 @@
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { redirect, type LoaderFunctionArgs } from "react-router";
 
 const SEO_TITLE =
@@ -25,11 +26,11 @@ function target(url: URL): string {
 }
 
 export function loader({ url }: LoaderFunctionArgs) {
-  throw redirect(target(url));
+  throw withSsrHtmlContentType(redirect(target(url)), { varyByQuery: true });
 }
 
 export function clientLoader({ url }: LoaderFunctionArgs) {
-  throw redirect(target(url));
+  throw withSsrHtmlContentType(redirect(target(url)), { varyByQuery: true });
 }
 
 export default function IndexRoute() {

package/corpus/templates/analytics/app/routes/adhoc.$id.tsx

@@ -1,3 +1,4 @@
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { redirect, type LoaderFunctionArgs } from "react-router";
 
 // `/adhoc/:id` is the legacy dashboard URL. The canonical, user-facing URL is
@@ -9,11 +10,15 @@ function target({ params, url }: LoaderFunctionArgs): string {
 }
 
 export function loader(args: LoaderFunctionArgs) {
-  throw redirect(target(args));
+  throw withSsrHtmlContentType(redirect(target(args)), {
+    varyByQuery: true,
+  });
 }
 
 export function clientLoader(args: LoaderFunctionArgs) {
-  throw redirect(target(args));
+  throw withSsrHtmlContentType(redirect(target(args)), {
+    varyByQuery: true,
+  });
 }
 
 export default function AdhocRedirectRoute() {

package/corpus/templates/analytics/app/routes/dashboard.tsx

@@ -1,3 +1,4 @@
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { redirect, type LoaderFunctionArgs } from "react-router";
 
 function target(url: URL): string {
@@ -5,11 +6,11 @@ function target(url: URL): string {
 }
 
 export function loader({ url }: LoaderFunctionArgs) {
-  throw redirect(target(url));
+  throw withSsrHtmlContentType(redirect(target(url)), { varyByQuery: true });
 }
 
 export function clientLoader({ url }: LoaderFunctionArgs) {
-  throw redirect(target(url));
+  throw withSsrHtmlContentType(redirect(target(url)), { varyByQuery: true });
 }
 
 export default function DashboardAliasRoute() {

package/corpus/templates/analytics/app/routes/overview.tsx

@@ -1,3 +1,4 @@
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { redirect, type LoaderFunctionArgs } from "react-router";
 
 function target(url: URL): string {
@@ -5,11 +6,11 @@ function target(url: URL): string {
 }
 
 export function loader({ url }: LoaderFunctionArgs) {
-  throw redirect(target(url));
+  throw withSsrHtmlContentType(redirect(target(url)), { varyByQuery: true });
 }
 
 export function clientLoader({ url }: LoaderFunctionArgs) {
-  throw redirect(target(url));
+  throw withSsrHtmlContentType(redirect(target(url)), { varyByQuery: true });
 }
 
 export default function OverviewAliasRoute() {

package/corpus/templates/analytics/app/routes/traffic.tsx

@@ -1,3 +1,4 @@
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { redirect, type LoaderFunctionArgs } from "react-router";
 
 const TRAFFIC_DASHBOARD_PATH = "/dashboards/agent-native-templates-first-party";
@@ -7,11 +8,11 @@ function target(url: URL): string {
 }
 
 export function loader({ url }: LoaderFunctionArgs) {
-  throw redirect(target(url));
+  throw withSsrHtmlContentType(redirect(target(url)), { varyByQuery: true });
 }
 
 export function clientLoader({ url }: LoaderFunctionArgs) {
-  throw redirect(target(url));
+  throw withSsrHtmlContentType(redirect(target(url)), { varyByQuery: true });
 }
 
 export default function TrafficDashboardAliasRoute() {

package/corpus/templates/analytics/changelog/2026-08-18-verify-cross-app-feature-flag-changes.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-18
+---
+
+Feature flag changes now preserve actionable failures and verify the target app's persisted state.

package/corpus/templates/analytics/server/lib/workspace-feature-flags.ts

@@ -1,9 +1,11 @@
 import { randomUUID } from "node:crypto";
 
 import { signA2AToken } from "@agent-native/core/a2a";
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
 import { fetchOrgApps, type OrgApp } from "@agent-native/core/mcp";
 import { getOrgDomain } from "@agent-native/core/org";
 
+import { VERIFIED_FLEET_FLAG_MUTATIONS } from "../../shared/feature-flags.js";
 import type { AnalyticsAdminContext } from "./db-admin-connections.js";
 
 const TARGET_TIMEOUT_MS = 3_000;
@@ -31,7 +33,16 @@ export interface WorkspaceFeatureFlagsResult {
   apps: FleetFlagApp[];
 }
 
-export interface WorkspaceFeatureFlagMutationResult {
+export interface VerifiedWorkspaceFeatureFlagMutationResult {
+  contractVersion: 3;
+  status: "verified";
+  key: string;
+  rules: Record<string, unknown>;
+  scope: { orgId: string | null; orgDomain: string | null };
+  enabledForCurrentUser: boolean;
+}
+
+interface TargetFeatureFlagMutationResult {
   contractVersion: 2;
   status: "ready";
   key: string;
@@ -39,6 +50,10 @@ export interface WorkspaceFeatureFlagMutationResult {
   scope: { orgId: string | null; orgDomain: string | null };
 }
 
+export type WorkspaceFeatureFlagMutationResult =
+  | TargetFeatureFlagMutationResult
+  | VerifiedWorkspaceFeatureFlagMutationResult;
+
 export interface WorkspaceFeatureFlagMutationInput {
   appId: string;
   key: string;
@@ -72,8 +87,8 @@ export function validateWorkspaceFeatureFlagMutation(
     rules?: Record<string, unknown>;
     enabledForEmail?: string;
   },
-): WorkspaceFeatureFlagMutationResult {
-  const payload = body as Partial<WorkspaceFeatureFlagMutationResult> | null;
+): TargetFeatureFlagMutationResult {
+  const payload = body as Partial<TargetFeatureFlagMutationResult> | null;
   const valid =
     payload?.contractVersion === 2 &&
     payload.status === "ready" &&
@@ -144,7 +159,7 @@ export function validateWorkspaceFeatureFlagMutation(
         "The target app did not enable the feature flag for the delegated operator.",
       );
   }
-  return payload as WorkspaceFeatureFlagMutationResult;
+  return payload as TargetFeatureFlagMutationResult;
 }
 
 function targetOrigin(app: OrgApp): string {
@@ -173,6 +188,39 @@ async function delegatedToken(
   }
 }
 
+export type WorkspaceFeatureFlagFailurePhase =
+  | "directory"
+  | "token-generation"
+  | "timeout"
+  | "network"
+  | "authorization"
+  | "unsupported-target"
+  | "target-action"
+  | "persistence"
+  | "verification";
+
+const FAILURE_MESSAGES: Record<WorkspaceFeatureFlagFailurePhase, string> = {
+  directory: "The organization app directory could not resolve this target.",
+  "token-generation":
+    "Analytics could not create delegated feature flag authority.",
+  timeout: "The target app timed out before the feature flag change completed.",
+  network: "Analytics could not reach the target app.",
+  authorization: "The target app denied this delegated flag operation.",
+  "unsupported-target":
+    "The target app does not support feature flag management.",
+  "target-action": "The target app could not complete the feature flag action.",
+  persistence:
+    "The target app did not persist the requested feature flag rules.",
+  verification: "Analytics could not verify the persisted feature flag change.",
+};
+
+export class WorkspaceFeatureFlagFailure extends Error {
+  constructor(readonly phase: WorkspaceFeatureFlagFailurePhase) {
+    super(`[${phase}] ${FAILURE_MESSAGES[phase]}`);
+    this.name = "WorkspaceFeatureFlagFailure";
+  }
+}
+
 type TargetFailureReason = "token-generation" | "timeout" | "network";
 
 class TargetCallFailure extends Error {
@@ -194,6 +242,30 @@ export function classifyWorkspaceFeatureFlagTargetFailure(
   return "network";
 }
 
+function targetFailure(error: unknown): WorkspaceFeatureFlagFailure {
+  const reason = classifyWorkspaceFeatureFlagTargetFailure(error);
+  return new WorkspaceFeatureFlagFailure(reason);
+}
+
+async function resolveTargetApp(
+  admin: AnalyticsAdminContext,
+  appId: string,
+): Promise<OrgApp> {
+  let apps: OrgApp[];
+  try {
+    apps = await fetchOrgApps({
+      selfId: "analytics",
+      includeDirectoryApp: true,
+      serviceOrgId: admin.orgId,
+    });
+  } catch {
+    throw new WorkspaceFeatureFlagFailure("directory");
+  }
+  const app = apps.find((candidate) => candidate.id === appId);
+  if (!app) throw new WorkspaceFeatureFlagFailure("directory");
+  return app;
+}
+
 async function callTarget(
   app: OrgApp,
   admin: AnalyticsAdminContext,
@@ -326,63 +398,139 @@ export async function setWorkspaceFeatureFlag(
   admin: AnalyticsAdminContext,
   input: WorkspaceFeatureFlagMutationInput,
 ): Promise<WorkspaceFeatureFlagMutationResult> {
-  const apps = await fetchOrgApps({
-    selfId: "analytics",
-    includeDirectoryApp: true,
-    serviceOrgId: admin.orgId,
-  });
-  const app = apps.find((candidate) => candidate.id === input.appId);
-  if (!app)
-    throw new Error(
-      "The requested app is not available in this organization directory.",
-    );
+  const app = await resolveTargetApp(admin, input.appId);
   const targetInput = workspaceFeatureFlagTargetInput(input);
   let orgDomain: string | undefined;
   try {
     orgDomain = (await getOrgDomain(admin.orgId))?.trim().toLowerCase();
   } catch {
-    throw new TargetCallFailure("token-generation");
+    throw new WorkspaceFeatureFlagFailure("token-generation");
+  }
+  if (!orgDomain) throw new WorkspaceFeatureFlagFailure("token-generation");
+  let result: Awaited<ReturnType<typeof callTarget>>;
+  try {
+    result = await callTarget(
+      app,
+      admin,
+      "set-feature-flag",
+      targetInput,
+      orgDomain,
+    );
+  } catch (error) {
+    throw targetFailure(error);
   }
-  if (!orgDomain) throw new TargetCallFailure("token-generation");
-  const result = await callTarget(
-    app,
-    admin,
-    "set-feature-flag",
-    targetInput,
-    orgDomain,
-  );
   if (result.status === 401 || result.status === 403)
-    throw new Error("The target app denied this delegated flag operation.");
+    throw new WorkspaceFeatureFlagFailure("authorization");
   if (result.status === 404 || result.status === 405)
-    throw new Error("The target app does not support feature flag management.");
+    throw new WorkspaceFeatureFlagFailure("unsupported-target");
   if (result.status < 200 || result.status >= 300)
-    throw new Error(
-      "The target app could not persist the feature flag change.",
-    );
-  return validateWorkspaceFeatureFlagMutation(result.body, {
-    key: input.key,
-    orgDomain,
-    allowExplicitNoOrgTarget: true,
-    ...(input.operation === "replace-rules" && input.rules
-      ? {
-          rules: {
-            mode: input.rules.mode,
-            emails: input.rules.emails ?? [],
-            orgIds: input.rules.orgIds ?? [],
-            percentage: input.rules.percentage ?? 0,
-          },
-        }
-      : input.operation === "off"
+    throw new WorkspaceFeatureFlagFailure("target-action");
+  let mutation: TargetFeatureFlagMutationResult;
+  try {
+    mutation = validateWorkspaceFeatureFlagMutation(result.body, {
+      key: input.key,
+      orgDomain,
+      allowExplicitNoOrgTarget: true,
+      ...(input.operation === "replace-rules" && input.rules
         ? {
             rules: {
-              mode: "off",
-              emails: [],
-              orgIds: [],
-              percentage: 0,
+              mode: input.rules.mode,
+              emails: input.rules.emails ?? [],
+              orgIds: input.rules.orgIds ?? [],
+              percentage: input.rules.percentage ?? 0,
             },
           }
-        : { enabledForEmail: admin.userEmail }),
-  });
+        : input.operation === "off"
+          ? {
+              rules: {
+                mode: "off",
+                emails: [],
+                orgIds: [],
+                percentage: 0,
+              },
+            }
+          : { enabledForEmail: admin.userEmail }),
+    });
+  } catch {
+    throw new WorkspaceFeatureFlagFailure("persistence");
+  }
+
+  if (
+    !(await isFeatureFlagEnabled(VERIFIED_FLEET_FLAG_MUTATIONS, {
+      userEmail: admin.userEmail,
+      userKey: admin.userEmail,
+      orgId: admin.orgId,
+    }))
+  ) {
+    return mutation;
+  }
+
+  let readBack: Awaited<ReturnType<typeof callTarget>>;
+  try {
+    readBack = await callTarget(
+      app,
+      admin,
+      "list-feature-flags",
+      {},
+      orgDomain,
+    );
+  } catch (error) {
+    throw targetFailure(error);
+  }
+  if (readBack.status === 401 || readBack.status === 403)
+    throw new WorkspaceFeatureFlagFailure("authorization");
+  if (readBack.status === 404 || readBack.status === 405)
+    throw new WorkspaceFeatureFlagFailure("unsupported-target");
+  if (readBack.status < 200 || readBack.status >= 300)
+    throw new WorkspaceFeatureFlagFailure("verification");
+  const verifiedApp = classifyWorkspaceFeatureFlagList(app, readBack);
+  if (verifiedApp.state === "forbidden")
+    throw new WorkspaceFeatureFlagFailure("authorization");
+  if (verifiedApp.state === "unsupported")
+    throw new WorkspaceFeatureFlagFailure("unsupported-target");
+  const verifiedFlag = verifiedApp.flags.find((flag) => flag.key === input.key);
+  const expectedEnabled =
+    input.operation === "enable-for-current-user"
+      ? true
+      : input.operation === "off"
+        ? false
+        : null;
+  if (
+    verifiedApp.state !== "ready" ||
+    !verifiedFlag ||
+    typeof verifiedFlag.enabledForCurrentUser !== "boolean" ||
+    (expectedEnabled !== null &&
+      verifiedFlag.enabledForCurrentUser !== expectedEnabled)
+  ) {
+    throw new WorkspaceFeatureFlagFailure("verification");
+  }
+  try {
+    validateWorkspaceFeatureFlagMutation(
+      {
+        contractVersion: 2,
+        status: "ready",
+        key: input.key,
+        rules: verifiedFlag.rules,
+        scope: mutation.scope,
+      },
+      {
+        key: input.key,
+        orgDomain,
+        allowExplicitNoOrgTarget: true,
+        rules: mutation.rules,
+      },
+    );
+  } catch {
+    throw new WorkspaceFeatureFlagFailure("verification");
+  }
+  return {
+    contractVersion: 3,
+    status: "verified",
+    key: mutation.key,
+    rules: verifiedFlag.rules as Record<string, unknown>,
+    scope: mutation.scope,
+    enabledForCurrentUser: verifiedFlag.enabledForCurrentUser,
+  };
 }
 
 export async function getWorkspaceFlagTarget(

package/corpus/templates/analytics/server/plugins/feature-flags.ts

@@ -0,0 +1,5 @@
+import { createFeatureFlagsPlugin } from "@agent-native/core/server";
+
+import { ANALYTICS_FEATURE_FLAGS } from "../../shared/feature-flags.js";
+
+export default createFeatureFlagsPlugin({ flags: ANALYTICS_FEATURE_FLAGS });

package/corpus/templates/analytics/shared/feature-flags.ts

@@ -0,0 +1,10 @@
+import { defineFeatureFlag } from "@agent-native/core/feature-flags/registry";
+
+export const VERIFIED_FLEET_FLAG_MUTATIONS = defineFeatureFlag({
+  key: "analytics.verified-fleet-flag-mutations",
+  displayName: "Verified fleet flag mutations",
+  description:
+    "Verify cross-app feature flag changes with an independent target read-back.",
+});
+
+export const ANALYTICS_FEATURE_FLAGS = [VERIFIED_FLEET_FLAG_MUTATIONS];

package/corpus/templates/assets/app/routes/brand-kits.$id.tsx

@@ -11,6 +11,7 @@ import {
 } from "@agent-native/core/client/hooks";
 import { useT } from "@agent-native/core/client/i18n";
 import { ShareButton } from "@agent-native/core/client/sharing";
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { CreativeContextShareSheet } from "@agent-native/creative-context/client";
 import {
   IconCheck,
@@ -311,7 +312,10 @@ function assetUpdatedTime(asset: any): number {
 
 export function loader({ params, request }: LoaderFunctionArgs) {
   const url = new URL(request.url);
-  return redirect(`/library/${params.id}${url.search}`);
+  return withSsrHtmlContentType(
+    redirect(`/library/${params.id}${url.search}`),
+    { varyByQuery: true },
+  );
 }
 
 export default function BrandKitDetailRedirect() {

package/corpus/templates/assets/app/routes/brand-kits._index.tsx

@@ -1,8 +1,11 @@
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { redirect, type LoaderFunctionArgs } from "react-router";
 
 export function loader({ request }: LoaderFunctionArgs) {
   const url = new URL(request.url);
-  return redirect(`/library${url.search}`);
+  return withSsrHtmlContentType(redirect(`/library${url.search}`), {
+    varyByQuery: true,
+  });
 }
 
 export default function BrandKitsIndexRedirect() {

package/corpus/templates/assets/app/routes/libraries.tsx

@@ -1,9 +1,12 @@
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { redirect, type LoaderFunctionArgs } from "react-router";
 
 // Legacy redirect: brand containers now live in the unified Library workspace.
 export function loader({ request }: LoaderFunctionArgs) {
   const url = new URL(request.url);
-  return redirect(`/library${url.search}`);
+  return withSsrHtmlContentType(redirect(`/library${url.search}`), {
+    varyByQuery: true,
+  });
 }
 
 export default function LibrariesRedirect() {

package/corpus/templates/assets/app/routes/picker.tsx

@@ -1,9 +1,12 @@
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { redirect, type LoaderFunctionArgs } from "react-router";
 
 // Legacy redirect: the image browser moved from "Picker" (/picker) to
 // "Library" (/library). Preserve any query string so deep links keep working.
 export function loader({ url }: LoaderFunctionArgs) {
-  return redirect(`/library${url.search}`);
+  return withSsrHtmlContentType(redirect(`/library${url.search}`), {
+    varyByQuery: true,
+  });
 }
 
 export default function PickerRedirect() {

package/corpus/templates/clips/app/routes/_app.wispr.tsx

@@ -1,7 +1,8 @@
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { redirect } from "react-router";
 
 export function loader() {
-  return redirect("/dictate");
+  return withSsrHtmlContentType(redirect("/dictate"));
 }
 
 export default function LegacyWisprRedirect() {

package/corpus/templates/clips/app/routes/_index.tsx

@@ -1,11 +1,10 @@
 import { DefaultSpinner } from "@agent-native/core/client/ui";
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { redirect, type LoaderFunctionArgs } from "react-router";
 
 const SEO_TITLE = "Clips - Open Source screen recorder";
 const SEO_DESCRIPTION =
   "Open Source screen recorder and meeting-notes app with AI transcripts, summaries, search, dictation, and agent-readable share links.";
-const SSR_REDIRECT_CONTENT_TYPE = "text/html; charset=utf-8";
-
 export function meta() {
   return [
     { title: SEO_TITLE },
@@ -39,18 +38,15 @@ function buildTarget(url: URL): string {
 }
 
 export function loader({ url }: LoaderFunctionArgs) {
-  const response = redirect(buildTarget(url));
-  // The deploy adapter uses the HTML content type to apply Clips' public SSR
-  // cache policy. Without it, the root redirect reaches origin on every visit
-  // even though the /library shell is already cached at the edge.
-  response.headers.set("content-type", SSR_REDIRECT_CONTENT_TYPE);
-  throw response;
+  throw withSsrHtmlContentType(redirect(buildTarget(url)), {
+    varyByQuery: true,
+  });
 }
 
 export function clientLoader({ url }: LoaderFunctionArgs) {
-  const response = redirect(buildTarget(url));
-  response.headers.set("content-type", SSR_REDIRECT_CONTENT_TYPE);
-  throw response;
+  throw withSsrHtmlContentType(redirect(buildTarget(url)), {
+    varyByQuery: true,
+  });
 }
 
 export function HydrateFallback() {

package/corpus/templates/design/app/routes/examples.tsx

@@ -1,7 +1,8 @@
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { redirect } from "react-router";
 
 export function loader() {
-  return redirect("/", 302);
+  return withSsrHtmlContentType(redirect("/", 302));
 }
 
 export default function ExamplesRedirect() {

package/corpus/templates/forms/app/routes/_index.tsx

@@ -1,4 +1,5 @@
 import { DefaultSpinner } from "@agent-native/core/client/ui";
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { redirect, type LoaderFunctionArgs } from "react-router";
 
 import messages from "@/i18n/en-US";
@@ -11,11 +12,11 @@ function target(url: URL): string {
 }
 
 export function loader({ url }: LoaderFunctionArgs) {
-  throw redirect(target(url));
+  throw withSsrHtmlContentType(redirect(target(url)), { varyByQuery: true });
 }
 
 export function clientLoader({ url }: LoaderFunctionArgs) {
-  throw redirect(target(url));
+  throw withSsrHtmlContentType(redirect(target(url)), { varyByQuery: true });
 }
 
 export function meta() {

package/corpus/templates/mail/app/routes/_index.tsx

@@ -1,3 +1,4 @@
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { redirect } from "react-router";
 
 import { Spinner } from "@/components/ui/spinner";
@@ -31,11 +32,11 @@ export function meta() {
  * hydrates. The app opens to the Important triage tab by default.
  */
 export function loader() {
-  throw redirect("/inbox?label=important");
+  throw withSsrHtmlContentType(redirect("/inbox?label=important"));
 }
 
 export function clientLoader() {
-  throw redirect("/inbox?label=important");
+  throw withSsrHtmlContentType(redirect("/inbox?label=important"));
 }
 
 export function HydrateFallback() {

package/corpus/templates/tasks/app/routes/_index.tsx

@@ -1,3 +1,4 @@
+import { withSsrHtmlContentType } from "@agent-native/core/shared";
 import { redirect } from "react-router";
 
 import { APP_TITLE } from "@/lib/app-config";
@@ -14,7 +15,7 @@ export function meta() {
 }
 
 export function loader() {
-  return redirect("/tasks");
+  return withSsrHtmlContentType(redirect("/tasks"));
 }
 
 export default function IndexRedirect() {

package/dist/cli/code-agent-executor.js

@@ -14,9 +14,9 @@ import { buildMergedConfig, McpClientManager, mcpToolsToActionEntries, } from ".
 import { readAgentsBundleFromFs, generateDevelopmentSkillsPromptBlock, } from "../server/agents-bundle.js";
 import { getAmbientOrgId, getAmbientUserEmail, runWithRequestContext, } from "../server/request-context.js";
 import { isReasoningEffort, } from "../shared/reasoning-effort.js";
-import { createCodeAgentAgentTools } from "./code-agent-agent-tools.js";
 import { createAgentNativeConfigContext, loadResolvedAgentNativeConfig, } from "../vite/agent-native-config-loader.js";
 import { runClaudeCodeParticipant, } from "./claude-code-participant.js";
+import { createCodeAgentAgentTools } from "./code-agent-agent-tools.js";
 import { codexMcpConfigArgs, mergeCodeAgentMcpConfig, restrictCodeAgentMcpConfig, } from "./code-agent-mcp-config.js";
 import { createCodeAgentOutputSmoother } from "./code-agent-output-smoother.js";
 import { addCodeAgentCommandToAllowlist, appendCodeAgentTranscriptEvent, dequeueCodeAgentFollowUp, getCodeAgentRunRecord, isCodeAgentCommandAllowed, listCodeAgentTranscriptEvents, updateCodeAgentRunRecord, } from "./code-agent-runs.js";

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
-    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
+    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
-    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
+    error?: undefined;
 }>>;

package/dist/deploy/build.js

@@ -23,7 +23,7 @@ import { INTEGRATION_RECOVERY_RUNTIME_MARKER, INTEGRATION_RETRY_SWEEP_PATH, INTE
 import { isValidCron } from "../jobs/cron.js";
 import { RECURRING_JOBS_SWEEP_PATH, RECURRING_JOBS_SWEEP_TOKEN_SUBJECT, } from "../jobs/scheduler-dispatch.js";
 import { normalizeAppBasePath } from "../server/app-base-path.js";
-import { DEFAULT_SPECULATION_RULES_PATH, resolveSsrCacheHeaders, resolveSsrCacheKeyHeaders, } from "../shared/cache-control.js";
+import { DEFAULT_SPECULATION_RULES_PATH, resolveSsrCacheHeaders, resolveSsrCacheKeyHeaders, SSR_QUERY_CACHE_KEY_HEADER, } from "../shared/cache-control.js";
 import { mcpEmbedStaticAssetRouteRules } from "../shared/mcp-embed-headers.js";
 import { isTruthyRuntimeValue } from "../shared/runtime-config.js";
 import { AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, } from "../shared/social-meta.js";
@@ -1107,6 +1107,7 @@ function injectHeadScript(html, script) {
 // Resolved from AGENT_NATIVE_SSR_CACHE at build time.
 const SSR_CACHE_HEADERS = ${JSON.stringify(ssrCacheHeaders)};
 const SSR_CACHE_KEY_HEADERS = ${JSON.stringify(ssrCacheKeyHeaders)};
+const SSR_QUERY_CACHE_KEY_HEADER = ${JSON.stringify(SSR_QUERY_CACHE_KEY_HEADER)};
 const DEFAULT_SPECULATION_RULES_PATH = ${JSON.stringify(DEFAULT_SPECULATION_RULES_PATH)};
 const IMMUTABLE_ASSET_CACHE_CONTROL = ${JSON.stringify(IMMUTABLE_ASSET_CACHE_CONTROL)};
 const IMMUTABLE_ASSET_PATHS = new Set(${JSON.stringify([...new Set(immutableAssetPaths)].sort())});
@@ -1174,6 +1175,9 @@ function isSsrHtmlOrDataResponse(headers, status, pathname) {
  * from the canonical Nitro/Netlify handler or send normal pages to origin.
  */
 function applyDefaultSsrCacheHeader(headers, status, pathname) {
+  const varyByQuery =
+    (headers.get(SSR_QUERY_CACHE_KEY_HEADER) || "").trim().toLowerCase() === "query";
+  headers.delete(SSR_QUERY_CACHE_KEY_HEADER);
   if (!isSsrHtmlOrDataResponse(headers, status, pathname)) return;
 
   headers.delete("set-cookie");
@@ -1193,9 +1197,11 @@ function applyDefaultSsrCacheHeader(headers, status, pathname) {
   for (const [name, value] of Object.entries(SSR_CACHE_HEADERS)) {
     headers.set(name, value);
   }
-  for (const [name, value] of Object.entries(SSR_CACHE_KEY_HEADERS)) {
-    headers.set(name, value);
-  }
+  const netlifyVary = varyByQuery
+    ? SSR_CACHE_KEY_HEADERS["netlify-vary"] ? "query" : undefined
+    : SSR_CACHE_KEY_HEADERS["netlify-vary"];
+  if (netlifyVary) headers.set("netlify-vary", netlifyVary);
+  else headers.delete("netlify-vary");
 }
 
 function applyDefaultSpeculationRulesHeader(headers, status, basePath) {

package/dist/notifications/routes.d.ts

@@ -11,14 +11,14 @@
  *   DELETE /_agent-native/notifications/:id         — delete
  */
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
-    error?: undefined;
     count: number;
     updated?: undefined;
+    error?: undefined;
     ok?: undefined;
 } | {
-    error?: undefined;
     count?: undefined;
     updated: number;
+    error?: undefined;
     ok?: undefined;
 } | {
     count?: undefined;
@@ -26,8 +26,8 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     count?: undefined;
     updated?: undefined;
+    error?: undefined;
     ok: boolean;
 }>>;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/server/ssr-handler.js

@@ -18,7 +18,7 @@ import { defineEventHandler } from "h3";
  */
 import { createRequestHandler } from "react-router";
 import { isMcpPublicPath } from "../mcp/route-paths.js";
-import { DEFAULT_SPECULATION_RULES_PATH, resolveSsrCacheHeaders, resolveSsrCacheKeyHeaders, } from "../shared/cache-control.js";
+import { DEFAULT_SPECULATION_RULES_PATH, resolveSsrCacheHeaders, resolveSsrCacheKeyHeaders, SSR_QUERY_CACHE_KEY_HEADER, } from "../shared/cache-control.js";
 import { AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, withAgentNativeSocialImageCacheBuster, } from "../shared/social-meta.js";
 import { getAppBasePathFromViteEnv, stripAppBasePath as canonicalStripAppBasePath, } from "./app-base-path.js";
 import { getAppOriginClientConfigScript } from "./app-origin-config.js";
@@ -204,6 +204,8 @@ function isSsrHtmlOrDataResponse(headers, status, pathname) {
  * that contradicts that.
  */
 function applyDefaultSsrCacheHeader(headers, status, pathname) {
+    const varyByQuery = headers.get(SSR_QUERY_CACHE_KEY_HEADER)?.trim().toLowerCase() === "query";
+    headers.delete(SSR_QUERY_CACHE_KEY_HEADER);
     if (!isSsrHtmlOrDataResponse(headers, status, pathname))
         return;
     // A public shell must never set a viewer cookie or vary by credentials.
@@ -234,9 +236,16 @@ function applyDefaultSsrCacheHeader(headers, status, pathname) {
     for (const [name, value] of Object.entries(resolveSsrCacheHeaders())) {
         headers.set(name, value);
     }
-    for (const [name, value] of Object.entries(resolveSsrCacheKeyHeaders())) {
-        headers.set(name, value);
-    }
+    const cacheKeyHeaders = resolveSsrCacheKeyHeaders();
+    const netlifyVary = varyByQuery
+        ? cacheKeyHeaders["netlify-vary"]
+            ? "query"
+            : undefined
+        : cacheKeyHeaders["netlify-vary"];
+    if (netlifyVary)
+        headers.set("netlify-vary", netlifyVary);
+    else
+        headers.delete("netlify-vary");
 }
 function applyDefaultSpeculationRulesHeader(headers, status, basePath) {
     if (status < 200 || status >= 400)

package/dist/shared/cache-control.d.ts

@@ -7,6 +7,28 @@ export declare const DEFAULT_SSR_CACHE_HEADERS: {
     readonly "cdn-cache-control": "public, max-age=600, stale-while-revalidate=604800, stale-if-error=3600";
     readonly "netlify-cdn-cache-control": "public, durable, s-maxage=31536000, stale-while-revalidate=604800, stale-if-error=3600";
 };
+/**
+ * Content type used by impersonal HTML redirects that should enter the
+ * deployment adapter's shared SSR cache path.
+ */
+export declare const SSR_HTML_CONTENT_TYPE = "text/html; charset=utf-8";
+/**
+ * Internal response marker for public HTML whose redirect target preserves
+ * request query parameters. The SSR adapters consume this marker and emit a
+ * provider-specific full-query cache key only where the provider supports it.
+ */
+export declare const SSR_QUERY_CACHE_KEY_HEADER = "x-agent-native-ssr-key";
+export type SsrHtmlContentTypeOptions = {
+    varyByQuery?: boolean;
+};
+/**
+ * Mark an already-built HTML response as HTML without changing its redirect
+ * status, location, or other headers. Only use this for redirects whose
+ * target is independent of the viewer and request credentials. Set
+ * `varyByQuery` when the target preserves request query parameters so the SSR
+ * adapter can request a full-query cache key on providers that support it.
+ */
+export declare function withSsrHtmlContentType<T extends Response>(response: T, options?: SsrHtmlContentTypeOptions): T;
 /**
  * Deployment-wide override for the SSR shell cache policy.
  *

package/dist/shared/cache-control.js

@@ -7,6 +7,31 @@ export const DEFAULT_SSR_CACHE_HEADERS = {
     "cdn-cache-control": DEFAULT_SSR_CDN_CACHE_CONTROL,
     "netlify-cdn-cache-control": DEFAULT_SSR_NETLIFY_CDN_CACHE_CONTROL,
 };
+/**
+ * Content type used by impersonal HTML redirects that should enter the
+ * deployment adapter's shared SSR cache path.
+ */
+export const SSR_HTML_CONTENT_TYPE = "text/html; charset=utf-8";
+/**
+ * Internal response marker for public HTML whose redirect target preserves
+ * request query parameters. The SSR adapters consume this marker and emit a
+ * provider-specific full-query cache key only where the provider supports it.
+ */
+export const SSR_QUERY_CACHE_KEY_HEADER = "x-agent-native-ssr-key";
+/**
+ * Mark an already-built HTML response as HTML without changing its redirect
+ * status, location, or other headers. Only use this for redirects whose
+ * target is independent of the viewer and request credentials. Set
+ * `varyByQuery` when the target preserves request query parameters so the SSR
+ * adapter can request a full-query cache key on providers that support it.
+ */
+export function withSsrHtmlContentType(response, options = {}) {
+    response.headers.set("content-type", SSR_HTML_CONTENT_TYPE);
+    if (options.varyByQuery) {
+        response.headers.set(SSR_QUERY_CACHE_KEY_HEADER, "query");
+    }
+    return response;
+}
 /**
  * Deployment-wide override for the SSR shell cache policy.
  *

package/dist/shared/index.d.ts

@@ -6,6 +6,7 @@ export { truncate } from "./truncate.js";
 export { isHumanReadableDocumentTitle, normalizeDocumentTitle, } from "./document-title.js";
 export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";
+export { SSR_HTML_CONTENT_TYPE, SSR_QUERY_CACHE_KEY_HEADER, type SsrHtmlContentTypeOptions, withSsrHtmlContentType, } from "./cache-control.js";
 export { AGENT_NATIVE_DOCS_ORIGIN, docsUrl, type DocsUrlOptions, } from "./docs-url.js";
 export { buildRuntimeConfigPrompt, formatRuntimeConfigReport, getRuntimeConfigReport, parseRuntimeConfigReport, runtimeConfigRequirementsFromSearchParams, type RuntimeConfigEnvironment, type RuntimeConfigIssue, type RuntimeConfigIssueCode, type RuntimeConfigIssueSeverity, type RuntimeConfigPhase, type RuntimeConfigReport, type RuntimeConfigRequirements, } from "./runtime-config.js";
 export { llmConnectionTrackingProperties, normalizeLlmConnection, type LlmConnectionStatus, } from "./llm-connection.js";

package/dist/shared/index.js

@@ -6,6 +6,7 @@ export { truncate } from "./truncate.js";
 export { isHumanReadableDocumentTitle, normalizeDocumentTitle, } from "./document-title.js";
 export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";
+export { SSR_HTML_CONTENT_TYPE, SSR_QUERY_CACHE_KEY_HEADER, withSsrHtmlContentType, } from "./cache-control.js";
 export { AGENT_NATIVE_DOCS_ORIGIN, docsUrl, } from "./docs-url.js";
 export { buildRuntimeConfigPrompt, formatRuntimeConfigReport, getRuntimeConfigReport, parseRuntimeConfigReport, runtimeConfigRequirementsFromSearchParams, } from "./runtime-config.js";
 export { llmConnectionTrackingProperties, normalizeLlmConnection, } from "./llm-connection.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.164.1",
+  "version": "0.164.3",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {