lua-cli 3.10.5 → 3.12.0

package/node_modules/@lua/shared-types/dist/index.d.ts

@@ -89,6 +89,77 @@ interface AiGenerateOutput {
  */
 declare function aiGenerateInputFromSimplified(prompt: string, content?: UserContent): AiGenerateInput;
 
+/**
+ * Wire-format input for sandbox `Agents.invoke` / `POST /chat/generate/:agentId`
+ * when triggered programmatically by another agent/skill/tool.
+ *
+ * Intentionally a narrow, safe subset of the public `ChatMessageDto` — omits
+ * sandbox-only overrides (`skillOverride`, `preprocessorOverride`, etc.),
+ * webhook payloads, navigation hints, and persona override.
+ *
+ * Either `prompt` or `messages` must be provided. When `prompt` is given, it is
+ * converted into a single `{ role: 'user', content: [{ type: 'text', text: prompt }] }`
+ * message downstream.
+ */
+interface AgentInvocationInput {
+    /** Shortcut: plain-text prompt. Mutually exclusive with `messages`. */
+    prompt?: string;
+    /** AI SDK `UserContent` (text/image/file parts). Mutually exclusive with `prompt`. */
+    messages?: UserContent;
+    /** Override the target agent's system prompt for this invocation. */
+    systemPrompt?: string;
+    /** Additional runtime context attached to the request. */
+    runtimeContext?: string;
+    /**
+     * Optional thread ID suffix for conversation scoping. When omitted, the
+     * invocation flows into the caller-user's default chat thread with the
+     * target agent (same behavior as a direct `POST /chat/generate/:agentId`
+     * call with no `threadId`). Pass a custom value to isolate invocations.
+     */
+    threadId?: string;
+    /** Channel identifier, defaults to `'agent-invocation'`. */
+    channel?: string;
+    /** Free-form request tag persisted on the stored Message record (e.g. a UUID
+     *  or external trace id for correlation). Not a user identifier. Omitted
+     *  by default. */
+    identifier?: string;
+    /**
+     * Explicit user to invoke as. Use from context-less triggers (webhooks,
+     * pre-defined jobs) where there is no ambient user — mirrors the `User.get(userId)`
+     * contract. When omitted from a webhook/pre-defined job, the invocation runs in
+     * system scope (no per-user identity, no conversation history). Ignored during
+     * a user-authenticated turn — the turn's user is always used, no impersonation.
+     */
+    userId?: string;
+}
+/**
+ * Narrowed, wire-safe output for `Agents.invoke`. A slice of the internal
+ * `FullOutput` shape — raw Mastra steps / tripwire payloads are intentionally
+ * not exposed to skill code.
+ */
+interface AgentInvocationOutput {
+    /** Final response text (post-processor-modified, if applicable). */
+    text: string;
+    /** AI SDK `FinishReason` (or `'preprocessor_blocked'` / `'governance_blocked'`). */
+    finishReason?: string;
+    /** Token usage summary. */
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+        reasoningTokens?: number;
+        cachedInputTokens?: number;
+    };
+    /** Names of tools invoked during generation. */
+    toolsUsed?: string[];
+    /**
+     * Echoes back the `threadId` suffix the caller passed in (if any). When the
+     * caller omitted `threadId`, this is undefined — the invocation ran in the
+     * user's default chat thread with the target agent.
+     */
+    threadId?: string;
+}
+
 /**
  * Sandbox contract: defines what every sandbox MUST expose.
  * Both lua-cli and lua-core test against this contract.
@@ -246,6 +317,25 @@ interface CachedDeviceTrigger {
     payloadSchema?: Record<string, any>;
     hasExecute: boolean;
 }
+/** Command definition sent by a device at connect time (self-describing) */
+interface DeviceCommandDefinition {
+    name: string;
+    description: string;
+    inputSchema?: Record<string, any>;
+    timeoutMs?: number;
+    retry?: {
+        maxAttempts: number;
+        backoffMs: number;
+    };
+}
+/** Standalone device trigger definition (compiled agent-side primitive) */
+interface CachedDeviceTriggerDefinition {
+    name: string;
+    description: string;
+    payloadSchema?: Record<string, any>;
+    artifact: string;
+    env: Record<string, string>;
+}
 
 /**
  * Shared type definitions for the model registry.
@@ -270,9 +360,40 @@ interface ApprovedModelDef {
     };
 }
 
+/**
+ * Per-agent message batching/debounce configuration.
+ * Overrides platform-wide env var defaults for this specific agent.
+ */
+interface BatchingConfig {
+    /** Hold first message N ms before processing, to allow rapid follow-ups to batch together. 0 = disabled. */
+    firstMessageDelayMs?: number;
+    /** Window to collect subsequent messages while one is in-flight (ms). 0 = batching disabled. */
+    debounceWindowMs?: number;
+    /** Maximum messages collected in a single batch. */
+    maxBatchMessages?: number;
+}
+/**
+ * Governance SDK configuration persisted on the SubAgent document.
+ *
+ * The API-mode bearer token is NEVER stored here. At runtime the
+ * platform resolves it from the `GOVERNANCE_API_KEY` env var. This
+ * keeps secrets out of MongoDB, support logs, and backups.
+ */
+interface GovernanceConfig {
+    mode: 'sdk' | 'api';
+    /** SDK mode — local in-memory policy rules */
+    rules?: {
+        blockTools?: string[];
+        requireApproval?: string[];
+        tokenBudget?: number;
+    };
+    /** API mode — remote enforcement server URL */
+    serverUrl?: string;
+}
+
 /**
  * Build a default persona guide with the agent name filled in.
  */
 declare function buildDefaultPersona(agentName: string): string;
 
