@frontmcp/sdk 0.6.3 → 0.7.2

package/common/interfaces/server.interface.d.ts

@@ -53,3 +53,4 @@ export declare abstract class FrontMcpServer {
      */
     abstract start(port?: number): Promise<void> | void;
 }
+//# sourceMappingURL=server.interface.d.ts.map

package/common/interfaces/server.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.interface.d.ts","sourceRoot":"","sources":["../../../src/common/interfaces/server.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,cAAc,IAAI,kBAAkB,EAAE,MAAM,MAAM,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1F,qBAAa,aAAc,SAAQ,eAAe;IACxC,MAAM,EAAE,UAAU,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACL,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IACzC,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B;AAED,8BAAsB,cAAe,SAAQ,kBAAkB;IAC7D,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;IAE7C,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI;IAEjC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI;IAEjC,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAEpC,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;CACrD;AAED,MAAM,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEhD,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEnH,8BAAsB,cAAc;IAClC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAEnG;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAE7G;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CACtB,OAAO,EAAE,oBAAoB,GAC5B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAEhE;;;OAGG;IACH,QAAQ,CAAC,OAAO,IAAI,IAAI;IAExB;;OAEG;IACH,QAAQ,CAAC,UAAU,IAAI,OAAO;IAE9B;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;CACpD"}

package/common/interfaces/session-hook.interface.d.ts

@@ -129,3 +129,4 @@ export declare enum SessionHookStage {
      */
     onMetrics = "onMetrics"
 }
+//# sourceMappingURL=session-hook.interface.d.ts.map

package/common/interfaces/session-hook.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-hook.interface.d.ts","sourceRoot":"","sources":["../../../src/common/interfaces/session-hook.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,oBAAY,gBAAgB;IAC1B;;;;;;OAMG;IACH,iBAAiB,sBAAsB;IAEvC;;;;OAIG;IACH,gBAAgB,qBAAqB;IAErC;;;;OAIG;IACH,iBAAiB,sBAAsB;IAIvC;;;;OAIG;IACH,aAAa,kBAAkB;IAE/B;;;;OAIG;IACH,aAAa,kBAAkB,CAAE,kCAAkC;IAEnE;;;;;;OAMG;IACH,iBAAiB,sBAAsB;IAEvC;;;;;OAKG;IACH,iBAAiB,sBAAsB;IAEvC;;;;OAIG;IACH,eAAe,oBAAoB;IAInC;;;;OAIG;IACH,cAAc,mBAAmB;IAEjC;;;;OAIG;IACH,aAAa,kBAAkB;IAI/B;;;OAGG;IACH,kBAAkB,uBAAuB;IAEzC;;;OAGG;IACH,iBAAiB,sBAAsB;IAIvC;;;;;OAKG;IACH,YAAY,iBAAiB;IAE7B;;;;;;OAMG;IACH,OAAO,YAAY;IAEnB;;;;OAIG;IACH,SAAS,cAAc;IAEvB;;;;OAIG;IACH,QAAQ,aAAa;IAErB;;;;;;OAMG;IACH,SAAS,cAAc;CACxB"}

package/common/interfaces/tool-hook.interface.d.ts

@@ -78,3 +78,4 @@ export declare enum ToolHookStage {
     /** Always runs at the very end (success or error). Cleanup/releases here. */
     willFinalizeInvoke = "willFinalizeInvoke"
 }
+//# sourceMappingURL=tool-hook.interface.d.ts.map

package/common/interfaces/tool-hook.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-hook.interface.d.ts","sourceRoot":"","sources":["../../../src/common/interfaces/tool-hook.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,oBAAY,aAAa;IACvB;gEAC4D;IAC5D,iBAAiB,sBAAsB;IAEvC,uFAAuF;IACvF,uBAAuB,4BAA4B;IAEnD,0EAA0E;IAC1E,sBAAsB,2BAA2B;IAEjD,kFAAkF;IAClF,aAAa,kBAAkB;IAE/B,8FAA8F;IAC9F,gBAAgB,qBAAqB;IAErC,oFAAoF;IACpF,qBAAqB,0BAA0B;IAI/C,+EAA+E;IAC/E,gBAAgB,qBAAqB;IAErC,0EAA0E;IAC1E,eAAe,oBAAoB;IAEnC,2EAA2E;IAC3E,oBAAoB,yBAAyB;IAE7C,wDAAwD;IACxD,mBAAmB,wBAAwB;IAI3C,8EAA8E;IAC9E,cAAc,mBAAmB;IAEjC,sEAAsE;IACtE,iBAAiB,sBAAsB;IAEvC,2EAA2E;IAC3E,kBAAkB,uBAAuB;IAEzC,+DAA+D;IAC/D,eAAe,oBAAoB;IAEnC,2EAA2E;IAC3E,iBAAiB,sBAAsB;IAIvC,gFAAgF;IAChF,aAAa,kBAAkB;IAE/B,0EAA0E;IAC1E,WAAW,gBAAgB;IAE3B,2EAA2E;IAC3E,YAAY,iBAAiB;IAE7B,wDAAwD;IACxD,cAAc,mBAAmB;IAIjC,mHAAmH;IACnH,aAAa,kBAAkB;IAE/B,4EAA4E;IAC5E,WAAW,gBAAgB;IAE3B,gFAAgF;IAChF,UAAU,eAAe;IAIzB,8EAA8E;IAC9E,gBAAgB,qBAAqB;IAErC,2EAA2E;IAC3E,kBAAkB,uBAAuB;IAEzC,mFAAmF;IACnF,mBAAmB,wBAAwB;IAI3C,oFAAoF;IACpF,OAAO,YAAY;IAEnB,gEAAgE;IAChE,QAAQ,aAAa;IAErB,uEAAuE;IACvE,SAAS,cAAc;IAEvB,+DAA+D;IAC/D,QAAQ,aAAa;IAErB,mDAAmD;IACnD,SAAS,cAAc;IAIvB,yFAAyF;IACzF,OAAO,YAAY;IAEnB,6EAA6E;IAC7E,kBAAkB,uBAAuB;CAC1C"}

