@frontmcp/sdk 0.7.2 → 0.8.0

package/auth/vault/auth-providers.vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-providers.vault.d.ts","sourceRoot":"","sources":["../../../src/auth/vault/auth-providers.vault.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAErG,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C;;GAEG;AACH,qBAAa,kBAAkB;IAI3B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAiB;gBAGtB,SAAS,EAAE,kBAAkB,EAC7B,SAAS,SAAmB,EAC7C,MAAM,CAAC,EAAE,cAAc;IAKzB;;;;;;;;OAQG;IACG,eAAe,CAAC,CAAC,SAAS,UAAU,EACxC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,CAAC,EACb,KAAK,EAAE,eAAe,EACtB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAqBhB;;;;;;;;OAQG;IACG,aAAa,CAAC,CAAC,SAAS,UAAU,EACtC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,eAAe,EACtB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAmCpB;;;;;;;OAOG;IACG,gBAAgB,CACpB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,eAAe,EACtB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;;;;;OAQG;IACG,oBAAoB,CACxB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;;;;;OAQG;IACG,sBAAsB,CAC1B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,EAC1E,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAYhB;;;;;;OAMG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAoD9G;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;CAkBtB;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAkD,KAAK,CAAC,kBAAkB,CAAC,CAAC"}

package/auth/vault/credential-cache.d.ts

@@ -0,0 +1,13 @@
+/**
+ * CredentialCache DI Token
+ *
+ * SDK-specific DI token for CredentialCache.
+ * The CredentialCache class itself is exported from @frontmcp/auth.
+ */
+import { Token } from '@frontmcp/di';
+import type { CredentialCache } from '@frontmcp/auth';
+/**
+ * DI Token for CredentialCache
+ */
+export declare const CREDENTIAL_CACHE: Token<CredentialCache>;
+//# sourceMappingURL=credential-cache.d.ts.map

package/auth/vault/credential-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-cache.d.ts","sourceRoot":"","sources":["../../../src/auth/vault/credential-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAA8C,KAAK,CAAC,eAAe,CAAC,CAAC"}

package/auth/vault/credential-loaders/eager-loader.d.ts

@@ -0,0 +1,46 @@
+/**
+ * EagerCredentialLoader - Loads credentials at session initialization
+ *
+ * Used for providers configured with `loading: 'eager'`.
+ * Credentials are loaded in parallel at session start.
+ */
+import type { CredentialCache, CredentialFactoryContext, ResolvedCredential } from '@frontmcp/auth';
+import type { AuthProvidersRegistry } from '../auth-providers.registry';
+import { FrontMcpLogger } from '../../../common';
+/**
+ * Result of eager loading
+ */
+export interface EagerLoadResult {
+    /** Successfully loaded credentials */
+    loaded: Map<string, ResolvedCredential>;
+    /** Failed provider names with errors */
+    failed: Map<string, Error>;
+    /** Total loading time in ms */
+    duration: number;
+}
+/**
+ * EagerCredentialLoader - Loads credentials at session initialization
+ */
+export declare class EagerCredentialLoader {
+    private readonly registry;
+    private readonly cache;
+    private readonly logger?;
+    constructor(registry: AuthProvidersRegistry, cache: CredentialCache, logger?: FrontMcpLogger);
+    /**
+     * Load all eager credentials for a session.
+     * Called during session initialization.
+     *
+     * @param context - Factory context with session/user info
+     * @returns Map of provider name to resolved credential
+     */
+    loadForSession(context: CredentialFactoryContext): Promise<EagerLoadResult>;
+    /**
+     * Load a single credential
+     */
+    private loadOne;
+    /**
+     * Wrap credential with resolved metadata
+     */
+    private wrapCredential;
+}
+//# sourceMappingURL=eager-loader.d.ts.map

package/auth/vault/credential-loaders/eager-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eager-loader.d.ts","sourceRoot":"","sources":["../../../../src/auth/vault/credential-loaders/eager-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAc,eAAe,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEhH,OAAO,KAAK,EAAE,qBAAqB,EAA4B,MAAM,4BAA4B,CAAC;AAClG,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACxC,wCAAwC;IACxC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC3B,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,qBAAqB;IAI9B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAiB;gBAGtB,QAAQ,EAAE,qBAAqB,EAC/B,KAAK,EAAE,eAAe,EACvC,MAAM,CAAC,EAAE,cAAc;IAKzB;;;;;;OAMG;IACG,cAAc,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,eAAe,CAAC;IAoDjF;;OAEG;YACW,OAAO;IAgBrB;;OAEG;IACH,OAAO,CAAC,cAAc;CAcvB"}

