lua-cli 3.1.0 → 3.2.0-alpha.1

package/README.md

@@ -559,8 +559,6 @@ Central configuration file:
 agent:
   agentId: your-agent-id
   orgId: your-org-id
-  persona: |
-    You are a helpful AI assistant...
 
 skills:
   - name: general-skill
@@ -576,11 +574,10 @@ jobs:
   - name: daily-cleanup
     version: 1.0.0
     jobId: job-id-789
-    schedule:
-      type: cron
-      pattern: "0 0 * * *"
 ```
 
+State-only: YAML tracks names, IDs, and server versions. Persona, env vars, and schedules live in code (for sandbox) or on the server (for production).
+
 ### Environment Variables
 
 ```.env

package/dist/api/marketplace.api.service.d.ts

@@ -1,4 +1,4 @@
-import { MarketplaceSkillWithVersionsResponse, MarketplaceVersionResponse, SkillResponse, UnpublishVersionResponse, UnlistSkillResponse } from "../interfaces/marketplace.js";
+import { MarketplaceSkillWithVersionsResponse, MarketplaceVersionResponse, SkillResponse, UnpublishVersionResponse, UnlistSkillResponse, PaginatedMarketplaceSkillsResponse } from "../interfaces/marketplace.js";
 export declare class MarketplaceApiService {
     private apiKey;
     private baseUrl;
@@ -15,7 +15,9 @@ export declare class MarketplaceApiService {
         name?: string;
         creatorId?: string;
         publishedVersionsOnly?: boolean;
-    }): Promise<MarketplaceSkillWithVersionsResponse[]>;
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedMarketplaceSkillsResponse>;
     getSkillById(marketplaceSkillId: string): Promise<MarketplaceSkillWithVersionsResponse>;
     getSkillVersions(marketplaceSkillId: string): Promise<MarketplaceVersionResponse[]>;
     installSkill(marketplaceSkillId: string, agentId: string, data: any): Promise<SkillResponse>;

package/dist/api/marketplace.api.service.js

