lua-cli 3.43.0 → 3.45.0

package/dist/api-exports.d.ts

@@ -720,6 +720,15 @@ export declare interface AgentsApi {
         promote(version: number, opts: {
             expectActive: number | null;
         }): Promise<unknown>;
+        /**
+         * WD — restore `version`, a version that was ACTIVE before, is OLDER than the active one and was active within the
+         * last 7 days (`supervision:rollback`, held only by a WATCHDOG grant; only from a workflow step the grant names).
+         * Compare-and-swap: refused (409 `supervision_rollback_conflict`) unless `expectActive` is the active version.
+         * Other refusals: `supervision_rollback_never_active`, `supervision_rollback_not_older`, `supervision_rollback_too_old`.
+         */
+        rollback(version: number, opts: {
+            expectActive: number;
+        }): Promise<unknown>;
         /**
          * Soft-delete `version` (`supervision:release`; only from a named workflow step). Refused
          * (409 `supervision_version_not_superseded`) unless the version is `superseded` — never the
@@ -788,10 +797,12 @@ export declare interface AgentsApi {
          * Publish workflow `version` (a semver). Compare-and-swap: refused (409 `WORKFLOW_DEPLOY_CONFLICT`, the
          * message names the live version) unless `expectActive` is the workflow's live version ID (null = none live).
          * A deploy also records a new active agent version, so a later `versions.promote` needs a fresh
-         * `expectActive`.
+         * `expectActive`. `commitHash` is the optional source commit the deployed version was built from; it is
+         * forwarded unchanged, and when omitted the platform decides what to record.
          */
         deploy(workflowId: string, version: string, opts: {
             expectActive: string | null;
+            commitHash?: string;
         }): Promise<unknown>;
     };
     persona(agentId: string): {
@@ -809,9 +820,14 @@ export declare interface AgentsApi {
                 size?: number;
             }[];
         }>;
+        /**
+         * The file's text. A file that is not valid UTF-8 (an image, an archive) comes back base64 with
+         * `encoding: 'base64'` — never decoded as text. Absent `encoding` ⇒ `content` is the UTF-8 text.
+         */
         get(path: string): Promise<{
             path: string;
             content: string;
+            encoding?: 'base64';
         }>;
     };
     /** Environment variable NAMES only — values are never returned (`supervision:observe`). */
@@ -820,6 +836,17 @@ export declare interface AgentsApi {
             keys: string[];
         }>;
     };
+    /**
+     * What the agent serves RIGHT NOW (`supervision:observe`): its live skills (each with its tools), the published
+     * persona, its pre/postprocessors and its `model`, read from each primitive's live pointer, never the latest push. Each
+     * `versionId` means what an agent version snapshot's does (skill = semver, processor = version id, persona =
+     * persona version id with the same `contentHash`), so you can diff live against a staged version even when the
+     * agent has no promoted agent version (`activeAgentVersion: null`). `model` is the model the agent runs now (`''`
+     * when unset, as in a snapshot): a promote applies the version's model, so compare it with the snapshot's. Metadata and hashes only: read code with
+     * `source(agentId).get(path)` and persona text with `persona(agentId).versions()`. Platform only: offline
+     * (`lua test` / `lua dev`) it throws `supervision_offline_unsupported`.
+     */
+    deployed(agentId: string): Promise<DeployedPrimitives>;
     /**
      * Supervision events of the target (`supervision:observe`). Each event of a subscribed kind
      * (`governance.blocked`, `workflow.run_failed`, `workflow.run_gated`, `connection.unhealthy`, …)
@@ -1196,6 +1223,12 @@ declare interface AgentToolScope_2 {
     connectionIds?: string[];
     /** Allowlisted skill ids (from the agent's `subAgent.skills`). */
     skillIds?: string[];
+    /**
+     * Allowlisted tool ids, as a workflow agent step's `toolScope.toolIds` declares them. Today the runtime applies
+     * it to device tools only: when it names at least one `device__<device>__<command>` tool, only the named device
+     * tools are offered; otherwise (absent, empty, or no device tool named) device tools are unaffected.
+     */
+    toolIds?: string[];
 }
 
 export declare const AI: AiApi;
