lua-cli 3.39.2 → 3.39.4

package/dist/api-exports.d.ts

@@ -1927,6 +1927,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;
 
 /**
@@ -3125,6 +3156,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 +3430,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.
  *
@@ -4201,14 +4240,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     }, {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"plugin">;
@@ -4222,15 +4261,15 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     }, {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"realtime">;
         provider: z.ZodEnum<["openai", "google", "xai"]>;
@@ -4242,13 +4281,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     }, {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     }>]>;
     stt: z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         kind: z.ZodLiteral<"inference">;
@@ -4267,14 +4306,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     }, {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"plugin">;
@@ -4288,15 +4327,15 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     }, {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"realtime">;
         provider: z.ZodEnum<["openai", "google", "xai"]>;
@@ -4308,13 +4347,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     }, {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     }>]>>;
     tts: z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
         kind: z.ZodLiteral<"inference">;
@@ -4333,14 +4372,14 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     }, {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"plugin">;
@@ -4354,15 +4393,15 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     }, {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"realtime">;
         provider: z.ZodEnum<["openai", "google", "xai"]>;
@@ -4374,13 +4413,13 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
          */
         options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, "strip", z.ZodTypeAny, {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     }, {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     }>]>>;
     vad: z.ZodOptional<z.ZodString>;
     vadOptions: z.ZodOptional<z.ZodObject<{
@@ -4541,50 +4580,50 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     name?: string;
     vad?: string;
     stt?: {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     } | {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     };
     volume?: number;
     llm?: {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     } | {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     };
     tts?: {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     } | {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -4635,50 +4674,50 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     name?: string;
     vad?: string;
     stt?: {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     } | {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     };
     volume?: number;
     llm?: {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     } | {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     };
     tts?: {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     } | {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -4729,50 +4768,50 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     name?: string;
     vad?: string;
     stt?: {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     } | {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     };
     volume?: number;
     llm?: {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     } | {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     };
     tts?: {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     } | {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -4823,50 +4862,50 @@ declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
     name?: string;
     vad?: string;
     stt?: {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     } | {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     };
     volume?: number;
     llm?: {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     } | {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     };
     tts?: {
+        voice?: string;
         kind?: "inference";
         options?: Record<string, unknown>;
-        voice?: string;
         model?: string;
     } | {
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+        provider?: "deepgram" | "elevenlabs";
         kind?: "plugin";
         options?: Record<string, unknown>;
-        provider?: "deepgram" | "elevenlabs";
-        class?: "LLM" | "STT" | "STTv2" | "TTS";
     } | {
+        provider?: "google" | "xai" | "openai";
         kind?: "realtime";
         options?: Record<string, unknown>;
-        provider?: "google" | "xai" | "openai";
     };
     vadOptions?: {
         minSpeechDuration?: number;
@@ -5088,6 +5127,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.
@@ -6468,6 +6538,46 @@ 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;
@@ -7320,6 +7430,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 +7493,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: {