lua-cli 3.27.0 → 3.29.0

package/README.md

@@ -44,7 +44,7 @@ lua --version
 
 ## Authentication
 
-lua-cli authenticates using your API key. Get yours at [admin.heylua.ai](https://admin.heylua.ai).
+lua-cli authenticates with a scoped personal credential or an existing API key. New email login limits the credential to the organization, agents, and role you select. Existing scoped and non-dotted legacy keys remain supported when you supply them directly.
 
 The key is resolved from the following sources in priority order:
 
@@ -60,21 +60,31 @@ The key is resolved from the following sources in priority order:
 lua auth configure
 ```
 
-Prompts you to choose between entering an API key directly or authenticating via email OTP. Credentials are saved to `~/.lua-cli/credentials`.
+Choose **Email** to confirm an OTP. Select one organization, one or more agents, and an assignable role. Builder is the default role. The CLI stores the scoped credential in `~/.lua-cli/credentials` with mode `0600` on POSIX systems.
+
+Choose **API Key** to validate and save an existing scoped or legacy key unchanged. The CLI does not rotate or revoke the supplied key.
 
 ```bash
 # Non-interactive variants:
-lua auth configure --api-key "lk_your_api_key_here"
-lua auth configure --email user@example.com            # Step 1: sends OTP
-lua auth configure --email user@example.com --otp 123456  # Step 2: verifies OTP
+lua auth configure --api-key "your-api-key"
+lua auth configure --email user@example.com
+lua auth configure \
+  --email user@example.com \
+  --otp 123456 \
+  --org-id org_123 \
+  --agent-id agent_123 \
+  --role builder \
+  --name "deployment laptop"
 ```
 
+Repeat `--agent-id` to bind the credential to more than one agent. For a new local login, prefer the interactive command and keep the email, OTP, and secret out of AI conversations.
+
 ### Option B — Environment variable (CI/CD, Docker, servers)
 
 Set `LUA_API_KEY` in your environment. This takes priority over all other sources and requires no file on disk — ideal for headless servers, VMs, and containers.
 
 ```bash
-export LUA_API_KEY="lk_your_api_key_here"
+export LUA_API_KEY="your-api-key"
 lua push all --force --auto-deploy
 ```
 
@@ -83,7 +93,7 @@ lua push all --force --auto-deploy
 Create a `.env` file in your project root:
 
 ```bash
-echo 'LUA_API_KEY=lk_your_api_key_here' >> .env
+echo 'LUA_API_KEY=your-api-key' >> .env
 ```
 
 lua-cli automatically loads `.env` on startup. Add `.env` to your `.gitignore` to avoid committing credentials.
@@ -138,7 +148,7 @@ lua auth logout --force  # No prompt
 lua auth configure
 ```
 
-Enter your API key when prompted (get one at [admin.heylua.ai](https://admin.heylua.ai)). For CI/CD or server environments, set `LUA_API_KEY` as an environment variable instead — see [Authentication](#authentication) above.
+Choose **Email** and select the organization, agents, and role for the new scoped credential. If you already have a working key, choose **API Key** to keep using it unchanged. For CI or server environments, set `LUA_API_KEY` from a secret manager. See [Authentication](#authentication).
 
 ### 2. Initialize Project
 

package/dist/api-exports.d.ts

@@ -415,7 +415,10 @@ declare interface ApiResponse<T = any> {
         message: string;
         code?: string;
         statusCode?: number;
+        retryAfterSeconds?: number;
         error?: string;
+        oldAccountLabel?: string;
+        newAccountLabel?: string;
     };
 }
 
@@ -1774,11 +1777,12 @@ declare type HeadersResolverFunction = () => Record<string, string>;
  */
 declare abstract class HttpClient {
     protected baseUrl: string;
+    private readonly requestCredential?;
     /**
      * Creates an instance of HttpClient
      * @param baseUrl - The base URL for all API requests
      */
-    constructor(baseUrl: string);
+    constructor(baseUrl: string, requestCredential?: RequestCredentialInput | undefined);
     /**
      * Makes an HTTP request with standardized error handling
      * @param url - The full URL to request
@@ -1829,6 +1833,13 @@ declare abstract class HttpClient {
      * @protected
      */
     protected httpPost<T>(url: string, data?: any, headers?: Record<string, string>): Promise<ApiResponse<T>>;
+    /**
+     * Performs one HTTP POST attempt.
+     *
+     * 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>>;
     /**
      * Performs an HTTP PUT request
      * @param url - The relative URL path to request (will be appended to baseUrl)
@@ -1925,6 +1936,18 @@ declare interface InboxPushInput {
     /** Idempotency/revision key: same key = revise the existing card in place,
      *  never a second knock. Omit for one-shot notices. */
     key?: string;
+    /** Cross-route resolution (PRO-1208 follow-up #2) — only meaningful on a
+     *  plain NOTICE push that carries a `key`. When `true`, this notice
+     *  declares it REPORTS THE RESOLUTION of whatever an open same-key
+     *  question card is still asking — the agent settled the cycle itself
+     *  (re-reviewed after the fix landed and auto-approved; the incident
+     *  closed on its own). Once the notice lands, the stale question card is
+     *  superseded: settled, no live actions, and never a knock. An in-flight
+     *  user answer always wins — their explicit decision stands. WITHOUT this
+     *  flag a same-key notice never touches the question track: routine
+     *  progress updates coexist with an open ask. Ignored without `key`, and
+     *  on question/fix pushes. Must be the literal boolean `true`. */
+    resolvesQuestion?: boolean;
     /** Conversation the card should hand off into when the user acts. */
     threadId?: string;
 }
@@ -2056,15 +2079,15 @@ declare interface Job {
  * Handles all job-related API calls
  */
 declare class JobApi extends HttpClient {
-    apiKey: string;
     agentId: string;
+    readonly credential: RequestCredentialInput;
     /**
      * Creates an instance of JobApi
      * @param baseUrl - The base URL for the API
-     * @param apiKey - The API key for authentication
+     * @param credential - The API key for authentication
      * @param agentId - The unique identifier of the agent
      */
-    constructor(baseUrl: string, apiKey: string, agentId: string);
+    constructor(baseUrl: string, credential: RequestCredentialInput, agentId: string);
     /**
      * Retrieves all jobs for the agent
      * @returns Promise resolving to an ApiResponse containing an array of jobs with their versions
@@ -3262,6 +3285,10 @@ export declare class LuaTrigger<T = any> {
     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>;
+    readonly tool?: {
+        name: string;
+        input?: (ctx: TriggerContext<T>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    };
     constructor(config: LuaTriggerConfig<T>);
     getName(): string;
     getDescription(): string;
@@ -3301,6 +3328,24 @@ export declare interface LuaTriggerConfig<T = any> {
      * transform to forward larger or hand-picked fields as the message.
      */
     transform?: (ctx: TriggerContext<T>) => string | AgentInvocationInput | Promise<string | AgentInvocationInput>;
+    /**
+     * Direct tool binding: after `verify`/`filter` pass, the platform executes
+     * this named skill tool DIRECTLY — no chat turn, no LLM, no visible
+     * conversation thread. `name` is the BARE authored tool name (skill-first
+     * resolution server-side); it must be a static string literal — the
+     * 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 `{}`.
+     *
+     * Declaring BOTH `tool` and `transform` runs the tool; the transform is
+     * ignored (the compiler warns). Approval-gated tools are refused server-
+     * side (fail closed) — the execution row records the refusal.
+     */
+    tool?: {
+        name: string;
+        input?: (ctx: TriggerContext<T>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    };
 }
 
 /**
@@ -4355,6 +4400,7 @@ export declare class LuaWebhook {
     private readonly querySchema?;
     private readonly headerSchema?;
     private readonly bodySchema?;
+    private readonly secret?;
     private readonly executeFunction;
     /**
      * Creates a new LuaWebhook instance.
@@ -4368,6 +4414,11 @@ export declare class LuaWebhook {
      * @param config.execute - Function that processes the webhook request
      */
     constructor(config: LuaWebhookConfig);
+    /**
+     * Gets the webhook's signing key, if one is configured.
+     * Never print this — it is the shared secret callers sign with.
+     */
+    getSecret(): string | undefined;
     /**
      * Gets the webhook name.
      */
@@ -4414,6 +4465,14 @@ export declare interface LuaWebhookConfig {
     headerSchema?: ZodType;
     /** Optional Zod schema for body validation */
     bodySchema?: ZodType;
+    /**
+     * Optional HMAC-SHA256 signing key. When set, Lua rejects any call to this
+     * webhook that does not carry `x-lua-signature: sha256=<hex digest of the
+     * raw request body>`. Must be a literal or a `const` resolvable at compile
+     * time — the compiler cannot read a runtime expression. Rotate by changing
+     * it and re-deploying.
+     */
+    secret?: string;
     /** Function that executes the webhook logic */
     execute: (event: LuaWebhookEvent) => Promise<any>;
 }
@@ -4577,15 +4636,14 @@ declare interface OrderAPI {
 }
 
 declare class OrderApi extends HttpClient implements OrderAPI {
-    private apiKey;
     private agentId;
     /**
      * Creates an instance of OrderApi
      * @param baseUrl - The base URL for the API
-     * @param apiKey - The API key for authentication
+     * @param credential - The API key for authentication
      * @param agentId - The unique identifier of the agent
      */
-    constructor(baseUrl: string, apiKey: string, agentId: string);
+    constructor(baseUrl: string, credential: RequestCredentialInput, agentId: string);
     /**
      * Creates a new order from a basket
      * @param orderData - The order creation request data containing basketId and additional order information
@@ -5405,6 +5463,22 @@ declare const REASONING_EFFORT_VALUES: readonly ["off", "minimal", "low", "mediu
 
 declare type ReasoningEffort = (typeof REASONING_EFFORT_VALUES)[number];
 
+declare interface RequestCredential {
+    readonly descriptor: RequestCredentialDescriptor;
+    bearer(): Promise<string>;
+}
+
+declare type RequestCredentialDescriptor = {
+    kind: 'api-key';
+    source: 'environment' | 'stored';
+} | {
+    kind: 'first-party-session';
+    source: 'stored';
+    uid: string;
+};
+
+declare type RequestCredentialInput = string | RequestCredential;
+
 /**
  * Additive field on primitive publish responses. When the agent is under
  * versioning the server performs a scoped promote and returns the newly