@agent-native/core 0.107.2 → 0.109.0

package/corpus/core/src/client/route-chunk-recovery.ts

@@ -201,6 +201,17 @@ function recoverToIntendedNavigation(
   return true;
 }
 
+function recoverFromDynamicImportFailure(
+  win: Window,
+  state: RouteChunkRecoveryState,
+  message: string,
+): boolean {
+  if (!isDynamicImportFailureMessage(message)) return false;
+  state.routeModuleFailureAt = Date.now();
+  if (recoverToIntendedNavigation(win, state)) return true;
+  return reloadForStaleChunk(win);
+}
+
 function patchHistoryMethod(
   win: Window,
   state: RouteChunkRecoveryState,
@@ -290,16 +301,17 @@ export function installRouteChunkRecovery(
   win.addEventListener("unhandledrejection", (event) => {
     const reason = (event as PromiseRejectionEvent).reason;
     const message = String(reason?.message || reason || "");
-    if (!isDynamicImportFailureMessage(message)) return;
-    state.routeModuleFailureAt = Date.now();
-    if (recoverToIntendedNavigation(win, state)) {
+    if (recoverFromDynamicImportFailure(win, state, message)) {
       event.preventDefault();
-      return;
     }
-    // No fresh cross-route target — the current route's own chunk went stale.
-    // Reload once (guarded) to fetch fresh assets instead of leaving the user
-    // on a broken view.
-    if (reloadForStaleChunk(win)) {
+  });
+
+  win.addEventListener("error", (event) => {
+    const errorEvent = event as ErrorEvent;
+    const message = String(
+      errorEvent.error?.message || errorEvent.message || "",
+    );
+    if (recoverFromDynamicImportFailure(win, state, message)) {
       event.preventDefault();
     }
   });

package/corpus/core/src/client/session-replay.ts

@@ -390,6 +390,8 @@ const SESSION_REPLAY_CLAIM_TIMEOUT_MS = 150;
 export const SESSION_REPLAY_CONSOLE_EVENT_TAG = "agent-native.console";
 /** rrweb custom-event tag for captured fetch/XHR request summaries. */
 export const SESSION_REPLAY_NETWORK_EVENT_TAG = "agent-native.network";
+/** Content-free agent-chat lifecycle markers for replay incident forensics. */
+export const SESSION_REPLAY_AGENT_CHAT_EVENT_TAG = "agent-native.chat";
 
 const DEFAULT_MAX_CONSOLE_EVENTS = 1000;
 const DEFAULT_MAX_NETWORK_EVENTS = 2000;
@@ -3384,3 +3386,32 @@ export function emitSessionReplayException(input: {
     ...(input.url ? { url: input.url } : {}),
   });
 }
+
+export type SessionReplayAgentChatEvent = {
+  phase: "surface-mounted" | "run-observed" | "run-stopped";
+  surface: string;
+  threadId?: string;
+  runId?: string;
+  tabId?: string;
+};
+
+/**
+ * Add a content-free chat lifecycle marker to the active replay. The payload
+ * deliberately accepts only ids and low-cardinality state; prompt/response
+ * content must never enter replay diagnostics through this path.
+ */
+export function emitSessionReplayAgentChatEvent(
+  input: SessionReplayAgentChatEvent,
+): void {
+  const state = getState();
+  if (!state.active || !state.addCustomEvent) return;
+  const bounded = (value: string | undefined, max = 160) =>
+    value?.trim().slice(0, max) || undefined;
+  emitReplayCustomEvent(state, SESSION_REPLAY_AGENT_CHAT_EVENT_TAG, {
+    phase: input.phase,
+    surface: bounded(input.surface, 80) ?? "app",
+    ...(bounded(input.threadId) ? { threadId: bounded(input.threadId) } : {}),
+    ...(bounded(input.runId) ? { runId: bounded(input.runId) } : {}),
+    ...(bounded(input.tabId) ? { tabId: bounded(input.tabId) } : {}),
+  });
+}

package/corpus/core/src/extensions/actions.ts

@@ -727,20 +727,8 @@ export function createExtensionActionEntries(): Record<string, ActionEntry> {
           !coerceBoolean(args?.allowFullReplacement)
         ) {
           const message =
-            "Full extension-body replacement was blocked to preserve the existing visual design. Read the current extension and use focused patches/edits for a data-only repair. Only retry with allowFullReplacement=true when the user explicitly requested a broad visual rewrite or supplied a complete replacement body.";
-          throw new AgentActionStopError(message, {
-            errorCode: "extension_full_replacement_requires_explicit_intent",
-            toolResult: JSON.stringify(
-              {
-                error: "extension_full_replacement_requires_explicit_intent",
-                message,
-                recoverable: false,
-                next: "Call get-extension once, then update-extension with patches or edits that change only the data-loading code. Use allowFullReplacement=true only for an explicitly requested visual rewrite.",
-              },
-              null,
-              2,
-            ),
-          });
+            "Full extension-body replacement requires allowFullReplacement=true. No changes were applied. If the user's request includes a broad visual rewrite such as changing layout, compactness, visible sections, naming, or padding, retry once with allowFullReplacement=true; otherwise read the current extension and use focused patches/edits for a data-only repair. Do not retry unchanged arguments.";
+          throw new ExtensionContentEditError(message);
         }
 
         // Full-replacement content can come inline (`content`) or by reference

package/corpus/core/src/extensions/routes.ts

@@ -982,7 +982,7 @@ export const DESTRUCTIVE_SQL_RE =
 // integrations, notifications, scheduling, sharing/orgs), and Postgres
 // catalogs that would let a extension enumerate or read internals.
 export const SENSITIVE_SQL_RE =
-  /\b(app_secrets|user|users|session|sessions|account|accounts|verification|oauth_tokens|tools|extensions|tool_shares|tool_slots|tool_slot_installs|tool_hidden_extensions|tool_history|member|organization|invitation|jwks|agent_trace_spans|agent_trace_summaries|agent_feedback|agent_satisfaction_scores|agent_evals|agent_runs|agent_run_events|notifications|progress_runs|integration_configs|integration_pending_tasks|integration_thread_mappings|resources|org_members|org_invitations|bigquery_cache|dashboard_views|pg_catalog|information_schema|pg_class|pg_proc|pg_namespace|pg_user|pg_roles|pg_authid|pg_shadow)\b/i;
+  /\b(app_secrets|settings|user|users|session|sessions|account|accounts|verification|oauth_tokens|tools|extensions|tool_shares|tool_slots|tool_slot_installs|tool_hidden_extensions|tool_history|member|organization|invitation|jwks|agent_trace_spans|agent_trace_summaries|agent_feedback|agent_satisfaction_scores|agent_evals|agent_runs|agent_run_events|notifications|progress_runs|integration_configs|integration_pending_tasks|integration_thread_mappings|resources|org_members|org_invitations|bigquery_cache|dashboard_views|pg_catalog|information_schema|pg_class|pg_proc|pg_namespace|pg_user|pg_roles|pg_authid|pg_shadow)\b/i;
 
 // Refuses positional INSERTs (no column list). `INSERT INTO recordings VALUES
 // (...)` would let a extension stuff arbitrary owner_email values into a row.

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

@@ -1192,7 +1192,7 @@ export async function updateExtensionContent(
 
   if (opts.content !== undefined && opts.allowFullReplacement !== true) {
     throw new ExtensionContentEditError(
-      "Full extension-body replacement requires explicit allowFullReplacement=true. Use patches or edits for a targeted data-only repair so the existing design is preserved.",
+      "Full extension-body replacement requires allowFullReplacement=true. No changes were applied. Use patches or edits for a targeted data-only repair, or set allowFullReplacement=true for a user-requested broad visual rewrite.",
     );
   }
 

package/corpus/core/src/feature-flags/a2a-action-route.ts

@@ -0,0 +1,56 @@
+import { getHeader } from "h3";
+import * as jose from "jose";
+
+import { verifyA2ATokenWithClaims } from "../a2a-claims.js";
+import type { ActionRouteAuthAdapter } from "../server/action-routes.js";
+
+const FLAG_ACTION_SCOPES = {
+  "list-feature-flags": "flags:read",
+  "set-feature-flag": "flags:write",
+} as const;
+
+export function declaresFeatureFlagDelegation(token: string): boolean {
+  try {
+    const raw = jose.decodeJwt(token);
+    const scopes =
+      typeof raw.scope === "string"
+        ? raw.scope.split(/\s+/)
+        : Array.isArray(raw.scope)
+          ? raw.scope.filter(
+              (scope): scope is string => 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: keyof typeof FLAG_ACTION_SCOPES,
+): ActionRouteAuthAdapter {
+  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,
+      };
+    },
+  };
+}

package/corpus/core/src/feature-flags/actions/get-feature-flags.ts

@@ -0,0 +1,24 @@
+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;
+  },
+});