package/auth/vault/credential-loaders/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Credential Loaders - Eager and Lazy credential loading strategies
+ */
+export { EagerCredentialLoader, type EagerLoadResult } from './eager-loader';
+export { LazyCredentialLoader } from './lazy-loader';
+export { extractCredentialExpiry } from '@frontmcp/auth';
+//# sourceMappingURL=index.d.ts.map

package/auth/vault/credential-loaders/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/auth/vault/credential-loaders/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC"}

package/auth/vault/credential-loaders/lazy-loader.d.ts

@@ -0,0 +1,53 @@
+/**
+ * LazyCredentialLoader - Loads credentials on first access
+ *
+ * Used for providers configured with `loading: 'lazy'` (default).
+ * Prevents concurrent loads for the same provider (deduplication).
+ */
+import type { Credential, CredentialFactoryContext, ResolvedCredential } from '@frontmcp/auth';
+import type { NormalizedProviderConfig } from '../auth-providers.registry';
+import { FrontMcpLogger } from '../../../common';
+/**
+ * LazyCredentialLoader - Loads credentials on first access
+ */
+export declare class LazyCredentialLoader {
+    /** In-flight loading promises for deduplication */
+    private readonly loading;
+    private readonly logger?;
+    constructor(logger?: FrontMcpLogger);
+    /**
+     * Load a credential lazily.
+     * If already loading, returns the in-flight promise (deduplication).
+     *
+     * @param config - Provider configuration
+     * @param context - Factory context
+     * @returns Resolved credential or null
+     */
+    load<T extends Credential>(config: NormalizedProviderConfig<T>, context: CredentialFactoryContext): Promise<ResolvedCredential<T> | null>;
+    /**
+     * Perform the actual credential loading
+     */
+    private doLoad;
+    /**
+     * Refresh a credential using the provider's refresh function or factory
+     *
+     * @param config - Provider configuration
+     * @param context - Factory context with existing credential
+     * @returns Refreshed credential or null
+     */
+    refresh<T extends Credential>(config: NormalizedProviderConfig<T>, context: CredentialFactoryContext & {
+        existingCredential: T;
+    }): Promise<ResolvedCredential<T> | null>;
+    /**
+     * Check if a credential is currently being loaded
+     *
+     * @param name - Provider name
+     * @returns true if loading is in progress
+     */
+    isLoading(name: string): boolean;
+    /**
+     * Cancel all in-flight loads (for cleanup)
+     */
+    cancelAll(): void;
+}
+//# sourceMappingURL=lazy-loader.d.ts.map

package/auth/vault/credential-loaders/lazy-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-loader.d.ts","sourceRoot":"","sources":["../../../../src/auth/vault/credential-loaders/lazy-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAE/F,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;GAEG;AACH,qBAAa,oBAAoB;IAC/B,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyD;IACjF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAiB;gBAE7B,MAAM,CAAC,EAAE,cAAc;IAInC;;;;;;;OAOG;IACG,IAAI,CAAC,CAAC,SAAS,UAAU,EAC7B,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC,EACnC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAmBxC;;OAEG;YACW,MAAM;IAsCpB;;;;;;OAMG;IACG,OAAO,CAAC,CAAC,SAAS,UAAU,EAChC,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC,EACnC,OAAO,EAAE,wBAAwB,GAAG;QAAE,kBAAkB,EAAE,CAAC,CAAA;KAAE,GAC5D,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAwCxC;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC;;OAEG;IACH,SAAS,IAAI,IAAI;CAGlB"}