package/common/interfaces/tool.interface.d.ts

@@ -1,8 +1,8 @@
-import { FuncType, Type } from './base.interface';
+import { FuncType, Type } from '@frontmcp/di';
 import { ToolInputType, ToolMetadata, ToolOutputType } from '../metadata';
 import { ToolInputOf, ToolOutputOf } from '../decorators';
 import { ExecutionContextBase, ExecutionContextBaseArgs } from './execution-context.interface';
-import type { AIPlatformType, ClientInfo } from '../../notification';
+import type { AIPlatformType, ClientInfo, McpLoggingLevel } from '../../notification';
 export type ToolType<T = any> = Type<T> | FuncType<T>;
 type HistoryEntry<T> = {
     at: number;
@@ -13,6 +13,8 @@ type HistoryEntry<T> = {
 export type ToolCtorArgs<In> = ExecutionContextBaseArgs & {
     metadata: ToolMetadata;
     input: In;
+    /** Progress token from the request's _meta, used for progress notifications */
+    progressToken?: string | number;
 };
 export declare abstract class ToolContext<InSchema extends ToolInputType = ToolInputType, OutSchema extends ToolOutputType = ToolOutputType, In = ToolInputOf<{
     inputSchema: InSchema;
@@ -28,6 +30,7 @@ export declare abstract class ToolContext<InSchema extends ToolInputType = ToolI
     private _output?;
     private readonly _inputHistory;
     private readonly _outputHistory;
+    private readonly _progressToken?;
     constructor(args: ToolCtorArgs<In>);
     abstract execute(input: In): Promise<Out>;
     get input(): In;
@@ -37,6 +40,52 @@ export declare abstract class ToolContext<InSchema extends ToolInputType = ToolI
     set output(v: Out | undefined);
     get outputHistory(): ReadonlyArray<HistoryEntry<Out>>;
     respond(value: Out): never;
+    /**
+     * Send a notification message to the current session.
+     * Uses 'notifications/message' per MCP 2025-11-25 spec.
+     *
+     * @param message - The notification message (string) or structured data (object)
+     * @param level - Log level: 'debug', 'info', 'warning', or 'error' (default: 'info')
+     * @returns true if the notification was sent, false if session unavailable
+     *
+     * @example
+     * ```typescript
+     * async execute(input: Input): Promise<Output> {
+     *   await this.notify('Starting processing...', 'info');
+     *   await this.notify({ step: 1, total: 5, status: 'in_progress' });
+     *   // ... processing
+     *   await this.notify('Processing complete', 'info');
+     *   return result;
+     * }
+     * ```
+     */
+    protected notify(message: string | Record<string, unknown>, level?: McpLoggingLevel): Promise<boolean>;
+    /**
+     * Send a progress notification to the current session.
+     * Uses 'notifications/progress' per MCP 2025-11-25 spec.
+     *
+     * Only works if the client requested progress updates by including a
+     * progressToken in the request's _meta field. If no progressToken was
+     * provided, this method logs a debug message and returns false.
+     *
+     * @param progress - Current progress value (should increase monotonically)
+     * @param total - Total progress value (optional)
+     * @param message - Progress message (optional)
+     * @returns true if the notification was sent, false if no progressToken or session
+     *
+     * @example
+     * ```typescript
+     * async execute(input: Input): Promise<Output> {
+     *   const items = input.items;
+     *   for (let i = 0; i < items.length; i++) {
+     *     await this.progress(i + 1, items.length, `Processing item ${i + 1}`);
+     *     await processItem(items[i]);
+     *   }
+     *   return { processed: items.length };
+     * }
+     * ```
+     */
+    protected progress(progress: number, total?: number, message?: string): Promise<boolean>;
     /**
      * Get the detected AI platform type for the current session.
      * This is auto-detected from the client info during MCP initialization.
@@ -73,3 +122,4 @@ export declare abstract class ToolContext<InSchema extends ToolInputType = ToolI
     get clientInfo(): ClientInfo | undefined;
 }
 export {};
+//# sourceMappingURL=tool.interface.d.ts.map

package/common/interfaces/tool.interface.d.ts.map

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

package/common/metadata/adapter.metadata.d.ts

@@ -12,3 +12,4 @@ export declare const frontMcpAdapterMetadataSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
+//# sourceMappingURL=adapter.metadata.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.metadata.d.ts","sourceRoot":"","sources":["../../../src/common/metadata/adapter.metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAGD,eAAO,MAAM,6BAA6B;;;;iBAIa,CAAC"}

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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"}