lua-cli 3.9.3 → 3.10.0

package/node_modules/@lua/shared-types/src/device.types.ts

@@ -0,0 +1,172 @@
+/**
+ * Device Gateway Types
+ *
+ * Types for bidirectional communication between AI agents and external devices.
+ * Used across lua-api (gateway), lua-core (runtime), and lua-cli (compilation).
+ */
+
+// =============================================================================
+// COMMAND (Agent → Device)
+// =============================================================================
+
+/** Command message sent from the server to a device */
+export interface DeviceCommandMessage {
+  /** Unique identifier for this command (UUID). Used for idempotency. */
+  commandId: string;
+  /** Command name (must match a command defined in defineDevice) */
+  command: string;
+  /** Command payload (validated against inputSchema if defined) */
+  payload: any;
+  /** Timeout in milliseconds (defaults to 30000) */
+  timeout?: number;
+}
+
+/** Response message sent from a device back to the server */
+export interface DeviceResponseMessage {
+  /** Must match the commandId of the original command */
+  commandId: string;
+  /** Whether the command executed successfully on the device */
+  success: boolean;
+  /** Response data (present when success=true) */
+  data?: any;
+  /** Error message (present when success=false) */
+  error?: string;
+}
+
+// =============================================================================
+// TRIGGER (Device → Agent)
+// =============================================================================
+
+/** Trigger message sent from a device to the server */
+export interface DeviceTriggerMessage {
+  /** Trigger name (must match a trigger defined in defineDevice) */
+  triggerName: string;
+  /** Trigger payload (validated against payloadSchema if defined) */
+  payload: any;
+}
+
+/** Acknowledgment sent from the server back to the device after receiving a trigger */
+export interface DeviceTriggerAckMessage {
+  /** Server-generated unique identifier for this trigger event */
+  triggerId: string;
+  /** Whether the trigger was received and queued for processing */
+  received: boolean;
+  /** Error details if the trigger was rejected */
+  error?: string;
+}
+
+// =============================================================================
+// STATE
+// =============================================================================
+
+/** Device connection status */
+export type DeviceStatus = 'online' | 'offline' | 'registered' | 'disabled';
+
+/** State of a command in the Valkey state machine */
+export type CommandState =
+  | 'PENDING'    // Command written to stream, not yet consumed
+  | 'SENT'       // Consumed by target pod, emitted to socket
+  | 'ACK'        // Device acknowledged receipt via Socket.IO ack
+  | 'COMPLETED'  // Device responded successfully
+  | 'FAILED'     // Device responded with error, or validation failed
+  | 'TIMED_OUT'; // No response within timeout period
+
+// =============================================================================
+// DEVICE INFO
+// =============================================================================
+
+/** Device information returned by API endpoints */
+export interface DeviceInfo {
+  /** Unique device name within the agent */
+  name: string;
+  /** Agent this device belongs to */
+  agentId: string;
+  /** Current connection status */
+  status: DeviceStatus;
+  /** Device group (optional, for fan-out commands) */
+  group?: string;
+  /** Device capabilities */
+  capabilities: string[];
+  /** Free-form device metadata */
+  metadata: Record<string, any>;
+  /** Last time the device was seen (heartbeat or connect) */
+  lastSeenAt: Date | null;
+}
+
+// =============================================================================
+// VALKEY STREAM ENTRIES
+// =============================================================================
+
+/** Entry written to the device command stream */
+export interface CommandStreamEntry {
+  commandId: string;
+  command: string;
+  payload: string; // JSON-serialized
+  originPodId: string;
+  agentId: string;
+  deviceName: string;
+}
+
+/** Entry written to the device response stream */
+export interface ResponseStreamEntry {
+  commandId: string;
+  success: string; // 'true' or 'false' (Redis streams store strings)
+  data?: string;   // JSON-serialized
+  error?: string;
+}
+
+/** Entry written to the device trigger stream */
+export interface TriggerStreamEntry {
+  triggerId: string;
+  agentId: string;
+  deviceName: string;
+  deviceId: string;
+  triggerName: string;
+  payload: string; // JSON-serialized
+  timestamp: string;
+}
+
+// =============================================================================
+// VALKEY COMMAND HASH
+// =============================================================================
+
+/** Data stored in the Valkey hash for a command's state */
+export interface CommandHashData {
+  status: CommandState;
+  agentId: string;
+  deviceName: string;
+  originPodId: string;
+  timestamp: number;
+}
+
+// =============================================================================
+// DEVICE DEFINITION (stored in lua-agents, cached in Redis)
+// =============================================================================
+
+/** Device definition as stored in Redis cache */
+export interface CachedDeviceDefinition {
+  name: string;
+  description?: string;
+  group?: string;
+  commands: CachedDeviceCommand[];
+  triggers: CachedDeviceTrigger[];
+  /** Compressed (gzip + base64) compiled artifact containing trigger handlers */
+  artifact: string;
+  /** Environment variables for the device */
+  env: Record<string, string>;
+}
+
+export interface CachedDeviceCommand {
+  name: string;
+  description: string;
+  inputSchema?: Record<string, any>; // JSON Schema
+  retry?: { maxAttempts: number; backoffMs: number };
+  timeoutMs?: number;
+}
+
+export interface CachedDeviceTrigger {
+  name: string;
+  description: string;
+  payloadSchema?: Record<string, any>; // JSON Schema
+  hasExecute: boolean;
+}