package/auth/vault/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * AuthProviders Vault - Secure credential management for FrontMCP
+ *
+ * This module provides a production-grade credential vault system with:
+ * - Multiple credential types (OAuth, API Keys, SSH, Service Accounts, etc.)
+ * - Session/User/Global scoping
+ * - Lazy and eager loading strategies
+ * - Encrypted storage with zero-knowledge architecture
+ * - Context extension for `this.authProviders` in tools
+ *
+ * @example Register providers
+ * ```typescript
+ * @FrontMcp({
+ *   authProviders: {
+ *     providers: [
+ *       {
+ *         name: 'github',
+ *         scope: 'user',
+ *         loading: 'lazy',
+ *         factory: async (ctx) => ({
+ *           type: 'oauth',
+ *           accessToken: await fetchGitHubToken(ctx.userSub),
+ *           tokenType: 'Bearer',
+ *         }),
+ *       },
+ *     ],
+ *   },
+ * })
+ * class MyServer {}
+ * ```
+ *
+ * @example Use in tools
+ * ```typescript
+ * @Tool({ name: 'my_tool', authProviders: ['github'] })
+ * class MyTool extends ToolContext {
+ *   async execute(input: Input) {
+ *     const headers = await this.authProviders.headers('github');
+ *     return fetch(url, { headers });
+ *   }
+ * }
+ * ```
+ */
+export type { CredentialScope, LoadingStrategy, GetCredentialOptions, ResolvedCredential, CredentialFactoryContext, CredentialFactory, CredentialRefreshFn, CredentialHeadersFn, CredentialProviderConfig, AuthProviderMapping, CredentialCacheEntry, VaultStorageKey, AuthProvidersVaultOptions, CredentialEventType, CredentialEvent, CacheStats, } from '@frontmcp/auth';
+export { credentialScopeSchema, loadingStrategySchema, getCredentialOptionsSchema, credentialProviderConfigSchema, authProviderMappingSchema, authProvidersVaultOptionsSchema, CredentialCache, extractCredentialExpiry, } from '@frontmcp/auth';
+export type { AuthProvidersAccessor } from './auth-providers.accessor';
+export { AUTH_PROVIDERS_ACCESSOR } from './auth-providers.accessor';
+export type { NormalizedProviderConfig } from './auth-providers.registry';
+export { AuthProvidersRegistry, AUTH_PROVIDERS_REGISTRY } from './auth-providers.registry';
+export { AuthProvidersVault, AUTH_PROVIDERS_VAULT } from './auth-providers.vault';
+export { CREDENTIAL_CACHE } from './credential-cache';
+export { EagerCredentialLoader, type EagerLoadResult } from './credential-loaders/eager-loader';
+export { LazyCredentialLoader } from './credential-loaders/lazy-loader';
+export { AuthProvidersAccessorImpl } from './auth-providers.accessor.impl';
+export { createAuthProvidersProviders, isAuthProvidersEnabled, LAZY_CREDENTIAL_LOADER, } from './auth-providers.providers';
+export { authProvidersContextExtension, getAuthProviders, tryGetAuthProviders, } from './auth-providers.context-extension';
+//# sourceMappingURL=index.d.ts.map

package/auth/vault/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/auth/vault/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAGH,YAAY,EACV,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,yBAAyB,EACzB,mBAAmB,EACnB,eAAe,EACf,UAAU,GACX,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,0BAA0B,EAC1B,8BAA8B,EAC9B,yBAAyB,EACzB,+BAA+B,EAC/B,eAAe,EACf,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAGpE,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAG3F,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAGlF,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAChG,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAGxE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAG3E,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACL,6BAA6B,EAC7B,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,oCAAoC,CAAC"}

