@agent-native/core 0.114.2 → 0.114.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.114.2",
+  "version": "0.114.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": {
@@ -159,6 +159,7 @@
     "./application-state": "./dist/application-state/index.js",
     "./settings": "./dist/settings/index.js",
     "./feature-flags": "./dist/feature-flags/index.js",
+    "./feature-flags/registry": "./dist/feature-flags/registry.js",
     "./feature-flags/actions/get-feature-flags": "./dist/feature-flags/actions/get-feature-flags.js",
     "./feature-flags/actions/list-feature-flags": "./dist/feature-flags/actions/list-feature-flags.js",
     "./feature-flags/actions/set-feature-flag": "./dist/feature-flags/actions/set-feature-flag.js",

package/src/db/request-telemetry.ts

@@ -1,4 +1,4 @@
-import { AsyncLocalStorage } from "node:async_hooks";
+import { getAsyncLocalStorageCtor } from "../shared/optional-node-builtins.js";
 
 export type DatabaseOperationKind = "connect" | "query";
 
@@ -30,15 +30,39 @@ interface StartupDatabaseTelemetryState {
   claimed: boolean;
   telemetry: DatabaseRequestTelemetry;
 }
+interface TelemetryStorage {
+  getStore(): DatabaseRequestTelemetry | undefined;
+  run<T>(store: DatabaseRequestTelemetry, fn: () => T): T;
+  enterWith(store: DatabaseRequestTelemetry): void;
+}
+
 type GlobalWithDatabaseTelemetry = typeof globalThis & {
-  [STORAGE_KEY]?: AsyncLocalStorage<DatabaseRequestTelemetry>;
+  [STORAGE_KEY]?: TelemetryStorage;
   [STARTUP_STATE_KEY]?: StartupDatabaseTelemetryState;
 };
 
 const globalRef = globalThis as GlobalWithDatabaseTelemetry;
-const storage =
-  globalRef[STORAGE_KEY] ??
-  (globalRef[STORAGE_KEY] = new AsyncLocalStorage<DatabaseRequestTelemetry>());
+
+// AsyncLocalStorage is resolved lazily, never at module load: this module can
+// land in the browser dev graph, where a top-level `new AsyncLocalStorage()`
+// would throw against Vite's externalized `node:async_hooks` stub. On non-Node
+// runtimes telemetry no-ops.
+const NOOP_STORAGE: TelemetryStorage = {
+  getStore: () => undefined,
+  run: (_store, fn) => fn(),
+  enterWith: () => {},
+};
+
+function getStorage(): TelemetryStorage {
+  const existing = globalRef[STORAGE_KEY];
+  if (existing) return existing;
+  const Ctor = getAsyncLocalStorageCtor();
+  const created: TelemetryStorage = Ctor
+    ? new Ctor<DatabaseRequestTelemetry>()
+    : NOOP_STORAGE;
+  globalRef[STORAGE_KEY] = created;
+  return created;
+}
 
 export function createDatabaseRequestTelemetry(): DatabaseRequestTelemetry {
   return {
@@ -66,7 +90,7 @@ const startupState =
   });
 
 function currentDatabaseTelemetry(): DatabaseRequestTelemetry | undefined {
-  const requestTelemetry = storage.getStore();
+  const requestTelemetry = getStorage().getStore();
   if (requestTelemetry) return requestTelemetry;
   if (!startupState.claimed && Date.now() <= startupState.captureUntil) {
     return startupState.telemetry;
@@ -86,13 +110,13 @@ export function runWithDatabaseRequestTelemetry<T>(
   telemetry: DatabaseRequestTelemetry,
   fn: () => T,
 ): T {
-  return storage.run(telemetry, fn);
+  return getStorage().run(telemetry, fn);
 }
 
 export function enterDatabaseRequestTelemetry(
   telemetry: DatabaseRequestTelemetry,
 ): void {
-  storage.enterWith(telemetry);
+  getStorage().enterWith(telemetry);
 }
 
 export function beginDatabaseOperation(

package/src/settings/store.ts

@@ -1,9 +1,10 @@
-import { EventEmitter } from "events";
+import type { EventEmitter } from "node:events";
 
 import { getDbExec, isPostgres, intType } from "../db/client.js";
 import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
 import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
 import { getRequestContext } from "../server/request-context.js";
+import { createEventEmitter } from "../shared/optional-node-builtins.js";
 
 let _initPromise: Promise<void> | undefined;
 
@@ -29,12 +30,20 @@ function requestSettingsCache(): Map<string, string | null> | null {
   return cache;
 }
 
-const _emitter = new EventEmitter();
+// Created lazily so this module can be evaluated in the browser dev graph
+// without a top-level `new EventEmitter()` tripping Vite's externalized
+// `node:events` stub. The emitter drives server-side SSE fan-out only.
+let _emitter: EventEmitter | undefined;
 
-export function getSettingsEmitter(): EventEmitter {
+function settingsEmitter(): EventEmitter {
+  if (!_emitter) _emitter = createEventEmitter();
   return _emitter;
 }
 
+export function getSettingsEmitter(): EventEmitter {
+  return settingsEmitter();
+}
+
 function settingsTable(): string {
   return isPostgres() ? "public.settings" : "settings";
 }
@@ -174,7 +183,7 @@ export async function mutateSetting(
           });
     if (result.rowsAffected === 0) continue;
     requestSettingsCache()?.set(key, nextRaw);
-    _emitter.emit("settings", {
+    settingsEmitter().emit("settings", {
       source: "settings",
       type: "change",
       key,
@@ -200,7 +209,7 @@ export async function putSetting(
     args: [key, JSON.stringify(value), Date.now()],
   });
   requestSettingsCache()?.set(key, JSON.stringify(value));
-  _emitter.emit("settings", {
+  settingsEmitter().emit("settings", {
     source: "settings",
     type: "change",
     key,
@@ -221,7 +230,7 @@ export async function deleteSetting(
   });
   requestSettingsCache()?.set(key, null);
   if (result.rowsAffected > 0) {
-    _emitter.emit("settings", {
+    settingsEmitter().emit("settings", {
       source: "settings",
       type: "delete",
       key,

package/src/shared/optional-node-builtins.ts

@@ -0,0 +1,66 @@
+/**
+ * Browser-safe accessors for optional Node builtins.
+ *
+ * `node:async_hooks` and `node:events` are server-only, but the modules that
+ * use them (db telemetry, settings/resource emitters) can land in the browser
+ * dev graph before tree-shaking runs. A static `import { X } from "node:..."`
+ * resolves to Vite's externalized stub and throws the instant the value is
+ * touched at module load. We read the builtin through `process.getBuiltinModule`
+ * instead — the same guard `server/request-context.ts` uses — so there is no
+ * static `node:` import to evaluate in the browser, and callers fall back to a
+ * no-op on non-Node runtimes (browser, or Node without getBuiltinModule).
+ */
+import type { AsyncLocalStorage } from "node:async_hooks";
+import type { EventEmitter } from "node:events";
+
+type BuiltinProcess = {
+  versions?: { node?: string };
+  getBuiltinModule?: (name: string) => unknown;
+};
+
+function nodeBuiltin<T>(name: string): T | undefined {
+  const proc =
+    typeof process === "undefined" ? undefined : (process as BuiltinProcess);
+  if (
+    typeof window !== "undefined" ||
+    !proc ||
+    !proc.versions?.node ||
+    typeof proc.getBuiltinModule !== "function"
+  ) {
+    return undefined;
+  }
+  return proc.getBuiltinModule(name) as T | undefined;
+}
+
+export type AsyncLocalStorageCtor = new <T>() => AsyncLocalStorage<T>;
+
+export function getAsyncLocalStorageCtor(): AsyncLocalStorageCtor | undefined {
+  return nodeBuiltin<{ AsyncLocalStorage: AsyncLocalStorageCtor }>(
+    "node:async_hooks",
+  )?.AsyncLocalStorage;
+}
+
+type EventEmitterCtor = new () => EventEmitter;
+
+/**
+ * Returns a real Node EventEmitter on Node, or a no-op emitter elsewhere. The
+ * emitters that use this drive server-side SSE fan-out; nothing subscribes in
+ * the browser, so the no-op fallback is inert rather than wrong.
+ */
+export function createEventEmitter(): EventEmitter {
+  const Ctor = nodeBuiltin<{ EventEmitter: EventEmitterCtor }>(
+    "node:events",
+  )?.EventEmitter;
+  if (Ctor) return new Ctor();
+  const noop = {
+    on: () => noop,
+    off: () => noop,
+    once: () => noop,
+    addListener: () => noop,
+    removeListener: () => noop,
+    removeAllListeners: () => noop,
+    setMaxListeners: () => noop,
+    emit: () => false,
+  };
+  return noop as unknown as EventEmitter;
+}

package/src/templates/chat/.agents/skills/feature-flags/SKILL.md

@@ -37,7 +37,7 @@ 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";
+import { defineFeatureFlag } from "@agent-native/core/feature-flags/registry";
 
 export const FULL_APP_BUILDING = defineFeatureFlag({
   key: "full-app-building",

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

@@ -37,7 +37,7 @@ 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";
+import { defineFeatureFlag } from "@agent-native/core/feature-flags/registry";
 
 export const FULL_APP_BUILDING = defineFeatureFlag({
   key: "full-app-building",

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

@@ -37,7 +37,7 @@ 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";
+import { defineFeatureFlag } from "@agent-native/core/feature-flags/registry";
 
 export const FULL_APP_BUILDING = defineFeatureFlag({
   key: "full-app-building",

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

@@ -37,7 +37,7 @@ 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";
+import { defineFeatureFlag } from "@agent-native/core/feature-flags/registry";
 
 export const FULL_APP_BUILDING = defineFeatureFlag({
   key: "full-app-building",

package/src/vite/client.ts

@@ -805,6 +805,7 @@ const CORE_CLIENT_SUBPATHS = [
   "@agent-native/core/client/components/RemoteSelectionRings",
   "@agent-native/core/client/visual-style-controls",
   "@agent-native/core/client/feature-flags",
+  "@agent-native/core/feature-flags/registry",
   "@agent-native/core/client/hooks",
   "@agent-native/core/client/host",
   "@agent-native/core/client/i18n",
@@ -1158,6 +1159,10 @@ function getCoreSourceAliases(
       coreSrc,
       "client/feature-flags/index.ts",
     ),
+    "@agent-native/core/feature-flags/registry": path.join(
+      coreSrc,
+      "feature-flags/registry.ts",
+    ),
     "@agent-native/core/client/hooks": path.join(
       coreSrc,
       "client/hooks/index.ts",