lua-cli 3.22.0 → 3.23.1

package/dist/api-exports.d.ts

@@ -1,11 +1,22 @@
 import { CallWarning } from 'ai';
 import { FinishReason } from 'ai';
 import { LanguageModelUsage } from 'ai';
+import { ModelMessage } from 'ai';
 import { ReasoningOutput } from 'ai';
 import { UserContent } from 'ai';
 import { z } from 'zod';
 import { ZodType } from 'zod';
 
+/**
+ * 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.
+ */
+declare interface AgentInvocationEffects {
+    reviewDraftsCreated: number;
+    storage: 'lua_inbox';
+}
+
 /**
  * Wire-format input for sandbox `Agents.invoke` / `POST /chat/generate/:agentId`
  * when triggered programmatically by another agent/skill/tool.
@@ -62,13 +73,22 @@ declare interface AgentInvocationInput {
     /** Per-call timeout in ms. Absent ⇒ the client default (120s). Set by scheduled agent jobs
      *  to 180s so the cloud tier cuts off at the same point the desktop's local runner does. */
     timeoutMs?: number;
+    /** Per-request model override ("provider/model" code). Unknown codes fall back per
+     *  approved-models policy server-side. */
+    model?: string;
+    /** Task 14 (tasks-redesign) — per-task connector + skill scoping. See `AgentToolScope`. */
+    toolScope?: AgentToolScope;
+    /**
+     * PRO-979 (A3) — cooperative mid-run cancellation. Honored where the
+     * transport boundary supports it (the loopback HTTP call is aborted); the
+     * in-flight server-side turn is NOT hard-killed — callers that abort must
+     * treat still-landing side effects as possible and record them (the job
+     * runner's ledger does, via postFence). NOT serialized on the wire — this
+     * field exists only on in-process invocations.
+     */
+    signal?: AbortSignal;
 }
 