package/builtin/config/config-resolver.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Context-aware configuration resolution with automatic fallbacks.
+ *
+ * Provides 3-level fallback resolution for entity configuration:
+ * 1. Entity-specific: `{entityType}.{entityName}.{key}`
+ * 2. Entity-type default: `{entityType}.{key}`
+ * 3. Global default: `{key}`
+ *
+ * @example
+ * ```typescript
+ * // For agent 'research-agent' looking for 'openaiKey':
+ * // Tries: agents.research-agent.openaiKey → agents.openaiKey → openaiKey
+ *
+ * const resolver = createContextResolver(configService, {
+ *   entityType: 'agents',
+ *   entityName: 'research-agent',
+ * });
+ *
+ * const apiKey = resolver.get('openaiKey');
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { ConfigService } from './providers/config.service';
+/**
+ * Entity types that support context-aware config resolution.
+ */
+export type ConfigEntityType = 'agents' | 'plugins' | 'adapters';
+/**
+ * Context for resolving configuration with fallbacks.
+ */
+export interface ConfigResolutionContext {
+    /**
+     * Type of entity (agents, plugins, adapters).
+     */
+    entityType: ConfigEntityType;
+    /**
+     * Name of the specific entity.
+     */
+    entityName: string;
+}
+/**
+ * Interface for resolving configuration values.
+ * Used by adapter factory and other components that need config access.
+ */
+export interface ConfigResolver {
+    /**
+     * Get a configuration value by path.
+     * Throws if not found.
+     *
+     * @param path - Dot-notation path (e.g., 'openaiKey')
+     * @returns The resolved value
+     * @throws Error if config key not found
+     */
+    get<T = unknown>(path: string): T;
+    /**
+     * Try to get a configuration value, returning undefined if not found.
+     *
+     * @param path - Dot-notation path
+     * @returns The resolved value or undefined
+     */
+    tryGet<T = unknown>(path: string): T | undefined;
+}
+/**
+ * Normalize an entity name for environment variable lookup.
+ * Converts to uppercase and replaces non-alphanumeric characters with underscores.
+ *
+ * @example
+ * ```typescript
+ * normalizeNameForEnv('research-agent') // 'RESEARCH_AGENT'
+ * normalizeNameForEnv('my agent')       // 'MY_AGENT'
+ * normalizeNameForEnv('plugin.name')    // 'PLUGIN_NAME'
+ * ```
+ */
+export declare function normalizeNameForEnv(name: string): string;
+/**
+ * Normalize a config path for nested object lookup.
+ * Replaces non-alphanumeric characters (except dots) with underscores in each segment.
+ *
+ * @example
+ * ```typescript
+ * normalizePathSegment('research-agent') // 'research_agent'
+ * ```
+ */
+export declare function normalizePathSegment(segment: string): string;
+/**
+ * Generate fallback paths for a config key based on entity context.
+ *
+ * Creates a 3-level fallback chain:
+ * 1. `{entityType}.{entityName}.{key}` - Entity-specific
+ * 2. `{entityType}.{key}` - Entity-type default
+ * 3. `{key}` - Global default
+ *
+ * @param key - The config key to look up
+ * @param context - Entity context (type and name)
+ * @returns Array of paths to try in order
+ *
+ * @example
+ * ```typescript
+ * generateFallbacks('openaiKey', { entityType: 'agents', entityName: 'research-agent' })
+ * // Returns: ['agents.research_agent.openaiKey', 'agents.openaiKey', 'openaiKey']
+ * ```
+ */
+export declare function generateFallbacks(key: string, context: ConfigResolutionContext): string[];
+/**
+ * Generate environment variable names for fallback lookup.
+ *
+ * Creates environment variable names matching the fallback paths:
+ * 1. `{ENTITY_TYPE}_{ENTITY_NAME}_{KEY}` - Entity-specific
+ * 2. `{ENTITY_TYPE}_{KEY}` - Entity-type default
+ * 3. `{KEY}` - Global default
+ *
+ * Note: Keys are converted to uppercase with non-alphanumeric chars replaced by underscores.
+ * CamelCase keys like 'openaiKey' become 'OPENAIKEY' (no word-boundary detection).
+ *
+ * @param key - The config key
+ * @param context - Entity context
+ * @returns Array of env var names to try
+ *
+ * @example
+ * ```typescript
+ * generateEnvFallbacks('openaiKey', { entityType: 'agents', entityName: 'research-agent' })
+ * // Returns: ['AGENTS_RESEARCH_AGENT_OPENAIKEY', 'AGENTS_OPENAIKEY', 'OPENAIKEY']
+ * ```
+ */
+export declare function generateEnvFallbacks(key: string, context: ConfigResolutionContext): string[];
+/**
+ * Resolve a config value with fallbacks.
+ * Tries each path in order until a value is found.
+ *
+ * @param config - ConfigService instance
+ * @param paths - Paths to try in order
+ * @returns The first found value, or undefined if none found
+ */
+export declare function resolveWithFallbacks<T>(config: ConfigService<Record<string, unknown>>, paths: string[]): T | undefined;
+/**
+ * Create a ConfigResolver that uses entity context for auto-fallbacks.
+ *
+ * @param config - ConfigService instance
+ * @param context - Entity context for generating fallbacks
+ * @returns ConfigResolver with fallback support
+ *
+ * @example
+ * ```typescript
+ * const resolver = createContextResolver(configService, {
+ *   entityType: 'agents',
+ *   entityName: 'research-agent',
+ * });
+ *
+ * // Tries: agents.research_agent.openaiKey → agents.openaiKey → openaiKey
+ * const apiKey = resolver.get('openaiKey');
+ * ```
+ */
+export declare function createContextResolver(config: ConfigService<Record<string, unknown>>, context: ConfigResolutionContext): ConfigResolver;
+/**
+ * Create a simple ConfigResolver without fallbacks (direct lookup only).
+ *
+ * @param config - ConfigService instance
+ * @returns ConfigResolver with direct lookup
+ */
+export declare function createDirectResolver(config: ConfigService<Record<string, unknown>>): ConfigResolver;
+//# sourceMappingURL=config-resolver.d.ts.map

package/builtin/config/config-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-resolver.d.ts","sourceRoot":"","sources":["../../../src/builtin/config/config-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAMhE;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,UAAU,EAAE,gBAAgB,CAAC;IAE7B;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC;IAElC;;;;;OAKG;IACH,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAClD;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,GAAG,MAAM,EAAE,CASzF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,GAAG,MAAM,EAAE,CAW5F;AAMD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC9C,KAAK,EAAE,MAAM,EAAE,GACd,CAAC,GAAG,SAAS,CASf;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC9C,OAAO,EAAE,uBAAuB,GAC/B,cAAc,CAehB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,cAAc,CAenG"}

package/builtin/config/config.plugin.d.ts

@@ -0,0 +1,63 @@
+import { DynamicPlugin, ProviderType } from '../../common';
+import type { ConfigPluginOptions, ConfigPluginOptionsInput } from './config.types';
+/**
+ * ConfigPlugin - Environment variable management for FrontMCP.
+ *
+ * Provides typed access to configuration with convict-style nested path support.
+ * Loads from .env files, YAML config files, and validates with Zod schemas.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (flat env vars)
+ * @FrontMcp({
+ *   plugins: [
+ *     ConfigPlugin.init({
+ *       envPath: '.env',
+ *       localEnvPath: '.env.local',
+ *     }),
+ *   ],
+ * })
+ * class MyServer {}
+ *
+ * // With typed schema (convict-style)
+ * import { z } from 'zod';
+ *
+ * const configSchema = z.object({
+ *   database: z.object({
+ *     url: z.string(),
+ *     port: z.number().default(5432),
+ *   }),
+ *   debug: z.boolean().default(false),
+ * });
+ *
+ * @FrontMcp({
+ *   plugins: [
+ *     ConfigPlugin.init({
+ *       schema: configSchema,
+ *       basePath: __dirname,
+ *     }),
+ *   ],
+ * })
+ * class ProductionServer {}
+ *
+ * // In a tool:
+ * class MyTool extends ToolContext {
+ *   async execute(input) {
+ *     // Typed access with dot notation
+ *     const dbUrl = this.config.getOrThrow('database.url');
+ *     const port = this.config.get('database.port', 5432);
+ *     const debug = this.config.get('debug');
+ *   }
+ * }
+ * ```
+ */
+export default class ConfigPlugin<TConfig extends object = Record<string, string>> extends DynamicPlugin<ConfigPluginOptions<TConfig>, ConfigPluginOptionsInput<TConfig>> {
+    static defaultOptions: ConfigPluginOptions;
+    options: ConfigPluginOptions<TConfig>;
+    constructor(options?: ConfigPluginOptionsInput<TConfig>);
+    /**
+     * Dynamic providers based on plugin options.
+     */
+    static dynamicProviders: <T extends object>(options: ConfigPluginOptionsInput<T>) => ProviderType[];
+}
+//# sourceMappingURL=config.plugin.d.ts.map

