lua-cli 3.39.3 → 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)`,
@@ -1927,6 +2014,37 @@ export declare function defineTrigger<T = any>(config: LuaTriggerConfig<T>): Lua
  */
 export declare function defineVoice(config: LuaVoiceConfig): LuaVoice;
 
+/**
+ * Define a web app on the agent.
+ *
+ * @example
+ * ```typescript
+ * import { defineWebApp, route, json } from 'lua-cli';
+ * import { z } from 'zod';
+ *
+ * export default defineWebApp({
+ *   name: 'ops-dashboard',
+ *   description: 'Open tickets per shop',
+ *   pages: { root: './web', nav: [{ path: '/', label: 'Overview' }] },
+ *   routes: {
+ *     'GET /tickets': route({
+ *       query: z.object({ status: z.enum(['open', 'closed']).default('open') }),
+ *       handler: async ({ query }) => ({ items: (await Data.get('tickets', { filter: { status: query.status } })).data }),
+ *     }),
+ *     'POST /tickets/:id/close': route({
+ *       params: z.object({ id: z.string() }),
+ *       body: z.object({ note: z.string().max(500) }),
+ *       handler: async ({ params, body, auth }) => {
+ *         await Data.patch('tickets', params.id, { set: { status: 'closed', closedBy: auth.userId, note: body.note } });
+ *         return json(undefined, 204);
+ *       },
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+export declare function defineWebApp(config: LuaWebAppConfig): LuaWebApp;
+
 export declare function defineWorkflow(cfg: LuaWorkflowConfig, build: (wf: LuaWorkflowBuilder) => LuaWorkflow): LuaWorkflow;
 
 /**
@@ -2414,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)
@@ -2647,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
@@ -3125,6 +3263,11 @@ declare interface JobVersion {
     metadata?: Record<string, any>;
 }
 
+/**
+ * Build a JSON `Response`. `json(undefined, 204)` answers with no body.
+ */
+export declare function json(data: unknown, status?: number, headers?: Record<string, string>): Response;
+
 export { JsonSchema }
 
 export { KnowledgeBindingSpec }
@@ -3394,6 +3537,9 @@ export declare interface LuaAgentConfig {
  */
 export declare type LuaAgentModel = string | ((request: LuaRequest) => string | Promise<string>);
 
+/** The signed-in person a route runs for (never an API key, never anonymous). */
+export declare type LuaAuth = WebRouteAuth;
+
 /**
  * LuaDevice class — represents an external device that an agent can communicate with.
  *
@@ -3586,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.
@@ -3627,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
@@ -3664,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;
 }
 
 /**
@@ -3825,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;
 }
 
 /**
@@ -4074,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-
@@ -4124,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'];
@@ -4152,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. */
@@ -5088,6 +5268,37 @@ export declare interface LuaVoiceTurnContext {
     }): void;
 }
 
+/**
+ * Lua Web App — the class form of `defineWebApp` (consistent with
+ * `LuaTrigger` / `defineTrigger`). Validates the definition eagerly so a
+ * mistake fails at `lua compile`, not at first request.
+ */
+export declare class LuaWebApp {
+    private readonly config;
+    constructor(config: LuaWebAppConfig);
+    getName(): string;
+    getDescription(): string | undefined;
+    getPages(): WebAppPages;
+    getBranding(): WebAppBranding | undefined;
+    getRoutes(): Record<string, RouteDefinition<any, any, any>>;
+    getFetch(): LuaWebAppConfig['fetch'];
+    getConfig(): LuaWebAppConfig;
+}
+
+export declare interface LuaWebAppConfig {
+    /** URL-safe name: `^[a-z][a-z0-9-]*$`. The app's identifier on the agent. */
+    name: string;
+    description?: string;
+    pages: WebAppPages;
+    branding?: WebAppBranding;
+    /** Typed route handlers keyed by `'<METHOD> /<path>'`. */
+    routes?: Record<string, RouteDefinition<any, any, any>>;
+    /** Escape hatch: a Web-standard `fetch` handler (Hono, itty-router, …) for
+     *  paths no route matches. Apps that use only `fetch` forgo manifest-driven
+     *  route access and the typed client. */
+    fetch?: (request: Request) => Promise<Response> | Response;
+}
+
 /**
  * Lua Webhook class.
  * Main class for building webhooks with validated inputs.
@@ -5255,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]`
@@ -5361,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;
@@ -5413,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;
 }
@@ -6397,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';
+    };
 }
 
 /**
@@ -6468,11 +6701,69 @@ declare type ResumeStepResult = {
  *  `maxBackoffSeconds` (default 3600) only meaningful with 'exponential' (`backoff-invalid` otherwise). */
 export declare type RetryPolicy = WorkflowRetryPolicy;
 
+/**
+ * Declare a route. Identity at runtime; exists so the compiler can see the
+ * schemas and the handler, and so `RouteContext` is inferred from them.
+ */
+export declare function route<P = Record<string, string>, Q = Record<string, string | string[]>, B = unknown>(def: RouteDefinition<P, Q, B>): RouteDefinition<P, Q, B>;
+
+/** What a route handler receives. `params`, `query` and `body` are already
+ *  validated by the route's schemas when those are declared. */
+export declare interface RouteContext<P = Record<string, string>, Q = Record<string, string | string[]>, B = unknown> {
+    params: P;
+    query: Q;
+    body: B;
+    /** Lower-cased, allow-listed request headers. */
+    headers: Record<string, string>;
+    method: WebRouteMethod;
+    path: string;
+    /** The matched route key. */
+    route?: string;
+    auth: LuaAuth;
+    app: WebRouteApp;
+    /** The Web `Request` the gateway received, for handlers that want it. */
+    request: Request;
+}
+
+export declare interface RouteDefinition<P = Record<string, string>, Q = Record<string, string | string[]>, B = unknown> {
+    description?: string;
+    /** Zod schema for path parameters; a failure answers 400 `VALIDATION`. */
+    params?: ZodType<P>;
+    /** Zod schema for query parameters; a failure answers 400 `VALIDATION`. */
+    query?: ZodType<Q>;
+    /** Zod schema for the request body; a failure answers 400 `VALIDATION`. */
+    body?: ZodType<B>;
+    /** Response schemas by status, for the typed client (not enforced at runtime). */
+    responses?: Record<number, ZodType>;
+    handler: (ctx: RouteContext<P, Q, B>) => Promise<RouteHandlerResult> | RouteHandlerResult;
+}
+
+/** A handler returns a Web `Response`, `undefined` (→ 204) or any JSON value (→ 200). */
+export declare type RouteHandlerResult = Response | undefined | unknown;
+
 export declare const rows: (s: LuaWorkflowStep<any, any, any> | string, path: string, page: {
     offset: number;
     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
@@ -6613,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
@@ -7320,6 +7640,60 @@ export declare interface WaitForSignalOptions {
     acceptedSources?: Array<'webhook' | 'api' | 'user' | 'agent'>;
 }
 
+/**
+ * Per-app additions to the gateway's strict Content-Security-Policy
+ * (`defineWebApp({ pages: { csp } })`, PRD 7.10.11). This camelCase shape is
+ * what lua-cli writes, what `webAppVersion.csp` stores and what the gateway
+ * reads; the gateway alone maps each key to its directive (`scriptSrc` →
+ * `script-src`, …). A key outside this list is ignored by the gateway.
+ */
+declare const WEB_APP_CSP_KEYS: readonly ["scriptSrc", "styleSrc", "imgSrc", "connectSrc", "fontSrc", "frameSrc", "workerSrc"];
+
+export declare const WEB_APP_NAME_PATTERN: RegExp;
+
+declare const WEB_ROUTE_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
+
+/** `defineWebApp({ branding })`, as lua-cli writes it and the version stores it. */
+export declare interface WebAppBranding {
+    /** Display name in the shells; defaults to the app name. */
+    name?: string;
+    /** Path to a logo inside the pages project, shipped as an asset. */
+    logo?: string;
+    /** Accent color (any CSS color; OKLCH preferred). */
+    accent?: string;
+}
+
+/** Per-app additions to the gateway's strict Content-Security-Policy (PRD 7.10.11),
+ *  in the one camelCase shape lua-cli stores and the gateway reads. */
+export declare type WebAppCsp = WebAppCsp_2;
+
+declare type WebAppCsp_2 = Partial<Record<WebAppCspKey, string[]>>;
+
+declare type WebAppCspKey = (typeof WEB_APP_CSP_KEYS)[number];
+
+/** One navigation entry of a web app (`defineWebApp({ pages: { nav } })`): drives the
+ *  app's nav rail and the shells' Apps tile. Written by lua-cli, stored on the version. */
+export declare interface WebAppNavItem {
+    /** Client route path inside the app, e.g. `/tickets`. */
+    path: string;
+    label: string;
+    /** An icon name from the design system's curated set. */
+    icon?: string;
+}
+
+export declare interface WebAppPages {
+    /** The Vite project directory, relative to the app definition (usually `./web`). */
+    root: string;
+    /** Serve the entry HTML for every non-asset path (client-side routing). Default true. */
+    spa?: boolean;
+    /** Navigation the app and the shells agree on; drives the app's nav rail and the Apps hub tile. */
+    nav?: WebAppNavItem[];
+    csp?: WebAppCsp;
+}
+
+/** Route keys are `'<METHOD> /<path>'`, e.g. `'POST /tickets/:id/close'`. */
+export declare type WebAppRouteKey = `${WebRouteMethod} /${string}`;
+
 /**
  * Webhook request information from channel integrations.
  * Contains the raw webhook payload from the channel provider.
@@ -7329,6 +7703,40 @@ export declare interface WebhookRequest {
     payload: any;
 }
 
+/** The app the handler belongs to, for `ctx.app` and log correlation. */
+declare interface WebRouteApp {
+    id: string;
+    name: string;
+    version: string;
+    /** Monotonic deployment ordinal of the app version being executed. */
+    deployment: number;
+    /** The app origin, e.g. `https://ops-dashboard-7f3a.apps.heylua.ai`; the
+     *  wrapper builds the Web `Request` URL against it. */
+    origin: string;
+    /** True for preview/sandbox deployments (reserved; always false in the MVP). */
+    preview: boolean;
+}
+
+/** The caller, as the gateway resolved it. Mirrors the shells' principal:
+ *  a first-party Lua session, never an API key, never anonymous. `roles` and
+ *  `scopes` are the effective ones on the app's agent target. */
+declare interface WebRouteAuth {
+    userId: string;
+    orgId: string;
+    agentId: string;
+    subjectType: 'user';
+    credentialType: 'firstPartySession';
+    sessionId?: string;
+    roles: string[];
+    scopes: string[];
+    name?: string;
+    email?: string;
+    /** ISO timestamp the session token expires at, when known. */
+    expiresAt?: string;
+}
+
+declare type WebRouteMethod = (typeof WEB_ROUTE_METHODS)[number];
+
 /** Body of POST /developer/agents/:agentId/channels/whatsapp/reaction */
 export declare interface WhatsAppReactionSendInput {
     to: {
@@ -7626,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';