lua-cli 3.39.4 → 3.40.0

package/dist/api-exports.d.ts

@@ -44,18 +44,6 @@ declare interface AgentInvocationEffects {
     blocker?: TaskRunBlocker;
 }
 
-/**
- * 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.),
- * 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.
- */
 declare interface AgentInvocationInput {
     /** Shortcut: plain-text prompt. Mutually exclusive with `messages`. */
     prompt?: string;
@@ -364,6 +352,87 @@ export declare interface AgentsApi {
      * ```
      */
     invoke(targetAgentId: string, input: AgentInvocationInput): Promise<AgentInvocationOutput>;
+    /** Agents of your organization, with the supervision actions you hold on each. */
+    list(): Promise<SupervisedAgentSummary[]>;
+    /** One agent of your organization. */
+    get(agentId: string): Promise<SupervisedAgentSummary & {
+        personaVersion?: number;
+    }>;
+    /** Recent execution logs of a supervised agent (`supervision:observe`). No user ids; message bodies only with `supervision:observe-content`. */
+    logs(agentId: string, opts?: {
+        since?: string | number;
+        limit?: number;
+        level?: 'debug' | 'info' | 'warn' | 'error';
+        logSource?: string;
+    }): Promise<SupervisionLogRow[]>;
+    /** Workflow run metadata (no inputs/outputs) (`supervision:observe`). */
+    runs(agentId: string): {
+        list(opts?: {
+            limit?: number;
+            status?: string;
+            workflowId?: string;
+        }): Promise<SupervisionRunSummary[]>;
+        get(runId: string): Promise<SupervisionRunSummary>;
+    };
+    /** Read-only Data — only the collections the org admin named on the grant (`supervision:observe`). */
+    data(agentId: string): {
+        get(collection: string, entryId: string): Promise<unknown>;
+        query(collection: string, filter?: Record<string, unknown>, opts?: {
+            page?: number;
+            limit?: number;
+        }): Promise<unknown>;
+    };
+    versions(agentId: string): {
+        list(opts?: {
+            limit?: number;
+        }): Promise<unknown>;
+        get(version: number): Promise<unknown>;
+        diff(from: number, to: number): Promise<unknown>;
+        /** Chat staged `version` (`supervision:preview`). No tools run unless `toolScope.skillIds` allowlists them. */
+        preview(version: number, prompt: string, opts?: {
+            toolScope?: {
+                skillIds?: string[];
+            };
+        }): Promise<{
+            version: number;
+            text: string;
+            toolsUsed: string[];
+            finishReason?: string;
+        }>;
+        /**
+         * Make `version` live (`supervision:release`; only from a workflow step whose workflow the grant names).
+         * Compare-and-swap: refused (409 `PROMOTE_CONFLICT`) unless `expectActive` is the live version.
+         */
+        promote(version: number, opts: {
+            expectActive: number | null;
+        }): Promise<unknown>;
+    };
+    persona(agentId: string): {
+        versions(): Promise<unknown>;
+        /** Serve persona `version` (`supervision:release`). CAS on the served persona version. */
+        activate(version: number, opts: {
+            expectActive: number | null;
+        }): Promise<unknown>;
+    };
+    /** The source backup (`supervision:observe`). */
+    source(agentId: string): {
+        list(): Promise<{
+            files: {
+                path: string;
+                size?: number;
+            }[];
+        }>;
+        get(path: string): Promise<{
+            path: string;
+            content: string;
+        }>;
+    };
+    /** Environment variable NAMES only — values are never returned (`supervision:observe`). */
+    env(agentId: string): {
+        keys(): Promise<{
+            keys: string[];
+        }>;
+    };
 }
 
 export declare interface AgentStepOptions {
@@ -396,6 +465,22 @@ export declare interface AgentStepOptions {
      */
     maxMessages?: number;
     maxInputTokens?: number;
+    /**
+     * Claude Code plugins a tier:'job' coding turn loads (EM-WS3). Platform allowlist only — today
+     * `'lua-agent-builder'` (the lua-cli playbooks). Needs the claude-code harness (an Anthropic model) and the `shell`
+     * job tool; the turn then reaches the Lua API through a platform proxy pinned to THIS workflow's agent that allows
+     * staging only (compile, push of skills/jobs/webhooks/triggers/processors/backup, `version create`, status, logs)
+     * and refuses every deploy, promote, publish, activate, env, chat and runtime call.
+     */
+    plugins?: WorkflowJobPluginId[];
+    /**
+     * EM-WS3: pin a plugin step's Lua-API proxy (and its key) to ANOTHER agent instead of this workflow's own. Legal only
+     * beside `plugins`. Refused at run time (`target_not_granted`) unless the platform's plugin-target switch is on AND
+     * this workflow's agent holds a `supervision:act` or `supervision:release` grant on the target.
+     */
+    target?: {
+        agentId: string;
+    };
     /**
      * What this step DOES: `classify` | `extract` | `transform` | `draft` | `research` | `reason` | `code` |
      * `judge`. On a PUSHED definition it must come with a `model` — a static `taskClass` with none is refused
@@ -1913,7 +1998,9 @@ export declare function defineDeviceTrigger(config: LuaDeviceTriggerConfig): Lua
  * });
  * ```
  */
-export declare function defineTrigger<T = any>(config: LuaTriggerConfig<T>): LuaTrigger<T>;
+export declare function defineTrigger<S extends ZodType = ZodType<any>>(config: Omit<LuaTriggerConfig<z.infer<S>>, 'inputSchema'> & {
+    inputSchema?: S;
+}): LuaTrigger<z.infer<S>>;
 
 /**
  * Function-style LuaVoice definition. Equivalent to `new LuaVoice(config)`,
@@ -2445,8 +2532,8 @@ declare abstract class HttpClient {
      * Use this only when a successful response contains a one-time secret that
      * cannot be recovered after an ambiguous network or server failure.
      */
-    protected httpPostOnce<T>(url: string, data?: any, headers?: Record<string, string>): Promise<ApiResponse<T>>;
-    protected httpPostCoreDrainRetry<T>(url: string, data?: any, headers?: Record<string, string>): Promise<ApiResponse<T>>;
+    protected httpPostOnce<T>(url: string, data?: any, headers?: Record<string, string>, overrides?: RequestOverrides): Promise<ApiResponse<T>>;
+    protected httpPostCoreDrainRetry<T>(url: string, data?: any, headers?: Record<string, string>, overrides?: RequestOverrides): Promise<ApiResponse<T>>;
     /**
      * Performs an HTTP PUT request
      * @param url - The relative URL path to request (will be appended to baseUrl)
@@ -2678,6 +2765,26 @@ export declare interface IntegrationsApi {
     passthrough(integrationType: string, request: IntegrationPassthroughRequest): Promise<IntegrationPassthroughResponse>;
 }
 
+/**
+ * Who invoked this turn, when another agent created it through `Agents.invoke`.
+ * Verified server-side from the invocation token; never caller-supplied.
+ *
+ * Treat any turn that carries `invokedBy` as agent-initiated: a mutating tool
+ * should refuse it unless `supervisor` is true (the caller holds `supervision:act`
+ * on this agent) and the tool's own supervisor allowlist admits the change. A
+ * `delegatedUserId` NEVER grants owner rights.
+ */
+export declare interface InvokedBy {
+    /** The calling agent's id. */
+    agentId: string;
+    /** True only when an org admin granted the caller `supervision:act` on this agent. */
+    supervisor: boolean;
+    /** The caller's supervision scopes on this agent (e.g. `supervision:act`); `[]` on preview turns. */
+    scopes: string[];
+    /** Set when the caller passed `input.userId` to `Agents.invoke` (a delegated turn). */
+    delegatedUserId?: string;
+}
+
 /**
  * Job with versions array
  * Matches JobDto and job.schema.ts
@@ -3625,6 +3732,7 @@ export declare class LuaJob {
     private readonly timeout;
     private readonly retry?;
     private readonly metadata?;
+    private readonly health?;
     private readonly executeFunction;
     /**
      * Creates a new LuaJob instance.
@@ -3666,6 +3774,10 @@ export declare class LuaJob {
      * Gets the job metadata.
      */
     getMetadata(): Record<string, any> | undefined;
+    /**
+     * Gets the schedule-health declaration (EM-WS10), if any.
+     */
+    getHealth(): ScheduleHealthConfig | undefined;
     /**
      * Executes the job with the provided job instance.
      * @param job - Job instance with metadata and context
@@ -3703,6 +3815,16 @@ export declare interface LuaJobConfig {
      * Sent to server and accessible during execution.
      */
     metadata?: Record<string, any>;
+    /**
+     * Schedule health — a dead-man for this job, watched by the platform. The job's owner (its creator, else the
+     * org admins) gets ONE notice per incident — inbox card plus `notify` ('app' push, 'email', or 'emailApp', the
+     * default) — when, while the job is active:
+     *  - `maxSilenceMinutes` (5..43200): no run has completed successfully for that long (needs a recurring schedule);
+     *  - `alertAfterConsecutiveFailures` (1..50): that many runs failed in a row;
+     * and the notice resolves in place when the job is healthy again. Every transition is also an agent log line, so
+     * a log drain routes it to Better Stack / Datadog. Takes effect when the version is published.
+     */
+    health?: ScheduleHealthConfig;
 }
 
 /**
@@ -3864,6 +3986,12 @@ export declare interface LuaRequest {
      * current speaker. Undefined on 1:1 turns and on non-chat executions.
      */
     conversation?: ConversationRef;
+    /**
+     * Present only when ANOTHER agent created this turn via `Agents.invoke`
+     * (absent on user, channel, job, webhook and self-invoked turns, and offline in
+     * `lua test`). Read it defensively — older runtimes do not set it.
+     */
+    invokedBy?: InvokedBy;
 }
 
 /**
@@ -4113,7 +4241,9 @@ export declare interface LuaTriggerConfig<T = any> {
      * compiler carries it into the trigger version as declared metadata.
      * `input` maps the trigger context to the tool's arguments and runs in the
      * same server-side slot sandbox (15s budget shared with verify/filter) —
-     * it CANNOT call platform APIs. Omit `input` to execute with `{}`.
+     * it CAN call platform APIs (Data, Products, Baskets, Orders, User, AI,
+     * Agents, Jobs, …), same as a tool or webhook, since all three build their
+     * VM context through the same sandbox factory. Omit `input` to execute with `{}`.
      *
      * Declaring BOTH `tool` and `transform` runs the tool; the transform is
      * ignored (the compiler warns). Approval-gated tools are refused server-
@@ -4163,8 +4293,8 @@ export declare class LuaVoice {
     readonly name: string;
     readonly description?: string;
     readonly llm: LuaVoiceModelInput;
-    readonly stt: LuaVoiceModelInput;
-    readonly tts: LuaVoiceModelInput;
+    readonly stt?: LuaVoiceModelInput;
+    readonly tts?: LuaVoiceModelInput;
     readonly vad: LuaVoiceConfig_2['vad'];
     readonly vadOptions: LuaVoiceConfig_2['vadOptions'];
     readonly turnDetection: LuaVoiceConfig_2['turnDetection'];
@@ -4191,11 +4321,22 @@ export declare class LuaVoice {
  * pass either a string descriptor or a plugin class instance. The wire schema
  * (validated server-side) is the discriminated union in `@lua/shared-types`;
  * the compiler is what bridges the two.
- */
-export declare interface LuaVoiceConfig extends Omit<LuaVoiceConfig_2, 'llm' | 'stt' | 'tts'> {
+ *
+ * `stt`/`tts` are unconditionally optional here at the type level — a
+ * realtime `llm` legitimately omits both. The realtime-vs-cascaded
+ * requirement (cascaded needs both) is enforced by the compiler's zod
+ * `superRefine` in `@lua/shared-types`, not by this type. `name` is
+ * deliberately required here (unlike `@lua/shared-types`'s wire schema,
+ * which leaves it optional for its own unrelated server-side
+ * placeholder-name use case) since the `LuaVoice` constructor throws
+ * without it and a nameless voice is otherwise silently dropped from the
+ * compiled manifest.
+ */
+export declare interface LuaVoiceConfig extends Omit<LuaVoiceConfig_2, 'llm' | 'stt' | 'tts' | 'name'> {
+    name: string;
     llm: LuaVoiceModelInput;
-    stt: LuaVoiceModelInput;
-    tts: LuaVoiceModelInput;
+    stt?: LuaVoiceModelInput;
+    tts?: LuaVoiceModelInput;
     /** Optional human-readable description (surfaced in manifest + admin listings). */
     description?: string;
     /** Voice-only tools, in addition to skills attached to the owning agent. */
@@ -5325,7 +5466,9 @@ export declare type LuaWorkflowBuildCode = 'duplicate-step-id' | 'unknown-step-r
 * verdict (deferred for an inherit child, 03 §3.1 table). Kept for one minor so a consumer switching on the union still
 * compiles; removed in the next.
 */
-| 'workspace-not-declared' | 'workspace-inherit-without-parent-workspace' | 'workspace-inherit-conflict' | 'harness-requires-job-tier' | 'max-turns-requires-job-tier' | 'max-turns-invalid' | 'cap-exceeded' | 'chunk-size-invalid' | 'rate-limit-invalid' | 'backoff-invalid' | 'loop-interval-out-of-range' | 'mapping-placement' | 'container-arm-empty'
+| 'workspace-not-declared' | 'workspace-inherit-without-parent-workspace' | 'workspace-inherit-conflict' | 'harness-requires-job-tier' | 'max-turns-requires-job-tier' | 'max-turns-invalid'
+/** EM-WS3: a step's `plugins` outside the allowlist, repeated, or off the Job tier. */
+| 'plugins-invalid' | 'cap-exceeded' | 'chunk-size-invalid' | 'rate-limit-invalid' | 'backoff-invalid' | 'loop-interval-out-of-range' | 'mapping-placement' | 'container-arm-empty'
 /**
 * @deprecated LUA-684 — the builder no longer throws it: an `approval` / `waitForSignal` IS a container arm
 * (`parallel(['approve', …])`). Where the engine cannot run one — a `loop` body, the step of a `[map, step]`
@@ -5431,6 +5574,18 @@ export declare interface LuaWorkflowConfig {
     backfillOnEnable?: {
         maxOccurrences?: number;
     };
+    /**
+     * Schedule health — a dead-man for this schedule, watched by the platform (no heartbeat service to wire up).
+     * The agent's owner (the schedule's creator, else the org admins) gets ONE notice per incident — inbox card plus
+     * `notify` ('app' push, 'email', or 'emailApp', the default) — when, while the schedule is active:
+     *  - `maxSilenceMinutes` (5..43200): no scheduled run has COMPLETED successfully for that long;
+     *  - `alertAfterConsecutiveFailures` (1..3): that many scheduled runs failed in a row (the platform turns a
+     *    schedule off after 3, which always alerts);
+     * and the notice resolves in place when the schedule is healthy again. Every transition is also an agent log
+     * line (`lua logs`), so a log drain routes it to Better Stack / Datadog. Needs `schedule`; silence needs a
+     * recurring one. See docs/workflows/schedule-health.md.
+     */
+    health?: ScheduleHealthConfig;
     /** Literal JSON passed as run input on every scheduled fire; must validate against `inputSchema` (P0-5e). */
     scheduleInput?: Record<string, unknown>;
     goal?: WorkflowGoalEnvelope;
@@ -5483,6 +5638,8 @@ export { MapDescriptor }
 export declare interface MCPServerBaseConfig {
     /** Unique identifier for this MCP server */
     name: string;
+    /** Optional description of this MCP server */
+    description?: string;
     /** Optional timeout in milliseconds (default: 60000) */
     timeout?: number;
 }
@@ -6467,6 +6624,12 @@ declare interface PushJobVersionDTO {
     code?: string;
     codeS3Hash?: string;
     metadata?: Record<string, any>;
+    /** EM-WS10 — `LuaJob({ health })`; sent only when declared. */
+    health?: {
+        maxSilenceMinutes?: number;
+        alertAfterConsecutiveFailures?: number;
+        notify?: 'app' | 'email' | 'emailApp';
+    };
 }
 
 /**
@@ -6583,6 +6746,24 @@ export declare const rows: (s: LuaWorkflowStep<any, any, any> | string, path: st
     limit: number;
 }) => MapDescriptor;
 
+/** Where an incident notice goes beyond the inbox card (which always lands). */
+declare const SCHEDULE_HEALTH_NOTIFY_CHANNELS: readonly ["app", "email", "emailApp"];
+
+/** The declaration an author writes. At least one threshold is required. */
+declare interface ScheduleHealthConfig {
+    /** Alert when no scheduled run has completed successfully for this many minutes (5..43200). */
+    maxSilenceMinutes?: number;
+    /**
+     * Alert when this many scheduled runs in a row failed. Workflows and agent tasks are parked by the
+     * platform after 3 consecutive failures, so for them the value is 1..3; code jobs accept 1..50.
+     */
+    alertAfterConsecutiveFailures?: number;
+    /** Out-of-inbox routing for the notice: 'app' (push), 'email', or 'emailApp' (both). Default 'emailApp'. */
+    notify?: ScheduleHealthNotify;
+}
+
+declare type ScheduleHealthNotify = (typeof SCHEDULE_HEALTH_NOTIFY_CHANNELS)[number];
+
 /**
  * Additive field on primitive publish responses. When the agent is under
  * versioning the server performs a scoped promote and returns the newly
@@ -6723,6 +6904,35 @@ export declare interface StepPathRef<TOut> {
 /** An inline step object, or a string naming an entry declared by an `agentStep`/`specialistStep`/`toolStep`/`map` call in the same chain (03 §3.2.0). */
 export declare type StepRef = LuaWorkflowStep<any, any, any> | string;
 
+declare interface SupervisedAgentSummary {
+    agentId: string;
+    name?: string;
+    /** The supervision actions the CALLER holds on this agent (explicit grant rows only). */
+    actions: string[];
+}
+
+declare interface SupervisionLogRow {
+    timestamp: string | number | Date;
+    level?: string;
+    /** Present only when the caller holds `supervision:observe-content` on the target. */
+    message?: string;
+    logSource?: string;
+    primitiveName?: string;
+    toolName?: string;
+}
+
+declare interface SupervisionRunSummary {
+    runId: string;
+    workflowId?: string;
+    workflowName?: string;
+    status: string;
+    reason?: string;
+    trigger?: string;
+    createdAt?: number;
+    startedAt?: number;
+    completedAt?: number;
+}
+
 /**
  * Why an unattended run could not finish, reported by the agent itself instead
  * of being guessed from its prose. The platform — not the agent — writes every
@@ -7824,6 +8034,9 @@ export declare type WorkflowJobHarness = WorkflowJobHarness_2;
 
 declare type WorkflowJobHarness_2 = (typeof WORKFLOW_JOB_HARNESSES)[number];
 
+/** EM-WS3: the Job-tier plugin allowlist — a structural twin of the registry's id, parity-checked below. */
+declare type WorkflowJobPluginId = 'lua-agent-builder';
+
 declare type WorkflowJobResources = (typeof WORKFLOW_JOB_RESOURCES)[number];
 
 export declare type WorkflowJobToolId = 'shell' | 'read' | 'write' | 'edit' | 'glob' | 'grep' | 'git' | 'gh' | 'fetch' | 'ripwire';