package/builtin/config/config.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.plugin.d.ts","sourceRoot":"","sources":["../../../src/builtin/config/config.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAU,YAAY,EAAiB,MAAM,cAAc,CAAC;AAClF,OAAO,KAAK,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAMpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAaH,MAAM,CAAC,OAAO,OAAO,YAAY,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAE,SAAQ,aAAa,CACtG,mBAAmB,CAAC,OAAO,CAAC,EAC5B,wBAAwB,CAAC,OAAO,CAAC,CAClC;IACC,MAAM,CAAC,cAAc,EAAE,mBAAmB,CAQxC;IAEF,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;gBAE1B,OAAO,GAAE,wBAAwB,CAAC,OAAO,CAAM;IAQ3D;;OAEG;IACH,OAAgB,gBAAgB,GAAI,CAAC,SAAS,MAAM,EAAE,SAAS,wBAAwB,CAAC,CAAC,CAAC,KAAG,YAAY,EAAE,CAmEzG;CACH"}

package/builtin/config/config.symbols.d.ts

@@ -0,0 +1,7 @@
+import { Reference } from '../../common';
+import type { ConfigPluginOptions } from './config.types';
+/**
+ * DI token for the plugin configuration.
+ */
+export declare const ConfigPluginConfigToken: Reference<ConfigPluginOptions>;
+//# sourceMappingURL=config.symbols.d.ts.map

