@agent-native/core 0.167.4 → 0.168.1

package/dist/vite/package-versions.js

@@ -0,0 +1,97 @@
+import fs from "fs";
+import { createRequire } from "module";
+import path from "path";
+import { fileURLToPath } from "url";
+const AGENT_NATIVE_PACKAGE_PREFIX = "@agent-native/";
+function readPackageManifest(manifestPath) {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        return manifest && typeof manifest === "object"
+            ? manifest
+            : null;
+    }
+    catch {
+        // coercion-ok: missing or malformed manifests are typed absence from the optional version inventory.
+        return null;
+    }
+}
+function dependencyNames(manifest, includeDevDependencies = false) {
+    if (!manifest) {
+        return [];
+    }
+    return [
+        ...Object.keys(manifest.dependencies ?? {}),
+        ...Object.keys(manifest.optionalDependencies ?? {}),
+        ...Object.keys(manifest.peerDependencies ?? {}),
+        ...(includeDevDependencies
+            ? Object.keys(manifest.devDependencies ?? {})
+            : []),
+    ];
+}
+function resolvePackageManifest(packageName, resolutionBase) {
+    let entryPath;
+    const packageRequire = createRequire(path.join(resolutionBase, "package.json"));
+    try {
+        entryPath = packageRequire.resolve(packageName);
+    }
+    catch {
+        if (packageName !== "@agent-native/core") {
+            return null;
+        }
+        const coreManifestPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
+        const coreManifest = readPackageManifest(coreManifestPath);
+        return coreManifest?.name === packageName
+            ? { manifest: coreManifest, manifestPath: coreManifestPath }
+            : null;
+    }
+    let directory = path.dirname(entryPath);
+    for (let depth = 0; depth < 20; depth += 1) {
+        const manifestPath = path.join(directory, "package.json");
+        const manifest = readPackageManifest(manifestPath);
+        if (manifest?.name === packageName) {
+            return { manifest, manifestPath };
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory) {
+            break;
+        }
+        directory = parent;
+    }
+    return null;
+}
+export function resolveAgentNativePackageVersions(cwd) {
+    const appManifest = readPackageManifest(path.join(cwd, "package.json"));
+    const packageNames = new Set([
+        "@agent-native/core",
+        ...dependencyNames(appManifest, true).filter((name) => name.startsWith(AGENT_NATIVE_PACKAGE_PREFIX)),
+    ]);
+    const resolvedVersions = new Map();
+    const queuedPackages = [...packageNames].map((packageName) => ({
+        packageName,
+        resolutionBase: cwd,
+    }));
+    while (queuedPackages.length > 0) {
+        const queuedPackage = queuedPackages.shift();
+        if (!queuedPackage)
+            continue;
+        const resolvedPackage = resolvePackageManifest(queuedPackage.packageName, queuedPackage.resolutionBase);
+        if (!resolvedPackage) {
+            continue;
+        }
+        const { manifest } = resolvedPackage;
+        if (typeof manifest.version === "string" && manifest.version.trim()) {
+            resolvedVersions.set(queuedPackage.packageName, manifest.version.trim());
+        }
+        for (const dependencyName of dependencyNames(manifest)) {
+            if (dependencyName.startsWith(AGENT_NATIVE_PACKAGE_PREFIX) &&
+                !packageNames.has(dependencyName)) {
+                packageNames.add(dependencyName);
+                queuedPackages.push({
+                    packageName: dependencyName,
+                    resolutionBase: path.dirname(resolvedPackage.manifestPath),
+                });
+            }
+        }
+    }
+    return Object.fromEntries([...resolvedVersions.entries()].sort(([left], [right]) => left.localeCompare(right)));
+}

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

@@ -16,13 +16,19 @@ The resolved configuration is serialized into the browser bundle. Treat every
 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. 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.
+This file is the primary home for public, app-owned configuration - the values
+that describe how an app should behave or what capabilities it exposes. Put
+the committed default here first. When the same public setting needs a
+deployment-specific value, the framework accepts a deterministic
+`AGENT_NATIVE_CONFIG*` environment alias as the final override. 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.
+
+The server-only `defineAppConfig()` schema is a deliberate boundary, not a
+second spelling of this file. It configures behavior that must stay out of the
+browser bundle, such as credential scoping, webhook trust, and workspace
+runtime wiring. Its declared environment aliases are documented separately in
+the maintainer environment inventory.
 
 ## File location and loading
 
