lua-cli 3.17.4 → 3.18.0

package/dist/api-exports.d.ts

@@ -12,7 +12,7 @@ import { ZodType } from 'zod';
  *
  * Intentionally a narrow, safe subset of the public `ChatMessageDto` — omits
  * sandbox-only overrides (`skillOverride`, `preprocessorOverride`, etc.),
- * webhook payloads, navigation hints, and persona override.
+ * 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 }] }`
@@ -48,6 +48,13 @@ declare interface AgentInvocationInput {
      * a user-authenticated turn — the turn's user is always used, no impersonation.
      */
     userId?: string;
+    /**
+     * Raw payload from the trigger source (webhook body, trigger envelope).
+     * Surfaces on the invoked agent's `runtimeContext` as `webhookPayload` and
+     * flows to tool executions — turn-scoped, not persisted to memory. Listed in
+     * the original BAC-107 spec; wired through as part of PRO-186.
+     */
+    webhookPayload?: unknown;
 }
 
 /**
@@ -688,6 +695,158 @@ export declare const CDN: {
  */
 export declare type Channel = 'web' | 'whatsapp' | 'facebook' | 'instagram' | 'slack' | 'teams' | 'front' | 'messagebird' | 'api' | 'dev' | 'email' | string;
 
+/** Channels accepted by the v1 unified send. Warm-only channels (teams,
+ * instagram, messenger) require a prior inbound conversation. */
+export declare const CHANNEL_SEND_CHANNELS: readonly ["whatsapp", "sms", "email", "webchat", "teams", "instagram", "messenger"];
+
+export declare const Channels: ChannelsApi;
+
+/**
+ * Channels API — send outbound messages over any supported channel from inside
+ * a job, webhook, or skill tool.
+ *
+ * Use `Channels.send` for text messages on whatsapp/sms/email/webchat and other
+ * channels. Use the nested namespaces for channel-specific payloads.
+ *
+ * A successful send with a failed persistence write returns `{ delivered: true,
+ * persisted: false, warning: '...' }` — this is HTTP 200 and is NOT thrown.
+ *
+ * @example
+ * ```typescript
+ * // Send a text message over WhatsApp
+ * await Channels.send({
+ *   channel: 'whatsapp',
+ *   to: { phoneNumber: '+15551234567' },
+ *   text: 'Your order has shipped!',
+ * });
+ *
+ * // Send a WhatsApp template
+ * await Channels.whatsapp.sendTemplate({
+ *   to: { phoneNumber: '+15551234567' },
+ *   templateName: 'order_shipped',
+ *   languageCode: 'en',
+ * });
+ *
+ * // Send an email
+ * await Channels.email.send({
+ *   to: { email: 'customer@example.com' },
+ *   subject: 'Your order',
+ *   html: '<p>Thanks for your order!</p>',
+ * });
+ * ```
+ */
+export declare interface ChannelsApi {
+    /**
+     * Send a text message on any supported channel.
+     * Returns `ChannelSendOutput` — check `persisted` if memory durability matters.
+     *
+     * @example
+     * ```typescript
+     * const result = await Channels.send({
+     *   channel: 'email',
+     *   to: { userId: 'u-42' },
+     *   text: 'Hi from Lua!',
+     * });
+     * if (!result.persisted) console.warn(result.warning);
+     * ```
+     */
+    send(input: ChannelSendInput): Promise<ChannelSendOutput>;
+    /** WhatsApp-specific send operations. */
+    whatsapp: {
+        /**
+         * Send a pre-approved WhatsApp Business template.
+         *
+         * @example
+         * ```typescript
+         * await Channels.whatsapp.sendTemplate({
+         *   to: { phoneNumber: '+447551166594' },
+         *   templateName: 'order_update',
+         *   languageCode: 'en',
+         *   components: [{ type: 'body', parameters: [{ type: 'text', text: 'ORD-99' }] }],
+         * });
+         * ```
+         */
+        sendTemplate(input: WhatsAppTemplateSendInput): Promise<ChannelSendOutput>;
+    };
+    /** Email-specific send operations. */
+    email: {
+        /**
+         * Send an email to a user or address.
+         *
+         * @example
+         * ```typescript
+         * await Channels.email.send({
+         *   to: { email: 'alice@example.com' },
+         *   subject: 'Welcome!',
+         *   html: '<h1>Hello, Alice</h1>',
+         * });
+         * ```
+         */
+        send(input: EmailSendInput): Promise<ChannelSendOutput>;
+    };
+}
+
+export declare type ChannelSendChannel = (typeof CHANNEL_SEND_CHANNELS)[number];
+
+/** Body of POST /developer/agents/:agentId/channels/send */
+export declare interface ChannelSendInput {
+    channel: ChannelSendChannel;
+    to: ChannelSendTarget;
+    /** Message text; may contain `::: marker` component blocks — each channel
+     * renders them through its existing component pipeline. */
+    text: string;
+    options?: ChannelSendOptions;
+}
+
+export declare interface ChannelSendOptions {
+    /** Pin a specific channel config (must belong to the sending agent). */
+    channelIdentifier?: string;
+    /** WhatsApp-specific send options. */
+    whatsapp?: {
+        /**
+         * Behavior when the 24h customer-service window is CLOSED (PRO-98):
+         * - 'queue' (default): send the system message-request template, queue the
+         *   text, and deliver it once the user replies.
+         * - 'fail': reject with a 400 so the caller can send their own approved
+         *   template via Channels.whatsapp.sendTemplate.
+         * Overrides the channel config's `autoMessageRequest` default.
+         */
+        onClosedWindow?: 'queue' | 'fail';
+    };
+}
+
+/**
+ * Send result. `delivered` and `persisted` are independent: a vendor-accepted
+ * send whose memory write failed returns 200 with `persisted: false` plus a
+ * `warning` — never an error status for a delivered message.
+ */
+export declare interface ChannelSendOutput {
+    delivered: boolean;
+    persisted: boolean;
+    /**
+     * True when the send was deferred to the WhatsApp message-request queue
+     * because the 24h window was closed (PRO-98). `delivered` is false until the
+     * user replies and the queued text flushes; persistence happens at flush.
+     */
+    queued?: boolean;
+    /** Lua userId the message was recorded against (resolved when omitted). */
+    userId?: string;
+    /** Channel-native recipient identifier actually used (phone, email, PSID…). */
+    identifier?: string;
+    /** Vendor message id when the channel returns one (e.g. SES MessageId). */
+    messageId?: string;
+    warning?: string;
+}
+
+/** Recipient — exactly one of the fields must be set. userId works on every
+ * channel (resolved via the user's channel history); raw identifiers only on
+ * cold-start-capable channels (whatsapp/sms → phoneNumber, email → email). */
+export declare interface ChannelSendTarget {
+    userId?: string;
+    phoneNumber?: string;
+    email?: string;
+}
+
 /**
  * Wire-format types for `GET /chat/history/:agentId` and the VM-sandbox
  * `User.getChatHistory()` API. Both paths return the same shape.
@@ -1017,6 +1176,30 @@ export declare function defineDevice(config: LuaDeviceConfig): LuaDevice;
  */
 export declare function defineDeviceTrigger(config: LuaDeviceTriggerConfig): LuaDeviceTrigger;
 
+/**
+ * Define an SDK trigger primitive (PRO-95).
+ *
+ * A trigger wakes the agent on an external webhook event with declarative
+ * verify → filter → transform shaping and no `execute`. Compiled, versioned,
+ * and pushed like other code primitives; deploys via `lua push`.
+ *
+ * @example
+ * ```typescript
+ * import { defineTrigger } from 'lua-cli';
+ * import { z } from 'zod';
+ *
+ * export const stripeTrigger = defineTrigger({
+ *   name: 'stripe-payments',
+ *   description: 'Fires on a successful Stripe payment',
+ *   inputSchema: z.object({ type: z.string() }),
+ *   verify: (ctx) => verifyStripeSignature(ctx.rawBody, ctx.headers['stripe-signature']),
+ *   filter: (ctx) => ctx.body.type === 'payment_intent.succeeded',
+ *   transform: (ctx) => `Payment received: ${ctx.body.data.object.amount}`,
+ * });
+ * ```
+ */
+export declare function defineTrigger<T = any>(config: LuaTriggerConfig<T>): LuaTrigger<T>;
+
 /**
  * Function-style LuaVoice definition. Equivalent to `new LuaVoice(config)`,
  * detected by the compiler via the `defineVoice(...)` AST pattern.
@@ -1085,6 +1268,29 @@ export declare interface DeviceTriggerConfig {
     }) => Promise<any>;
 }
 
+/** A single email attachment, referenced by URL — lua-email fetches the bytes
+ * server-side and attaches them, keeping large files off the SDK→API hops. */
+declare interface EmailAttachmentInput {
+    filename: string;
+    contentType: string;
+    url: string;
+}
+
+/** Body of POST /developer/agents/:agentId/channels/email/send */
+export declare interface EmailSendInput {
+    to: {
+        userId?: string;
+        email?: string;
+    };
+    subject?: string;
+    text?: string;
+    html?: string;
+    cc?: string[];
+    bcc?: string[];
+    attachments?: EmailAttachmentInput[];
+    options?: ChannelSendOptions;
+}
+
 /**
  * Safe environment variable access function.
  * Gets injected at runtime with skill-specific environment variables.
@@ -1149,7 +1355,17 @@ declare interface GetJobsResponseData {
  */
 declare interface GovernanceConfig {
     mode: 'sdk' | 'api';
-    /** SDK mode — local in-memory policy rules */
+    /**
+     * SDK mode — a named governance-sdk preset composed as the base rule set. The platform builder
+     * maps this to the SDK's preset factories (e.g. `securityBaseline()`), then layers any explicit
+     * `rules`/`injection` on top. `'security'` = block dangerous tools + requireLevel(2).
+     */
+    preset?: 'security';
+    /** SDK mode — prompt-injection scan on inputs (maps to the SDK's `createInjectionGuard`). */
+    injection?: {
+        threshold: number;
+    };
+    /** SDK mode — local in-memory policy rules layered on top of any `preset`. */
     rules?: {
         blockTools?: string[];
         requireApproval?: string[];
@@ -1829,6 +2045,7 @@ export declare class LuaAgent {
     private readonly modelSettings?;
     private readonly skills;
     private readonly webhooks;
+    private readonly triggers;
     private readonly jobs;
     private readonly preProcessors;
     private readonly postProcessors;
@@ -1861,6 +2078,7 @@ export declare class LuaAgent {
     getModelSettings(): AgentModelSettings | undefined;
     getSkills(): LuaSkill[];
     getWebhooks(): LuaWebhook[];
+    getTriggers(): LuaTrigger[];
     getJobs(): LuaJob[];
     getPreProcessors(): PreProcessor[];
     getPostProcessors(): PostProcessor[];
@@ -1890,6 +2108,8 @@ export declare interface LuaAgentConfig {
     skills?: LuaSkill[];
     /** Array of webhooks */
     webhooks?: LuaWebhook[];
+    /** Array of SDK triggers (defineTrigger) — wake the agent on external events with verify/filter/transform */
+    triggers?: LuaTrigger[];
     /** Array of scheduled jobs */
     jobs?: LuaJob[];
     /** Array of preprocessors (run before messages reach the agent) */
@@ -2417,6 +2637,74 @@ declare interface LuaToolCtx {
     };
 }
 
+/**
+ * Lua Trigger class (PRO-95). Wakes an agent on an external webhook event with
+ * declarative verify → filter → transform shaping and no `execute`.
+ *
+ * @example
+ * ```typescript
+ * import { LuaTrigger } from 'lua-cli';
+ * import { z } from 'zod';
+ *
+ * export default new LuaTrigger({
+ *   name: 'stripe-payments',
+ *   description: 'Fires on a successful Stripe payment',
+ *   inputSchema: z.object({ type: z.string() }),
+ *   verify: (ctx) => verifyStripeSignature(ctx.rawBody, ctx.headers['stripe-signature']),
+ *   filter: (ctx) => ctx.body.type === 'payment_intent.succeeded',
+ *   transform: (ctx) => `Payment received: ${ctx.body.data.object.amount}`,
+ * });
+ * ```
+ */
+export declare class LuaTrigger<T = any> {
+    readonly name: string;
+    readonly description: string;
+    readonly source: 'webhook';
+    readonly inputSchema?: ZodType;
+    readonly verify?: (ctx: TriggerContext<T>) => boolean | Promise<boolean>;
+    readonly filter?: (ctx: TriggerContext<T>) => boolean | Promise<boolean>;
+    readonly transform?: (ctx: TriggerContext<T>) => string | AgentInvocationInput | Promise<string | AgentInvocationInput>;
+    constructor(config: LuaTriggerConfig<T>);
+    getName(): string;
+    getDescription(): string;
+}
+
+/**
+ * Lua Trigger configuration (PRO-95).
+ *
+ * A trigger wakes an agent on an external event with declarative shaping. It has
+ * NO `execute` function — that's the defining feature. The only customization
+ * surface is the three optional slots, run server-side per request:
+ *   - `verify`    — false ⇒ HTTP 401, no invocation (put HMAC checks here)
+ *   - `filter`    — false ⇒ HTTP 200, no invocation (intentionally ignore the event)
+ *   - `transform` — shapes the agent input; default is `body → message`
+ *
+ * For full request/response control (a custom HTTP response, side effects),
+ * reach for `LuaWebhook` instead.
+ */
+export declare interface LuaTriggerConfig<T = any> {
+    /** Trigger name (required; used as the server-side identifier). */
+    name: string;
+    /** Short description (a dashboard note; NOT sent to the agent). */
+    description: string;
+    /** Event source discriminator. Only 'webhook' in v1; 'cron'/'event' are future. */
+    source?: 'webhook';
+    /** Optional Zod schema for the event body (types `ctx.body`). */
+    inputSchema?: ZodType;
+    /** Reject the event with HTTP 401 when this returns false. */
+    verify?: (ctx: TriggerContext<T>) => boolean | Promise<boolean>;
+    /** Skip invocation (HTTP 200, no agent run) when this returns false. */
+    filter?: (ctx: TriggerContext<T>) => boolean | Promise<boolean>;
+    /**
+     * Shape the agent input. Return a `string` (the message) or a full
+     * `AgentInvocationInput` (you own the turn). Returning null/undefined is an
+     * error — use `filter` to skip. Omit to use the default `body → message`,
+     * whose payload is capped at ~50k chars (like a no-code trigger); return a
+     * transform to forward larger or hand-picked fields as the message.
+     */
+    transform?: (ctx: TriggerContext<T>) => string | AgentInvocationInput | Promise<string | AgentInvocationInput>;
+}
+
 /**
  * Code-defined voice agent. Pushed via `lua push`, attached to channels through
  * the owning `LuaAgent.voice` field. Auto-dispatched into LiveKit rooms when a
@@ -2466,6 +2754,7 @@ export declare class LuaVoice {
     readonly preemptiveGeneration: LuaVoiceConfig_2['preemptiveGeneration'];
     readonly interruption: LuaVoiceConfig_2['interruption'];
     readonly sttLanguage: LuaVoiceConfig_2['sttLanguage'];
+    readonly excludeTools: LuaVoiceConfig_2['excludeTools'];
     readonly tools: ReadonlyArray<LuaTool<any> | LuaVoiceTool<any>>;
     readonly onEnter?: LuaVoiceConfig['onEnter'];
     readonly onUserTurnCompleted?: LuaVoiceConfig['onUserTurnCompleted'];
@@ -2866,6 +3155,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     pronunciations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     persistTranscript: z.ZodOptional<z.ZodBoolean>;
     onToolFailureSay: z.ZodOptional<z.ZodString>;
+    excludeTools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     vad?: string;
     stt?: {
@@ -2959,6 +3249,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     pronunciations?: Record<string, string>;
     persistTranscript?: boolean;
     onToolFailureSay?: string;
+    excludeTools?: string[];
 }, {
     vad?: string;
     stt?: {
@@ -3052,6 +3343,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     pronunciations?: Record<string, string>;
     persistTranscript?: boolean;
     onToolFailureSay?: string;
+    excludeTools?: string[];
 }>, {
     vad?: string;
     stt?: {
@@ -3145,6 +3437,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     pronunciations?: Record<string, string>;
     persistTranscript?: boolean;
     onToolFailureSay?: string;
+    excludeTools?: string[];
 }, {
     vad?: string;
     stt?: {
@@ -3238,6 +3531,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     pronunciations?: Record<string, string>;
     persistTranscript?: boolean;
     onToolFailureSay?: string;
+    excludeTools?: string[];
 }>;
 
 /**
@@ -3311,10 +3605,10 @@ export declare interface LuaVoiceToolConfig<TInput extends ZodType = ZodType> {
  * its second `execute` arg whether it runs over chat or voice; this
  * extension just adds the Phase-5 fields (currently optional + experimental).
  *
- * `say()` is wired today and delegates to the active LiveKit `voice.AgentSession`.
- * `disallowInterruptions()` and `handoff()` are optional placeholders for
- * Phase 5 (BAC-213, the LuaVoice handoffs + test framework ticket).
- * Marked optional both because they aren't implemented yet AND so this
+ * `say()`, `transferToHuman()`, `endCall()` and `handoff()` are wired today
+ * and delegate to the active LiveKit `voice.AgentSession`.
+ * `disallowInterruptions()` is an optional placeholder — the barge-in lock
+ * plumbing isn't implemented yet. The delegates are marked optional so this
  * type stays structurally compatible with `LuaToolCtx` — that
  * compatibility is what lets a `LuaVoiceTool` (which extends `LuaTool`)
  * present `(ctx?: LuaVoiceToolCtx)` while satisfying the parent's
@@ -3376,9 +3670,24 @@ export declare interface LuaVoiceToolCtx {
          */
         disallowInterruptions?(): void;
         /**
-         * @experimental Reserved for Phase 5 (BAC-213). Optional because
-         * unimplemented — handoffs require `chatCtx.copy(exclude_instructions=True)`
-         * + `update_agent` plumbing that's part of the multi-LuaVoice flow ticket.
+         * Hand the live call to another LuaVoice on the same agent,
+         * addressed by its `name`. The caller stays in the same room; only
+         * the agent identity flips — the receiving voice starts cold from
+         * its own persona + greeting (no conversation history carries
+         * over). Pass `context` to surface a structured payload to the
+         * receiving voice on its first turn.
+         *
+         * In `lua voice test`, register reachable voices via
+         * `runVoice({ handoffTargets })`; in production, any voice pushed
+         * on the same agent is reachable. An unknown name degrades
+         * in-call (spoken fallback, no crash).
+         *
+         * @example
+         * ```typescript
+         * await ctx.voice?.handoff('billing-line', {
+         *   context: { reason: 'invoice question', orderId: input.orderId },
+         * });
+         * ```
          */
         handoff?(otherVoiceName: string, opts?: {
             context?: Record<string, unknown>;
@@ -4513,7 +4822,12 @@ export declare interface SendTemplateResponse {
 }
 
 export declare interface SendTemplateValues {
-    header?: Record<string, string>;
+    header?: Record<string, string> & {
+        image_url?: string;
+        video_url?: string;
+        document_url?: string;
+        document_filename?: string;
+    };
     body?: Record<string, string>;
     buttons?: SendTemplateButtonValue[];
 }
@@ -4684,6 +4998,30 @@ export declare enum ToolFlag {
     DISALLOW_INTERRUPTION = "disallow_interruption"
 }
 
+/**
+ * Context delivered to a trigger's verify / filter / transform slots.
+ *
+ * Unlike a webhook event, `rawBody` carries the EXACT unparsed request bytes
+ * (utf8) — HMAC signature schemes (Stripe `t=…,v1=…`, GitHub `sha256=…`, Slack
+ * `v0:…`) are computed over the wire bytes, which `JSON.stringify(body)` does
+ * not reproduce. `headers` keys arrive lowercased (Express), e.g.
+ * `ctx.headers['x-hub-signature-256']`.
+ */
+export declare interface TriggerContext<T = any> {
+    /** Parsed request body (typed by `inputSchema` when provided). */
+    body: T;
+    /** Exact unparsed request bytes as a utf8 string — for HMAC signature checks. */
+    rawBody?: string;
+    /** Request headers (lowercased keys). */
+    headers: Record<string, any>;
+    /** Parsed query-string parameters. */
+    query: Record<string, any>;
+    /** This trigger's name. */
+    triggerName: string;
+    /** Event source discriminator ('webhook' in v1). */
+    source: string;
+}
+
 /**
  * Response from updating custom data entry.
  */
@@ -4911,6 +5249,18 @@ export declare interface VoiceApi {
      * ```
      */
     call(input: VoiceDispatchInput): Promise<VoiceDispatchOutput>;
