@agent-native/core 0.165.4 → 0.167.0

package/dist/vite/agents-bundle-plugin.js

@@ -14,7 +14,9 @@ import fs from "fs";
  * without restarting the server.
  */
 import path from "path";
+import { loadEnv } from "vite";
 import { getWorkspaceCoreExports } from "../deploy/workspace-core.js";
+import { findWorkspaceRoot } from "../scripts/utils.js";
 import { readAgentsBundleFromFs, resolveAgentInstructionPaths, } from "../server/agents-bundle.js";
 import { createAgentNativeConfigContext, loadResolvedAgentNativeConfig, } from "./agent-native-config-loader.js";
 const VIRTUAL_ID = "virtual:agents-bundle";
@@ -72,7 +74,17 @@ export function agentsBundlePlugin(options = {}) {
         name: "agent-native-agents-bundle",
         async configResolved(config) {
             projectRoot = config.root;
-            agentConfigPromise = loadResolvedAgentNativeConfig(projectRoot, createAgentNativeConfigContext(config.command, config.mode), {
+            const mode = config.mode ?? "development";
+            const workspaceRoot = findWorkspaceRoot(projectRoot);
+            const environment = {
+                ...(workspaceRoot && workspaceRoot !== projectRoot
+                    ? loadEnv(mode, workspaceRoot, "")
+                    : {}),
+                ...loadEnv(mode, projectRoot, ""),
+                ...process.env,
+            };
+            agentConfigPromise = loadResolvedAgentNativeConfig(projectRoot, createAgentNativeConfigContext(config.command, mode), {
+                environment,
                 loadProjectConfig: options.agentNativeConfig === undefined,
                 projectConfig: options.agentNativeConfig,
             });

package/dist/vite/client.js

@@ -7,7 +7,7 @@ import { renderDesignSystemThemeCss, } from "@agent-native/toolkit/design-system
 import { loadEnv, } from "vite";
 import { mergePendingChangelog, parsePendingEntry, } from "../changelog/parse.js";
 import { getViteDevRecoveryScript } from "../client/vite-dev-recovery-script.js";
-import { inferAgentNativeDeploymentEnvironment, mergeAgentNativeConfigs, resolveAgentNativeConfig, } from "../config.js";
+import { inferAgentNativeDeploymentEnvironment, mergeAgentNativeConfigs, readAgentNativeConfigEnv, resolveAgentNativeConfig, } from "../config.js";
 import { writeAgentNativeNitroPresetMarker } from "../deploy/nitro-preset.js";
 import { findWorkspaceRoot } from "../scripts/utils.js";
 import { verifyEmbedSessionToken } from "../server/embed-session.js";
@@ -2805,7 +2805,19 @@ function createAgentNativeConfig(options = {}, command, userConfig = {}, mode =
     const cwd = process.cwd();
     const configContext = createAgentNativeConfigContext(command, mode);
     const projectConfigInput = projectConfig ?? options.agentNativeConfig;
-    const appConfig = resolveAgentNativeConfig(mergeAgentNativeConfigs(readAgentNativeJsonConfig(cwd), projectConfigInput
+    // Workspace env fallback. If this app is inside a workspace, tell Vite to
+    // also look for .env files at the workspace root. Per-app .env still wins
+    // (Vite's loadEnv merges in precedence order — app dir is loaded after).
+    const workspaceRoot = findWorkspaceRoot(cwd);
+    const envDir = workspaceRoot && workspaceRoot !== cwd ? workspaceRoot : cwd;
+    const runtimeEnv = {
+        ...(workspaceRoot && workspaceRoot !== cwd
+            ? loadEnv(mode, workspaceRoot, "")
+            : {}),
+        ...loadEnv(mode, cwd, ""),
+        ...process.env,
+    };
+    const appConfig = resolveAgentNativeConfig(mergeAgentNativeConfigs(mergeAgentNativeConfigs(readAgentNativeJsonConfig(cwd), readAgentNativeConfigEnv(runtimeEnv)), projectConfigInput
         ? resolveAgentNativeConfig(projectConfigInput, configContext)
         : {}), configContext);
     const inferredDeploymentEnvironment = appConfig.deployment?.environment ??
@@ -2823,11 +2835,6 @@ function createAgentNativeConfig(options = {}, command, userConfig = {}, mode =
         process.env.CF_PAGES_COMMIT_SHA?.trim() ||
         process.env.AGENT_NATIVE_BUILD_SHA?.trim() ||
         "development";
-    // Workspace env fallback. If this app is inside a workspace, tell Vite to
-    // also look for .env files at the workspace root. Per-app .env still wins
-    // (Vite's loadEnv merges in precedence order — app dir is loaded after).
-    const workspaceRoot = findWorkspaceRoot(cwd);
-    const envDir = workspaceRoot && workspaceRoot !== cwd ? workspaceRoot : cwd;
     // Preload workspace-root .env into process.env so Nitro server code sees
     // shared keys during dev (Nitro reads process.env, not vite's envDir).
     if (workspaceRoot && workspaceRoot !== cwd) {
@@ -2844,13 +2851,6 @@ function createAgentNativeConfig(options = {}, command, userConfig = {}, mode =
         }
         catch { }
     }
-    const runtimeEnv = {
-        ...(workspaceRoot && workspaceRoot !== cwd
-            ? loadEnv(mode, workspaceRoot, "")
-            : {}),
-        ...loadEnv(mode, cwd, ""),
-        ...process.env,
-    };
     reportRuntimeConfigDiagnostics(appConfig, configContext, mode, runtimeEnv);
     const { base } = getConfiguredAppBasePath();
     const isWorkspaceChild = isTruthyRuntimeValue(process.env.AGENT_NATIVE_WORKSPACE) ||

package/docs/content/agent-native-config.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Agent-Native app configuration"
-description: "Configure public Agent-Native app defaults with agent-native.config.ts, its typed aliases, or agent-native.json compatibility."
-search: "agent-native.config.ts agent-native.ts agent-native.mts agent-native.config.mts agent-native.json onboarding runtime readiness configuration instructions"
+description: "Configure public Agent-Native app defaults with agent-native.config.ts, deterministic environment aliases, or agent-native.json compatibility."
+search: "agent-native.config.ts agent-native.ts agent-native.mts agent-native.config.mts agent-native.json AGENT_NATIVE_CONFIG onboarding runtime readiness configuration instructions"
 ---
 
 # Agent-Native app configuration
@@ -17,10 +17,12 @@ value in these files as public. Put credentials and deployment-specific values
 in the environment or the scoped secret store instead.
 
 This file is the home for public, app-owned configuration - the values that
-describe how an app should behave or what capabilities it exposes. It is not a
-second environment-variable file. Environment variables still own secrets,
-provider credentials, database URLs, host-specific values, and other values
-that must change between deployments.
+describe how an app should behave or what capabilities it exposes. Prefer it
+for new non-secret app settings. When the same public setting needs a
+deployment-specific value, the framework also accepts a deterministic
+`AGENT_NATIVE_CONFIG*` environment alias. Environment variables still own
+secrets, provider credentials, database URLs, host-specific values, and other
+server-only values that are not part of this public config.
 
 ## File location and loading
 
@@ -101,6 +103,48 @@ configuration portion of `agent-native.json`:
 | `changelog.enabled`            | `boolean`                                                         | Enables the app changelog workflow and lets agents create user-facing entries.                                                                                                            |
 | `harness`                      | `boolean` or `{ runtimes: string[] }`                             | Enables the hosted tools-only harness, optionally narrowed to `claude-code`, `codex`, `pi`, or `opencode`. See [Harness Agents](/docs/harness-agents).                                    |
 
+## Deterministic environment aliases
+
+Every supported public config path has an environment alias under the
+`AGENT_NATIVE_CONFIG` namespace. Convert each lower-camel-case path segment to
+upper snake case and join segments with underscores:
+
+| Config path            | Environment alias                          |
+| ---------------------- | ------------------------------------------ |
+| the whole config       | `AGENT_NATIVE_CONFIG`                      |
+| `runtime`              | `AGENT_NATIVE_CONFIG_RUNTIME`              |
+| `runtime.auth`         | `AGENT_NATIVE_CONFIG_RUNTIME_AUTH`         |
+| `runtime.auth.enabled` | `AGENT_NATIVE_CONFIG_RUNTIME_AUTH_ENABLED` |
+| `translations.locales` | `AGENT_NATIVE_CONFIG_TRANSLATIONS_LOCALES` |
+
+The whole config, an object section, or a deeply nested object can be supplied
+as one JSON string. Arrays also use JSON strings. More-specific aliases are
+applied after broader aliases, so a leaf or nested fragment can refine a
+whole-config value. Objects merge recursively. Arrays and scalar values are
+replaced by the more-specific alias.
+
+```bash
+AGENT_NATIVE_CONFIG='{"runtime":{"auth":{"enabled":true}}}'
+AGENT_NATIVE_CONFIG_RUNTIME='{"database":{"required":false}}'
+AGENT_NATIVE_CONFIG_RUNTIME_AUTH_ENABLED=false
+AGENT_NATIVE_CONFIG_TRANSLATIONS_LOCALES='["en-US","es-ES"]'
+```
+
+Boolean leaves accept `true`, `false`, `1`, `0`, `yes`, `no`, `on`, and `off`.
+Number leaves accept finite decimal values. String leaves accept normal
+environment strings or JSON-quoted strings. Object and array values must be
+valid JSON of the matching shape. An invalid JSON value or an unknown
+`AGENT_NATIVE_CONFIG*` path fails configuration loading with the offending
+variable name. Unknown keys inside fixed-shape JSON fragments fail as well;
+the per-mode `onboarding.firstRun` map is the intentional dynamic-key
+exception.
+
+These aliases are for public configuration only. Their resolved values are
+serialized into the browser bundle, just like values from
+`agent-native.config.ts`. Do not put API keys, tokens, passwords, database
+URLs, or other secrets in them. Keep those in deployment configuration or the
+scoped secret and connection stores.
+
 ## Configuration vs environment variables
 
 Use the config file or JSON manifest for stable, non-secret application
@@ -243,16 +287,21 @@ For a Vite app, the effective shared configuration follows this order:
 1. Framework defaults. First-run onboarding defaults to `off`; auth and a
    persistent database default to required in production diagnostics.
 2. `agent-native.json` at the app root.
-3. The automatically loaded typed file, if present. The loader checks these
+3. `AGENT_NATIVE_CONFIG` and its path aliases from the deployment environment.
+   The legacy `AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT` variable remains a
+   fallback for deployment inference only; it does not override explicit JSON,
+   typed, or canonical config-alias values.
+4. The automatically loaded typed file, if present. The loader checks these
    candidates in order: `agent-native.config.ts`, `agent-native.ts`,
    `agent-native.mts`, `agent-native.config.mts`.
-4. An explicit `agentNativeConfig` passed to `agentNative()` or the legacy
+5. An explicit `agentNativeConfig` passed to `agentNative()` or the legacy
    `defineConfig()` wrapper. Supplying this option skips automatic typed-file
    loading, while the explicit value still overlays `agent-native.json`.
-5. For onboarding only, the legacy public Vite variables
+6. For onboarding only, the legacy public Vite variables
    `VITE_AGENT_NATIVE_FIRST_RUN_ONBOARDING` and
    `VITE_AGENT_NATIVE_FIRST_RUN_ONBOARDING_SKIP_INTEGRATIONS` can override the
-   resolved onboarding mode. Use the config file for new work.
+   resolved onboarding mode. Use the config file or its canonical path alias
+   for new work.
 
 Use only one of the four typed filenames. If more than one exists, the first
 candidate in the loader's order wins, with `agent-native.config.ts` preferred
@@ -325,7 +374,9 @@ default that never depends on the Vite command or mode:
 ```
 
 For new app-owned configuration, prefer `agent-native.config.ts` when the app needs
-types, a mode-aware factory, or a clear place to evolve public defaults. Keep
+types, a mode-aware factory, or a clear place to evolve public defaults. Use a
+canonical `AGENT_NATIVE_CONFIG_<PATH>` alias only when a non-secret public value
+needs to vary by deployment. Keep
 `agent-native.json` when portability or existing manifest sections are the
 reason to use it. Both formats accept the same shared options shown above.
 

package/docs/content/agent-surfaces.mdx

@@ -188,6 +188,12 @@ createAgentChatPlugin({
 });
 ```
 
+When the same resolver also handles unrestricted chat, return
+`{ mode: "default" }`. This preserves the normal `initialToolNames` filtering
+and `tool-search` discovery instead of loading every available schema on the
+first model request. The explicit mode is preserved across durable
+continuations.
+
 An empty list exposes no native actions. Unknown names fail the request instead
 of widening access. Every allowed action is loaded directly on the first model
 request; include `tool-search` explicitly only when discovery inside the

package/docs/content/environment-variables.mdx

@@ -19,8 +19,11 @@ use environment variables for deploy-level configuration.
 
 For committed, non-secret app defaults such as first-run onboarding, use the
 [Agent-Native app configuration guide](/docs/agent-native-config) instead of
-adding another browser-exposed environment setting. Keep credentials and
-deployment-specific values in the environment or scoped secret store.
+adding another standalone environment setting. If a public config value must
+vary by deployment, use its deterministic `AGENT_NATIVE_CONFIG_<PATH>` alias,
+which also becomes part of the public browser bundle. Keep credentials and
+user-, organization-, or workspace-scoped values in the appropriate secret or
+connection store.
 
 ## Common application and deployment variables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.165.4",
+  "version": "0.167.0",
   "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": {
@@ -427,8 +427,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.32",
     "zod": "^4.3.6",
-    "@agent-native/recap-cli": "0.5.5",
-    "@agent-native/toolkit": "^0.16.8"
+    "@agent-native/recap-cli": "0.5.6",
+    "@agent-native/toolkit": "^0.16.9"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/templates/chat/.agents/skills/secrets/SKILL.md

@@ -38,7 +38,11 @@ connection exists:
   register a `kind: "oauth"` entry so the shared UI renders Connect and the
   runtime owns status, refresh, and reauthorization.
 - **Deploy- or app-level configuration** - use deployment/runtime
-  configuration, not a per-user secret row.
+  configuration, not a per-user secret row. For a non-secret public setting
+  already represented by `AgentNativeConfig`, put the default in
+  `agent-native.config.ts` and use its `AGENT_NATIVE_CONFIG_<PATH>` alias only
+  for a deployment override. Never put a credential or provider key in that
+  public namespace.
 - **Account, customer, manager, or other non-secret identifier** - store it as
   scoped connection metadata or app data, not as a masked secret field.
 

package/src/templates/chat/.agents/skills/workspace-conventions/SKILL.md

@@ -55,7 +55,10 @@ Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
   ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
   storage and persist only URLs, ids, or handles.
 - Store shared runtime configuration in the workspace root `.env`; use
-  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
+  `apps/<app>/.env` only for app-specific overrides. For public app behavior,
+  prefer the default in `agent-native.config.ts` and use the deterministic
+  `AGENT_NATIVE_CONFIG_<UPPER_SNAKE_PATH>` alias only when a non-secret value
+  needs a deployment override. Never hardcode API keys,
   tokens, webhook URLs, signing secrets, private Builder/internal data, customer
   data, or credential-looking literals in source, docs, prompts, fixtures,
   application state, action responses, or generated app content. Use

package/src/templates/chat/actions/navigate.ts

@@ -14,7 +14,7 @@
  */
 
 import { defineAction } from "@agent-native/core/action";
-import { writeAppState } from "@agent-native/core/application-state";
+import { writeAppStateForCurrentTab } from "@agent-native/core/application-state";
 import { z } from "zod";
 
 export default defineAction({
@@ -35,7 +35,7 @@ export default defineAction({
     if (args.path) nav.path = args.path;
     if (args.threadId) nav.threadId = args.threadId;
     nav._writeId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    await writeAppState("navigate", nav);
+    await writeAppStateForCurrentTab("navigate", nav);
     return `Navigating to ${args.view || args.path}`;
   },
 });

package/src/templates/default/.agents/skills/secrets/SKILL.md

@@ -38,7 +38,11 @@ connection exists:
   register a `kind: "oauth"` entry so the shared UI renders Connect and the
   runtime owns status, refresh, and reauthorization.
 - **Deploy- or app-level configuration** - use deployment/runtime
-  configuration, not a per-user secret row.
+  configuration, not a per-user secret row. For a non-secret public setting
+  already represented by `AgentNativeConfig`, put the default in
+  `agent-native.config.ts` and use its `AGENT_NATIVE_CONFIG_<PATH>` alias only
+  for a deployment override. Never put a credential or provider key in that
+  public namespace.
 - **Account, customer, manager, or other non-secret identifier** - store it as
   scoped connection metadata or app data, not as a masked secret field.
 

package/src/templates/default/.agents/skills/workspace-conventions/SKILL.md

@@ -55,7 +55,10 @@ Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
   ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
   storage and persist only URLs, ids, or handles.
 - Store shared runtime configuration in the workspace root `.env`; use
-  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
+  `apps/<app>/.env` only for app-specific overrides. For public app behavior,
+  prefer the default in `agent-native.config.ts` and use the deterministic
+  `AGENT_NATIVE_CONFIG_<UPPER_SNAKE_PATH>` alias only when a non-secret value
+  needs a deployment override. Never hardcode API keys,
   tokens, webhook URLs, signing secrets, private Builder/internal data, customer
   data, or credential-looking literals in source, docs, prompts, fixtures,
   application state, action responses, or generated app content. Use

package/src/templates/headless/.agents/skills/secrets/SKILL.md

@@ -38,7 +38,11 @@ connection exists:
   register a `kind: "oauth"` entry so the shared UI renders Connect and the
   runtime owns status, refresh, and reauthorization.
 - **Deploy- or app-level configuration** - use deployment/runtime
-  configuration, not a per-user secret row.
+  configuration, not a per-user secret row. For a non-secret public setting
+  already represented by `AgentNativeConfig`, put the default in
+  `agent-native.config.ts` and use its `AGENT_NATIVE_CONFIG_<PATH>` alias only
+  for a deployment override. Never put a credential or provider key in that
+  public namespace.
 - **Account, customer, manager, or other non-secret identifier** - store it as
   scoped connection metadata or app data, not as a masked secret field.
 

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

@@ -38,7 +38,11 @@ connection exists:
   register a `kind: "oauth"` entry so the shared UI renders Connect and the
   runtime owns status, refresh, and reauthorization.
 - **Deploy- or app-level configuration** - use deployment/runtime
-  configuration, not a per-user secret row.
+  configuration, not a per-user secret row. For a non-secret public setting
+  already represented by `AgentNativeConfig`, put the default in
+  `agent-native.config.ts` and use its `AGENT_NATIVE_CONFIG_<PATH>` alias only
+  for a deployment override. Never put a credential or provider key in that
+  public namespace.
 - **Account, customer, manager, or other non-secret identifier** - store it as
   scoped connection metadata or app data, not as a masked secret field.
 

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

@@ -55,7 +55,10 @@ Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
   ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
   storage and persist only URLs, ids, or handles.
 - Store shared runtime configuration in the workspace root `.env`; use
-  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
+  `apps/<app>/.env` only for app-specific overrides. For public app behavior,
+  prefer the default in `agent-native.config.ts` and use the deterministic
+  `AGENT_NATIVE_CONFIG_<UPPER_SNAKE_PATH>` alias only when a non-secret value
+  needs a deployment override. Never hardcode API keys,
   tokens, webhook URLs, signing secrets, private Builder/internal data, customer
   data, or credential-looking literals in source, docs, prompts, fixtures,
   application state, action responses, or generated app content. Use