@@ -74,6 +74,12 @@ export class MarketplaceApiService {
         if (filters?.publishedVersionsOnly !== undefined) {
             params.append("publishedVersionsOnly", String(filters.publishedVersionsOnly));
         }
+        if (filters?.page !== undefined) {
+            params.append("page", String(filters.page));
+        }
+        if (filters?.limit !== undefined) {
+            params.append("limit", String(filters.limit));
+        }
         return this._fetch(`/marketplace/skills?${params.toString()}`);
     }
     async getSkillById(marketplaceSkillId) {

package/dist/api/persona.api.service.d.ts

@@ -0,0 +1,54 @@
+import { HttpClient } from "../common/http.client.js";
+import { ApiResponse } from "../interfaces/common.js";
+import { PersonaVersion, PersonaVersionsResponse, CreatePersonaVersionResponse, SetPersonaVersionResponse } from "../interfaces/persona.js";
+/**
+ * Persona API Service
+ * Handles all persona-related API calls
+ */
+export default class PersonaApi extends HttpClient {
+    apiKey: string;
+    agentId: string;
+    /**
+     * Creates an instance of PersonaApi
+     * @param baseUrl - The base URL for the API
+     * @param apiKey - The API key for authentication
+     * @param agentId - The unique identifier of the agent
+     */
+    constructor(baseUrl: string, apiKey: string, agentId: string);
+    /**
+     * Retrieves all persona versions for the agent
+     * @param status - Filter by status: 'draft', 'published', or 'all' (default)
+     * @returns Promise resolving to an ApiResponse containing persona versions response
+     */
+    getVersions(status?: 'draft' | 'published' | 'all'): Promise<ApiResponse<PersonaVersionsResponse>>;
+    /**
+     * Creates a new persona version
+     * @param persona - The persona content
+     * @returns Promise resolving to an ApiResponse with the created version
+     */
+    createVersion(persona: string): Promise<ApiResponse<CreatePersonaVersionResponse>>;
+    /**
+     * Deploys/activates a persona version to production
+     * @param version - The version number to deploy
+     * @returns Promise resolving to an ApiResponse with confirmation
+     */
+    deployVersion(version: number): Promise<ApiResponse<SetPersonaVersionResponse>>;
+    /**
+     * Gets the latest persona version (sorted by createdDate, includes drafts)
+     * @returns Promise resolving to the latest PersonaVersion or null if none exist
+     */
+    getLatestVersion(): Promise<PersonaVersion | null>;
+    /**
+     * Gets the latest published persona version (excludes drafts)
+     * This is the most recently pushed version, regardless of whether it's currently active.
+     * Use this for sync - code should match the latest push, not a rollback.
+     * @returns Promise resolving to the latest published PersonaVersion or null if none exist
+     */
+    getLatestPublishedVersion(): Promise<PersonaVersion | null>;
+    /**
+     * Gets the currently deployed/active persona version
+     * Note: This might be an older rollback version, not the latest push.
+     * @returns Promise resolving to the current PersonaVersion or null if none deployed
+     */
+    getCurrentVersion(): Promise<PersonaVersion | null>;
+}

package/dist/api/persona.api.service.js

@@ -0,0 +1,89 @@
+import { HttpClient } from "../common/http.client.js";
+/**
+ * Persona API Service
+ * Handles all persona-related API calls
+ */
+export default class PersonaApi extends HttpClient {
+    /**
+     * Creates an instance of PersonaApi
+     * @param baseUrl - The base URL for the API
+     * @param apiKey - The API key for authentication
+     * @param agentId - The unique identifier of the agent
+     */
+    constructor(baseUrl, apiKey, agentId) {
+        super(baseUrl);
+        this.apiKey = apiKey;
+        this.agentId = agentId;
+    }
+    /**
+     * Retrieves all persona versions for the agent
+     * @param status - Filter by status: 'draft', 'published', or 'all' (default)
+     * @returns Promise resolving to an ApiResponse containing persona versions response
+     */
+    async getVersions(status = 'all') {
+        const statusParam = status !== 'all' ? `?status=${status}` : '';
+        return this.httpGet(`/developer/agents/${this.agentId}/persona/versions${statusParam}`, {
+            Authorization: `Bearer ${this.apiKey}`,
+        });
+    }
+    /**
+     * Creates a new persona version
+     * @param persona - The persona content
+     * @returns Promise resolving to an ApiResponse with the created version
+     */
+    async createVersion(persona) {
+        return this.httpPost(`/developer/agents/${this.agentId}/persona/version`, { persona }, {
+            Authorization: `Bearer ${this.apiKey}`,
+        });
+    }
+    /**
+     * Deploys/activates a persona version to production
+     * @param version - The version number to deploy
+     * @returns Promise resolving to an ApiResponse with confirmation
+     */
+    async deployVersion(version) {
+        return this.httpPost(`/developer/agents/${this.agentId}/persona/version/${version}`, {}, {
+            Authorization: `Bearer ${this.apiKey}`,
+        });
+    }
+    /**
+     * Gets the latest persona version (sorted by createdDate, includes drafts)
+     * @returns Promise resolving to the latest PersonaVersion or null if none exist
+     */
+    async getLatestVersion() {
+        const response = await this.getVersions();
+        if (!response.success || !response.data?.versions || response.data.versions.length === 0) {
+            return null;
+        }
+        // Sort by createdDate descending to get the latest
+        const sorted = response.data.versions.sort((a, b) => b.createdDate - a.createdDate);
+        return sorted[0];
+    }
+    /**
+     * Gets the latest published persona version (excludes drafts)
+     * This is the most recently pushed version, regardless of whether it's currently active.
+     * Use this for sync - code should match the latest push, not a rollback.
+     * @returns Promise resolving to the latest published PersonaVersion or null if none exist
+     */
+    async getLatestPublishedVersion() {
+        const response = await this.getVersions('published');
+        if (!response.success || !response.data?.versions || response.data.versions.length === 0) {
+            return null;
+        }
+        // Sort by createdDate descending to get the latest published
+        const sorted = response.data.versions.sort((a, b) => b.createdDate - a.createdDate);
+        return sorted[0];
+    }
+    /**
+     * Gets the currently deployed/active persona version
+     * Note: This might be an older rollback version, not the latest push.
+     * @returns Promise resolving to the current PersonaVersion or null if none deployed
+     */
+    async getCurrentVersion() {
+        const response = await this.getVersions();
+        if (!response.success || !response.data?.versions || response.data.versions.length === 0) {
+            return null;
+        }
+        return response.data.versions.find(v => v.isCurrent) || null;
+    }
+}

package/dist/api-exports.d.ts

@@ -547,7 +547,26 @@ export declare const CDN: {
      */
     get(fileId: string): Promise<File>;
 };
+import { LuaRuntime } from "./interfaces/lua.js";
+/**
+ * Lua Runtime API
+ * Access request-level runtime information in your tools, conditions, and processors.
+ *
+ * @example
+ * ```typescript
+ * import { Lua } from 'lua-cli';
+ *
+ * // Access the current channel
+ * const channel = Lua.request.channel;
+ *
+ * if (channel === 'whatsapp') {
+ *   // WhatsApp-specific logic
+ * }
+ * ```
+ */
+export declare const Lua: LuaRuntime;
 export { LuaSkill, LuaTool, LuaWebhook, LuaWebhookConfig, LuaJob, LuaJobConfig, JobSchedule, PreProcessor, PreProcessorConfig, PreProcessorAction, PreProcessorResult, PreProcessorBlockResponse, PreProcessorProceedResponse, PostProcessor, PostProcessorConfig, PostProcessorResponse, LuaAgent, LuaAgentConfig, LuaMCPServer, LuaMCPServerConfig, MCPStdioServerConfig, MCPSSEServerConfig, MCPTransport, MCPServerBaseConfig, BasketStatus, OrderStatus, env };
 export { JobInstance, UserDataInstance, DataEntryInstance, ProductInstance, BasketInstance, OrderInstance };
 export { ChatHistoryMessage, ChatHistoryContent, ChatMessage, TextMessage, ImageMessage, FileMessage, PreProcessorOverride, PostProcessorOverride };
 export { WhatsAppTemplate, PaginatedTemplatesResponse, ListTemplatesOptions, SendTemplateData, SendTemplateResponse, WhatsAppTemplateCategory, WhatsAppTemplateStatus, WhatsAppTemplateComponent, SendTemplateValues } from "./interfaces/whatsapp-templates.js";
+export { Channel, LuaRuntime, LuaRequest } from "./interfaces/lua.js";

package/dist/api-exports.js

@@ -696,6 +696,27 @@ export const CDN = {
         return instance.get(fileId);
     }
 };
