lua-cli 3.15.3 → 3.16.0

package/dist/types/skill.d.ts

@@ -1,1079 +0,0 @@
-/**
- * Lua Skill System
- * Core types and classes for building Lua AI skills
- */
-import { ZodType } from 'zod';
-import UserDataInstance from '../instances/user.instance.js';
-import { JobInstance } from '../instances/job.instance.js';
-import type { LuaRequest } from '../interfaces/lua.js';
-import type { PersonaText, SkillContextText } from '@lua/shared-types';
-/**
- * Safe environment variable access function.
- * Gets injected at runtime with skill-specific environment variables.
- *
- * Checks process environment variables (.env file)
- *
- * @param key - The environment variable key to retrieve
- * @returns The environment variable value or undefined if not found
- *
- * @example
- * ```typescript
- * const baseUrl = env('BASE_URL');
- * const apiKey = env('API_KEY');
- * ```
- */
-export declare const env: (key: string) => string | undefined;
-/**
- * Lua Tool interface.
- * Defines the structure of a tool that can be added to a LuaSkill.
- *
- * @template TInput - Zod schema type for input validation
- *
- * @example
- * ```typescript
- * import { z } from 'zod';
- * import { LuaTool } from 'lua-cli';
- *
- * const weatherTool: LuaTool = {
- *   name: 'get_weather',
- *   description: 'Gets current weather for a city',
- *   inputSchema: z.object({
- *     city: z.string(),
- *     units: z.enum(['metric', 'imperial']).optional()
- *   }),
- *   execute: async (input) => {
- *     // Fetch weather data...
- *     return { temperature: 72, condition: 'sunny' };
- *   }
- * };
- * ```
- *
- * @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) */
-    name: string;
-    /** Description of what the tool does */
-    description: string;
-    /** Zod schema for input validation */
-    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.
- * Used to initialize a new LuaSkill instance.
- */
-export interface LuaSkillConfig {
-    /** Skill name (optional, defaults to 'unnamed-skill') */
-    name?: string;
-    /** Short description of the skill (1-2 sentences) */
-    description: string;
-    /** Detailed context for how the agent should use the tools */
-    context: SkillContextText;
-    /** Optional array of tools to add during construction */
-    tools?: LuaTool<any>[];
-}
-/**
- * Lua Skill class.
- * Main class for building AI skills with tools.
- *
- * A skill is a collection of tools that the AI agent can use to accomplish tasks.
- * Tools are functions with validated inputs and well-defined outputs.
- *
- * @example
- * ```typescript
- * import { LuaSkill } from 'lua-cli';
- *
- * const skill = new LuaSkill({
- *   name: 'weather-skill',
- *   description: "Weather and calculator utilities",
- *   context: "This skill provides weather information and math operations. " +
- *            "Use get_weather for current conditions and calculator for arithmetic.",
- *   tools: [weatherTool, calculatorTool]
- * });
- *
- * // Or add tools after construction
- * skill.addTool(anotherTool);
- * ```
- */
-export declare class LuaSkill {
-    private readonly tools;
-    private readonly name;
-    private readonly description;
-    private readonly context;
-    /**
-     * Creates a new LuaSkill instance.
-     *
-     * @param config - Configuration object containing skill metadata
-     * @param config.name - Skill name (optional, defaults to 'unnamed-skill')
-     * @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
-     */
-    constructor(config: LuaSkillConfig);
-    getContext(): SkillContextText;
-    /**
-     * Adds a single tool to the skill.
-     * Tool name is validated before being added.
-     *
-     * @param tool - Tool to add
-     * @throws Error if tool name is invalid
-     */
-    addTool<TInput extends ZodType>(tool: LuaTool<TInput>): void;
-    /**
-     * Adds multiple tools to the skill.
-     * All tool names are validated before being added.
-     *
-     * @param tools - Array of tools to add
-     * @throws Error if any tool name is invalid
-     */
-    addTools(tools: LuaTool<any>[]): void;
-    /**
-     * Executes a tool by name with provided input.
-     * Input is validated against the tool's Zod schema.
-     *
-     * @param input - Input object containing tool name and parameters
-     * @param input.tool - Name of the tool to execute
-     * @returns Promise resolving to tool execution result
-     * @throws Error if tool not found or input validation fails
-     */
-    run(input: Record<string, any>): Promise<any>;
-}
-/**
- * Job schedule configuration
- * Supports either cron-style recurring schedules or one-time execution
- */
-export type JobSchedule = {
-    type: 'cron';
-    expression: string;
-    timezone?: string;
-} | {
-    type: 'once';
-    executeAt: Date | string;
-} | {
-    type: 'interval';
-    seconds: number;
-};
-/**
- * Lua Job configuration.
- * Used to initialize a new LuaJob instance.
- */
-export interface LuaJobConfig {
-    /** Job name (optional, defaults to 'unnamed-job') */
-    name?: string;
-    /** Short description of the job (1-2 sentences) */
-    description: string;
-    /** Schedule configuration - cron, once, or interval */
-    schedule: JobSchedule;
-    /**
-     * Function that executes the job logic.
-     * Receives metadata as parameter for accessing job configuration.
-     */
-    execute: (job: JobInstance) => Promise<any>;
-    /** Optional timeout in seconds (default: 300) */
-    timeout?: number;
-    /** Optional retry configuration */
-    retry?: {
-        maxAttempts: number;
-        backoffSeconds?: number;
-    };
-    /**
-     * Optional metadata for the job.
-     * Can store any custom data (tags, config, context, etc.)
-     * Sent to server and accessible during execution.
-     */
-    metadata?: Record<string, any>;
-}
-/**
- * Lua Job class.
- * Main class for building scheduled jobs (cron jobs, one-time tasks, intervals).
- *
- * A job is a scheduled task that executes at specific times or intervals.
- * Jobs can run once, on a recurring schedule (cron), or at fixed intervals.
- *
- * @example
- * ```typescript
- * import { LuaJob } from 'lua-cli';
- *
- * // Daily cleanup job at 2 AM
- * const dailyCleanup = new LuaJob({
- *   name: 'daily-cleanup',
- *   description: "Daily database cleanup job",
- *   schedule: {
- *     type: 'cron',
- *     expression: '0 2 * * *',  // 2 AM every day
- *     timezone: 'America/New_York'
- *   },
- *   timeout: 600, // 10 minutes
- *   retry: {
- *     maxAttempts: 3,
- *     backoffSeconds: 60
- *   },
- *   execute: async () => {
- *     // Cleanup logic
- *     console.log('Running cleanup...');
- *     return { recordsDeleted: 150 };
- *   }
- * });
- *
- * // One-time job
- * const sendWelcome = new LuaJob({
- *   name: 'send-welcome',
- *   description: "Send welcome email to new users",
- *   schedule: {
- *     type: 'once',
- *     executeAt: new Date('2025-12-31T10:00:00Z')
- *   },
- *   execute: async () => {
- *     console.log('Sending welcome emails...');
- *     return { emailsSent: 100 };
- *   }
- * });
- *
- * // Interval-based job (every 5 minutes)
- * const healthCheck = new LuaJob({
- *   name: 'health-check',
- *   description: "System health check",
- *   schedule: {
- *     type: 'interval',
- *     seconds: 300  // 5 minutes
- *   },
- *   execute: async () => {
- *     return { status: 'healthy' };
- *   }
- * });
- * ```
- */
-export declare class LuaJob {
-    private readonly name;
-    private readonly description;
-    private readonly schedule;
-    private readonly timeout;
-    private readonly retry?;
-    private readonly metadata?;
-    private readonly executeFunction;
-    /**
-     * Creates a new LuaJob instance.
-     *
-     * @param config - Configuration object containing job metadata
-     * @param config.name - Job name (optional, defaults to 'unnamed-job')
-     * @param config.description - Short description of what the job does (1-2 sentences)
-     * @param config.schedule - Schedule configuration (cron, once, or interval)
-     * @param config.timeout - Optional timeout in seconds (default: 300)
-     * @param config.retry - Optional retry configuration
-     * @param config.metadata - Optional metadata for the job
-     * @param config.execute - Function that processes the job (receives job instance as parameter)
-     */
-    constructor(config: LuaJobConfig);
-    /**
-     * Gets the job name.
-     */
-    getName(): string;
-    /**
-     * Gets the job description.
-     */
-    getDescription(): string;
-    /**
-     * Gets the job schedule.
-     */
-    getSchedule(): JobSchedule;
-    /**
-     * Gets the job timeout in seconds.
-     */
-    getTimeout(): number;
-    /**
-     * Gets the retry configuration.
-     */
-    getRetry(): {
-        maxAttempts: number;
-        backoffSeconds?: number;
-    } | undefined;
-    /**
-     * Gets the job metadata.
-     */
-    getMetadata(): Record<string, any> | undefined;
-    /**
-     * Executes the job with the provided job instance.
-     * @param job - Job instance with metadata and context
-     * @returns Promise resolving to job execution result
-     */
-    execute(job: JobInstance): Promise<any>;
-}
-/**
- * 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.
- */
-export interface LuaWebhookConfig {
-    /** Webhook name (optional, defaults to 'unnamed-webhook') */
-    name?: string;
-    /** Short description of the webhook (1-2 sentences) */
-    description: string;
-    /** Optional Zod schema for query parameter validation */
-    querySchema?: ZodType;
-    /** Optional Zod schema for header validation */
-    headerSchema?: ZodType;
-    /** Optional Zod schema for body validation */
-    bodySchema?: ZodType;
-    /** Function that executes the webhook logic */
-    execute: (event: LuaWebhookEvent) => Promise<any>;
-}
-/**
- * Lua Webhook class.
- * Main class for building webhooks with validated inputs.
- *
- * A webhook is an HTTP endpoint that can receive requests with validated
- * query parameters, headers, and body. The execute function processes the
- * validated input and returns a response.
- *
- * @example
- * ```typescript
- * import { LuaWebhook } from 'lua-cli';
- * import { z } from 'zod';
- *
- * const webhook = new LuaWebhook({
- *   name: 'user-created',
- *   description: "Webhook that handles user creation events",
- *   querySchema: z.object({
- *     source: z.string().optional()
- *   }),
- *   headerSchema: z.object({
- *     'x-api-key': z.string(),
- *     'content-type': z.string().optional()
- *   }),
- *   bodySchema: z.object({
- *     userId: z.string(),
- *     email: z.string().email(),
- *     name: z.string()
- *   }),
- *   execute: async (event) => {
- *     const { query, headers, body } = event;
- *     // Process the webhook...
- *     console.log('New user:', body.email);
- *     return { success: true, userId: body.userId };
- *   }
- * });
- *
- * // Execute the webhook with validated inputs
- * const result = await webhook.execute(
- *   { source: 'mobile' },
- *   { 'x-api-key': 'secret-key' },
- *   { userId: '123', email: 'user@example.com', name: 'John' }
- * );
- * ```
- */
-export declare class LuaWebhook {
-    private readonly name;
-    private readonly description;
-    private readonly querySchema?;
-    private readonly headerSchema?;
-    private readonly bodySchema?;
-    private readonly executeFunction;
-    /**
-     * Creates a new LuaWebhook instance.
-     *
-     * @param config - Configuration object containing webhook metadata
-     * @param config.name - Webhook name (optional, defaults to 'unnamed-webhook')
-     * @param config.description - Short description of what the webhook does (1-2 sentences)
-     * @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
-     * @param config.execute - Function that processes the webhook request
-     */
-    constructor(config: LuaWebhookConfig);
-    /**
-     * Gets the webhook name.
-     */
-    getName(): string;
-    /**
-     * Gets the webhook description.
-     */
-    getDescription(): string;
-    /**
-     * Executes the webhook with validated input.
-     * Validates query parameters, headers, and body against their respective schemas
-     * before executing the webhook function.
-     *
-     * @param query - Query parameters object
-     * @param headers - Headers object
-     * @param body - Request body
-     * @returns Promise resolving to webhook execution result
-     * @throws Error if validation fails for any input
-     *
-     * @example
-     * ```typescript
-     * const result = await webhook.execute(
-     *   { limit: '10' },
-     *   { 'x-api-key': 'secret' },
-     *   { data: 'value' }
-     * );
-     * ```
-     */
-    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;
-    /** Short description of the preprocessor */
-    description: string;
-    /**
-     * Async flag - indicates if processor should run in background on server:
-     * - true: Run asynchronously (non-blocking, for slow operations like API calls)
-     * - false: Run synchronously (blocking, for fast operations like text filtering)
-     * Default: false (synchronous)
-     */
-    async?: boolean;
-    /**
-     * Execution priority (lower runs first).
-     * Default: 100
-     */
-    priority?: number;
-    /**
-     * Function that processes messages before sending to agent.
-     */
-    execute: (user: UserDataInstance, messages: import('../interfaces/chat.js').ChatMessage[], channel: string) => Promise<PreProcessorResult>;
-}
-/**
- * PreProcessor class.
- * Processes user messages before they reach the agent.
- * Can handle rich content (text, images, files).
- *
- * @example
- * ```typescript
- * const contentFilter = new PreProcessor({
- *   name: 'content-filter',
- *   description: 'Filters and processes message content',
- *   priority: 10,
- *   execute: async (user, messages, channel) => {
- *     // 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 description;
-    private readonly asyncMode;
-    private readonly priority;
-    private readonly executeFunction;
-    constructor(config: PreProcessorConfig);
-    getName(): string;
-    getDescription(): string;
-    getAsync(): boolean;
-    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.
- */
-export interface PostProcessorConfig {
-    /** PostProcessor name (optional, defaults to 'unnamed-postprocessor') */
-    name?: string;
-    /** Short description of the postprocessor */
-    description: string;
-    /**
-     * Execution priority (lower runs first).
-     * Default: 100
-     */
-    priority?: number;
-    /**
-     * Function that processes the agent's response before sending to user.
-     * MUST return { modifiedResponse: string } - the formatted response text.
-     */
-    execute: (user: UserDataInstance, message: string, response: string, channel: string) => Promise<PostProcessorResponse>;
-}
-/**
- * PostProcessor class.
- * Processes agent responses before they reach the user.
- *
- * @example
- * ```typescript
- * const responseFormatter = new PostProcessor({
- *   name: 'response-formatter',
- *   description: 'Formats responses with branding',
- *   execute: async (user, message, response, channel) => {
- *     return { modifiedResponse: response + '\n\n---\nPowered by Acme Corp' };
- *   }
- * });
- * ```
- */
-export declare class PostProcessor {
-    private readonly name;
-    private readonly description;
-    private readonly priority;
-    private readonly executeFunction;
-    constructor(config: PostProcessorConfig);
-    getName(): string;
-    getDescription(): string;
-    getPriority(): number;
-    execute(user: UserDataInstance, message: string, response: string, channel: string): Promise<PostProcessorResponse>;
-}
-/**
- * MCP Server transport type - determines how to connect to the server.
- *
- * - 'streamable-http': Modern MCP standard (recommended) - single endpoint for bidirectional communication
- * - 'sse': Legacy Server-Sent Events transport - for older MCP servers
- *
- * Note: 'stdio' transport is not supported yet.
- */
-export type MCPTransport = 'sse' | 'streamable-http';
-/**
- * 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;
-}
-/**
- * Function type for resolving environment variables at runtime.
- * Use env() inside to access agent environment variables.
- *
- * @example
- * ```typescript
- * env: () => ({
- *   API_KEY: env("MY_API_KEY"),
- *   DEBUG: "true"
- * })
- * ```
- */
-export type EnvResolverFunction = () => Record<string, string>;
-/**
- * Function type for resolving headers at runtime.
- * Use env() inside to access agent environment variables.
- *
- * @example
- * ```typescript
- * headers: () => ({
- *   'Authorization': `Bearer ${env("API_TOKEN")}`
- * })
- * ```
- */
-export type HeadersResolverFunction = () => Record<string, string>;
-/**
- * Function type for resolving URL at runtime.
- * Use env() inside to access agent environment variables.
- *
- * @example
- * ```typescript
- * url: () => env("MCP_SERVER_URL") || "https://default.example.com/mcp"
- * ```
- */
-export type UrlResolverFunction = () => string;
-/**
- * Configuration for SSE-based MCP servers (legacy remote endpoints)
- *
- * Use this for older MCP servers that don't support Streamable HTTP.
- * For new integrations, prefer MCPStreamableHttpServerConfig.
- */
-export interface MCPSSEServerConfig extends MCPServerBaseConfig {
-    transport: 'sse';
-    /**
-     * URL of the MCP server endpoint.
-     * Can be a static string or a function that returns the URL at runtime.
-     *
-     * @example
-     * // Static
-     * url: "https://api.example.com/mcp"
-     *
-     * // Function (evaluated at runtime)
-     * url: () => env("MCP_SERVER_URL")
-     */
-    url: string | UrlResolverFunction;
-    /**
-     * Optional headers to send with requests.
-     * Can be a static object or a function that returns headers at runtime.
-     * Use a function to access env() for dynamic resolution from agent env vars.
-     *
-     * @example
-     * // Static (NOT recommended for secrets)
-     * headers: { 'X-Custom': 'value' }
-     *
-     * // Function (evaluated at runtime - recommended for auth)
-     * headers: () => ({
-     *   'Authorization': `Bearer ${env("API_TOKEN")}`
-     * })
-     */
-    headers?: Record<string, string> | HeadersResolverFunction;
-}
-/**
- * Configuration for Streamable HTTP MCP servers (modern standard - RECOMMENDED)
- *
- * This is the recommended transport for new MCP server integrations.
- * Streamable HTTP is the modern MCP standard (spec 2025-03-26) that provides:
- * - Single endpoint for bidirectional communication
- * - Session management via Mcp-Session-Id header
- * - Resumability via SSE event IDs
- *
- * @example
- * ```typescript
- * const docsServer = new LuaMCPServer({
- *   name: 'docs',
- *   transport: 'streamable-http',
- *   url: 'https://mcp.example.com/mcp',
- *   headers: () => ({
- *     'Authorization': `Bearer ${env("MCP_API_TOKEN")}`
- *   })
- * });
- * ```
- */
-export interface MCPStreamableHttpServerConfig extends MCPServerBaseConfig {
-    transport: 'streamable-http';
-    /**
-     * URL of the MCP server endpoint.
-     * Can be a static string or a function that returns the URL at runtime.
-     *
-     * @example
-     * // Static
-     * url: "https://api.example.com/mcp"
-     *
-     * // Function (evaluated at runtime)
-     * url: () => env("MCP_SERVER_URL")
-     */
-    url: string | UrlResolverFunction;
-    /**
-     * Optional headers to send with requests.
-     * Can be a static object or a function that returns headers at runtime.
-     * Use a function to access env() for dynamic resolution from agent env vars.
-     *
-     * @example
-     * // Static (NOT recommended for secrets)
-     * headers: { 'X-Custom': 'value' }
-     *
-     * // Function (evaluated at runtime - recommended for auth)
-     * headers: () => ({
-     *   'Authorization': `Bearer ${env("API_TOKEN")}`
-     * })
-     */
-    headers?: Record<string, string> | HeadersResolverFunction;
-}
-/**
- * Union type for all MCP server configurations.
- *
- * Note: stdio transport is not supported yet.
- * Use 'streamable-http' (recommended) or 'sse' (legacy) instead.
- */
-export type LuaMCPServerConfig = MCPSSEServerConfig | MCPStreamableHttpServerConfig;
-/**
- * LuaMCPServer class.
- * Defines an MCP (Model Context Protocol) server connection.
- *
- * MCP servers provide tools that can be used by your agent at runtime.
- * Connect to remote MCP servers via Streamable HTTP (recommended) or SSE (legacy).
- *
- * Environment variables can be provided as static values or as functions that
- * resolve at runtime using the env() API (consistent with tool execute functions).
- *
- * @example
- * ```typescript
- * import { LuaMCPServer, env } from 'lua-cli';
- *
- * // Remote MCP server via Streamable HTTP (recommended)
- * const docsServer = new LuaMCPServer({
- *   name: 'docs',
- *   transport: 'streamable-http',
- *   url: 'https://mcp.example.com/mcp',
- *   headers: () => ({
- *     'Authorization': `Bearer ${env("MCP_API_TOKEN")}`
- *   })
- * });
- *
- * // Remote MCP server via SSE (legacy)
- * const legacyServer = new LuaMCPServer({
- *   name: 'legacy-api',
- *   transport: 'sse',
- *   url: 'https://old-mcp.example.com/sse',
- *   headers: () => ({
- *     'Authorization': `Bearer ${env("API_KEY")}`
- *   })
- * });
- * ```
- */
-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.
- * Provides a simplified, unified way to configure an agent with all its components.
- *
- * This is the recommended approach for defining your agent. Instead of exporting
- * individual skills, jobs, webhooks, etc., you export a single LuaAgent object
- * that contains everything.
- */
-/**
- * Per-agent message batching/debounce configuration.
- * Overrides platform-wide env var defaults for this specific agent.
- * Any field left undefined falls back to the env var, then to the hardcoded default.
- *
- * @example
- * ```typescript
- * export default new LuaAgent({
- *   name: 'my-agent',
- *   persona: '...',
- *   batching: {
- *     firstMessageDelayMs: 200,  // hold first message 200ms to allow batch formation
- *     debounceWindowMs: 1500,    // extend window 1.5s per new message while in-flight
- *     maxBatchMessages: 5,
- *   }
- * });
- * ```
- */
-import type { BatchingConfig, GovernanceConfig } from '@lua/shared-types';
-/**
- * Type for the agent's model property.
- *
- * Can be either:
- * - A static `'provider/model'` string (e.g., `'openai/gpt-4o'`)
- * - A resolver function that receives `LuaRequest` and returns a model string.
- *   The function runs in the full sandbox with access to all APIs (User, Baskets, etc.)
- *
- * @example
- * ```typescript
- * // Static model
- * model: 'openai/gpt-4o'
- *
- * // Dynamic model based on channel
- * model: async (request) => {
- *   if (request.channel === 'whatsapp') return 'openai/gpt-4o-mini';
- *   return 'openai/gpt-4o';
- * }
- * ```
- */
-export type LuaAgentModel = string | ((request: LuaRequest) => string | Promise<string>);
-export interface LuaAgentConfig {
-    /** Agent name (used for identification) */
-    name: string;
-    /** Agent persona - defines the agent's behavior and personality */
-    persona: PersonaText;
-    /** LLM model to use — 'provider/model' string or resolver function */
-    model?: LuaAgentModel;
-    /** Array of skills (each with tools) */
-    skills?: LuaSkill[];
-    /** Array of webhooks */
-    webhooks?: LuaWebhook[];
-    /** Array of scheduled jobs */
-    jobs?: LuaJob[];
-    /** Array of preprocessors (run before messages reach the agent) */
-    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[];
-    /** Array of devices (external hardware that the agent can send commands to and receive triggers from) */
-    devices?: LuaDevice[];
-    /** Standalone device triggers — agent-side logic that any device can fire */
-    deviceTriggers?: LuaDeviceTrigger[];
-    /** Per-agent message batching/debounce configuration. Overrides platform env var defaults. */
-    batching?: BatchingConfig;
-    /** Governance policy configuration. When set, tool calls, preprocessors, and postprocessors are governed. */
-    governance?: GovernanceConfig;
-}
-/**
- * LuaAgent class.
- * Unified agent configuration that consolidates skills, webhooks, jobs, and processors.
- *
- * This is the simplest way to define an agent. Instead of exporting multiple separate
- * components, you create one LuaAgent that contains everything.
- *
- * @example
- * ```typescript
- * import { LuaAgent, LuaSkill, LuaJob, LuaWebhook } from 'lua-cli';
- *
- * // Define your skills, jobs, webhooks in separate files
- * import { userSkill } from './skills/user-skill';
- * import { healthCheckJob } from './jobs/health-check';
- * import { webhookHandler } from './webhooks/handler';
- *
- * // Create a single agent configuration
- * export const agent = new LuaAgent({
- *   name: 'my-assistant',
- *   persona: 'You are a helpful AI assistant that can manage users and products.',
- *   skills: [userSkill],
- *   jobs: [healthCheckJob],
- *   webhooks: [webhookHandler],
- *   preProcessors: [],
- *   postProcessors: []
- * });
- * ```
- */
-export declare class LuaAgent {
-    private readonly name;
-    private readonly persona;
-    private readonly model?;
-    private readonly skills;
-    private readonly webhooks;
-    private readonly jobs;
-    private readonly preProcessors;
-    private readonly postProcessors;
-    private readonly mcpServers;
-    private readonly devices;
-    private readonly deviceTriggers;
-    private readonly batching?;
-    private readonly governance?;
-    /**
-     * Creates a new LuaAgent instance.
-     *
-     * @param config - Agent configuration
-     * @param config.name - Agent name
-     * @param config.persona - Agent persona (behavior and personality)
-     * @param config.model - Optional LLM model ('provider/model' string or resolver function)
-     * @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
-     * @param config.devices - Optional array of devices (external hardware)
-     * @param config.batching - Optional per-agent batching/debounce configuration
-     */
-    constructor(config: LuaAgentConfig);
-    getName(): string;
-    getPersona(): PersonaText;
-    getModel(): LuaAgentModel | undefined;
-    getSkills(): LuaSkill[];
-    getWebhooks(): LuaWebhook[];
-    getJobs(): LuaJob[];
-    getPreProcessors(): PreProcessor[];
-    getPostProcessors(): PostProcessor[];
-    getMCPServers(): LuaMCPServer[];
-    getBatching(): BatchingConfig | undefined;
-    getDevices(): LuaDevice[];
-}
-/** Configuration for a single device command (agent → device) */
-export interface DeviceCommandConfig {
-    /** Description of what this command does */
-    description: string;
-    /** Zod schema for command input validation */
-    inputSchema?: ZodType;
-    /** Retry configuration for failed commands */
-    retry?: {
-        maxAttempts: number;
-        backoffMs: number;
-    };
-    /** Timeout in milliseconds (default: 30000) */
-    timeoutMs?: number;
-}
-/** Configuration for a single device trigger (device → agent) */
-export interface DeviceTriggerConfig {
-    /** Description of when this trigger fires */
-    description: string;
-    /** Zod schema for trigger payload validation */
-    payloadSchema?: ZodType;
-    /**
-     * Handler that runs on lua-core when the device fires this trigger.
-     * Has full access to agent context (can call agent.chat(), use tools, etc.)
-     */
-    execute?: (payload: any, context: {
-        agent: any;
-        device: any;
-        trigger: any;
-    }) => Promise<any>;
-}
-/**
- * Configuration for defining a device that an agent can communicate with.
- *
- * @example
- * ```typescript
- * import { defineDevice } from 'lua-cli';
- * import { z } from 'zod';
- *
- * export const printer = defineDevice({
- *   name: 'label-printer',
- *   description: 'Thermal label printer on Raspberry Pi',
- *   group: 'printers',
- *   commands: {
- *     print: {
- *       description: 'Print a label',
- *       inputSchema: z.object({ text: z.string(), copies: z.number().default(1) }),
- *       retry: { maxAttempts: 3, backoffMs: 1000 },
- *       timeoutMs: 30000,
- *     },
- *     status: {
- *       description: 'Get printer status',
- *       timeoutMs: 5000,
- *     },
- *   },
- *   triggers: {
- *     paper_low: {
- *       description: 'Fired when paper level drops below threshold',
- *       payloadSchema: z.object({ level: z.number(), threshold: z.number() }),
- *       execute: async (payload, { agent }) => {
- *         await agent.chat(\`Printer paper low: \${payload.level}%\`);
- *       },
- *     },
- *   },
- * });
- * ```
- */
-export interface LuaDeviceConfig {
-    /** Unique device name (lowercase, hyphens, e.g., 'label-printer') */
-    name: string;
-    /** Description of the device */
-    description?: string;
-    /** Optional group name for fan-out commands (e.g., 'printers') */
-    group?: string;
-    /** Commands the agent can send to the device */
-    commands?: Record<string, DeviceCommandConfig>;
-    /** Triggers the device can fire to the agent */
-    triggers?: Record<string, DeviceTriggerConfig>;
-}
-/**
- * LuaDevice class — represents an external device that an agent can communicate with.
- *
- * Used in two ways:
- * - Class-based: `export default new LuaDevice({ ... })`
- * - Function-based: `export const myDevice = defineDevice({ ... })` (preferred)
- */
-export declare class LuaDevice {
-    readonly name: string;
-    readonly description: string;
-    readonly group?: string;
-    readonly commands: Record<string, DeviceCommandConfig>;
-    readonly triggers: Record<string, DeviceTriggerConfig>;
-    constructor(config: LuaDeviceConfig);
-}
-/**
- * Configuration for a standalone device trigger primitive.
- *
- * Device triggers represent events fired from a device to an agent.
- * Unlike triggers defined inline within a `defineDevice()`, standalone
- * device triggers are first-class primitives that can be compiled,
- * versioned, and pushed independently.
- *
- * @example
- * ```typescript
- * import { defineDeviceTrigger } from 'lua-cli';
- * import { z } from 'zod';
- *
- * export const paperLow = defineDeviceTrigger({
- *   name: 'paper-low',
- *   description: 'Fired when printer paper drops below threshold',
- *   payloadSchema: z.object({ level: z.number() }),
- *   execute: async (payload, { agent, device }) => {
- *     await agent.chat(`Printer ${device.name} paper low: ${payload.level}%`);
- *   },
- * });
- * ```
- */
-export interface LuaDeviceTriggerConfig {
-    /** Trigger name (lowercase, hyphens, e.g., 'paper-low') */
-    name: string;
-    /** Description of when this trigger fires */
-    description?: string;
-    /** Zod schema for trigger payload validation */
-    payloadSchema?: ZodType;
-    /** Function that executes when the trigger fires */
-    execute: (payload: any, context: {
-        agent: any;
-        device: {
-            name: string;
-        };
-    }) => Promise<any>;
-}
-/**
- * Lua Device Trigger class.
- *
- * Standalone device trigger primitive. Can be used with either:
- * - Class-based: `export default new LuaDeviceTrigger({ ... })`
- * - Function-based: `export const myTrigger = defineDeviceTrigger({ ... })` (preferred)
- */
-export declare class LuaDeviceTrigger {
-    config: LuaDeviceTriggerConfig;
-    readonly name: string;
-    readonly description: string;
-    readonly payloadSchema?: ZodType;
-    readonly execute: (payload: any, context: {
-        agent: any;
-        device: {
-            name: string;
-        };
-    }) => Promise<any>;
-    constructor(config: LuaDeviceTriggerConfig);
-}
-//# sourceMappingURL=skill.d.ts.map