-export { type AiGenerateInput, type AiGenerateOutput, type AiGenerateSource, type AiGenerateToolCall, type AiGenerateToolResult, type ApprovedModelDef, type CachedDeviceCommand, type CachedDeviceDefinition, type CachedDeviceTrigger, type Channel, type CommandHashData, type CommandState, type CommandStreamEntry, type DeviceCommandMessage, type DeviceInfo, type DeviceResponseMessage, type DeviceStatus, type DeviceTriggerAckMessage, type DeviceTriggerMessage, REQUIRED_ENUMS, REQUIRED_NESTED_APIS, REQUIRED_PLATFORM_APIS, REQUIRED_PRIMITIVE_SHIMS, REQUIRED_UTILITIES, type ResponseStreamEntry, type TriggerStreamEntry, UNSTRUCTURED_SUPPORTED_MEDIA_TYPES, aiGenerateInputFromSimplified, buildDefaultPersona };
+export { type AgentInvocationInput, type AgentInvocationOutput, type AiGenerateInput, type AiGenerateOutput, type AiGenerateSource, type AiGenerateToolCall, type AiGenerateToolResult, type ApprovedModelDef, type BatchingConfig, type CachedDeviceCommand, type CachedDeviceDefinition, type CachedDeviceTrigger, type CachedDeviceTriggerDefinition, type Channel, type CommandHashData, type CommandState, type CommandStreamEntry, type DeviceCommandDefinition, type DeviceCommandMessage, type DeviceInfo, type DeviceResponseMessage, type DeviceStatus, type DeviceTriggerAckMessage, type DeviceTriggerMessage, type GovernanceConfig, REQUIRED_ENUMS, REQUIRED_NESTED_APIS, REQUIRED_PLATFORM_APIS, REQUIRED_PRIMITIVE_SHIMS, REQUIRED_UTILITIES, type ResponseStreamEntry, type TriggerStreamEntry, UNSTRUCTURED_SUPPORTED_MEDIA_TYPES, aiGenerateInputFromSimplified, buildDefaultPersona };

package/node_modules/@lua/shared-types/src/agent-config.types.ts

@@ -0,0 +1,31 @@
+/**
+ * Per-agent message batching/debounce configuration.
+ * Overrides platform-wide env var defaults for this specific agent.
+ */
+export interface BatchingConfig {
+  /** Hold first message N ms before processing, to allow rapid follow-ups to batch together. 0 = disabled. */
+  firstMessageDelayMs?: number;
+  /** Window to collect subsequent messages while one is in-flight (ms). 0 = batching disabled. */
+  debounceWindowMs?: number;
+  /** Maximum messages collected in a single batch. */
+  maxBatchMessages?: number;
+}
+
+/**
+ * Governance SDK configuration persisted on the SubAgent document.
+ *
+ * The API-mode bearer token is NEVER stored here. At runtime the
+ * platform resolves it from the `GOVERNANCE_API_KEY` env var. This
+ * keeps secrets out of MongoDB, support logs, and backups.
+ */
+export interface GovernanceConfig {
+  mode: 'sdk' | 'api';
+  /** SDK mode — local in-memory policy rules */
+  rules?: {
+    blockTools?: string[];
+    requireApproval?: string[];
+    tokenBudget?: number;
+  };
+  /** API mode — remote enforcement server URL */
+  serverUrl?: string;
+}

package/node_modules/@lua/shared-types/src/agent-invocation.types.ts