@@ -1251,6 +1284,27 @@ export declare interface AiApi {
      * ```
      */
     generate(options: AiGenerateInput): Promise<AiGenerateOutput>;
+    /**
+     * Generate ONE image from a prompt and return its hosted CDN url. The image sibling of `generate`:
+     * proxied to the API (server-side provider + CDN upload + org billing), not the agent chat pipeline.
+     * Returns a public `https://cdn.heylua.ai/…` url ready to embed (e.g. in a deck or a message).
+     *
+     * @example
+     * ```typescript
+     * const url = await AI.image('A sunrise over a calm sea, minimal, no text');
+     * const wide = await AI.image('A clean product hero shot', { size: '1536x1024', quality: 'high' });
+     * ```
+     */
+    image(prompt: string, options?: Omit<AiImageInput, 'prompt'>): Promise<string>;
+    /**
+     * Generate one image with full options. Returns the full `{ url, model, provider }`.
+     *
+     * @example
+     * ```typescript
+     * const { url, model } = await AI.image({ prompt: 'A minimal abstract cover', size: '1536x1024' });
+     * ```
+     */
+    image(options: AiImageInput): Promise<AiImageOutput>;
 }
 
 /**
@@ -1392,6 +1446,34 @@ export declare interface AiGenerateToolResult {
     isError?: boolean;
 }
 
+/**
+ * Wire-format types for sandbox `AI.image` / `POST developer/ai/:agentId/image` (JSON-serializable).
+ * The image sibling of `AI.generate`: generates ONE image from a prompt, hosts it on the CDN, bills the
+ * agent's org, and returns the public URL. Not the agent chat pipeline. DTOs live in `@lua/shared-dto`.
+ */
+declare interface AiImageInput {
+    /** Plain-language description of the image to draw (3–4000 chars). */
+    prompt: string;
+    /** Provider-prefixed image model, e.g. "openai/gpt-image-2". Defaults to the agent/platform image model. */
+    model?: string;
+    /** Image size, e.g. "1024x1024", "1536x1024", "1024x1536" (provider-dependent). */
+    size?: string;
+    /** Render quality. */
+    quality?: 'low' | 'medium' | 'high';
+    /** Output image format. */
+    outputFormat?: 'png' | 'jpeg' | 'webp';
+}
+
+/** Result from the image-generation surface. `url` is a public, hosted CDN link. */
+declare interface AiImageOutput {
+    /** Public CDN URL of the generated image. */
+    url: string;
+    /** The model that produced the image. */
+    model: string;
+    /** The provider that produced the image. */
+    provider: string;
+}
+
 export declare const and: (...args: LuaPredicate[]) => LuaPredicate;
 
 /**
@@ -1906,9 +1988,9 @@ export declare const CDN: {
 /**
  * Channel type.
  * Represents the communication channel through which a request originated.
- * Known channels are typed as string literals, unrecognized channels are unknown.
+ * Known channels are typed as string literals; unrecognised channels fall through as plain strings.
  */
-export declare type Channel = 'web' | 'whatsapp' | 'facebook' | 'instagram' | 'slack' | 'teams' | 'front' | 'messagebird' | 'api' | 'dev' | 'email' | string;
+export declare type Channel = 'web' | 'pop' | 'phone' | 'meeting' | 'whatsapp' | 'facebook' | 'instagram' | 'slack' | 'teams' | 'front' | 'messagebird' | 'api' | 'dev' | 'email' | 'rcs' | 'sms' | 'mms' | 'imessage' | 'device' | string;
 
 /** Channels accepted by the v1 unified send. Warm-only channels (teams,
  * instagram, messenger) require a prior inbound conversation. */