@@ -109,13 +115,23 @@ 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` |
+| Config path                    | Environment alias                                  |
+| ------------------------------ | -------------------------------------------------- |
+| the whole config               | `AGENT_NATIVE_CONFIG`                              |
+| `onboarding.firstRun`          | `AGENT_NATIVE_CONFIG_ONBOARDING_FIRST_RUN`         |
+| `runtime`                      | `AGENT_NATIVE_CONFIG_RUNTIME`                      |
+| `runtime.auth`                 | `AGENT_NATIVE_CONFIG_RUNTIME_AUTH`                 |
+| `runtime.auth.enabled`         | `AGENT_NATIVE_CONFIG_RUNTIME_AUTH_ENABLED`         |
+| `runtime.database.required`    | `AGENT_NATIVE_CONFIG_RUNTIME_DATABASE_REQUIRED`    |
+| `runtime.environment.required` | `AGENT_NATIVE_CONFIG_RUNTIME_ENVIRONMENT_REQUIRED` |
+| `deployment.environment`       | `AGENT_NATIVE_CONFIG_DEPLOYMENT_ENVIRONMENT`       |
+| `diagnostics.failOnBuild`      | `AGENT_NATIVE_CONFIG_DIAGNOSTICS_FAIL_ON_BUILD`    |
+| `instructions.runtime`         | `AGENT_NATIVE_CONFIG_INSTRUCTIONS_RUNTIME`         |
+| `instructions.development`     | `AGENT_NATIVE_CONFIG_INSTRUCTIONS_DEVELOPMENT`     |
+| `translations.locales`         | `AGENT_NATIVE_CONFIG_TRANSLATIONS_LOCALES`         |
+| `changelog.enabled`            | `AGENT_NATIVE_CONFIG_CHANGELOG_ENABLED`            |
+| `harness`                      | `AGENT_NATIVE_CONFIG_HARNESS`                      |
+| `harness.runtimes`             | `AGENT_NATIVE_CONFIG_HARNESS_RUNTIMES`             |
 
 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
@@ -148,12 +164,16 @@ scoped secret and connection stores.
 ## Configuration vs environment variables
 
 Use the config file or JSON manifest for stable, non-secret application
-defaults. Use environment variables or the scoped secret store for values that
-belong to a deployment or a user or organization connection:
+defaults. Use the canonical config alias when a public value needs a deployment
+override. Use a separate environment variable or the scoped secret store only
+when the value belongs to a deployment, the server, or a user or organization
+connection:
 
 | Put it in                                                             | Examples                                                                                                           | Notes                                                                                                                                               |
 | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `agent-native.config.ts` or the shared section of `agent-native.json` | onboarding mode, required runtime contracts, release lane, shipped locales, changelog, hosted harness capabilities | Committed app policy. It is resolved during the Vite config phase and can use `command`, `mode`, `isDev`, and `isBuild`.                            |
+| `agent-native.config.ts` or the shared section of `agent-native.json` | onboarding mode, required runtime contracts, release lane, shipped locales, changelog, hosted harness capabilities | Committed public app policy. It is resolved during the Vite config phase and can use `command`, `mode`, `isDev`, and `isBuild`.                     |
+| `AGENT_NATIVE_CONFIG_<PATH>`                                          | A deployment-specific public override of one config path                                                           | Final override for the typed/JSON public config. Its value is bundled for the browser, so it is never a secret.                                     |
+| Server-only `defineAppConfig()`                                       | credential scoping, webhook trust, agent runtime controls, workspace wiring                                        | Not serialized into the browser. Its declared aliases are the deliberate exception for server behavior.                                             |
 | Deployment environment variables                                      | `DATABASE_URL`, `BETTER_AUTH_SECRET`, `APP_URL`, `NITRO_PRESET`, provider keys, host-specific toggles              | Set by the deployment platform or local `.env`. Keep secret values out of source control. See [Environment Variables](/docs/environment-variables). |
 | `runtime.environment.required`                                        | `"PUBLIC_API_ORIGIN"`, `"STRIPE_PUBLISHABLE_KEY"`                                                                  | A declaration of names the production readiness check must find. It does not set, expose, or replace the values.                                    |
 
@@ -282,26 +302,28 @@ the same setting as the separate `doctor.failOnBuild` option documented in the
 
 ## Precedence and merge behavior
 
-For a Vite app, the effective shared configuration follows this order:
+For a Vite app, the effective public 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. `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.
+2. A workspace-level typed config, when the app is inside a configured
+   workspace.
+3. `agent-native.json` at the app root.
 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`.
 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`.
-6. For onboarding only, the legacy public Vite variables
+6. `AGENT_NATIVE_CONFIG` and its path aliases from the deployment environment.
+   These are the final public-config overrides. The legacy
+   `AGENT_NATIVE_DEPLOYMENT_ENVIRONMENT` variable remains a fallback for
+   deployment inference only; it does not override an explicit config value.
+7. 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 or its canonical path alias
-   for new work.
+   resolved onboarding mode for backwards compatibility. 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
@@ -319,9 +341,10 @@ The JSON and typed sources are merged by supported nested section:
   supplies it, it replaces the lower-precedence string or mode map as a whole.
 
 For example, JSON can provide `runtime.auth.enabled` and