-/**
- * 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.
- */
 declare interface AgentInvocationOutput {
     /** Final response text (post-processor-modified, if applicable). */
     text: string;
@@ -84,6 +104,10 @@ declare interface AgentInvocationOutput {
     };
     /** Names of tools invoked during generation. */
     toolsUsed?: string[];
+    /** Trusted effects emitted by Lua-owned tool wrappers. This is intentionally
+     *  a small aggregate, not raw tool output: unattended task receipts use it
+     *  to report what happened without trusting model-authored prose. */
+    effects?: AgentInvocationEffects;
     /**
      * Echoes back the `threadId` suffix the caller passed in (if any). When the
      * caller omitted `threadId`, this is undefined — the invocation ran in the
@@ -175,6 +199,23 @@ export declare interface AgentsApi {
     invoke(targetAgentId: string, input: AgentInvocationInput): Promise<AgentInvocationOutput>;
 }
 
+/**
+ * Task 14 (tasks-redesign) — per-task connector + skill scoping for a scheduled
+ * agent run. Non-empty `connectionIds` restricts the turn's MCP servers to the
+ * listed agent connections; non-empty `skillIds` restricts the turn's skills.
+ * Absent field or empty array ⇒ no filtering (the agent's full toolset).
+ *
+ * SECURITY: only honored on internally-authenticated invocations (the
+ * `X-Internal-Auth` agent-invoke path used by the server-side job runner) —
+ * lua-core drops it from any client-authenticated `/chat/*` request.
+ */
+declare interface AgentToolScope {
+    /** Allowlisted agent connection ids (UnifiedTo `unifiedId`s). */
+    connectionIds?: string[];
+    /** Allowlisted skill ids (from the agent's `subAgent.skills`). */
+    skillIds?: string[];
+}
+
 export declare const AI: AiApi;
 
 /**
@@ -219,13 +260,13 @@ export declare interface AiApi {
 /**
  * Wire-format input for sandbox `AI.generate` / `POST .../generate` (JSON-serializable).
  * Serializable subset of AI SDK `generateText` parameters.
- * `messages` is untyped over HTTP; callers typically send AI SDK `ModelMessage[]`.
  */
 export declare interface AiGenerateInput {
     model?: string;
     system?: string;
     prompt?: string;
-    messages?: unknown[];
+    /** AI SDK `ModelMessage[]`. Server-validated; malformed messages are rejected with 400. */
+    messages?: ModelMessage[];
     temperature?: number;
     maxOutputTokens?: number;
     /**
@@ -1064,7 +1105,7 @@ declare interface CustomDataAPI {
      * @param limit - Items per page
      * @returns Promise resolving to paginated entries
      */
-    get(collectionName: string, filter?: Record<string, any>, page?: number, limit?: number): Promise<GetCustomDataResponse>;
+    get(collectionName: string, filter?: LuaQuery, page?: number, limit?: number): Promise<GetCustomDataResponse>;
     /**
      * Gets a specific entry by ID.
      * @param collectionName - Collection name
@@ -1081,6 +1122,12 @@ declare interface CustomDataAPI {
      * @returns Promise resolving to update response
      */
     update(collectionName: string, entryId: string, data: Record<string, any>, searchText?: string): Promise<UpdateCustomDataResponse>;
+    /** Atomically sets and removes top-level entry fields and optionally changes search text. */
+    patch(collectionName: string, entryId: string, mutation: {
+        set?: Record<string, any>;
+        unset?: string[];
+        searchText?: string | null;
+    }): Promise<UpdateCustomDataResponse>;
     /**
      * Performs vector search on a collection.
      * @param collectionName - Collection name
@@ -1139,7 +1186,7 @@ export declare const Data: {
      * @param limit - Items per page (default: 10)
      * @returns Promise resolving to array of entries
      */
-    get(collectionName: string, filter?: any, page?: number, limit?: number): Promise<GetCustomDataResponse>;
+    get(collectionName: string, filter?: LuaQuery, page?: number, limit?: number): Promise<GetCustomDataResponse>;
     /**
      * Retrieves a specific entry by ID.
      *
@@ -1211,6 +1258,12 @@ export declare class DataEntryInstance {
      * @throws Error if the update fails
      */
     update(data: Record<string, any>, searchText?: string): Promise<Record<string, any>>;
+    patch(mutation: {
+        set?: Record<string, any>;
+        unset?: string[];
+        searchText?: string | null;
+    }): Promise<Record<string, any>>;
+    unset(...fields: string[]): Promise<Record<string, any>>;
     /**
      * Deletes the custom data entry
      * @returns Promise resolving to true if deletion was successful
@@ -1543,6 +1596,18 @@ declare interface GovernanceConfig {
     /** SDK mode — local in-memory policy rules layered on top of any `preset`. */
     rules?: {
         blockTools?: string[];
+        /**
+         * Tool names that require human approval before executing. Matched against
+         * the runtime tool name on each tool_call (the SDK's `requireToolApproval`
+         * preset). Canonical key — writers use this.
+         */
+        requireToolApproval?: string[];
+        /**
+         * @deprecated Legacy key for `requireToolApproval`. Historically fed into the
+         * SDK's `requireApproval(actions)` preset, which matches action CATEGORIES —
+         * so tool names stored here never matched at runtime (PRO-257). Read-compat
+         * only: accepted on read when `requireToolApproval` is absent; never written.
+         */
         requireApproval?: string[];
         tokenBudget?: number;
     };
@@ -1875,7 +1940,11 @@ declare interface JobExecution {
     retryCount?: number;
 }
 
-declare type JobExecutionStatus = 'pending' | 'running' | 'completed' | 'failed' | 'timeout';
+/** The complete persisted vocabulary (shared-schemas job.execution.schema.ts
+ *  is the source of truth): PRO-979 added the explicit cancellation/ownership
+ *  lifecycle; claimed/killed/cancelled predate it. Additive — existing
+ *  consumers narrowing on the old five values keep compiling. */
+declare type JobExecutionStatus = 'pending' | 'claimed' | 'running' | 'cancellation_requested' | 'completed' | 'failed' | 'timeout' | 'killed' | 'cancelled' | 'abandoned' | 'reaped';
 
 /**
  * Job Instance class.
@@ -2546,7 +2615,7 @@ export declare class LuaJob {
      * @param config.name - Job name (required; non-empty string)
      * @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.timeout - Optional timeout in seconds (default: 300, supported range: 1-600)
      * @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)
@@ -2603,7 +2672,7 @@ export declare interface LuaJobConfig {
      * Receives metadata as parameter for accessing job configuration.
      */
     execute: (job: JobInstance) => Promise<any>;
-    /** Optional timeout in seconds (default: 300) */
+    /** Optional timeout in seconds (default: 300, supported range: 1-600) */
     timeout?: number;
     /** Optional retry configuration */
     retry?: {
@@ -2675,6 +2744,33 @@ export declare class LuaMCPServer {
  */
 export declare type LuaMCPServerConfig = MCPSSEServerConfig | MCPStreamableHttpServerConfig;
 
+/**
+ * The entity-independent, bounded Mongo-style filter accepted by Lua APIs.
+ * Root `$and`/`$or` branches and nested data fields share this recursive shape;
+ * the runtime compiler performs the stricter placement and resource checks.
+ */
+export declare interface LuaQuery {
+    [fieldOrLogicalOperator: string]: LuaQueryValue;
+}
+
+/** Field-level operators shared by every Lua platform Query surface. */
+export declare interface LuaQueryFieldOperators {
+    $eq?: LuaQueryScalar;
+    $ne?: LuaQueryScalar;
+    $gt?: LuaQueryScalar;
+    $gte?: LuaQueryScalar;
+    $lt?: LuaQueryScalar;
+    $lte?: LuaQueryScalar;
+    $in?: readonly LuaQueryScalar[];
+    $nin?: readonly LuaQueryScalar[];
+    $exists?: boolean;
+}
+
+/** JSON scalar accepted by the bounded Lua Query language. */
+export declare type LuaQueryScalar = string | number | boolean | null;
+
+declare type LuaQueryValue = LuaQueryScalar | readonly LuaQueryScalar[] | LuaQueryFieldOperators | LuaQuery | readonly LuaQuery[];
+
 /**
  * Lua request context.
  * Contains information about the current request.
@@ -4631,7 +4727,7 @@ declare interface ProductAPI {
     get(options?: {
         page?: number;
         limit?: number;
-        filter?: Record<string, any>;
+        filter?: LuaQuery;
     }): Promise<any>;
     /**
      * Creates a new product.
@@ -4684,7 +4780,7 @@ declare interface ProductAPI {
 declare interface ProductFilterOptions {
     page?: number;
     limit?: number;
-    filter?: Record<string, any>;
+    filter?: LuaQuery;
 }
 
 /**
@@ -5402,6 +5498,11 @@ declare interface UserDataAPI {
      * @returns Promise resolving to updated user data
      */
     update(data: Record<string, any>): Promise<any>;
+    /** Atomically sets and removes top-level user data fields. */
+    patch(mutation: {
+        set?: Record<string, any>;
+        unset?: string[];
+    }): Promise<any>;
     /**
      * Clears user data.
      * @returns Promise resolving when data is cleared
@@ -5452,6 +5553,11 @@ export declare class UserDataInstance {
      * @throws Error if the update fails
      */
     update(data: Record<string, any>): Promise<any>;
+    patch(mutation: {
+        set?: Record<string, any>;
+        unset?: string[];
+    }): Promise<any>;
+    unset(...fields: string[]): Promise<any>;
     /**
      * Clears all user data for the current user
      * @returns Promise resolving to true if clearing was successful