@@ -2918,8 +3000,8 @@ export { DatasetRef }
  *     paper_low: {
  *       description: 'Fired when paper level drops below threshold',
  *       payloadSchema: z.object({ level: z.number() }),
- *       execute: async (payload, { agent }) => {
- *         await agent.chat(\`Printer paper low: \${payload.level}%\`);
+ *       execute: async (payload, { device, trigger }) => {
+ *         return { device: device.name, trigger: trigger.name, level: payload.level };
  *       },
  *     },
  *   },
@@ -2944,8 +3026,8 @@ export declare function defineDevice(config: LuaDeviceConfig): LuaDevice;
  *   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}%\`);
+ *   execute: async (payload, { device, trigger }) => {
+ *     return { device: device.name, trigger: trigger.name, level: payload.level };
  *   },
  * });
  * ```
@@ -3139,6 +3221,69 @@ export declare interface DeliveryView {
     failedAt?: string;
 }
 
+declare interface DeployedPersona {
+    versionId: string;
+    version?: number;
+    /** The same hash an agent version snapshot stores for its persona. */
+    contentHash: string;
+}
+
+/**
+ * SV (LUA-1080) — `primitives.deployed` / `Agents.deployed(id)`: the target's CURRENTLY DEPLOYED primitives, read from
+ * each primitive's live pointer (never the latest push). An agent whose live state was deployed primitive by
+ * primitive, with no promoted agent version, answers the same shape, so a supervisor can diff it against a staged
+ * version.
+ *
+ * `versionId` follows the agent version snapshot's semantics entry by entry: a skill's is its semver, a processor's
+ * the version document id, the persona's the PersonaVersion id with the same `contentHash`. Never code, tool source
+ * or persona text: read those with `source.get` and `persona.versions`.
+ */
+declare interface DeployedPrimitives {
+    agentId: string;
+    /** The promoted (`active`) agent version, or null when the live state is not a promoted version. */
+    activeAgentVersion: number | null;
+    /**
+     * The model the agent runs now (`SubAgent.model`), with the agent version snapshot's meaning: a promote writes
+     * `snapshot.model` here, and an unset model reads `''` as it does in a snapshot, so `model === snapshot.model`
+     * holds exactly when the release would leave the model unchanged.
+     */
+    model: string;
+    skills: DeployedSkill[];
+    /** The served (`published`) persona, or null when none is published. */
+    persona: DeployedPersona | null;
+    preprocessors: DeployedProcessor[];
+    postprocessors: DeployedProcessor[];
+}
+
+declare interface DeployedProcessor {
+    id: string;
+    name?: string;
+    /** The live version document id (`activeVersionId`). */
+    versionId: string;
+    version: string;
+    codeHash?: string;
+}
+
+declare interface DeployedSkill {
+    skillId: string;
+    name?: string;
+    /** The live semver (`Skills.activeVersionId`), as an agent version snapshot pins it. */
+    versionId: string;
+    version: string;
+    /** Where the skill came from: `cli`, `marketplace`, `manual` or `template`. */
+    origin?: string;
+    /** The deployed version's tools. Equal skill `versionId` ⇒ equal tools. */
+    tools: DeployedTool[];
+}
+
+declare interface DeployedTool {
+    name: string;
+    /** The uploaded bundle's content hash, when the version stores one. */
+    codeHash?: string;
+    /** Whether the author's TypeScript source is attached to this version. */
+    hasSource: boolean;
+}
+
 declare type Depth = [never, 0, 1, 2, 3, 4];
 
 /** Configuration for a single device command (agent → device) */
@@ -3164,13 +3309,20 @@ export declare interface DeviceTriggerConfig {
     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.)
+     * Receives `(payload, { device, trigger })`; the returned value is the trigger result.
      */
-    execute?: (payload: any, context: {
-        agent: any;
-        device: any;
-        trigger: any;
-    }) => Promise<any>;
+    execute?: (payload: any, context: DeviceTriggerContext) => Promise<any>;
+}
+
+/** Context a device-trigger handler receives; mirrors what lua-core (execute.device-trigger.service.ts) and sandbox-runtime (wrapper-templates.ts) pass. */
+export declare interface DeviceTriggerContext {
+    device: {
+        name: string;
+    };
+    trigger: {
+        name: string;
+        triggerId: string;
+    };
 }
 
 /** A matched org member and their shareable channel targets (empty when none shared). */
@@ -3657,6 +3809,12 @@ declare abstract class HttpClient {
      * @private
      */
     private request;
+    /**
+     * A backoff wait the caller's signal can cut short (BAC-1097): resolves at `ms` or on abort, whichever is
+     * first, and never leaves the timer or the listener behind. The caller re-checks `signal.aborted` afterwards.
+     * @private
+     */
+    private sleep;
     /**
      * Non-2xx classification shared by `request` and `httpStream` (WF-204): 401s become
      * `AuthenticationError` (ownership vs credential), 403s throw, everything else returns the
@@ -4970,8 +5128,8 @@ export declare class LuaDevice {
  *     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}%\`);
+ *       execute: async (payload, { device, trigger }) => {
+ *         return { device: device.name, trigger: trigger.name, level: payload.level };
  *       },
  *     },
  *   },
@@ -5003,12 +5161,7 @@ export declare class LuaDeviceTrigger {
     readonly name: string;
     readonly description: string;
     readonly payloadSchema?: ZodType;
-    readonly execute: (payload: any, context: {
-        agent: any;
-        device: {
-            name: string;
-        };
-    }) => Promise<any>;
+    readonly execute: (payload: any, context: DeviceTriggerContext) => Promise<any>;
     constructor(config: LuaDeviceTriggerConfig);
 }
 
@@ -5029,8 +5182,8 @@ export declare class LuaDeviceTrigger {
  *   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}%`);
+ *   execute: async (payload, { device, trigger }) => {
+ *     return { device: device.name, trigger: trigger.name, level: payload.level };
  *   },
  * });
  * ```
@@ -5043,12 +5196,7 @@ export declare interface LuaDeviceTriggerConfig {
     /** 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>;
+    execute: (payload: any, context: DeviceTriggerContext) => Promise<any>;
 }
 
 /**
@@ -6894,7 +7042,11 @@ export declare type LuaWorkflowBuildCode = 'duplicate-step-id' | 'unknown-step-r
 */
 | 'approval-inside-container' | 'node-type-unsupported-in-container' | 'empty-graph' | 'ephemeral-role-too-long' | 'role-ref-and-inline' | 'approver-excludes-only-candidate' | 'four-eyes-requires-editable' | 'escalation-chain-not-terminal' | 'escalation-chain-too-long'
 /** LUA-973: `remindAfterHours` is not a number of hours in 1..720 (`validateApprovalReminder`). */
-| 'remind-after-invalid' | 'editable-path-invalid' | 'env-template-secret-key' | 'invalid-envelope' | 'invalid-step' | 'invalid-step-id' | 'invalid-workflow-name' | 'schedule-input-required' | 'schedule-input-invalid' | 'hitl-duration-defaulted' | 'WORKFLOW_UNPLACED_STEP';
+| 'remind-after-invalid'
+/** BAC-2062: the builder mirror of the BAC-619 validator codes: a `waitForSignal` name a delivery refuses. */
+| 'signal-name-invalid'
+/** BAC-2062: a numeric approval / waitForSignal `timeoutHours` outside 1..720. */
+| 'timeout-hours-out-of-range' | 'editable-path-invalid' | 'env-template-secret-key' | 'invalid-envelope' | 'invalid-step' | 'invalid-step-id' | 'invalid-workflow-name' | 'schedule-input-required' | 'schedule-input-invalid' | 'hitl-duration-defaulted' | 'WORKFLOW_UNPLACED_STEP';
 
 export declare interface LuaWorkflowBuilder {
     then(step: StepRef): this;
@@ -6985,7 +7137,10 @@ export declare interface LuaWorkflowConfig {
      * marketplace template freezes from this schedule: `'installer'` (the default when absent — every install's
      * fires run as the person who installed, who gets the run card in their inbox) or `'system'` (the frozen copy
      * runs user-less and unwatched — no inbox card for its runs; the install response says so). On this agent the
-     * schedule runs as you either way.
+     * schedule runs as you, unless the platform has enabled author system schedules: then `'system'` makes this
+     * agent's own schedule run as the agent (`system:<agentId>`), like a template copy's, with you recorded as the
+     * deployer who scheduled it (the schedule stops if you lose access to the agent). A manual run ("Run now")
+     * always runs as the person who starts it.
      */
     schedule?: JobSchedule & {
         runAs?: 'installer' | 'system';
@@ -7208,6 +7363,13 @@ export declare type MCPTransport = 'sse' | 'streamable-http';
 
 declare type Message = TextMessage_2 | ImageMessage_2 | FileMessage_2;
 
+/**
+ * The text of a postprocessor's `message`, whichever shape it arrived in: a string as is,
+ * parts as their `text` parts joined with a newline (image and file parts are skipped).
+ * Anything else yields `''`.
+ */
+export declare function messageText(message: PostProcessorMessage | null | undefined): string;
+
 export declare const Metrics: MetricsApi;
 
 /**
@@ -7564,7 +7726,7 @@ declare class PostProcessor {
     getName(): string;
     getDescription(): string;
     getPriority(): number;
-    execute(user: UserDataInstance, message: string, response: string, channel: string): Promise<PostProcessorResponse>;
+    execute(user: UserDataInstance, message: PostProcessorMessage, response: string, channel: string): Promise<PostProcessorResponse>;
 }
 export { PostProcessor as LuaPostprocessor }
 export { PostProcessor }
@@ -7585,10 +7747,18 @@ export declare interface PostProcessorConfig {
     /**
      * Function that processes the agent's response before sending to user.
      * MUST return { modifiedResponse: string } - the formatted response text.
+     * `message` is the user's message: a string or its parts — read it with `messageText(message)`.
      */
-    execute: (user: UserDataInstance, message: string, response: string, channel: string) => Promise<PostProcessorResponse>;
+    execute: (user: UserDataInstance, message: PostProcessorMessage, response: string, channel: string) => Promise<PostProcessorResponse>;
 }
 
+/**
+ * The user's message as a postprocessor receives it (LUA-1075).
+ * lua-core passes the turn's user content unchanged: a plain string, or the message parts
+ * (`[{ type: 'text', text }, { type: 'image', ... }]`). Use {@link messageText} for its text.
+ */
+export declare type PostProcessorMessage = string | ChatMessage[];
+
 /**
  * PostProcessor override for sandbox testing.
  * Maps production postprocessor ID to sandbox version ID.
@@ -8252,13 +8422,19 @@ declare type RequestCredentialDescriptor = {
 declare type RequestCredentialInput = string | RequestCredential;
 
 /**
- * Optional per-request overrides (WF-202, 03 §3.7 client-deadline rule). Today only
- * `timeoutMs`: `WorkflowApi.startRun` long-polls with `waitSeconds ≤ 55` and raises
- * its deadline to `(waitSeconds + 10) s` so the 30 s default abort never races the
- * server. Every other call site is untouched (undefined ⇒ the 30 s default).
+ * Optional per-request overrides (WF-202, 03 §3.7 client-deadline rule).
+ * - `timeoutMs`: `WorkflowApi.startRun` long-polls with `waitSeconds ≤ 55` and raises
+ *   its deadline to `(waitSeconds + 10) s` so the 30 s default abort never races the
+ *   server. Every other call site is untouched (undefined ⇒ the 30 s default).
+ * - `signal` (BAC-1097): a caller's AbortSignal. It is linked to the request's own
+ *   AbortController (which still owns the `timeoutMs` deadline — one controller, no
+ *   double-cancel), so aborting closes the in-flight fetch, stops any retry / Core-drain
+ *   backoff, and answers the `REQUEST_ABORTED` envelope. `AgentsApiService.invoke` passes
+ *   `AgentInvocationInput.signal` here; the signal is never serialized.
  */
 declare interface RequestOverrides {
     timeoutMs?: number;
+    signal?: AbortSignal;
 }
 
 /**
@@ -8969,6 +9145,14 @@ declare interface SupervisionLogRow {
     logSource?: string;
     primitiveName?: string;
     toolName?: string;
+    /**
+     * LUA-1076 — the agent version that served the row (string form of the version number / id), when the writer
+     * stamped it. Lets a supervisor tell a staged version's errors from the live version's. Filter with
+     * `{ agentVersion }` on the `logs` op.
+     */
+    agentVersion?: string;
+    /** 'production' for the promoted (live) version; 'sandbox' for previews, practice and dev. Filter with `{ environment }`. */
+    environment?: string;
     /**
      * A non-identifying conversation key: the same value for every row of one conversation (thread) on this target,
      * never the thread id itself (which embeds the end user's id), and different on another target. Present on rows
@@ -10691,9 +10875,6 @@ export declare const Workflows: WorkflowsApi;
  *
  * - `start` options are checked: an option key it does not know throws
  *   `WorkflowApiError{ code:'VALIDATION_FAILED' }` naming it — never silently dropped.
- *
- * `startBatch`, `signalByKey`, `raiseBudget`, `setGoal` and `goals.*` are part of the
- * frozen member list and throw `WORKFLOWS_API_UNAVAILABLE` until their routes ship.
  */
 export declare interface WorkflowsApi {
     start(nameOrId: string, input?: unknown, opts?: {
@@ -10791,6 +10972,11 @@ export declare interface WorkflowsApi {
             code?: string;
         }>;
     }>;
+    /**
+     * Raise a parked or in-flight run's caps (increases only). Only the run's creator/holder or an
+     * org admin may raise it. Refusals are typed `WorkflowApiError`s: 400 `VALIDATION_FAILED` /
+     * `CAP_EXCEEDED`, 403 `NOT_RUN_CREATOR`, 404 `RUN_NOT_FOUND`, 409 `BUDGET_NOT_RAISABLE`.
+     */
     raiseBudget(runId: string, patch: {
         maxCredits?: number;
         maxSteps?: number;
@@ -10805,6 +10991,7 @@ export declare interface WorkflowsApi {
     } | {
         raised: false;
         reason: 'already_raised';
+        runStatus?: WorkflowRunStatus;
     }>;
     setGoal(agentId: string, goal: Record<string, unknown>): Promise<Record<string, unknown>>;
     goals: {