-`NOTION_API_KEY`, while `agent-native.config.ts` adds `runtime.database.required` and
-`GOOGLE_CLIENT_ID`. The result keeps the auth setting, adds the database
-setting, and checks both environment names.
+`runtime.environment.required: ["NOTION_API_KEY"]`, while
+`agent-native.config.ts` adds `runtime.database.required` and
+`runtime.environment.required: ["GOOGLE_CLIENT_ID"]`. The result keeps the
+auth setting, adds the database setting, and checks both environment names.
 
 ## What is safe to commit
 
@@ -342,8 +365,9 @@ Do not commit these values to either config format:
   vary by environment.
 
 Even a value that is not a secret should stay in deployment configuration when
-it changes between targets. `agent-native.config.ts` should describe the app's
-public shape, not become a second environment-variable file.
+it is a platform fact, a routing detail, or server-only behavior that changes
+between targets. For public app behavior, use the typed config plus its
+canonical deployment alias rather than inventing another standalone variable.
 
 ## `agent-native.json` compatibility
 

package/docs/content/environment-variables.mdx

@@ -12,20 +12,57 @@ deployment system in this repository. Template-only values stay in the
 maintainer inventory; the setup tables below focus on the shared configuration
 most apps need.
 
-For a normal app, start with [Deployment: Environment Variables](/docs/deployment-environment-variables)
-and [Authentication](/docs/authentication). Keep user-, organization-, and
-workspace-scoped credentials in the database-backed secret or connection store;
-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 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
+For a normal app, start with the [Agent-Native app configuration guide](/docs/agent-native-config),
+then use [Deployment: Environment Variables](/docs/deployment-environment-variables)
+and [Authentication](/docs/authentication) for the deliberate environment-only
+parts. Keep user-, organization-, and workspace-scoped credentials in the
+database-backed secret or connection store; use environment variables for
+deploy-level configuration.
+
+For committed, non-secret app defaults, use `agent-native.config.ts` first. If a
+public config value must vary by deployment, use its deterministic
+`AGENT_NATIVE_CONFIG_<PATH>` alias. That alias is the final override of the
+typed/JSON config and also becomes part of the public browser bundle. Do not
+create another standalone Vite-prefixed or Agent-Native-prefixed variable for
+a public setting already represented by the config guide.
+
+## Start with Agent-Native app configuration
+
+The typed config is the primary documentation and default source for public
+app behavior. Its deployment aliases are the standard environment override:
+
+| Config path                    | Deployment override alias                          |
+| ------------------------------ | -------------------------------------------------- |
+| `onboarding.firstRun`          | `AGENT_NATIVE_CONFIG_ONBOARDING_FIRST_RUN`         |
+| `runtime.auth.enabled`         | `AGENT_NATIVE_CONFIG_RUNTIME_AUTH_ENABLED`         |
+| `runtime.database.required`    | `AGENT_NATIVE_CONFIG_RUNTIME_DATABASE_REQUIRED`    |
+| `runtime.environment.required` | `AGENT_NATIVE_CONFIG_RUNTIME_ENVIRONMENT_REQUIRED` |
+| `deployment.environment`       | `AGENT_NATIVE_CONFIG_DEPLOYMENT_ENVIRONMENT`       |
+| `diagnostics.failOnBuild`      | `AGENT_NATIVE_CONFIG_DIAGNOSTICS_FAIL_ON_BUILD`    |
+| `instructions.runtime`         | `AGENT_NATIVE_CONFIG_INSTRUCTIONS_RUNTIME`         |
+| `instructions.development`     | `AGENT_NATIVE_CONFIG_INSTRUCTIONS_DEVELOPMENT`     |
+| `translations.locales`         | `AGENT_NATIVE_CONFIG_TRANSLATIONS_LOCALES`         |
+| `changelog.enabled`            | `AGENT_NATIVE_CONFIG_CHANGELOG_ENABLED`            |
+| `harness`                      | `AGENT_NATIVE_CONFIG_HARNESS`                      |
+| `harness.runtimes`             | `AGENT_NATIVE_CONFIG_HARNESS_RUNTIMES`             |
+
+Use [Agent-Native app configuration](/docs/agent-native-config) for the full
+schema, mode-aware examples, JSON fragments, and precedence rules. The
+resolved public config is bundled into the browser, so it must contain only
+non-secret app policy.
+
+Some non-secret environment variables remain deliberate exceptions because
+they configure server-only behavior, platform facts, routing, or deployment
+secrets. Server-only product controls use the framework's `defineAppConfig()`
+schema and its declared aliases; they are not public `agent-native.config.ts`
+fields. The maintainer inventory's generated **Declared app configuration**
+section is the exhaustive list of those server fields and aliases.
+
+## Server, environment-only, and deployment variables
+
+The table below covers values that belong to the running deployment, a
+server-only config surface, or an environment-only compatibility surface. For
+public app behavior, use the config paths above instead.
 
 | Variable                                       | What it controls                                                                                                                                                        | Supported values or format                                                                                              |
 | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.167.4",
+  "version": "0.168.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": {