Repository navigation
@agent-native/core@0.159.0
Minor Changes
-
d003981: Add
defineAppConfig()andgetAppConfig()— one zod schema undersrc/app-config/that owns server-side configuration, so a value can be set in typed app code instead of only through an environment variable. Environment variables become declared.meta({ env })aliases into a schema field, parsed and validated in one place rather than at each call site, and resolve below explicit app configuration. A field can declare several aliases in precedence order, which is how one concept with many historical spellings collapses to a single declared ladder.Five domains are declared so far, replacing roughly thirty hand-rolled
process.envreads:privateBlob—providerselects which registered provider is active, replacing the implicit "first one whoseisConfigured()returns true in module import order" rule (still the fallback when unset), and throwing when the named provider is not registered.publicUploadFallbackreplaces a setter and an environment variable whose precedence was decided by statement order insideputPrivateBlob.setPrivateBlobPublicUploadFallbackEnabledis deprecated but keeps working, now with a stated position in the ladder.app—id,workspaceId,name,packageName, andtemplatereplace nine fallback chains across agent chat, SSO, credential scoping, onboarding, the CLI, data programs, durable background dispatch, and workspace OAuth. They stay separate fields on purpose:vault_grantsrows are written with the workspace-assigned id, so credential scoping keeps preferring it, andnameis a display name rather than an identifier. None has a default, so an app with no configured identity is still denied a credential grant lookup instead of resolving one scoped to an app literally namedapp.agent—engine,model,mode,preferBringYourOwnKey,runSoftTimeoutMs,completedRunRetentionMs,erroredRunRetentionMs.resolveEngine's documented resolution order is unchanged andcreateAgentChatPlugin({ model })keeps working; the explicit option stays a function parameter above the declared field.a2aandintegrations—allowUnsignedInternalandallowUnverifiedWebhooks, the latter replacing three byte-identical copies of the same check in the telegram, whatsapp, and email webhook adapters.workspace—gatewayUrlandoauthOrigin. Together withapp.urlthese retire theVITE_mirrors of the URL keys: the prefix only ever answered "how does this value reach the browser", so the value is now one declared field and delivery goes throughwindow.__AGENT_NATIVE_CONFIG__alongside the existing Sentry, PostHog, and realtime scripts.
Two self-dispatch bugs are fixed along the way.
integrations/webhook-handler.tsandintegrations/a2a-continuation-processor.tseach carried their own copy of "resolve my own base URL"; both omittedDEPLOY_PRIME_URL, so a Netlify deploy preview dispatched background work to production, and the continuation copy silently fell back tohttp://localhost:${PORT}in production, where the request never arrives and the work is dropped with no error. Both now delegate toresolveSelfDispatchBaseUrl.A new guard keeps the surface from growing back:
pnpm guard:no-legacy-configfails when a line this branch adds readsprocess.envinpackages/core/srcoutside the four resolvers, or calls a deprecated entry point. Opt out per line with// config-ok: <reason>.Declared configuration now generates its own documentation:
pnpm sync:config-docswrites the field table intodocs/environment-variables.md, andpnpm guard:config-docsfails when it is stale.Malformed values in migrated keys now fail at startup naming the key, instead of silently reading as
falseor falling back to a default. This affectsAGENT_ENGINE_PREFER_BYO_KEY,A2A_ALLOW_UNSIGNED_INTERNAL,AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS, and the three agent run timeout/retention keys.