lua-cli 3.53.0 → 3.54.0

package/dist/api-exports.d.ts

@@ -189,6 +189,17 @@ declare interface AgentDirectoryEntry {
     callerActions: string[];
 }
 
+/**
+ * A fresh agent identity assertion (ADR 0025): a 60-second, single-use, platform-signed proof that the call comes
+ * from a live execution of this agent.
+ */
+export declare interface AgentIdentityAssertion {
+    /** Send as the `X-Lua-Agent-Assertion` header on ONE call to the system named by `audience`. */
+    token: string;
+    /** ISO-8601 instant the token expires (60 s after it was minted). */
+    expiresAt: string;
+}
+
 /**
  * Narrowed, wire-safe output for `Agents.invoke`. A slice of the internal
  * `FullOutput` shape — raw Mastra steps / tripwire payloads are intentionally
@@ -3870,6 +3881,10 @@ export declare function defineVoice(config: LuaVoiceConfig): LuaVoice;
 /**
  * Define a web app on the agent.
  *
+ * `GET` routes must only read. People a view was shared with view-only (`auth.accessLevel === 'view_only'`) can call
+ * every `GET` route with the agent's own data and connections, and nothing else; any change belongs in a
+ * `POST`, `PUT`, `PATCH` or `DELETE` route, which only people with full access reach.
+ *
  * @example
  * ```typescript
  * import { defineWebApp, route, json } from 'lua-cli';
@@ -5946,7 +5961,14 @@ 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). */
+/**
+ * The signed-in person a route runs for (never an API key, never anonymous).
+ *
+ * `auth.accessLevel` says how much of the app they may use: `'full'` when they can read the app's agent, or
+ * `'view_only'` when someone shared just this view with them (or it is org-wide in their workspace) — then only
+ * `GET` routes reach your handlers, `roles` and `scopes` are empty, and the agent pane is off. A `GET` route must
+ * therefore only read: never create, change or delete anything in one.
+ */
 export declare type LuaAuth = WebRouteAuth;
 
 export declare class LuaBrowser {
@@ -6122,6 +6144,29 @@ export declare interface LuaDeviceTriggerConfig {
     execute: (payload: any, context: DeviceTriggerContext) => Promise<any>;
 }
 
+/**
+ * The agent's own identity, proven by the platform (ADR 0025).
+ */
+export declare interface LuaIdentity {
+    /**
+     * Mint a fresh agent identity assertion for `audience`. Only platform-allowlisted audiences are minted; today
+     * that is `'lua-api:staff'` (Lua's staff API, for an agent enrolled as a staff service principal).
+     *
+     * Throws an `AgentIdentityError` (`err.code`):
+     * - `agent_identity_requires_live_execution` outside a live execution (always in `lua test` / `lua dev`);
+     * - `agent_identity_audience_not_allowed` for any other audience;
+     * - `agent_identity_input_invalid` when `audience` is missing;
+     * - `agent_identity_unavailable` when the platform cannot mint one right now.
+     *
+     * Inside a test session it throws a `TestSessionError` with `test_session_tier_unsupported` instead.
+     *
+     * Mint one per call. A token is single-use, so never cache or reuse it.
+     */
+    assertion(input: {
+        audience: string;
+    }): Promise<AgentIdentityAssertion>;
+}
+
 /**
  * Lua Job class.
  * Main class for building scheduled jobs (cron jobs, one-time tasks, intervals).
@@ -6469,6 +6514,11 @@ export declare interface LuaRequest {
 export declare interface LuaRuntime {
     /** Request context information */
     request: LuaRequest;
+    /**
+     * The agent's platform-proven identity (ADR 0025). Optional because older runtimes do not provide it, so read it
+     * defensively: `Lua.identity?.assertion`.
+     */
+    identity?: LuaIdentity;
 }
 
 /**
@@ -6584,6 +6634,25 @@ export declare interface LuaTool<TInput extends ZodType = ZodType> {
     name: string;
     /** Description of what the tool does */
     description: string;
+    /**
+     * Optional text the chat shows to the user while this tool runs and after it
+     * finishes, instead of the tool's name. Either one text for both moments, or
+     * one for each:
+     *
+     * ```ts
+     * label = { running: 'Creating a ticket for {subject}', done: 'Created a ticket for {subject}' };
+     * label = 'Checked stock';
+     * ```
+     *
+     * `{argName}` is replaced with that argument's value from the call (string
+     * and number arguments only). Don't end the text with "…": the chat adds it
+     * while the tool runs. Each text is a string literal (or a const holding one)
+     * of at most 80 characters; `lua compile` ignores a computed label.
+     */
+    label?: string | {
+        running: string;
+        done: string;
+    };
     /** Zod schema for input validation */
     inputSchema: TInput;
     /**
@@ -11251,6 +11320,9 @@ export declare interface WebhookRequest {
     payload: any;
 }
 
+/** LUA-1353 — see {@link WebRouteAuth.accessLevel}. */
+declare type WebRouteAccessLevel = 'full' | 'view_only';
+
 /** The app the handler belongs to, for `ctx.app` and log correlation. */
 declare interface WebRouteApp {
     id: string;
@@ -11281,6 +11353,14 @@ declare interface WebRouteAuth {
     email?: string;
     /** ISO timestamp the session token expires at, when known. */
     expiresAt?: string;
+    /**
+     * LUA-1353 — how much of the app the caller may use. `full`: they can read the app's agent (every route, the
+     * agent pane). `view_only`: the app was shared with them, or is org-wide in their workspace, without access to
+     * the agent — only `GET` routes reach a handler, `roles` and `scopes` are empty, and the agent pane is off. A
+     * `GET` handler must therefore never change anything. Absent only from a gateway older than LUA-1353 (read it
+     * as `full`).
+     */
+    accessLevel?: WebRouteAccessLevel;
 }
 
 declare type WebRouteMethod = (typeof WEB_ROUTE_METHODS)[number];