package/builtin/config/config.symbols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.symbols.d.ts","sourceRoot":"","sources":["../../../src/builtin/config/config.symbols.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,CAAC,mBAAmB,CAEhC,CAAC"}

package/builtin/config/config.types.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+/**
+ * Options for ConfigPlugin initialization.
+ */
+export interface ConfigPluginOptions<TConfig extends object = Record<string, string>> {
+    /**
+     * Zod schema defining the configuration structure.
+     * When provided, enables:
+     * - Type inference for config paths
+     * - Automatic env var mapping (database.url -> DATABASE_URL)
+     * - Schema validation with defaults
+     */
+    schema?: z.ZodType<TConfig>;
+    /**
+     * Path to the .env file.
+     * @default '.env'
+     */
+    envPath?: string;
+    /**
+     * Path to local override file.
+     * Local file takes precedence over base env file.
+     * @default '.env.local'
+     */
+    localEnvPath?: string;
+    /**
+     * Path to YAML config file.
+     * @default 'config.yml'
+     */
+    configPath?: string;
+    /**
+     * Whether to load .env files.
+     * Set to false if env is already loaded (e.g., by CLI).
+     * @default true
+     */
+    loadEnv?: boolean;
+    /**
+     * Whether to load YAML config file.
+     * @default false
+     */
+    loadYaml?: boolean;
+    /**
+     * Whether to populate process.env with loaded values.
+     * @default true
+     */
+    populateProcessEnv?: boolean;
+    /**
+     * Whether to throw on validation errors.
+     * @default true
+     */
+    strict?: boolean;
+    /**
+     * Base path for resolving .env and config files.
+     * @default process.cwd()
+     */
+    basePath?: string;
+}
+/**
+ * Input options (what users provide to init()).
+ * All fields are optional since we have defaults.
+ */
+export type ConfigPluginOptionsInput<T extends object = Record<string, string>> = Partial<ConfigPluginOptions<T>>;
+/**
+ * Parsed and validated environment configuration.
+ */
+export interface ParsedEnvConfig {
+    /** Raw environment variables (string values) */
+    raw: Record<string, string>;
+    /** Parsed values (if schema provided) */
+    parsed?: Record<string, unknown>;
+}
+//# sourceMappingURL=config.types.d.ts.map

package/builtin/config/config.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.types.d.ts","sourceRoot":"","sources":["../../../src/builtin/config/config.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAClF;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAE5B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;AAElH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC"}