+/**
+ * Lua Runtime API
+ * Access request-level runtime information in your tools, conditions, and processors.
+ *
+ * @example
+ * ```typescript
+ * import { Lua } from 'lua-cli';
+ *
+ * // Access the current channel
+ * const channel = Lua.request.channel;
+ *
+ * if (channel === 'whatsapp') {
+ *   // WhatsApp-specific logic
+ * }
+ * ```
+ */
+export const Lua = {
+    request: {
+        channel: 'unknown',
+    },
+};
 // ============================================================================
 // EXPORTS
 // ============================================================================

package/dist/cli/command-definitions.js

@@ -2,7 +2,7 @@
  * Command Definitions
  * Centralized command structure for the CLI
  */
-import { configureCommand, initCommand, destroyCommand, apiKeyCommand, compileCommand, testCommand, pushCommand, deployCommand, devCommand, chatCommand, chatClearCommand, envCommand, personaCommand, productionCommand, resourcesCommand, adminCommand, evalsCommand, docsCommand, channelsCommand, logsCommand, completionCommand, skillsCommand, webhooksCommand, jobsCommand, featuresCommand, preprocessorsCommand, postprocessorsCommand, marketplaceCommand, mcpCommand } from "../commands/index.js";
+import { configureCommand, initCommand, destroyCommand, apiKeyCommand, compileCommand, testCommand, pushCommand, deployCommand, devCommand, chatCommand, chatClearCommand, envCommand, personaCommand, productionCommand, resourcesCommand, adminCommand, evalsCommand, docsCommand, channelsCommand, logsCommand, completionCommand, skillsCommand, webhooksCommand, jobsCommand, featuresCommand, preprocessorsCommand, postprocessorsCommand, marketplaceCommand, mcpCommand, syncCommand } from "../commands/index.js";
 /**
  * Sets up authentication-related commands.
  *
@@ -77,7 +77,23 @@ export function setupSkillCommands(program) {
         .command("compile")
         .description("📦 Compile skill to deployable format")
         .option("--debug", "Enable debug mode with verbose logging and temp file preservation")
+        .option("--no-sync", "Skip drift detection check")
+        .option("--force-sync", "Auto-accept server state if drift detected")
         .action(compileCommand);
+    program
+        .command("sync")
+        .description("🔄 Sync local code with server state")
+        .addHelpText('after', `
+Detects drift between server-deployed state and local code.
+Allows updating local code from the server to stay in sync.
+
+Currently syncs:
+  • Persona - Agent persona from LuaAgent definition
+
+Examples:
+  $ lua sync              Check for drift and sync interactively
+`)
+        .action(syncCommand);
     program
         .command("test [type]")
         .description("🧪 Test skills, webhooks, or jobs interactively")
@@ -138,6 +154,18 @@ Examples:
     chatCmd
         .command("clear")
         .description("Clear conversation history")
+        .option("--user <identifier>", "User ID, email, or mobile number of the user whose history to clear")
+        .addHelpText('after', `
+Examples:
+  $ lua chat clear                                   Clear history
+  $ lua chat clear --user <userId>                   Clear user's history by user ID
+  $ lua chat clear --user <email>                    Clear user's history by email
+  $ lua chat clear --user <mobile>                   Clear user's history by mobile number
+
+Notes:
+  - User identifier can be UUID, email address, or mobile number
+  - Mobile numbers should be in international format without + (e.g., 919876543210)
+`)
         .action(chatClearCommand);
     // Configuration Commands
     program

package/dist/commands/chat.js

@@ -13,6 +13,7 @@ import { getAllSandboxSkillIds, getAllSandboxPreProcessorIds, getAllSandboxPostP
 import ChatApi from '../api/chat.api.service.js';
 import { BASE_URLS } from '../config/constants.js';
 import { readDeployJson, validateConfig, validateDeployData, validateAgentConfig, } from '../utils/dev-helpers.js';
+import { loadPersonaFromCode } from '../utils/agent-code-utils.js';
 /**
  * Main chat command - starts interactive chat session
  *
@@ -110,9 +111,7 @@ async function setupSandboxEnvironment(chatEnv, config) {
     chatEnv.preprocessorOverrides = await getAllSandboxPreProcessorIds(config);
     chatEnv.postprocessorOverrides = await getAllSandboxPostProcessorIds(config);
     // Check for persona in config
-    if (config.agent?.persona) {
-        chatEnv.persona = config.agent.persona;
-    }
+    chatEnv.persona = loadPersonaFromCode();
 }
 /**
  * Starts the interactive chat loop

package/dist/commands/chatClear.d.ts

@@ -9,7 +9,11 @@
  * - Warning message about data loss
  * - Confirmation prompt
  * - Calls DELETE endpoint to clear history
+ * - Optional: clear user's history by identifier
  *
+ * @param options - Command options including optional user identifier
  * @returns Promise that resolves when history is cleared
  */