package/corpus/core/src/feature-flags/actions/list-feature-flags.ts

@@ -0,0 +1,69 @@
+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 as { statusCode?: number }).statusCode === 403
+      ) {
+        return {
+          contractVersion: 1,
+          status: "forbidden" as const,
+          reason: "forbidden" as const,
+          flags: [],
+          canManage: false,
+        };
+      }
+      throw error;
+    }
+    if (definitions.length === 0)
+      return {
+        contractVersion: 1,
+        status: "no-definitions" as const,
+        reason: "no-definitions" as const,
+        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" as const,
+      reason: "ready" as const,
+      flags,
+      canManage: true,
+    };
+  },
+});

package/corpus/core/src/feature-flags/actions/set-feature-flag.ts

@@ -0,0 +1,89 @@
+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 as const,
+      status: "ready" as const,
+      key: args.key,
+      rules: persistedRules,
+      scope: { orgId: manager.orgId },
+    };
+  },
+});

package/corpus/core/src/feature-flags/index.ts

@@ -0,0 +1,21 @@
+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";

package/corpus/core/src/feature-flags/permissions.ts

@@ -0,0 +1,53 @@
+import { getOrgRoleForEmail } from "../mcp/actions/service-token-access.js";
+import { canManageOrg } from "../org/permissions.js";
+
+export class FeatureFlagPermissionError extends Error {
+  statusCode: number;
+
+  constructor(message: string, statusCode: number) {
+    super(message);
+    this.statusCode = statusCode;
+  }
+}
+
+function productionAdminAllowlist(): Set<string> {
+  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: {
+  userEmail?: string;
+  orgId?: string | null;
+}): Promise<{ email: string; orgId: string | null }> {
+  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 };
+}