+    /**
+     * Create a voice room + client access token for your own frontend
+     * (standard livekit-client). The session runs under a synthetic identity;
+     * pass `userId` to scope conversation memory + transcript to your end user.
+     *
+     * @example
+     * ```typescript
+     * const { url, roomName, token } = await Voice.createSession({ userId: 'u-42' });
+     * // hand url + token to livekit-client's room.connect(url, token)
+     * ```
+     */
+    createSession(input?: VoiceSessionInput): Promise<VoiceSessionOutput>;
 }
 
 /**
@@ -5022,6 +5372,28 @@ string | {
     returnToken?: boolean;
 };
 
+/** Input for creating a developer voice room (custom frontend). */
+declare interface VoiceSessionInput {
+    /** Voice channel for the session. Defaults to 'web'. */
+    channel?: string;
+    /** External end-user id, for conversation-memory + transcript scoping. */
+    userId?: string;
+    /** LuaVoice id to run, overriding the agent's channel-bound voice. */
+    voiceId?: string;
+    displayName?: string;
+}
+
+/** Room + client token a livekit-client frontend connects with. */
+declare interface VoiceSessionOutput {
+    /** LiveKit server URL (wss://). */
+    url: string;
+    roomName: string;
+    /** Client access token (LiveKit AccessToken JWT). */
+    token: string;
+    participantIdentity: string;
+    agentName: string;
+}
+
 /**
  * Webhook request information from channel integrations.
  * Contains the raw webhook payload from the channel provider.
@@ -5085,13 +5457,14 @@ declare interface WhatsAppTemplateFooterComponent {
 
 declare interface WhatsAppTemplateHeaderComponent {
     type: 'HEADER';
-    format: 'TEXT';
-    text: string;
+    format: 'TEXT' | 'IMAGE' | 'VIDEO' | 'DOCUMENT';
+    text?: string;
     example?: {
-        header_text_named_params: Array<{
+        header_text_named_params?: Array<{
             param_name: string;
             example: string;
         }>;
+        header_handle?: string[];
     };
 }
 
@@ -5106,6 +5479,21 @@ declare interface WhatsAppTemplateQuickReplyButton {
     text: string;
 }
 
+/** Body of POST /developer/agents/:agentId/channels/whatsapp/template */
+export declare interface WhatsAppTemplateSendInput {
+    to: {
+        userId?: string;
+        phoneNumber?: string;
+    };
+    templateName: string;
+    languageCode?: string;
+    /** Meta template components (header/body/buttons parameter values). */
+    components?: Array<Record<string, unknown>>;
+    /** Text persisted to the agent's memory as what this template said. */
+    messageContext?: string;
+    options?: ChannelSendOptions;
+}
+
 export declare type WhatsAppTemplateStatus = 'APPROVED' | 'REJECTED' | 'PENDING';
 
 declare interface WhatsAppTemplateUrlButton {