@@ -0,0 +1,73 @@
+import type { UserContent } from 'ai';
+
+/**
+ * Wire-format input for sandbox `Agents.invoke` / `POST /chat/generate/:agentId`
+ * when triggered programmatically by another agent/skill/tool.
+ *
+ * Intentionally a narrow, safe subset of the public `ChatMessageDto` — omits
+ * sandbox-only overrides (`skillOverride`, `preprocessorOverride`, etc.),
+ * webhook payloads, navigation hints, and persona override.
+ *
+ * Either `prompt` or `messages` must be provided. When `prompt` is given, it is
+ * converted into a single `{ role: 'user', content: [{ type: 'text', text: prompt }] }`
+ * message downstream.
+ */
+export interface AgentInvocationInput {
+  /** Shortcut: plain-text prompt. Mutually exclusive with `messages`. */
+  prompt?: string;
+  /** AI SDK `UserContent` (text/image/file parts). Mutually exclusive with `prompt`. */
+  messages?: UserContent;
+  /** Override the target agent's system prompt for this invocation. */
+  systemPrompt?: string;
+  /** Additional runtime context attached to the request. */
+  runtimeContext?: string;
+  /**
+   * Optional thread ID suffix for conversation scoping. When omitted, the
+   * invocation flows into the caller-user's default chat thread with the
+   * target agent (same behavior as a direct `POST /chat/generate/:agentId`
+   * call with no `threadId`). Pass a custom value to isolate invocations.
+   */
+  threadId?: string;
+  /** Channel identifier, defaults to `'agent-invocation'`. */
+  channel?: string;
+  /** Free-form request tag persisted on the stored Message record (e.g. a UUID
+   *  or external trace id for correlation). Not a user identifier. Omitted
+   *  by default. */
+  identifier?: string;
+  /**
+   * Explicit user to invoke as. Use from context-less triggers (webhooks,
+   * pre-defined jobs) where there is no ambient user — mirrors the `User.get(userId)`
+   * contract. When omitted from a webhook/pre-defined job, the invocation runs in
+   * system scope (no per-user identity, no conversation history). Ignored during
+   * a user-authenticated turn — the turn's user is always used, no impersonation.
+   */
+  userId?: string;
+}
+
+/**
+ * Narrowed, wire-safe output for `Agents.invoke`. A slice of the internal
+ * `FullOutput` shape — raw Mastra steps / tripwire payloads are intentionally
+ * not exposed to skill code.
+ */
+export interface AgentInvocationOutput {
+  /** Final response text (post-processor-modified, if applicable). */
+  text: string;
+  /** AI SDK `FinishReason` (or `'preprocessor_blocked'` / `'governance_blocked'`). */
+  finishReason?: string;
+  /** Token usage summary. */
+  usage?: {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    reasoningTokens?: number;
+    cachedInputTokens?: number;
+  };
+  /** Names of tools invoked during generation. */
+  toolsUsed?: string[];
+  /**
+   * Echoes back the `threadId` suffix the caller passed in (if any). When the
+   * caller omitted `threadId`, this is undefined — the invocation ran in the
+   * user's default chat thread with the target agent.
+   */
+  threadId?: string;
+}

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

@@ -170,3 +170,21 @@ export interface CachedDeviceTrigger {
   payloadSchema?: Record<string, any>; // JSON Schema
   hasExecute: boolean;
 }
+
+/** Command definition sent by a device at connect time (self-describing) */
+export interface DeviceCommandDefinition {
+  name: string;
+  description: string;
+  inputSchema?: Record<string, any>;
+  timeoutMs?: number;
+  retry?: { maxAttempts: number; backoffMs: number };
+}
+
+/** Standalone device trigger definition (compiled agent-side primitive) */
+export interface CachedDeviceTriggerDefinition {
+  name: string;
+  description: string;
+  payloadSchema?: Record<string, any>;
+  artifact: string; // Compressed execute handler
+  env: Record<string, string>;
+}

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

@@ -2,7 +2,9 @@ export * from './channel.type';
 export * from './unstructured-types';
 export * from './ai-generate.types';
 export * from './ai-generate.utils';
+export * from './agent-invocation.types';
 export * from './sandbox-contract';
 export * from './device.types';
 export * from './model-registry';
+export * from './agent-config.types';
 export * from './persona-defaults';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.10.5",
+  "version": "3.12.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",
@@ -64,6 +64,7 @@
     "@lua/shared-types": "workspace:*",
     "@tailwindcss/postcss": "^4.1.14",
     "@tanstack/react-query": "^5.90.11",
+    "@truestamp/canonify": "^2.1.0",
     "ai": "^5.0.76",
     "autoprefixer": "^10.4.21",
     "chalk": "^5.3.0",

package/template/package.json

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