package/builtin/config/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Built-in ConfigPlugin for environment variable management.
+ *
+ * Provides typed access to configuration with convict-style nested path support.
+ * Loads from .env files, YAML config files, and validates with Zod schemas.
+ *
+ * @example
+ * ```typescript
+ * import { FrontMcp, App, ConfigPlugin } from '@frontmcp/sdk';
+ * import { z } from 'zod';
+ *
+ * // Define configuration schema
+ * const configSchema = z.object({
+ *   database: z.object({
+ *     url: z.string().describe('Database URL'),
+ *     port: z.number().default(5432).describe('Database port'),
+ *   }),
+ *   debug: z.boolean().default(false),
+ * });
+ *
+ * @FrontMcp({
+ *   plugins: [
+ *     ConfigPlugin.init({
+ *       schema: configSchema,
+ *       basePath: __dirname,
+ *     }),
+ *   ],
+ * })
+ * class MyServer {}
+ *
+ * // In tools:
+ * class MyTool extends ToolContext {
+ *   async execute(input) {
+ *     // Typed access with dot notation
+ *     const dbUrl = this.config.getOrThrow('database.url');
+ *     const port = this.config.get('database.port', 5432);
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { default as ConfigPlugin } from './config.plugin';
+export type { ConfigPluginOptions, ConfigPluginOptionsInput, ParsedEnvConfig } from './config.types';
+export { ConfigService, ConfigMissingError, ConfigValidationError } from './providers/config.service';
+export { loadConfig, deepMerge } from './providers/config-loader';
+export type { ConfigLoaderOptions } from './providers/config-loader';
+export { loadEnvFiles, parseEnvContent, parseEnvContentSync, populateProcessEnv, pathToEnvKey, setNestedValue, getNestedValue, extractSchemaPaths, mapEnvToNestedConfig, } from './providers/env-loader';
+export { ConfigPluginConfigToken } from './config.symbols';
+export { ConfigEntityType, ConfigResolutionContext, ConfigResolver, normalizeNameForEnv, normalizePathSegment, generateFallbacks, generateEnvFallbacks, resolveWithFallbacks, createContextResolver, createDirectResolver, } from './config-resolver';
+import { ConfigService } from './providers/config.service';
+/**
+ * Get the ConfigService from an execution context.
+ * Alternative to `this.config` for explicit function-style access.
+ *
+ * @throws Error if ConfigPlugin is not installed
+ */
+export declare function getConfig<T extends {
+    get: (token: unknown) => unknown;
+}>(ctx: T): ConfigService;
+/**
+ * Try to get the ConfigService, returning undefined if not available.
+ * Use this for graceful degradation when the plugin might not be installed.
+ */
+export declare function tryGetConfig<T extends {
+    tryGet?: (token: unknown) => unknown;
+}>(ctx: T): ConfigService | undefined;
+//# sourceMappingURL=index.d.ts.map

package/builtin/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/builtin/config/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAGH,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG1D,YAAY,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGrG,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGtG,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAClE,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAGrE,OAAO,EACL,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAG3D,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS;IAAE,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;CAAE,EAAE,GAAG,EAAE,CAAC,GAAG,aAAa,CAE/F;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS;IAAE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;CAAE,EAAE,GAAG,EAAE,CAAC,GAAG,aAAa,GAAG,SAAS,CAKlH"}

package/builtin/config/providers/config-loader.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+/**
+ * Options for the config loader.
+ */
+export interface ConfigLoaderOptions {
+    /** Base path for resolving files (default: process.cwd()) */
+    basePath?: string;
+    /** Path to .env file (default: '.env') */
+    envPath?: string;
+    /** Path to local override file (default: '.env.local') */
+    localEnvPath?: string;
+    /** Path to YAML config file (default: 'config.yml') */
+    configPath?: string;
+    /** Whether to load .env files (default: true) */
+    loadEnv?: boolean;
+    /** Whether to load YAML config (default: false - opt-in) */
+    loadYaml?: boolean;
+    /** Whether to populate process.env (default: true) */
+    populateProcessEnv?: boolean;
+}
+/**
+ * Load configuration from multiple sources and merge.
+ * Priority: env > yaml > schema defaults
+ *
+ * @param schema - Zod schema defining the configuration structure
+ * @param options - Loader options
+ * @returns Validated and merged configuration
+ */
+export declare function loadConfig<T extends object>(schema: z.ZodType<T>, options?: ConfigLoaderOptions): Promise<T>;
+/**
+ * Deep merge two objects, with source values taking precedence.
+ * Arrays are replaced, not merged.
+ */
+declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
+export { deepMerge };
+//# sourceMappingURL=config-loader.d.ts.map

package/builtin/config/providers/config-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../../../src/builtin/config/providers/config-loader.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sDAAsD;IACtD,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,MAAM,EAC/C,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,CAAC,CAAC,CAmDZ;AA2BD;;;GAGG;AACH,iBAAS,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyB5G;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}