lua-cli 3.17.6 → 3.20.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 }] }`
@@ -27,6 +27,10 @@ declare interface AgentInvocationInput {
     systemPrompt?: string;
     /** Additional runtime context attached to the request. */
     runtimeContext?: string;
+    /** Client-side context (e.g. the caller's IANA timezone) for this invocation. */
+    clientContext?: {
+        timezone?: string;
+    };
     /**
      * Optional thread ID suffix for conversation scoping. When omitted, the
      * invocation flows into the caller-user's default chat thread with the
@@ -48,6 +52,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;
 }
 
 /**
@@ -79,11 +90,19 @@ declare interface AgentInvocationOutput {
 }
 
 /**
- * Per-agent LLM call settings. Maps directly onto Mastra's
+ * Per-agent LLM call settings PLUS normalized reasoning config. The
+ * `CallSettings` leafs (`temperature`, `topP`, …) map directly onto Mastra's
  * `agent.stream({ modelSettings })` / `agent.generate({ modelSettings })`,
- * which in turn maps onto the AI SDK's `CallSettings`. Pass-through:
- * we don't validate ranges here; the provider will reject invalid combos
- * (e.g. topP > 1, presencePenalty out of provider range).
+ * which in turn maps onto the AI SDK's `CallSettings` — pass-through, we
+ * don't validate ranges here; the provider will reject invalid combos (e.g.
+ * topP > 1, presencePenalty out of provider range).
+ *
+ * `reasoning` is NOT a `CallSettings` key — it's the agent-level tier of the
+ * `ModelRequestOptions` precedence chain (request > agent `reasoning` >
+ * per-model DB `modelOptions` > code defaults). lua-core splits this bag
+ * before calling Mastra: `reasoning` is stripped and merged into the
+ * provider-options resolution seam instead of being passed through as a
+ * `CallSettings` field.
  *
  * Deliberately excludes `abortSignal` (not serializable), `headers`
  * (security — could exfiltrate credentials), and `maxRetries` (platform
@@ -106,6 +125,17 @@ export declare interface AgentModelSettings {
     stopSequences?: string[];
     /** Random seed for deterministic sampling (provider support varies). */
     seed?: number;
+    /**
+     * Per-agent reasoning default. Lower precedence than a per-request
+     * `options.reasoning` override; higher precedence than the per-model DB
+     * `modelOptions.reasoning` override. Verbosity is deliberately NOT
+     * available here — it stays request-level only (`ModelRequestOptions.verbosity`).
+     */
+    reasoning?: {
+        effort?: ReasoningEffort;
+        /** Whether to surface the reasoning trace to the caller. Default true. */
+        show?: boolean;
+    };
 }
 
 export declare const Agents: AgentsApi;
@@ -627,6 +657,23 @@ declare interface BatchingConfig {
     serializeProcessing?: boolean;
 }
 
+/**
+ * Browser switch config (LuaBrowser). `browser: true` is the zero-code form —
+ * the agent gets browser tools injected, like `searchWeb`, routed to the user's
+ * local browser (desktop) or the Browser-Use cloud fallback. The object form
+ * adds optional policy.
+ */
+declare interface BrowserSwitchConfig {
+    /** Preferred engine; 'auto' lets the platform pick local (desktop) vs cloud. */
+    engine?: 'auto' | 'browser-use' | 'agent-browser';
+    /** Egress allowlist — domains the browser may navigate/sub-request. */
+    allowedDomains?: string[];
+    /** Names of vault credential entries the agent may use (never raw secrets). */
+    credentials?: string[];
+    /** Hard cap on a single browser session's duration (cost control). */
+    maxSessionMinutes?: number;
+}
+
 /**
  * CDN API
  * Upload and retrieve files from the Lua CDN
@@ -688,6 +735,182 @@ 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',
+ * });
+ *
+ * // React to a WhatsApp message
+ * await Channels.whatsapp.sendReaction({
+ *   to: { phoneNumber: '+15551234567' },
+ *   messageId: 'wamid.HBgL...',
+ *   emoji: '👍',
+ * });
+ *
+ * // 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>;
+        /**
+         * React to a WhatsApp message with a single emoji.
+         *
+         * `messageId` is the vendor message id (`wamid...`) — e.g. read it off an
+         * inbound message from the channel webhook/history — and must be ≤30 days
+         * old (Meta limit). Pass `emoji: ''` to remove an existing reaction.
+         *
+         * @example
+         * ```typescript
+         * await Channels.whatsapp.sendReaction({
+         *   to: { phoneNumber: '+447551166594' },
+         *   messageId: 'wamid.HBgL...',
+         *   emoji: '👍',
+         * });
+         * ```
+         */
+        sendReaction(input: WhatsAppReactionSendInput): 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.
@@ -700,12 +923,27 @@ export declare type Channel = 'web' | 'whatsapp' | 'facebook' | 'instagram' | 's
 /**
  * One content part of a chat-history message.
  *
- * `text` parts carry plain text. Media parts (`image` / `video` / `audio`
- * / `file`) carry a URL or base64 payload in `data` (or `image` / `video`
- * for legacy reasons) plus a `mediaType` MIME string.
+ * `text` parts carry plain text. `reasoning` parts carry the model's
+ * chain-of-thought in the `text` field so a history reload can re-render the
+ * reasoning component (PRO-391). `tool` parts carry a persisted tool
+ * invocation (`toolName`, `toolCallId`, `input` args, and — on a terminal
+ * turn — the `output` result and `toolState`) so a reloaded turn can
+ * re-render its tool-call cards. `source` parts carry a web-search citation
+ * (`url` + optional `title`/`sourceId`) so a reloaded turn keeps its sources
+ * footer — the persisted twin of the live stream's `source-url` parts.
+ * Media parts (`image` / `video` / `audio` / `file`) carry a URL or base64
+ * payload in `data` (or `image` / `video` for legacy reasons) plus a
+ * `mediaType` MIME string.
+ * `source-url` / `source-document` parts carry a persisted citation
+ * (web-search grounding / document citation, PRO-430): `url` + `title` for
+ * URLs; `mediaType` + `title` + `filename` (+ citation offsets inside
+ * `providerMetadata`) for documents; both keyed by `sourceId`.
+ * `data-lua-*` parts carry a persisted enriched stream part (e.g. a
+ * sub-agent delegation card) with its original data object in `payload`
+ * (`data` is reserved for media payload strings).
  */
 export declare interface ChatHistoryContent {
-    type: 'text' | 'image' | 'video' | 'audio' | 'file';
+    type: 'text' | 'reasoning' | 'tool' | 'image' | 'video' | 'audio' | 'file' | 'source-url' | 'source-document' | `data-lua-${string}`;
     text?: string;
     image?: string;
     video?: string;
@@ -713,6 +951,17 @@ export declare interface ChatHistoryContent {
     mediaType?: string;
     latitude?: number;
     longitude?: number;
+    toolName?: string;
+    toolCallId?: string;
+    input?: unknown;
+    output?: unknown;
+    toolState?: string;
+    sourceId?: string;
+    url?: string;
+    title?: string;
+    filename?: string;
+    providerMetadata?: Record<string, unknown>;
+    payload?: unknown;
 }
 
 /**
@@ -727,6 +976,24 @@ export declare interface ChatHistoryMessage {
     /** ISO-8601 timestamp string. */
     createdAt: string;
     content: ChatHistoryContent[];
+    /**
+     * Origin of the message, derived from the `mastra_messages.type` column:
+     * `'voice'` for turns mirrored from a finished LiveKit voice call, `'chat'`
+     * for everything else. Additive/optional — absent on rows written before this
+     * landed and on call sites that don't select the `type` column. Clients use it
+     * to render a "Voice call" divider in the thread.
+     */
+    source?: 'voice' | 'chat';
+    /**
+     * Permanent recording for a voice-note turn (Lua Desktop). Populated by the
+     * admin threads history endpoint from the row's `content.metadata.audio` — a
+     * sibling of the model content, so the url is NEVER part of the LLM prompt.
+     * Present only on desktop voice-note user turns; clients render an audio
+     * player / voice bubble off `audio.url`. Absent on all other messages.
+     */
+    audio?: {
+        url: string;
+    };
 }
 
 /**
@@ -1017,6 +1284,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 +1376,82 @@ export declare interface DeviceTriggerConfig {
     }) => Promise<any>;
 }
 
+/** A matched org member and their shareable channel targets (empty when none shared). */
+export declare interface DirectoryMatch {
+    userId: string;
+    fullName?: string;
+    primaryEmail?: string;
+    targets: DirectoryTarget[];
+}
+
+/** Result of POST /developer/agents/:agentId/directory/resolve. */
+export declare interface DirectoryResolveResult {
+    query: string;
+    matches: DirectoryMatch[];
+}
+
+/**
+ * Wire contracts for the workspace directory resolve endpoint.
+ *
+ * lua-cli `Team.findMember(name)` ↔ lua-api `POST /developer/agents/:agentId/directory/resolve`.
+ * Resolves a teammate by name within the AGENT's organization (the org is derived
+ * server-side from the agent), returning only the channel handles each member opted
+ * to share. Returns a list — the caller disambiguates when more than one matches.
+ */
+/** A channel the teammate opted to be reachable on within the workspace. */
+export declare interface DirectoryTarget {
+    channel: 'whatsapp' | 'sms' | 'email';
+    /** E.164 for whatsapp/sms; address for email. */
+    value: string;
+    label?: string;
+    validated: boolean;
+}
+
+/** 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 {
+    /** Recipient — `email` (cold) or `userId` (resolved to the user's email
+     * address from their channel history). At least one must be set. */
+    to: {
+        userId?: string;
+        email?: string;
+    };
+    subject?: string;
+    /** Plain-text body, sent as-is (the MIME text/plain part). */
+    text?: string;
+    /** Exact HTML body, sent as-is (the MIME text/html part) — no template wrap. */
+    html?: string;
+    /**
+     * Rich body — markdown and `:::` component markers, rendered server-side into
+     * the branded email template (the same rendering the agent's own replies use).
+     * Use this for "send this message as a nice email"; use `html` instead when you
+     * want to control the exact markup. Mutually exclusive with `html`/`text`.
+     */
+    richBody?: string;
+    cc?: string[];
+    bcc?: string[];
+    attachments?: EmailAttachmentInput[];
+    /**
+     * RFC 5322 threading: the `Message-ID` of the email this one replies to. Set
+     * `In-Reply-To` (and append to `References`) so mail clients thread the reply
+     * into the right conversation — e.g. a per-ticket thread. The value is the
+     * inbound email's Message-ID, surfaced to agent code as `webhookPayload.messageId`.
+     * Angle brackets are optional; lua-email wraps bare ids. Honoured on the SES
+     * (branded/`existing`) email channel.
+     */
+    inReplyTo?: string;
+    /** RFC 5322 `References` chain — the accumulated Message-IDs of the thread. */
+    references?: string[];
+    options?: ChannelSendOptions;
+}
+
 /**
  * Safe environment variable access function.
  * Gets injected at runtime with skill-specific environment variables.
@@ -1149,7 +1516,28 @@ 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`).
+     * `ml: true` additionally runs the Governance Cloud ML ensemble (regex+DeBERTa) per
+     * message and adds the SDK's `mlInjectionGuard` rule — a hybrid that blocks when EITHER
+     * the regex score crosses `threshold` OR the ML score crosses `mlThreshold`. The two are
+     * scored independently: `threshold` (~0.8) suits the regex weights, while the ML score is
+     * a calibrated model confidence with its own tuned operating point (`mlThreshold`, default
+     * 0.95 — the ensemble's confirmation gate). Requires GOVERNANCE_ML_URL / GOVERNANCE_ML_API_KEY
+     * on the platform; falls back to regex-only when unset or on error.
+     */
+    injection?: {
+        threshold: number;
+        ml?: boolean;
+        mlThreshold?: number;
+    };
+    /** SDK mode — local in-memory policy rules layered on top of any `preset`. */
     rules?: {
         blockTools?: string[];
         requireApproval?: string[];
@@ -1417,7 +1805,7 @@ declare class JobApi extends HttpClient {
      * @returns Promise resolving to an ApiResponse containing the full updated job
      * @throws Error if the job or version is not found or the publish operation fails
      */
-    publishJobVersion(jobId: string, version: string): Promise<ApiResponse<Job>>;
+    publishJobVersion(jobId: string, version: string): Promise<ApiResponse<Job & ScopedPromoteFields>>;
     /**
      * Deletes a job and all its versions, or deactivates it if it has versions
      * @param jobId - The unique identifier of the job to delete
@@ -1829,6 +2217,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;
@@ -1838,6 +2227,7 @@ export declare class LuaAgent {
     private readonly voices?;
     private readonly batching?;
     private readonly governance?;
+    private readonly browser?;
     /**
      * Creates a new LuaAgent instance.
      *
@@ -1856,11 +2246,14 @@ export declare class LuaAgent {
      */
     constructor(config: LuaAgentConfig);
     getName(): string;
+    /** Browser switch (LuaBrowser) — `true`/config when the agent can browse. */
+    getBrowser(): LuaAgentConfig['browser'];
     getPersona(): PersonaText;
     getModel(): LuaAgentModel | undefined;
     getModelSettings(): AgentModelSettings | undefined;
     getSkills(): LuaSkill[];
     getWebhooks(): LuaWebhook[];
+    getTriggers(): LuaTrigger[];
     getJobs(): LuaJob[];
     getPreProcessors(): PreProcessor[];
     getPostProcessors(): PostProcessor[];
@@ -1882,14 +2275,20 @@ export declare interface LuaAgentConfig {
      * Passed straight through to Mastra / AI SDK on every `chat/stream` and
      * `chat/generate`. Undefined leaves provider defaults in place.
      *
+     * `reasoning` is the exception — it's not a sampling setting. It sets this
+     * agent's default reasoning effort/visibility across providers (Claude,
+     * GPT, Gemini, …); a per-request `options.reasoning` override always wins.
+     *
      * @example
-     * modelSettings: { temperature: 0.2, maxOutputTokens: 4096 }
+     * modelSettings: { temperature: 0.2, maxOutputTokens: 4096, reasoning: { effort: 'low' } }
      */
     modelSettings?: AgentModelSettings;
     /** Array of skills (each with tools) */
     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) */
@@ -1913,6 +2312,13 @@ export declare interface LuaAgentConfig {
     batching?: BatchingConfig;
     /** Governance policy configuration. When set, tool calls, preprocessors, and postprocessors are governed. */
     governance?: GovernanceConfig;
+    /**
+     * Browser switch (LuaBrowser). `true` turns on browser tools with platform
+     * defaults; an object adds policy (engine, allowedDomains, credentials,
+     * maxSessionMinutes). Off by default — a browser session costs money and
+     * carries risk, so it's opt-in (unlike always-on searchWeb).
+     */
+    browser?: boolean | BrowserSwitchConfig;
 }
 
 /**
@@ -2417,6 +2823,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 +2940,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'];
@@ -2574,11 +3049,11 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     }, {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     }>]>;
     stt: z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         kind: z.ZodLiteral<"inference">;
@@ -2640,11 +3115,11 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     }, {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     }>]>>;
     tts: z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         kind: z.ZodLiteral<"inference">;
@@ -2706,11 +3181,11 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     }, {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     }>]>>;
     vad: z.ZodOptional<z.ZodString>;
     vadOptions: z.ZodOptional<z.ZodObject<{
@@ -2743,28 +3218,28 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
         maxDelay: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         enabled?: boolean;
-        mode?: "vad" | "adaptive";
+        mode?: "adaptive" | "vad";
         falseInterruptionTimeout?: number;
         resumeFalseInterruption?: boolean;
         minDelay?: number;
         maxDelay?: number;
     }, {
         enabled?: boolean;
-        mode?: "vad" | "adaptive";
+        mode?: "adaptive" | "vad";
         falseInterruptionTimeout?: number;
         resumeFalseInterruption?: boolean;
         minDelay?: number;
         maxDelay?: number;
     }>, {
         enabled?: boolean;
-        mode?: "vad" | "adaptive";
+        mode?: "adaptive" | "vad";
         falseInterruptionTimeout?: number;
         resumeFalseInterruption?: boolean;
         minDelay?: number;
         maxDelay?: number;
     }, {
         enabled?: boolean;
-        mode?: "vad" | "adaptive";
+        mode?: "adaptive" | "vad";
         falseInterruptionTimeout?: number;
         resumeFalseInterruption?: boolean;
         minDelay?: number;
@@ -2866,7 +3341,9 @@ 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, {
+    name?: string;
     vad?: string;
     stt?: {
         voice?: string;
@@ -2881,10 +3358,9 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     } | {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     };
     volume?: number;
-    name?: string;
     llm?: {
         voice?: string;
         options?: Record<string, unknown>;
@@ -2898,7 +3374,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     } | {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     };
     tts?: {
         voice?: string;
@@ -2913,7 +3389,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     } | {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -2928,7 +3404,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     preemptiveGeneration?: boolean;
     interruption?: {
         enabled?: boolean;
-        mode?: "vad" | "adaptive";
+        mode?: "adaptive" | "vad";
         falseInterruptionTimeout?: number;
         resumeFalseInterruption?: boolean;
         minDelay?: number;
@@ -2959,7 +3435,9 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     pronunciations?: Record<string, string>;
     persistTranscript?: boolean;
     onToolFailureSay?: string;
+    excludeTools?: string[];
 }, {
+    name?: string;
     vad?: string;
     stt?: {
         voice?: string;
@@ -2974,10 +3452,9 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     } | {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     };
     volume?: number;
-    name?: string;
     llm?: {
         voice?: string;
         options?: Record<string, unknown>;
@@ -2991,7 +3468,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     } | {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     };
     tts?: {
         voice?: string;
@@ -3006,7 +3483,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     } | {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -3021,7 +3498,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     preemptiveGeneration?: boolean;
     interruption?: {
         enabled?: boolean;
-        mode?: "vad" | "adaptive";
+        mode?: "adaptive" | "vad";
         falseInterruptionTimeout?: number;
         resumeFalseInterruption?: boolean;
         minDelay?: number;
@@ -3052,7 +3529,9 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     pronunciations?: Record<string, string>;
     persistTranscript?: boolean;
     onToolFailureSay?: string;
+    excludeTools?: string[];
 }>, {
+    name?: string;
     vad?: string;
     stt?: {
         voice?: string;
@@ -3067,10 +3546,9 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     } | {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     };
     volume?: number;
-    name?: string;
     llm?: {
         voice?: string;
         options?: Record<string, unknown>;
@@ -3084,7 +3562,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     } | {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     };
     tts?: {
         voice?: string;
@@ -3099,7 +3577,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     } | {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -3114,7 +3592,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     preemptiveGeneration?: boolean;
     interruption?: {
         enabled?: boolean;
-        mode?: "vad" | "adaptive";
+        mode?: "adaptive" | "vad";
         falseInterruptionTimeout?: number;
         resumeFalseInterruption?: boolean;
         minDelay?: number;
@@ -3145,7 +3623,9 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     pronunciations?: Record<string, string>;
     persistTranscript?: boolean;
     onToolFailureSay?: string;
+    excludeTools?: string[];
 }, {
+    name?: string;
     vad?: string;
     stt?: {
         voice?: string;
@@ -3160,10 +3640,9 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     } | {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     };
     volume?: number;
-    name?: string;
     llm?: {
         voice?: string;
         options?: Record<string, unknown>;
@@ -3177,7 +3656,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     } | {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     };
     tts?: {
         voice?: string;
@@ -3192,7 +3671,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     } | {
         options?: Record<string, unknown>;
         kind?: "realtime";
-        provider?: "openai" | "google" | "xai";
+        provider?: "google" | "xai" | "openai";
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -3207,7 +3686,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     preemptiveGeneration?: boolean;
     interruption?: {
         enabled?: boolean;
-        mode?: "vad" | "adaptive";
+        mode?: "adaptive" | "vad";
         falseInterruptionTimeout?: number;
         resumeFalseInterruption?: boolean;
         minDelay?: number;
@@ -3238,6 +3717,7 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     pronunciations?: Record<string, string>;
     persistTranscript?: boolean;
     onToolFailureSay?: string;
+    excludeTools?: string[];
 }>;
 
 /**
@@ -3311,10 +3791,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 +3856,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>;
@@ -4484,6 +4979,29 @@ declare interface PushJobVersionDTO {
     metadata?: Record<string, any>;
 }
 
+/**
+ * Normalized, provider-agnostic model request options.
+ *
+ * This is the shape clients (Lua Desktop, lua-cli, admin overrides) use to
+ * ask for a reasoning effort / output verbosity without knowing which
+ * provider dialect (Anthropic `thinking`, OpenAI `reasoningEffort`, Google
+ * `thinkingConfig`, …) the resolved model actually speaks. lua-core's
+ * `buildProviderOptions` translates this into the wire-level
+ * `providerOptions` shape per model.
+ */
+declare const REASONING_EFFORT_VALUES: readonly ["off", "minimal", "low", "medium", "high", "max"];
+
+declare type ReasoningEffort = (typeof REASONING_EFFORT_VALUES)[number];
+
+/**
+ * Additive field on primitive publish responses. When the agent is under
+ * versioning the server performs a scoped promote and returns the newly
+ * minted + promoted agent version here; absent when the agent has no versions.
+ */
+declare interface ScopedPromoteFields {
+    agentVersion?: number;
+}
+
 /**
  * Response from product search.
  */
@@ -4534,6 +5052,33 @@ declare type SkillContextText = string | {
     text?: string;
 };
 
+export declare const Team: TeamApi;
+
+/**
+ * Team API — resolve a teammate by name within the agent's organization and get
+ * the channel handles they opted to share. Pair with `Channels.send` to message a
+ * colleague without typing their number.
+ *
+ * The org is derived server-side from the agent; you can only resolve members of
+ * your own org. Returns a list — disambiguate when more than one member matches.
+ *
+ * @example
+ * ```typescript
+ * const { matches } = await Team.findMember('Stefan');
+ * const wa = matches[0]?.targets.find((t) => t.channel === 'whatsapp');
+ * if (wa) {
+ *   await Channels.send({ channel: 'whatsapp', to: { phoneNumber: wa.value }, text: 'Hi Stefan!' });
+ * }
+ * ```
+ */
+export declare interface TeamApi {
+    /**
+     * Resolve teammates whose name matches, each with their shareable channel
+     * targets (empty `targets[]` when the member shared nothing).
+     */
+    findMember(name: string): Promise<DirectoryResolveResult>;
+}
+
 /**
  * Templates API
  *
@@ -4689,6 +5234,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.
  */
@@ -4916,6 +5485,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>;
 }
 
 /**
@@ -5027,6 +5608,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.
@@ -5036,6 +5639,20 @@ export declare interface WebhookRequest {
     payload: any;
 }
 
+/** Body of POST /developer/agents/:agentId/channels/whatsapp/reaction */
+export declare interface WhatsAppReactionSendInput {
+    to: {
+        userId?: string;
+        phoneNumber?: string;
+    };
+    /** Vendor id (`wamid...`) of the message to react to — e.g. an inbound
+     * message's id from the conversation history, ≤30 days old per Meta. */
+    messageId: string;
+    /** A single emoji. An empty string removes the agent's existing reaction. */
+    emoji: string;
+    options?: ChannelSendOptions;
+}
+
 export declare interface WhatsAppTemplate {
     id: string;
     name: string;
@@ -5112,6 +5729,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 {