@agent-native/core 0.165.4 → 0.167.1

package/dist/resources/handlers.d.ts

@@ -51,8 +51,8 @@ export declare function handleDeleteResource(event: any): Promise<{
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>;
 /** POST /_agent-native/resources/upload — upload a file as a resource */
 export declare function handleUploadResource(event: any): Promise<import("./store.js").Resource | {
@@ -73,10 +73,10 @@ export declare function handleUploadResource(event: any): Promise<import("./stor
     runId: string | null;
     expiresAt: number | null;
     metadata: string | null;
+    error?: undefined;
     url: string;
     provider: string;
     storageSetupRequired?: undefined;
-    error?: undefined;
 } | {
     error: string;
     storageSetupRequired: boolean;

package/dist/secrets/routes.d.ts

@@ -34,37 +34,37 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    ok?: undefined;
     status?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
-    ok?: undefined;
     error: string;
     removed?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
     note?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: undefined;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     note: string;
+    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

package/dist/server/agent-chat/plugin-options.d.ts

@@ -171,8 +171,9 @@ export interface AgentChatPluginOptions {
     }>;
     /**
      * Resolve the exact native action surface for each interactive chat request.
-     * Omitted names are not sent to the model and are not discoverable through
-     * tool-search. When configured, every allowed action is loaded directly.
+     * Omitted allowlist names are not sent to the model or discoverable through
+     * tool-search. Return `{ mode: "default" }` to keep the normal initial-tool
+     * and discovery behavior for a request instead.
      */
     resolveActionSurface?: ProductionAgentOptions["resolveActionSurface"];
     /**

package/dist/server/agent-chat-plugin.js

@@ -13,7 +13,7 @@ import { resolveEngine, createAnthropicEngine, getStoredModelForEngine, normaliz
 import { SYSTEM_PROMPT_CACHE_SPLIT } from "../agent/engine/prompt-cache.js";
 import { PROVIDER_TO_ENV } from "../agent/engine/provider-env-vars.js";
 import { hostedHarnessSystemPrompt } from "../agent/harness/hosted.js";
-import { createProductionAgentHandler, actionsToEngineTools, executeAgentToolCall, filterActionsByAllowedNames, readPersistedActionSurface, toolCallCacheKey, getActiveRunForThreadAsync, abortRunDurably, abortTurnDurably, subscribeToRun, } from "../agent/production-agent.js";
+import { createProductionAgentHandler, actionsToEngineTools, executeAgentToolCall, filterActionsByAllowedNames, normalizeAgentActionSurfaceResolution, readPersistedActionSurface, toolCallCacheKey, getActiveRunForThreadAsync, abortRunDurably, abortTurnDurably, subscribeToRun, } from "../agent/production-agent.js";
 import { callerHasRunAccess, callerHasThreadAccess, } from "../agent/run-ownership.js";
 import { markTurnAborted, readBackgroundRunClaim } from "../agent/run-store.js";
 import { buildCurrentTimeUserContext, buildRuntimeContextPrompt, } from "../agent/runtime-context.js";
@@ -2974,11 +2974,14 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                             ...details,
                             availableActionNames: appActionNames,
                         });
+                        const normalizedSurface = normalizeAgentActionSurfaceResolution(surface);
+                        if (normalizedSurface.mode === "default")
+                            return surface;
                         const localActionNames = details.availableActionNames.filter((name) => localDevActionNames.has(name));
                         return {
                             allowedActionNames: [
                                 ...new Set([
-                                    ...surface.allowedActionNames,
+                                    ...normalizedSurface.allowedActionNames,
                                     ...localActionNames,
                                 ]),
                             ],

package/dist/server/index.d.ts

@@ -15,7 +15,7 @@ export { requireEnvKey, type MissingKeyResponse } from "./missing-key.js";
 export { assertCurrentRequestUserIsOrgAdmin, currentRequestUserIsOrgAdmin, } from "./org-admin.js";
 export { verifyCaptcha, type CaptchaVerifyResult } from "./captcha.js";
 export { getLocaleInitScript, parseAcceptLanguage, resolveLocaleFromRequest, type LocaleInitScriptOptions, type ResolveLocaleFromRequestOptions, type ResolvedRequestLocale, } from "../localization/server.js";
-export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type AgentActionSurface, type AgentActionSurfaceDetails, type ActionTool, type ScriptTool, type AgentMessage, type AgentChatRequest, type AgentChatEvent, type AgentChatAttachment, type AgentChatReference, type MentionProvider, type MentionProviderItem, type AgentLoopFinalResponseGuard, type AgentLoopFinalResponseGuardContext, type AgentLoopFinalResponseGuardResult, type AgentLoopToolCallSummary, type AgentLoopToolResultSummary, } from "../agent/index.js";
+export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type AgentActionSurface, type DefaultAgentActionSurface, type AgentActionSurfaceResolution, type AgentActionSurfaceDetails, type ActionTool, type ScriptTool, type AgentMessage, type AgentChatRequest, type AgentChatEvent, type AgentChatAttachment, type AgentChatReference, type MentionProvider, type MentionProviderItem, type AgentLoopFinalResponseGuard, type AgentLoopFinalResponseGuardContext, type AgentLoopFinalResponseGuardResult, type AgentLoopToolCallSummary, type AgentLoopToolResultSummary, } from "../agent/index.js";
 export { actionsToEngineTools, executeAgentToolCall, getOwnerActiveApiKey, getOwnerApiKeyForEngine, resolveOwnerEngineApiKey, runAgentLoop, type AgentToolCallExecutionResult, type ExecuteAgentToolCallOptions, type ResolvedOwnerApiKey, } from "../agent/production-agent.js";
 export { mountRealtimeVoiceRoutes, realtimeVoiceSafetyIdentifier, REALTIME_VOICE_MAX_SDP_BYTES, REALTIME_VOICE_MAX_TOOL_BODY_BYTES, REALTIME_VOICE_MAX_TOOL_OUTPUT_CHARS, REALTIME_VOICE_SESSION_PATH, REALTIME_VOICE_TOOL_PATH, type MountRealtimeVoiceRoutesOptions, type RealtimeVoiceRequestContext, type RealtimeVoiceToolExecutionRequest, type RealtimeVoiceToolExecutionResult, } from "./realtime-voice.js";
 export { getStoredModelForEngine, resolveEngine, } from "../agent/engine/index.js";

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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

package/dist/vite/agent-native-config-loader.d.ts

@@ -11,6 +11,7 @@ export declare function loadAgentNativeConfigFile(cwd: string): Promise<AgentNat
  */
 export declare function loadWorkspaceAgentNativeConfigFile(cwd: string): Promise<AgentNativeConfigInput | undefined>;
 export declare function loadResolvedAgentNativeConfig(cwd: string, context: AgentNativeConfigContext, options?: {
+    environment?: Record<string, string | undefined>;
     loadProjectConfig?: boolean;
     projectConfig?: AgentNativeConfigInput;
 }): Promise<AgentNativeConfig>;

package/dist/vite/agent-native-config-loader.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { mergeAgentNativeConfigs, normalizeAgentNativeConfig, resolveAgentNativeConfig, } from "../config.js";
+import { mergeAgentNativeConfigs, normalizeAgentNativeConfig, readAgentNativeConfigEnv, resolveAgentNativeConfig, } from "../config.js";
 /** The canonical filename comes first; the remaining names stay compatible. */
 export const AGENT_NATIVE_CONFIG_FILE_CANDIDATES = [
     "agent-native.config.ts",
@@ -79,9 +79,9 @@ export async function loadResolvedAgentNativeConfig(cwd, context, options = {})
         (options.loadProjectConfig === false
             ? undefined
             : await loadAgentNativeConfigFile(cwd));
-    return resolveAgentNativeConfig(mergeAgentNativeConfigs(mergeAgentNativeConfigs(workspaceConfig
+    return resolveAgentNativeConfig(mergeAgentNativeConfigs(mergeAgentNativeConfigs(mergeAgentNativeConfigs(workspaceConfig
         ? resolveAgentNativeConfig(workspaceConfig, context)
-        : {}, readAgentNativeJsonConfig(cwd)), projectConfig ? resolveAgentNativeConfig(projectConfig, context) : {}), context);
+        : {}, readAgentNativeJsonConfig(cwd)), readAgentNativeConfigEnv(options.environment ?? process.env)), projectConfig ? resolveAgentNativeConfig(projectConfig, context) : {}), context);
 }
 function findConfigPath(cwd) {
     return AGENT_NATIVE_CONFIG_FILE_CANDIDATES.map((filename) => path.join(cwd, filename)).find((candidate) => fs.existsSync(candidate));

package/dist/vite/agents-bundle-plugin.d.ts

@@ -1,4 +1,4 @@
-import type { Plugin } from "vite";
+import { type Plugin } from "vite";
 import type { AgentNativeConfigInput } from "../config.js";
 export interface AgentsBundlePluginOptions {
     agentNativeConfig?: AgentNativeConfigInput;

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.1",
   "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.