package/node_modules/@lua/shared-types/src/index.ts

@@ -3,4 +3,6 @@ export * from './unstructured-types';
 export * from './ai-generate.types';
 export * from './ai-generate.utils';
 export * from './sandbox-contract';
+export * from './device.types';
 export * from './model-registry';
+export * from './persona-defaults';

package/node_modules/@lua/shared-types/src/persona-defaults.ts

@@ -0,0 +1,59 @@
+const AGENT_NAME_TOKEN = '[Your Agent Name]';
+
+/**
+ * Structured persona guide template for newly created agents.
+ * Each section teaches the developer what to write, with a brief example.
+ */
+const DEFAULT_PERSONA_GUIDE = `# ${AGENT_NAME_TOKEN} - Persona
+
+This is a starting template to help you think about your agent's persona.
+Use it as-is, rearrange it, or replace it entirely with your own format — whatever works best for your use case.
+The sections below are suggestions, not requirements.
+
+## Identity & Role
+Who is your agent? What's their name and core purpose?
+- Give it a name and a clear one-line role
+- e.g. a customer support rep, a shopping assistant, an internal ops copilot, a scheduling bot
+
+## Business Context
+What company, product, or service does the agent represent? What does the business do?
+- Describe the business in a sentence or two so the agent understands the world it operates in
+- Include industry, value proposition, and anything the agent should "know" about the brand
+
+## Tone & Communication Style
+How should the agent sound?
+- Formal or casual? Concise or detailed? Empathetic or matter-of-fact?
+- Should it match a specific brand voice or adapt to the user's tone?
+- Any language or cultural considerations (e.g. greetings, local expressions)?
+
+## Target Audience
+Who will the agent be talking to?
+- Describe the typical user: consumers, business customers, internal team members, etc.
+- What do they usually need help with? What matters most to them?
+
+## Capabilities
+What can the agent help with? List the main things it should handle.
+- e.g. answering product questions, placing orders, looking up account info, scheduling meetings
+- Be specific — this shapes which skills and tools the agent will use
+
+## Boundaries
+What should the agent NOT do? When should it escalate to a human?
+- e.g. cannot process refunds, should not give medical/legal advice
+- Define when to hand off: frustrated user, request outside scope, sensitive data
+
+## Guidelines
+Any rules for how the agent behaves?
+- Response length limits (e.g. keep messages under 300 words)
+- Formatting preferences (e.g. use bullet points, avoid jargon)
+- Things to always or never do (e.g. always confirm before changes, never share internal IDs)
+
+---
+Feel free to add, remove, or rename sections. Your persona can be a single paragraph or a detailed playbook — whatever gives your agent the context it needs.
+`;
+
+/**
+ * Build a default persona guide with the agent name filled in.
+ */
+export function buildDefaultPersona(agentName: string): string {
+  return DEFAULT_PERSONA_GUIDE.replace(AGENT_NAME_TOKEN, () => agentName || 'My Agent');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.9.3",
+  "version": "3.10.0",
   "description": "Build, test, and deploy AI agents with custom tools, webhooks, and scheduled jobs. Features LuaAgent unified configuration, streaming chat, and batch deployment.",
   "readmeFilename": "README.md",
   "main": "dist/api-exports.js",

package/template/package.json

@@ -20,7 +20,7 @@
     "inquirer": "^12.9.6",
     "stripe": "^17.5.0",
     "js-yaml": "^4.1.0",
-    "lua-cli": "^3.9.3",
+    "lua-cli": "^3.10.0",
     "openai": "^5.23.0",
     "uuid": "^13.0.0",
     "zod": "^3.24.1"