-export declare function chatClearCommand(): Promise<void>;
+export declare function chatClearCommand(options?: {
+    user?: string;
+}): Promise<void>;

package/dist/commands/chatClear.js

@@ -15,10 +15,12 @@ import { validateConfig, validateAgentConfig, } from '../utils/dev-helpers.js';
  * - Warning message about data loss
  * - Confirmation prompt
  * - Calls DELETE endpoint to clear history
+ * - Optional: clear user's history by identifier
  *
+ * @param options - Command options including optional user identifier
  * @returns Promise that resolves when history is cleared
  */
-export async function chatClearCommand() {
+export async function chatClearCommand(options) {
     return withErrorHandling(async () => {
         // Step 1: Load configuration
         const config = readSkillConfig();
@@ -33,14 +35,19 @@ export async function chatClearCommand() {
         }
         await checkApiKey(apiKey);
         writeProgress("✅ Authenticated");
-        // Step 3: Show warning and confirm
-        console.log("\n⚠️  WARNING: This will clear ALL conversation history!");
+        // Step 3: Prepare target user info (if --user flag provided)
+        const targetIdentifier = options?.user;
+        const userContext = targetIdentifier
+            ? `for user ${targetIdentifier}`
+            : "";
+        // Step 4: Show warning and confirm
+        console.log(`\n⚠️  WARNING: This will clear ALL conversation history ${userContext}!`);
         console.log("⚠️  This action cannot be undone.\n");
         const confirmAnswer = await safePrompt([
             {
                 type: 'confirm',
                 name: 'confirm',
-                message: 'Are you sure you want to clear the conversation history?',
+                message: `Are you sure you want to clear the conversation history ${userContext}?`,
                 default: false
             }
         ]);
@@ -48,10 +55,14 @@ export async function chatClearCommand() {
             // console.log("\n❌ Operation cancelled. History not cleared.\n");
             return;
         }
-        // Step 4: Clear history via API
+        // Step 5: Clear history via API
         writeProgress("🔄 Clearing conversation history...");
         try {
-            const response = await fetch(`${BASE_URLS.API}/chat/history/${agentId}`, {
+            // Construct URL with optional targetIdentifier query parameter
+            const url = targetIdentifier
+                ? `${BASE_URLS.API}/chat/history/${agentId}?targetIdentifier=${encodeURIComponent(targetIdentifier)}`
+                : `${BASE_URLS.API}/chat/history/${agentId}`;
+            const response = await fetch(url, {
                 method: 'DELETE',
                 headers: {
                     'accept': '*/*',
@@ -62,8 +73,8 @@ export async function chatClearCommand() {
                 const errorText = await response.text();
                 throw new Error(`HTTP error! status: ${response.status} - ${errorText}`);
             }
-            writeSuccess("✅ Conversation history cleared successfully");
-            console.log("💡 The chat history has been completely removed.\n");
+            writeSuccess(`✅ Conversation history cleared successfully ${userContext}`);
+            console.log(`💡 The chat history has been completely removed ${userContext}.\n`);
         }
         catch (error) {
             console.error('❌ Error clearing conversation history:', error);

package/dist/commands/compile.d.ts

@@ -27,9 +27,12 @@
  * - Skills deleted from code are removed from YAML
  * - Skills not in YAML are deleted from server (or deactivated if they have versions)
  *
- * @param options - Command options including debug flag
+ * @param options - Command options including debug, noSync, and forceSync flags
  * @returns Promise that resolves when compilation is complete
  */
 export declare function compileCommand(options?: {
     debug?: boolean;
+    noSync?: boolean;
+    forceSync?: boolean;
+    sync?: boolean;
 }): Promise<void>;

package/dist/commands/compile.js

@@ -18,7 +18,8 @@ import { ensurePostProcessorsExistInYaml, syncServerPostProcessorsWithYaml } fro
 import { ensureMCPServersExistInYaml, syncServerMCPServersWithYaml } from '../utils/mcp-server-management.js';
 import { readSkillConfig } from '../utils/files.js';
 import { COMPILE_DIRS, COMPILE_FILES } from '../config/compile.constants.js';
-import { syncAgentPersonaWithYaml } from '../utils/agent-management.js';
+import { loadApiKey } from '../services/auth.js';
+import { runSyncCheck } from './sync.js';
 /**
  * Main compile command - orchestrates the entire skill compilation process.
  *
@@ -44,18 +45,42 @@ import { syncAgentPersonaWithYaml } from '../utils/agent-management.js';
  * - Skills deleted from code are removed from YAML
  * - Skills not in YAML are deleted from server (or deactivated if they have versions)
  *
- * @param options - Command options including debug flag
+ * @param options - Command options including debug, noSync, and forceSync flags
  * @returns Promise that resolves when compilation is complete
  */
 export async function compileCommand(options) {
     return withErrorHandling(async () => {
         const debugMode = options?.debug || process.env.LUA_DEBUG === 'true';
+        // Commander uses --no-sync which sets sync=false, so we check for sync !== false
+        const noSync = options?.noSync || options?.sync === false;
+        const forceSync = options?.forceSync || false;
         if (debugMode) {
             console.log('🐛 Debug mode enabled');
             console.log('   - Verbose logging: ON');
             console.log('   - Temp file preservation: ON');
             console.log('   - Full error stacks: ON\n');
         }
+        // Step 0: Run sync check (unless --no-sync is set)
+        if (!noSync) {
+            try {
+                const config = readSkillConfig();
+                const agentId = config?.agent?.agentId;
+                const apiKey = await loadApiKey();
+                if (apiKey && agentId) {
+                    const shouldContinue = await runSyncCheck(apiKey, agentId, { noSync, forceSync });
+                    if (!shouldContinue) {
+                        return; // User cancelled due to unresolved drift
+                    }
+                }
+                // If no API key or agentId, skip sync silently (sandbox-only development)
+            }
+            catch (error) {
+                // Sync check failed, continue with compilation anyway
+                if (debugMode) {
+                    console.warn('⚠️  Sync check failed, continuing with compilation:', error);
+                }
+            }
+        }
         writeProgress("🔨 Compiling Lua skill...");
         // Track compilation issues
         const compilationWarnings = [];
@@ -90,8 +115,6 @@ export async function compileCommand(options) {
         if (agentMetadata) {
             writeProgress(`✨ Found LuaAgent: ${agentMetadata.name}`);
             writeProgress(`   Using new unified agent configuration approach`);
-            // Sync persona and welcome message with YAML
-            await syncAgentPersonaWithYaml(agentMetadata);
             // Resolve references to get actual metadata for all components
             resolvedAgentData = resolveLuaAgentReferences(agentMetadata, indexFile, project);
             // Get file paths where skills are defined so we can scan them for tools

package/dist/commands/index.d.ts

@@ -27,3 +27,4 @@ export { preprocessorsCommand } from "./preprocessors.js";
 export { postprocessorsCommand } from "./postprocessors.js";
 export { marketplaceCommand } from "./marketplace.js";
 export { mcpCommand } from "./mcp.js";
+export { syncCommand } from "./sync.js";

package/dist/commands/index.js

@@ -27,3 +27,4 @@ export { preprocessorsCommand } from "./preprocessors.js";
 export { postprocessorsCommand } from "./postprocessors.js";
 export { marketplaceCommand } from "./marketplace.js";
 export { mcpCommand } from "./mcp.js";
+export { syncCommand } from "./sync.js";

package/dist/commands/init.js

@@ -133,9 +133,9 @@ export async function initCommand(options = {}) {
         if (yamlExists) {
             // Update existing YAML and LuaAgent in index.ts
             writeInfo("📝 Updating existing lua.skill.yaml with new agent...");
-            updateYamlAgent(selectedAgent.agentId, selectedOrg.id, persona);
+            updateYamlAgent(selectedAgent.agentId, selectedOrg.id);
             // Also update LuaAgent in index.ts if it exists
-            const { updateLuaAgentInIndexFile } = await import("../utils/init-helpers.js");
+            const { updateLuaAgentInIndexFile } = await import("../utils/agent-code-utils.js");
             updateLuaAgentInIndexFile(process.cwd(), selectedAgent.name, persona);
             writeSuccess("✅ lua.skill.yaml updated successfully!");
             writeSuccess("✅ LuaAgent configuration updated!");
@@ -299,9 +299,9 @@ async function handleAgentSwitch(userData, apiKey, existingYaml) {
     const finalPersona = await promptPersonaReplacement(existingYaml, persona);
     // Update existing YAML file with new agent
     writeInfo("\n📝 Updating lua.skill.yaml with new agent...");
-    updateYamlAgent(selectedAgent.agentId, selectedOrg.id, finalPersona);
+    updateYamlAgent(selectedAgent.agentId, selectedOrg.id);
     // Also update LuaAgent in index.ts if it exists
-    const { updateLuaAgentInIndexFile } = await import("../utils/init-helpers.js");
+    const { updateLuaAgentInIndexFile } = await import("../utils/agent-code-utils.js");
     updateLuaAgentInIndexFile(process.cwd(), selectedAgent.name, finalPersona);
     writeSuccess("✅ lua.skill.yaml updated successfully!");
     writeSuccess("✅ LuaAgent configuration updated!");