@frontmcp/sdk 0.6.2 → 0.7.1

package/common/metadata/agent.metadata.d.ts

@@ -0,0 +1,398 @@
+import { z } from 'zod';
+import { FuncType, Type, Token } from '@frontmcp/di';
+import { ProviderType } from '../interfaces/provider.interface';
+import { PluginType } from '../interfaces/plugin.interface';
+import { AdapterType } from '../interfaces/adapter.interface';
+import { ToolType } from '../interfaces/tool.interface';
+import { ResourceType } from '../interfaces/resource.interface';
+import { PromptType } from '../interfaces/prompt.interface';
+import { ToolInputType, ToolOutputType } from './tool.metadata';
+/**
+ * Agent type definition (class or factory function).
+ * Used in app/plugin metadata for defining agents.
+ */
+export type AgentType<T = unknown> = Type<T> | FuncType<T>;
+declare global {
+    /**
+     * Declarative metadata extends to the McpAgent decorator.
+     * Extends ExtendFrontMcpToolMetadata so agents can use plugin metadata
+     * options (e.g., cache, codecall) since agents are exposed as tools.
+     * Uses interface for declaration merging support.
+     */
+    interface ExtendFrontMcpAgentMetadata extends ExtendFrontMcpToolMetadata {
+    }
+}
+/**
+ * Supported LLM providers for the built-in adapter shorthand.
+ */
+export type AgentLlmProviderType = 'openai' | 'anthropic' | 'google' | 'mistral' | 'groq';
+/**
+ * Helper type for resolving configuration from app config paths.
+ * @example withConfig('llm.openai.apiKey')
+ */
+export interface WithConfig<T = string> {
+    /**
+     * Dot-notation path to resolve from app configuration.
+     * @example 'llm.openai.apiKey' or 'agents.research.model'
+     */
+    configPath: string;
+    /**
+     * Optional transform function to convert the raw config value.
+     */
+    transform?: (value: unknown) => T;
+}
+/**
+ * Factory function to create a WithConfig reference.
+ */
+export declare function withConfig<T = string>(configPath: string, transform?: (value: unknown) => T): WithConfig<T>;
+/**
+ * API key configuration - supports direct string, environment variable, or config path.
+ */
+export type AgentApiKeyConfig = string | {
+    env: string;
+} | WithConfig<string>;
+/**
+ * Built-in provider shorthand configuration.
+ * Use this for quick setup with standard LLM providers.
+ * The SDK will auto-create the appropriate LangChain adapter.
+ */
+export interface AgentLlmBuiltinConfig {
+    /**
+     * LLM provider to use.
+     */
+    provider: AgentLlmProviderType;
+    /**
+     * Model identifier (e.g., 'gpt-4-turbo', 'claude-3-opus').
+     */
+    model: string | WithConfig;
+    /**
+     * API key for the LLM provider.
+     */
+    apiKey: AgentApiKeyConfig;
+    /**
+     * Optional base URL for custom/self-hosted endpoints.
+     */
+    baseUrl?: string | WithConfig;
+    /**
+     * Default temperature for generations (0-2).
+     */
+    temperature?: number;
+    /**
+     * Maximum tokens for responses.
+     */
+    maxTokens?: number;
+}
+/**
+ * Interface for LLM adapter (local type for use in metadata).
+ * Full interface with same name defined in llm-adapter.interface.ts
+ * This is intentionally a separate type to avoid circular dependencies.
+ */
+interface AgentLlmAdapterLocal {
+    completion(prompt: unknown, tools?: unknown[], options?: unknown): Promise<unknown>;
+    streamCompletion?(prompt: unknown, tools?: unknown[], options?: unknown): AsyncGenerator<unknown>;
+}
+/**
+ * Direct adapter instance or factory configuration.
+ * Use this for custom LLM integrations or complex setups.
+ */
+export interface AgentLlmAdapterConfig {
+    /**
+     * Direct adapter instance or factory function.
+     * Factory receives ProviderRegistry for dependency injection.
+     */
+    adapter: AgentLlmAdapterLocal | ((providers: unknown) => AgentLlmAdapterLocal);
+}
+/**
+ * Combined LLM configuration type.
+ * Supports built-in adapters, custom adapters, or DI token injection.
+ *
+ * Note: AgentLlmAdapter is defined in llm-adapter.interface.ts
+ * Use Token<any> here to avoid circular dependency; runtime validation
+ * will check the adapter instance.
+ */
+export type AgentLlmConfig = AgentLlmBuiltinConfig | AgentLlmAdapterConfig | Token<unknown>;
+/**
+ * Configuration for agent swarm capabilities (agent-to-agent communication).
+ */
+export interface AgentSwarmConfig {
+    /**
+     * Whether this agent can see and invoke other agents as tools.
+     * @default false (agents are isolated by default)
+     */
+    canSeeOtherAgents?: boolean;
+    /**
+     * Explicit whitelist of agent IDs this agent can see.
+     * If undefined and canSeeOtherAgents=true, sees all registered agents.
+     */
+    visibleAgents?: string[];
+    /**
+     * Whether this agent is visible to other agents.
+     * @default true (agents are discoverable unless hidden)
+     */
+    isVisible?: boolean;
+    /**
+     * Maximum depth for agent-to-agent calls (prevents infinite loops).
+     * @default 3
+     */
+    maxCallDepth?: number;
+}
+/**
+ * Configuration for agent execution behavior.
+ */
+export interface AgentExecutionConfig {
+    /**
+     * Maximum execution time in milliseconds.
+     * @default 120000 (2 minutes)
+     */
+    timeout?: number;
+    /**
+     * Maximum iterations for the agent loop.
+     * @default 10
+     */
+    maxIterations?: number;
+    /**
+     * Enable streaming responses via SSE/WebSocket.
+     * @default false
+     */
+    enableStreaming?: boolean;
+    /**
+     * Enable MCP notifications for progress updates.
+     * @default true
+     */
+    enableNotifications?: boolean;
+    /**
+     * Interval for progress notifications in milliseconds.
+     * @default 1000
+     */
+    notificationInterval?: number;
+    /**
+     * Whether to inherit parent scope's tools.
+     * @default true
+     */
+    inheritParentTools?: boolean;
+    /**
+     * Whether to execute tools through the call-tool flow (with plugins, hooks, authorization).
+     * When true, tool calls go through the full MCP flow with all middleware.
+     * When false, tools are executed directly for performance-critical scenarios.
+     * @default true
+     */
+    useToolFlow?: boolean;
+    /**
+     * Whether to inherit plugins from the parent scope.
+     * When true, the agent's tools will benefit from standard plugin extensions
+     * (e.g., cache, codecall) registered in the parent scope.
+     * @default true
+     */
+    inheritPlugins?: boolean;
+    /**
+     * Whether to automatically send progress notifications during agent execution.
+     * When true, the agent sends notifications about LLM calls, tool executions,
+     * and completion status via `notifications/progress` and `notifications/message`.
+     * Requires `enableNotifications` to also be true.
+     * @default false (opt-in feature)
+     */
+    enableAutoProgress?: boolean;
+}
+/**
+ * Configuration for exporting agent resources/prompts to parent scope.
+ */
+export interface AgentExportsConfig {
+    /**
+     * Resources to export to parent scope.
+     * Use '*' to export all resources.
+     */
+    resources?: ResourceType[] | '*';
+    /**
+     * Prompts to export to parent scope.
+     * Use '*' to export all prompts.
+     */
+    prompts?: PromptType[] | '*';
+    /**
+     * Providers to export to parent scope.
+     */
+    providers?: ProviderType[];
+}
+/**
+ * Declarative metadata describing an autonomous Agent in FrontMCP.
+ *
+ * Agents are self-contained units with their own LLM provider, isolated scope
+ * (tools, resources, prompts, providers, hooks), and the ability to be invoked
+ * as tools by other agents or the parent app.
+ *
+ * @example
+ * ```typescript
+ * @Agent({
+ *   name: 'research-agent',
+ *   description: 'Researches topics and compiles reports',
+ *   systemInstructions: 'You are a research assistant...',
+ *   llm: {
+ *     adapter: 'openai',
+ *     model: 'gpt-4-turbo',
+ *     apiKey: { env: 'OPENAI_API_KEY' },
+ *   },
+ *   tools: [WebSearchTool, SummarizeTool],
+ *   swarm: { canSeeOtherAgents: true },
+ * })
+ * export default class ResearchAgent extends AgentContext { ... }
+ * ```
+ */
+export interface AgentMetadata<InSchema extends ToolInputType = ToolInputType, OutSchema extends ToolOutputType = ToolOutputType> extends ExtendFrontMcpAgentMetadata {
+    /**
+     * Unique identifier for the agent.
+     * Used for tool routing (use-agent:<id>) and swarm discovery.
+     * If omitted, derived from the class name or 'name' property.
+     */
+    id?: string;
+    /**
+     * Human-readable name of the agent.
+     * This becomes the base for the tool name when the agent is exposed as a tool.
+     */
+    name: string;
+    /**
+     * Description of what the agent does.
+     * Used in tool discovery and as context for LLM system instructions.
+     */
+    description?: string;
+    /**
+     * System instructions for the agent.
+     * Defines the agent's persona, capabilities, and behavior.
+     */
+    systemInstructions?: string;
+    /**
+     * Zod schema for the agent's input (what triggers the agent).
+     * Becomes the tool's inputSchema when agent is exposed as a tool.
+     */
+    inputSchema?: InSchema;
+    /**
+     * Zod schema for the agent's output.
+     * Becomes the tool's outputSchema when agent is exposed as a tool.
+     */
+    outputSchema?: OutSchema;
+    /**
+     * LLM configuration for the agent.
+     * Supports built-in adapters, custom adapters, or DI token injection.
+     */
+    llm: AgentLlmConfig;
+    /**
+     * Agent-scoped providers (dependencies).
+     */
+    providers?: ProviderType[];
+    /**
+     * Agent-scoped plugins for additional capabilities.
+     */
+    plugins?: PluginType[];
+    /**
+     * Agent-scoped adapters for external integrations.
+     */
+    adapters?: AdapterType[];
+    /**
+     * Nested agents - agents inside this agent!
+     * Nested agents are automatically registered as tools within the parent agent's scope.
+     */
+    agents?: AgentType[];
+    /**
+     * Agent-scoped tools available to the agent's LLM.
+     */
+    tools?: ToolType[];
+    /**
+     * Agent-scoped resources.
+     */
+    resources?: ResourceType[];
+    /**
+     * Agent-scoped prompts.
+     */
+    prompts?: PromptType[];
+    /**
+     * Resources, prompts, and providers to export to parent scope.
+     */
+    exports?: AgentExportsConfig;
+    /**
+     * Swarm configuration for agent-to-agent communication.
+     */
+    swarm?: AgentSwarmConfig;
+    /**
+     * Execution configuration.
+     */
+    execution?: AgentExecutionConfig;
+    /**
+     * Tags for categorization and filtering.
+     */
+    tags?: string[];
+    /**
+     * Whether to hide this agent from discovery.
+     * The agent can still be invoked by name if known.
+     * @default false
+     */
+    hideFromDiscovery?: boolean;
+}
+/**
+ * Zod schema for validating AgentMetadata at runtime.
+ */
+export declare const frontMcpAgentMetadataSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    systemInstructions: z.ZodOptional<z.ZodString>;
+    inputSchema: z.ZodOptional<z.ZodCustom<Object, Object>>;
+    outputSchema: z.ZodOptional<z.ZodAny>;
+    llm: z.ZodUnion<readonly [z.ZodObject<{
+        provider: z.ZodEnum<{
+            openai: "openai";
+            anthropic: "anthropic";
+            google: "google";
+            mistral: "mistral";
+            groq: "groq";
+        }>;
+        model: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            configPath: z.ZodString;
+            transform: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+        }, z.core.$strip>]>;
+        apiKey: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            configPath: z.ZodString;
+            transform: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+        }, z.core.$strip>]>;
+        baseUrl: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            configPath: z.ZodString;
+            transform: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>;
+        }, z.core.$strip>]>>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        adapter: z.ZodUnion<readonly [z.ZodCustom<Object, Object>, z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>]>;
+    }, z.core.$strip>, z.ZodCustom<symbol, symbol>, z.ZodCustom<AgentLlmAdapterLocal, AgentLlmAdapterLocal>]>;
+    providers: z.ZodOptional<z.ZodArray<z.ZodCustom<Type<unknown>, Type<unknown>>>>;
+    plugins: z.ZodOptional<z.ZodArray<z.ZodCustom<Type<unknown>, Type<unknown>>>>;
+    adapters: z.ZodOptional<z.ZodArray<z.ZodCustom<Type<unknown>, Type<unknown>>>>;
+    agents: z.ZodOptional<z.ZodArray<z.ZodCustom<AgentType, AgentType>>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodCustom<Type<unknown>, Type<unknown>>>>;
+    resources: z.ZodOptional<z.ZodArray<z.ZodCustom<Type<unknown>, Type<unknown>>>>;
+    prompts: z.ZodOptional<z.ZodArray<z.ZodCustom<Type<unknown>, Type<unknown>>>>;
+    exports: z.ZodOptional<z.ZodObject<{
+        resources: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodAny>, z.ZodLiteral<"*">]>>;
+        prompts: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodAny>, z.ZodLiteral<"*">]>>;
+        providers: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+    }, z.core.$strip>>;
+    swarm: z.ZodOptional<z.ZodObject<{
+        canSeeOtherAgents: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        visibleAgents: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        isVisible: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        maxCallDepth: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, z.core.$strip>>;
+    execution: z.ZodOptional<z.ZodObject<{
+        timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        maxIterations: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        enableStreaming: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        enableNotifications: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        notificationInterval: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        inheritParentTools: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        useToolFlow: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        inheritPlugins: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        enableAutoProgress: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, z.core.$strip>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hideFromDiscovery: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$loose>;
+export {};
+//# sourceMappingURL=agent.metadata.d.ts.map

package/common/metadata/agent.metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.metadata.d.ts","sourceRoot":"","sources":["../../../src/common/metadata/agent.metadata.ts"],"names":[],"mappings":"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"}

package/common/metadata/app.metadata.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { AuthOptions } from '../types';
-import { ProviderType, PromptType, ResourceType, ToolType, AuthProviderType, PluginType, AdapterType } from '../interfaces';
+import { AuthOptionsInput } from '../types';
+import { AgentType, ProviderType, PromptType, ResourceType, ToolType, AuthProviderType, PluginType, AdapterType } from '../interfaces';
 /**
  * Declarative metadata describing what a local mcp app contributes at app scope.
  *
@@ -65,11 +65,18 @@ export interface LocalAppMetadata {
     tools?: ToolType[];
     resources?: ResourceType[];
     prompts?: PromptType[];
+    /**
+     * Autonomous AI agents with their own LLM providers and isolated scopes.
+     * Each agent is automatically exposed as a callable tool with the name
+     * `use-agent:<agent_id>`. Agents can have nested tools, resources, prompts,
+     * and even other agents.
+     */
+    agents?: AgentType[];
     /**
      * Configures the app's default authentication provider.
      * If not provided, the app will use the gateway's default auth provider.
      */
-    auth?: AuthOptions;
+    auth?: AuthOptionsInput;
     /**
      * If true, the app will NOT be included and will act as a separated scope.
      * If false, the app will be included in MultiApp frontmcp server.
@@ -82,13 +89,14 @@ export declare const frontMcpLocalAppMetadataSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
-    providers: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodCustom<import("../interfaces").Type<unknown>, import("../interfaces").Type<unknown>>>>>;
-    authProviders: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodCustom<import("../interfaces").Type<unknown>, import("../interfaces").Type<unknown>>>>>;
-    plugins: z.ZodOptional<z.ZodArray<z.ZodCustom<import("../interfaces").Type<unknown>, import("../interfaces").Type<unknown>>>>;
-    adapters: z.ZodOptional<z.ZodArray<z.ZodCustom<import("../interfaces").Type<unknown>, import("../interfaces").Type<unknown>>>>;
-    tools: z.ZodOptional<z.ZodArray<z.ZodCustom<import("../interfaces").Type<unknown>, import("../interfaces").Type<unknown>>>>;
-    resources: z.ZodOptional<z.ZodArray<z.ZodCustom<import("../interfaces").Type<unknown>, import("../interfaces").Type<unknown>>>>;
-    prompts: z.ZodOptional<z.ZodArray<z.ZodCustom<import("../interfaces").Type<unknown>, import("../interfaces").Type<unknown>>>>;
+    providers: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodCustom<import("libs/di/dist/interfaces/base.interface").Type<unknown>, import("libs/di/dist/interfaces/base.interface").Type<unknown>>>>>;
+    authProviders: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodCustom<import("libs/di/dist/interfaces/base.interface").Type<unknown>, import("libs/di/dist/interfaces/base.interface").Type<unknown>>>>>;
+    plugins: z.ZodOptional<z.ZodArray<z.ZodCustom<import("libs/di/dist/interfaces/base.interface").Type<unknown>, import("libs/di/dist/interfaces/base.interface").Type<unknown>>>>;
+    adapters: z.ZodOptional<z.ZodArray<z.ZodCustom<import("libs/di/dist/interfaces/base.interface").Type<unknown>, import("libs/di/dist/interfaces/base.interface").Type<unknown>>>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodCustom<import("libs/di/dist/interfaces/base.interface").Type<unknown>, import("libs/di/dist/interfaces/base.interface").Type<unknown>>>>;
+    resources: z.ZodOptional<z.ZodArray<z.ZodCustom<import("libs/di/dist/interfaces/base.interface").Type<unknown>, import("libs/di/dist/interfaces/base.interface").Type<unknown>>>>;
+    prompts: z.ZodOptional<z.ZodArray<z.ZodCustom<import("libs/di/dist/interfaces/base.interface").Type<unknown>, import("libs/di/dist/interfaces/base.interface").Type<unknown>>>>;
+    agents: z.ZodOptional<z.ZodArray<z.ZodCustom<AgentType, AgentType>>>;
     auth: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         mode: z.ZodLiteral<"public">;
         issuer: z.ZodOptional<z.ZodString>;
@@ -355,6 +363,80 @@ export declare const frontMcpLocalAppMetadataSchema: z.ZodObject<{
     }, z.core.$strip>]>>;
     standalone: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"includeInParent">, z.ZodBoolean]>>>;
 }, z.core.$loose>;
+/**
+ * Transport options for remote MCP connections
+ */
+export interface RemoteTransportOptions {
+    /**
+     * Request timeout in milliseconds.
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Number of retry attempts for failed requests.
+     * @default 3
+     */
+    retryAttempts?: number;
+    /**
+     * Delay between retries in milliseconds.
+     * @default 1000
+     */
+    retryDelayMs?: number;
+    /**
+     * Whether to fallback to SSE if Streamable HTTP fails.
+     * Only applies to 'url' transport type.
+     * @default true
+     */
+    fallbackToSSE?: boolean;
+    /**
+     * Additional headers to include in all requests.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Static credentials for remote server authentication
+ */
+export interface RemoteStaticCredentials {
+    type: 'bearer' | 'basic' | 'apiKey';
+    value: string;
+    /**
+     * Header name for apiKey type.
+     * @default 'X-API-Key'
+     */
+    headerName?: string;
+}
+/**
+ * Authentication configuration for remote MCP connections.
+ * This controls how the gateway authenticates with the remote server.
+ */
+export type RemoteAuthConfig = {
+    /**
+     * Use static credentials for the remote server.
+     * Good for trusted internal services.
+     */
+    mode: 'static';
+    credentials: RemoteStaticCredentials;
+} | {
+    /**
+     * Forward gateway user's token to remote server.
+     * Enables remote authorization decisions based on gateway user.
+     */
+    mode: 'forward';
+    /**
+     * Specific claim to extract from token (default: entire token)
+     */
+    tokenClaim?: string;
+    /**
+     * Header name to use (default: 'Authorization')
+     */
+    headerName?: string;
+} | {
+    /**
+     * Let remote server handle its own OAuth flow.
+     * No auth headers are added by the gateway.
+     */
+    mode: 'oauth';
+};
 /**
  * Declarative metadata describing what a remote encapsulated mcp app.
  */
@@ -375,20 +457,53 @@ export interface RemoteAppMetadata {
      */
     description?: string;
     /**
-     * The type of the remote app.
-     * - 'worker': The remote app is a worker file.
-     * - 'url': The remote app is a remote URL.
+     * The type of the remote app transport.
+     * - 'url': Standard HTTP MCP server (Streamable HTTP with SSE fallback)
+     * - 'worker': Local worker subprocess
+     * - 'npm': NPM package loaded via esm.sh CDN
+     * - 'esm': Direct ESM module URL
      */
-    urlType: 'worker' | 'url';
+    urlType: 'worker' | 'url' | 'npm' | 'esm';
     /**
-     * The URL of the remote app. This can be a local worker file or a remote URL.
+     * The URL or path for the remote app.
+     * - For 'url': HTTP(S) endpoint (e.g., 'https://api.example.com/mcp')
+     * - For 'worker': Path to worker script (e.g., './workers/my-mcp.js')
+     * - For 'npm': Package specifier (e.g., '@frontmcp/slack-mcp@latest')
+     * - For 'esm': ESM module URL (e.g., 'https://esm.sh/@scope/pkg')
      */
     url: string;
+    /**
+     * Namespace prefix for tools, resources, and prompts from this remote app.
+     * Helps avoid naming conflicts when orchestrating multiple remote servers.
+     * @default Uses app name
+     */
+    namespace?: string;
+    /**
+     * Transport-specific options for the remote connection.
+     */
+    transportOptions?: RemoteTransportOptions;
+    /**
+     * Authentication configuration for the remote server.
+     * Controls how the gateway authenticates with the remote MCP server.
+     */
+    remoteAuth?: RemoteAuthConfig;
     /**
      * Configures the app's default authentication provider.
      * If not provided, the app will use the gateway's default auth provider.
      */
-    auth?: AuthOptions;
+    auth?: AuthOptionsInput;
+    /**
+     * Interval in milliseconds to refresh capabilities from the remote server.
+     * Set to 0 to disable automatic refresh.
+     * @default 0
+     */
+    refreshInterval?: number;
+    /**
+     * TTL in milliseconds for cached capabilities from the remote server.
+     * Capabilities are cached to avoid repeated discovery calls.
+     * @default 60000 (60 seconds)
+     */
+    cacheTTL?: number;
     /**
      * If true, the app will NOT be included and will act as a separated scope.
      * If false, the app will be included in MultiApp frontmcp server.
@@ -404,8 +519,36 @@ export declare const frontMcpRemoteAppMetadataSchema: z.ZodObject<{
     urlType: z.ZodEnum<{
         url: "url";
         worker: "worker";
+        npm: "npm";
+        esm: "esm";
     }>;
     url: z.ZodString;
+    namespace: z.ZodOptional<z.ZodString>;
+    transportOptions: z.ZodOptional<z.ZodObject<{
+        timeout: z.ZodOptional<z.ZodNumber>;
+        retryAttempts: z.ZodOptional<z.ZodNumber>;
+        retryDelayMs: z.ZodOptional<z.ZodNumber>;
+        fallbackToSSE: z.ZodOptional<z.ZodBoolean>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    remoteAuth: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"static">;
+        credentials: z.ZodObject<{
+            type: z.ZodEnum<{
+                bearer: "bearer";
+                basic: "basic";
+                apiKey: "apiKey";
+            }>;
+            value: z.ZodString;
+            headerName: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"forward">;
+        tokenClaim: z.ZodOptional<z.ZodString>;
+        headerName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"oauth">;
+    }, z.core.$strip>], "mode">>;
     auth: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         mode: z.ZodLiteral<"public">;
         issuer: z.ZodOptional<z.ZodString>;
@@ -670,6 +813,9 @@ export declare const frontMcpRemoteAppMetadataSchema: z.ZodObject<{
             userInfoEndpoint: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     }, z.core.$strip>]>>;
+    refreshInterval: z.ZodOptional<z.ZodNumber>;
+    cacheTTL: z.ZodOptional<z.ZodNumber>;
     standalone: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"includeInParent">, z.ZodBoolean]>>>;
 }, z.core.$loose>;
 export type AppMetadata = LocalAppMetadata | RemoteAppMetadata;
+//# sourceMappingURL=app.metadata.d.ts.map

package/common/metadata/app.metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.metadata.d.ts","sourceRoot":"","sources":["../../../src/common/metadata/app.metadata.ts"],"names":[],"mappings":"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"}

package/common/metadata/auth-provider.metadata.d.ts

@@ -21,3 +21,4 @@ export declare const frontMcpAuthProviderMetadataSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     scope: z.ZodDefault<z.ZodOptional<z.ZodEnum<typeof AuthProviderScope>>>;
 }, z.core.$loose>;
+//# sourceMappingURL=auth-provider.metadata.d.ts.map

package/common/metadata/auth-provider.metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-provider.metadata.d.ts","sourceRoot":"","sources":["../../../src/common/metadata/auth-provider.metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED;;GAEG;AACH,oBAAY,iBAAiB;IAC3B,MAAM,WAAW;IACjB,OAAO,YAAY;CACpB;AAED,eAAO,MAAM,kCAAkC;;;;;iBAKa,CAAC"}