package/corpus/core/src/feature-flags/plugin.ts

@@ -0,0 +1,44 @@
+import { getSetting } from "../settings/store.js";
+import {
+  registerFeatureFlags,
+  type FeatureFlagDefinition,
+} from "./registry.js";
+import { mutateFeatureFlagRules } from "./store.js";
+
+type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
+
+/** A tiny startup plugin for app-local, explicit feature-flag registration. */
+export 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 {
+  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",
+          };
+        });
+      }),
+    );
+  };
+}

package/corpus/core/src/feature-flags/registry.ts

@@ -0,0 +1,96 @@
+/**
+ * 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;
+}
+
+const registry = new Map<string, FeatureFlagDefinition>();
+
+function normalizeDefinition(
+  definition: FeatureFlagDefinition,
+): FeatureFlagDefinition {
+  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: FeatureFlagDefinition,
+): FeatureFlagDefinition {
+  return Object.freeze(normalizeDefinition(definition));
+}
+
+/** Define a small app-owned feature-flag registry. */
+export function defineFeatureFlags(
+  definitions: readonly FeatureFlagDefinition[],
+): readonly FeatureFlagDefinition[] {
+  const seen = new Set<string>();
+  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: readonly FeatureFlagDefinition[],
+): void {
+  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(): readonly FeatureFlagDefinition[] {
+  return [...registry.values()].sort((a, b) => a.key.localeCompare(b.key));
+}
+
+export function getFeatureFlagDefinition(
+  key: string,
+): FeatureFlagDefinition | null {
+  return registry.get(key) ?? null;
+}
+
+/** Test-only registry reset; not exported from package entrypoints. */
+export function _resetFeatureFlagRegistryForTests(): void {
+  registry.clear();
+}