lua-cli 3.1.0-alpha.3 → 3.1.0-alpha.5

package/dist/types/skill.d.ts

@@ -47,6 +47,24 @@ export declare const env: (key: string) => string | undefined;
  *   }
  * };
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Tool with condition - only available to premium users
+ * class PremiumSearchTool implements LuaTool {
+ *   name = "premium_search";
+ *   description = "Advanced search for premium users";
+ *   inputSchema = z.object({ query: z.string() });
+ *
+ *   // Condition runs before tool is offered to LLM
+ *   condition = async () => {
+ *     const user = await User.get();
+ *     return user.data?.isPremium === true;
+ *   };
+ *
+ *   execute = async (input) => { ... };
+ * }
+ * ```
  */
 export interface LuaTool<TInput extends ZodType = ZodType> {
     /** Unique tool name (alphanumeric, hyphens, underscores only) */
@@ -57,6 +75,8 @@ export interface LuaTool<TInput extends ZodType = ZodType> {
     inputSchema: TInput;
     /** Async function that executes the tool logic */
     execute: (input: any) => Promise<any>;
+    /** Optional async function that determines if the tool should be available */
+    condition?: () => Promise<boolean>;
 }
 /**
  * Lua Skill configuration.
@@ -65,8 +85,6 @@ export interface LuaTool<TInput extends ZodType = ZodType> {
 export interface LuaSkillConfig {
     /** Skill name (optional, defaults to 'unnamed-skill') */
     name?: string;
-    /** Skill version (optional, defaults to '1.0.0') */
-    version?: string;
     /** Short description of the skill (1-2 sentences) */
     description: string;
     /** Detailed context for how the agent should use the tools */
@@ -87,7 +105,6 @@ export interface LuaSkillConfig {
  *
  * const skill = new LuaSkill({
  *   name: 'weather-skill',
- *   version: '1.0.0',
  *   description: "Weather and calculator utilities",
  *   context: "This skill provides weather information and math operations. " +
  *            "Use get_weather for current conditions and calculator for arithmetic.",
@@ -101,7 +118,6 @@ export interface LuaSkillConfig {
 export declare class LuaSkill {
     private readonly tools;
     private readonly name;
-    private readonly version;
     private readonly description;
     private readonly context;
     /**
@@ -109,7 +125,6 @@ export declare class LuaSkill {
      *
      * @param config - Configuration object containing skill metadata
      * @param config.name - Skill name (optional, defaults to 'unnamed-skill')
-     * @param config.version - Skill version (optional, defaults to '1.0.0')
      * @param config.description - Short description of what the skill does (1-2 sentences)
      * @param config.context - Detailed explanation of how the agent should use the tools
      * @param config.tools - Optional array of tools to add immediately
@@ -164,12 +179,8 @@ export type JobSchedule = {
 export interface LuaJobConfig {
     /** Job name (optional, defaults to 'unnamed-job') */
     name?: string;
-    /** Job version (optional, defaults to '1.0.0') */
-    version?: string;
     /** Short description of the job (1-2 sentences) */
     description: string;
-    /** Detailed context for what this job does */
-    context: string;
     /** Schedule configuration - cron, once, or interval */
     schedule: JobSchedule;
     /**
@@ -205,9 +216,7 @@ export interface LuaJobConfig {
  * // Daily cleanup job at 2 AM
  * const dailyCleanup = new LuaJob({
  *   name: 'daily-cleanup',
- *   version: '1.0.0',
  *   description: "Daily database cleanup job",
- *   context: "Runs at 2 AM daily to clean up old records and optimize tables.",
  *   schedule: {
  *     type: 'cron',
  *     expression: '0 2 * * *',  // 2 AM every day
@@ -228,9 +237,7 @@ export interface LuaJobConfig {
  * // One-time job
  * const sendWelcome = new LuaJob({
  *   name: 'send-welcome',
- *   version: '1.0.0',
  *   description: "Send welcome email to new users",
- *   context: "Scheduled one-time task to send welcome emails.",
  *   schedule: {
  *     type: 'once',
  *     executeAt: new Date('2025-12-31T10:00:00Z')
@@ -244,9 +251,7 @@ export interface LuaJobConfig {
  * // Interval-based job (every 5 minutes)
  * const healthCheck = new LuaJob({
  *   name: 'health-check',
- *   version: '1.0.0',
  *   description: "System health check",
- *   context: "Runs every 5 minutes to check system health.",
  *   schedule: {
  *     type: 'interval',
  *     seconds: 300  // 5 minutes
@@ -259,9 +264,7 @@ export interface LuaJobConfig {
  */
 export declare class LuaJob {
     private readonly name;
-    private readonly version;
     private readonly description;
-    private readonly context;
     private readonly schedule;
     private readonly timeout;
     private readonly retry?;
@@ -272,9 +275,7 @@ export declare class LuaJob {
      *
      * @param config - Configuration object containing job metadata
      * @param config.name - Job name (optional, defaults to 'unnamed-job')
-     * @param config.version - Job version (optional, defaults to '1.0.0')
      * @param config.description - Short description of what the job does (1-2 sentences)
-     * @param config.context - Detailed explanation of the job's purpose
      * @param config.schedule - Schedule configuration (cron, once, or interval)
      * @param config.timeout - Optional timeout in seconds (default: 300)
      * @param config.retry - Optional retry configuration
@@ -286,18 +287,10 @@ export declare class LuaJob {
      * Gets the job name.
      */
     getName(): string;
-    /**
-     * Gets the job version.
-     */
-    getVersion(): string;
     /**
      * Gets the job description.
      */
     getDescription(): string;
-    /**
-     * Gets the job context.
-     */
-    getContext(): string;
     /**
      * Gets the job schedule.
      */
@@ -318,6 +311,19 @@ export declare class LuaJob {
      */
     getMetadata(): Record<string, any> | undefined;
 }
+/**
+ * Event payload delivered to webhook execute functions.
+ */
+export interface LuaWebhookEvent {
+    /** Parsed query parameters */
+    query?: Record<string, any>;
+    /** Request headers */
+    headers?: Record<string, any>;
+    /** Request body (JSON or raw data) */
+    body?: any;
+    /** ISO timestamp when the webhook was received */
+    timestamp: string;
+}
 /**
  * Lua Webhook configuration.
  * Used to initialize a new LuaWebhook instance.
@@ -325,12 +331,8 @@ export declare class LuaJob {
 export interface LuaWebhookConfig {
     /** Webhook name (optional, defaults to 'unnamed-webhook') */
     name?: string;
-    /** Webhook version (optional, defaults to '1.0.0') */
-    version?: string;
     /** Short description of the webhook (1-2 sentences) */
     description: string;
-    /** Detailed context for what this webhook does and how it should be used */
-    context: string;
     /** Optional Zod schema for query parameter validation */
     querySchema?: ZodType;
     /** Optional Zod schema for header validation */
@@ -338,7 +340,7 @@ export interface LuaWebhookConfig {
     /** Optional Zod schema for body validation */
     bodySchema?: ZodType;
     /** Function that executes the webhook logic */
-    execute: (query?: any, headers?: any, body?: any) => Promise<any>;
+    execute: (event: LuaWebhookEvent) => Promise<any>;
 }
 /**
  * Lua Webhook class.
@@ -355,10 +357,7 @@ export interface LuaWebhookConfig {
  *
  * const webhook = new LuaWebhook({
  *   name: 'user-created',
- *   version: '1.0.0',
  *   description: "Webhook that handles user creation events",
- *   context: "This webhook processes new user registration events. " +
- *            "It validates the user data and sends welcome emails.",
  *   querySchema: z.object({
  *     source: z.string().optional()
  *   }),
@@ -371,7 +370,8 @@ export interface LuaWebhookConfig {
  *     email: z.string().email(),
  *     name: z.string()
  *   }),
- *   execute: async (query, headers, body) => {
+ *   execute: async (event) => {
+ *     const { query, headers, body } = event;
  *     // Process the webhook...
  *     console.log('New user:', body.email);
  *     return { success: true, userId: body.userId };
@@ -388,9 +388,7 @@ export interface LuaWebhookConfig {
  */
 export declare class LuaWebhook {
     private readonly name;
-    private readonly version;
     private readonly description;
-    private readonly context;
     private readonly querySchema?;
     private readonly headerSchema?;
     private readonly bodySchema?;
@@ -400,9 +398,7 @@ export declare class LuaWebhook {
      *
      * @param config - Configuration object containing webhook metadata
      * @param config.name - Webhook name (optional, defaults to 'unnamed-webhook')
-     * @param config.version - Webhook version (optional, defaults to '1.0.0')
      * @param config.description - Short description of what the webhook does (1-2 sentences)
-     * @param config.context - Detailed explanation of the webhook's purpose and behavior
      * @param config.querySchema - Optional Zod schema for query parameter validation
      * @param config.headerSchema - Optional Zod schema for header validation
      * @param config.bodySchema - Optional Zod schema for body validation
@@ -413,18 +409,10 @@ export declare class LuaWebhook {
      * Gets the webhook name.
      */
     getName(): string;
-    /**
-     * Gets the webhook version.
-     */
-    getVersion(): string;
     /**
      * Gets the webhook description.
      */
     getDescription(): string;
-    /**
-     * Gets the webhook context.
-     */
-    getContext(): string;
     /**
      * Executes the webhook with validated input.
      * Validates query parameters, headers, and body against their respective schemas
@@ -447,18 +435,35 @@ export declare class LuaWebhook {
      */
     execute(query?: Record<string, any>, headers?: Record<string, any>, body?: any): Promise<any>;
 }
+export type PreProcessorAction = 'proceed' | 'block';
+export type PreProcessorBlockResponse = {
+    /** Stop processing immediately */
+    action: 'block';
+    /** Message to show to the user */
+    response: string;
+    /** Optional metadata */
+    metadata?: Record<string, any>;
+};
+export type PreProcessorProceedResponse = {
+    /** Proceed to next preprocessor or agent */
+    action: 'proceed';
+    /** Optional modified message (if not provided, uses original/current message) */
+    modifiedMessage?: import("../interfaces/chat.js").ChatMessage[];
+    /** Optional metadata to pass along */
+    metadata?: Record<string, any>;
+};
+/**
+ * Result returned by the preprocessor
+ */
+export type PreProcessorResult = PreProcessorBlockResponse | PreProcessorProceedResponse;
 /**
  * PreProcessor configuration.
  */
 export interface PreProcessorConfig {
     /** PreProcessor name (optional, defaults to 'unnamed-preprocessor') */
     name?: string;
-    /** PreProcessor version (optional, defaults to '1.0.0') */
-    version?: string;
     /** Short description of the preprocessor */
     description: string;
-    /** Detailed context for what this preprocessor does */
-    context: string;
     /**
      * Async flag - indicates if processor should run in background on server:
      * - true: Run asynchronously (non-blocking, for slow operations like API calls)
@@ -466,11 +471,15 @@ export interface PreProcessorConfig {
      * Default: false (synchronous)
      */
     async?: boolean;
+    /**
+     * Execution priority (lower runs first).
+     * Default: 100
+     */
+    priority?: number;
     /**
      * Function that processes messages before sending to agent.
-     * MUST return ChatMessage[] - array of text, image, or file messages.
      */
-    execute: (user: UserDataInstance, messages: import("../interfaces/chat.js").ChatMessage[], channel: string) => Promise<import("../interfaces/chat.js").ChatMessage[]>;
+    execute: (user: UserDataInstance, messages: import("../interfaces/chat.js").ChatMessage[], channel: string) => Promise<PreProcessorResult>;
 }
 /**
  * PreProcessor class.
@@ -481,41 +490,46 @@ export interface PreProcessorConfig {
  * ```typescript
  * const contentFilter = new PreProcessor({
  *   name: 'content-filter',
- *   version: '1.0.0',
  *   description: 'Filters and processes message content',
- *   context: 'Filters spam, validates images, and adds context',
+ *   priority: 10,
  *   execute: async (user, messages, channel) => {
- *     // Process each message
- *     return messages.map(msg => {
- *       if (msg.type === 'text') {
- *         // Filter spam from text
- *         const filtered = msg.text.replace(/spam/gi, '[filtered]');
- *         return { type: 'text', text: filtered };
- *       }
- *       if (msg.type === 'image') {
- *         // Could validate image, add watermark, etc.
- *         return msg;
- *       }
- *       return msg;
- *     });
+ *     // Check for spam
+ *     const hasSpam = messages.some(msg =>
+ *       msg.type === 'text' && msg.text.includes('spam')
+ *     );
+ *
+ *     if (hasSpam) {
+ *       return {
+ *         action: 'block',
+ *         response: "Message blocked due to spam content"
+ *       };
+ *     }
+ *
+ *     // Return messages to proceed
+ *     return { action: 'proceed' };
  *   }
  * });
  * ```
  */
 export declare class PreProcessor {
     private readonly name;
-    private readonly version;
     private readonly description;
-    private readonly context;
     private readonly asyncMode;
+    private readonly priority;
     private readonly executeFunction;
     constructor(config: PreProcessorConfig);
     getName(): string;
-    getVersion(): string;
     getDescription(): string;
-    getContext(): string;
     getAsync(): boolean;
-    execute(user: UserDataInstance, messages: import("../interfaces/chat.js").ChatMessage[], channel: string): Promise<import("../interfaces/chat.js").ChatMessage[]>;
+    getPriority(): number;
+    execute(user: UserDataInstance, messages: import("../interfaces/chat.js").ChatMessage[], channel: string): Promise<PreProcessorResult>;
+}
+/**
+ * PostProcessor response type.
+ * The execute function must return an object with the modified response.
+ */
+export interface PostProcessorResponse {
+    modifiedResponse: string;
 }
 /**
  * PostProcessor configuration.
@@ -523,24 +537,13 @@ export declare class PreProcessor {
 export interface PostProcessorConfig {
     /** PostProcessor name (optional, defaults to 'unnamed-postprocessor') */
     name?: string;
-    /** PostProcessor version (optional, defaults to '1.0.0') */
-    version?: string;
     /** Short description of the postprocessor */
     description: string;
-    /** Detailed context for what this postprocessor does */
-    context: string;
-    /**
-     * Async flag - indicates if processor should run in background on server:
-     * - true: Run asynchronously (non-blocking, for slow operations like API calls, translations)
-     * - false: Run synchronously (blocking, for fast operations like text formatting)
-     * Default: false (synchronous)
-     */
-    async?: boolean;
     /**
      * Function that processes the agent's response before sending to user.
-     * MUST return string - the formatted response text.
+     * MUST return { modifiedResponse: string } - the formatted response text.
      */
-    execute: (user: UserDataInstance, message: string, response: string, channel: string) => Promise<string>;
+    execute: (user: UserDataInstance, message: string, response: string, channel: string) => Promise<PostProcessorResponse>;
 }
 /**
  * PostProcessor class.
@@ -550,29 +553,105 @@ export interface PostProcessorConfig {
  * ```typescript
  * const responseFormatter = new PostProcessor({
  *   name: 'response-formatter',
- *   version: '1.0.0',
  *   description: 'Formats responses with branding',
- *   context: 'Adds company signature to all responses',
  *   execute: async (user, message, response, channel) => {
- *     return response + '\n\n---\nPowered by Acme Corp';
+ *     return { modifiedResponse: response + '\n\n---\nPowered by Acme Corp' };
  *   }
  * });
  * ```
  */
 export declare class PostProcessor {
     private readonly name;
-    private readonly version;
     private readonly description;
-    private readonly context;
-    private readonly asyncMode;
     private readonly executeFunction;
     constructor(config: PostProcessorConfig);
     getName(): string;
-    getVersion(): string;
     getDescription(): string;
-    getContext(): string;
-    getAsync(): boolean;
-    execute(user: UserDataInstance, message: string, response: string, channel: string): Promise<string>;
+    execute(user: UserDataInstance, message: string, response: string, channel: string): Promise<PostProcessorResponse>;
+}
+/**
+ * MCP Server transport type - determines how to connect to the server.
+ */
+export type MCPTransport = 'stdio' | 'sse';
+/**
+ * Base configuration for all MCP servers.
+ */
+export interface MCPServerBaseConfig {
+    /** Unique identifier for this MCP server */
+    name: string;
+    /** Optional timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+/**
+ * Configuration for stdio-based MCP servers (local execution via npx, node, etc.)
+ */
+export interface MCPStdioServerConfig extends MCPServerBaseConfig {
+    transport: 'stdio';
+    /** Command to execute (e.g., 'npx', 'node') */
+    command: string;
+    /** Arguments to pass to the command */
+    args?: string[];
+    /** Environment variables for the command */
+    env?: Record<string, string>;
+}
+/**
+ * Configuration for SSE/HTTP-based MCP servers (remote endpoints)
+ */
+export interface MCPSSEServerConfig extends MCPServerBaseConfig {
+    transport: 'sse';
+    /** URL of the MCP server endpoint */
+    url: string;
+    /** Optional headers to send with requests (e.g., Authorization) */
+    headers?: Record<string, string>;
+}
+/**
+ * Union type for all MCP server configurations.
+ */
+export type LuaMCPServerConfig = MCPStdioServerConfig | MCPSSEServerConfig;
+/**
+ * LuaMCPServer class.
+ * Defines an MCP (Model Context Protocol) server connection.
+ *
+ * MCP servers provide tools that can be used by your agent at runtime.
+ * You can connect to local servers (via stdio) or remote servers (via SSE/HTTP).
+ *
+ * @example
+ * ```typescript
+ * import { LuaMCPServer } from 'lua-cli';
+ *
+ * // Local MCP server via npx
+ * const wikipediaServer = new LuaMCPServer({
+ *   name: 'wikipedia',
+ *   transport: 'stdio',
+ *   command: 'npx',
+ *   args: ['-y', 'wikipedia-mcp'],
+ *   description: 'Wikipedia search and retrieval'
+ * });
+ *
+ * // Remote MCP server via SSE
+ * const weatherServer = new LuaMCPServer({
+ *   name: 'weather',
+ *   transport: 'sse',
+ *   url: 'https://api.example.com/mcp',
+ *   headers: {
+ *     'Authorization': 'Bearer ${env.WEATHER_API_KEY}'
+ *   },
+ *   description: 'Weather information service'
+ * });
+ * ```
+ */
+export declare class LuaMCPServer {
+    private readonly config;
+    constructor(config: LuaMCPServerConfig);
+    getName(): string;
+    getTransport(): MCPTransport;
+    getTimeout(): number | undefined;
+    getConfig(): LuaMCPServerConfig;
+    /**
+     * Returns the server configuration in a format suitable for serialization.
+     * Environment variable references (${env.VAR_NAME}) are preserved for runtime resolution.
+     */
+    toJSON(): Record<string, any>;
 }
 /**
  * LuaAgent configuration interface.
@@ -587,8 +666,6 @@ export interface LuaAgentConfig {
     name: string;
     /** Agent persona - defines the agent's behavior and personality */
     persona: string;
-    /** Optional welcome message shown when users first interact */
-    welcomeMessage?: string;
     /** Array of skills (each with tools) */
     skills?: LuaSkill[];
     /** Array of webhooks */
@@ -599,6 +676,8 @@ export interface LuaAgentConfig {
     preProcessors?: PreProcessor[];
     /** Array of postprocessors (run after agent generates responses) */
     postProcessors?: PostProcessor[];
+    /** Array of MCP servers (Model Context Protocol) for external tool integrations */
+    mcpServers?: LuaMCPServer[];
 }
 /**
  * LuaAgent class.
@@ -620,7 +699,6 @@ export interface LuaAgentConfig {
  * export const agent = new LuaAgent({
  *   name: 'my-assistant',
  *   persona: 'You are a helpful AI assistant that can manage users and products.',
- *   welcomeMessage: 'Hello! How can I help you today?',
  *   skills: [userSkill],
  *   jobs: [healthCheckJob],
  *   webhooks: [webhookHandler],
@@ -632,32 +710,32 @@ export interface LuaAgentConfig {
 export declare class LuaAgent {
     private readonly name;
     private readonly persona;
-    private readonly welcomeMessage?;
     private readonly skills;
     private readonly webhooks;
     private readonly jobs;
     private readonly preProcessors;
     private readonly postProcessors;
+    private readonly mcpServers;
     /**
      * Creates a new LuaAgent instance.
      *
      * @param config - Agent configuration
      * @param config.name - Agent name
      * @param config.persona - Agent persona (behavior and personality)
-     * @param config.welcomeMessage - Optional welcome message
      * @param config.skills - Optional array of skills
      * @param config.webhooks - Optional array of webhooks
      * @param config.jobs - Optional array of jobs
      * @param config.preProcessors - Optional array of preprocessors
      * @param config.postProcessors - Optional array of postprocessors
+     * @param config.mcpServers - Optional array of MCP servers
      */
     constructor(config: LuaAgentConfig);
     getName(): string;
     getPersona(): string;
-    getWelcomeMessage(): string | undefined;
     getSkills(): LuaSkill[];
     getWebhooks(): LuaWebhook[];
     getJobs(): LuaJob[];
     getPreProcessors(): PreProcessor[];
     getPostProcessors(): PostProcessor[];
+    getMCPServers(): LuaMCPServer[];
 }