lua-cli 3.40.0 → 3.42.0-beta.1

package/docs/workflows/reply-channels.md

@@ -4,8 +4,8 @@ _Source of truth: workflows-spec (Cluster K B42). This page is the developer sum
 
 A run started from a conversation carries `replyTo: { channel, threadId }`; at terminal state the platform sends the outcome back through a **`ChannelAdapter`** — a new channel is one adapter file + one registry entry.
 
-- Registered today: **whatsapp**. `sms` / `email` / `webchat` / `slack` are specified and land behind their E-10 pins; an unregistered channel fails loudly (`channel_unsupported`), never silently drops.
-- Slack `threadId` format: `<channelId>:<thread_ts>`.
+- Registered today: **whatsapp** and **slack**. `sms` / `email` / `webchat` are specified and land behind their E-10 pins; an unregistered channel fails loudly (`channel_unsupported`), never silently drops.
+- Slack posts through `Channels.send` on the agent's own Slack connection, never another bot; the run's occurrence id is the idempotency key, so a redelivery never posts twice. `threadId` is any Slack `conversationId` (usually `<channelId>:<thread_ts>`; with several Slack connections use the room key `T…:A…:<channelId>:<thread_ts>`). No Slack connection, or the bot not in the channel, fails the reply permanently. Attachments go out as links.
 - A step may answer the customer itself mid-run (`Channels.<channel>.send` inside `ctx.once`) — the terminal reply then lands as a duplicate-safe fallback on the same thread.
 
 Offline: `--reply-to <channel>:<threadId>` prints the would-be reply on the terminal.

package/docs/workflows/workspaces-and-long-steps.md

@@ -10,7 +10,7 @@ _Source of truth: workflows-spec 05 §5.17 (D19-r1/r2). This page is the develop
 
 `credentialsRef` is a connection id **or a key you declare under `connections: [{ key, integrationType }]`** — declare a key; it resolves against the owner agent's own connections on any agent at run time (see [Git credentials](./git-credentials.md)), so the definition never freezes a production id.
 
-**The release-at-suspension rule:** when your run waits for a person or a signal, its volume is released: committed work is on the run branch `lua/wf-<lineageId>` on your remote; untracked files — `node_modules`, build output — are rebuilt when the next step restores the checkout.
+**Suspension does not release the workspace.** When your run waits for a person or a signal, its volume is left exactly as it was — it keeps holding one of the org's `maxWorkspacesPerOrg` slots until a terminal reason releases it, or, for a kept `empty` workspace, `ttlHours` expires. Releasing a workspace at suspension is not implemented yet (tracked as SA-134); until then, commit before a step suspends so your work is durable on the run branch `lua/wf-<lineageId>` independent of the volume.
 
 **Worktree arms:** parallel arms never share a filesystem; each gets its own clone and branch and the `merge` step integrates them — put `verify` on the workspace so an agent-resolved conflict must pass your tests. `onConflict:'agent'` lets one resolver turn fix conflicts.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.40.0",
+  "version": "3.42.0-beta.1",
   "description": "Build, test, and deploy AI agents with custom tools, webhooks, and scheduled jobs. Features LuaAgent unified configuration, streaming chat, and batch deployment.",
   "readmeFilename": "README.md",
   "main": "dist/api-exports.js",
@@ -61,6 +61,7 @@
   "files": [
     "dist/**/*",
     "template/**/*",
+    "template-web-app/**/*",
     "docs/**/*",
     "scripts/**/*",
     "README.md",

package/template/package.json

@@ -20,7 +20,7 @@
     "inquirer": "^12.9.6",
     "stripe": "^17.5.0",
     "js-yaml": "^4.1.0",
-    "lua-cli": "^3.40.0",
+    "lua-cli": "^3.42.0-beta.1",
     "openai": "^5.23.0",
     "uuid": "^13.0.0",
     "zod": "^3.24.1"

package/template/tsconfig.json

@@ -14,5 +14,5 @@
       "@/services/*": ["src/services/*"]
     }
   },
-  "exclude": ["dist", "dist-v2", "node_modules"]
+  "exclude": ["dist", "dist-v2", "node_modules", "src/apps/*/web"]
 }

package/template-web-app/app.ts

@@ -0,0 +1,29 @@
+import { defineWebApp, route } from 'lua-cli';
+import { z } from 'zod';
+
+/**
+ * __APP_NAME__ — a Lua web app.
+ *
+ * Pages: the Vite project in ./web (runs in the browser, inside Lua Workspace
+ * and the admin console). Routes: the handlers below (run in the Lua sandbox
+ * with the signed-in person as `auth`; Data, env() and fetch are available).
+ *
+ *   lua apps dev __APP_NAME__        pages with hot reload, routes run locally as you
+ *   lua test webapp --name __APP_NAME__ --route 'GET /hello'
+ *   lua push webapp --name __APP_NAME__
+ */
+export default defineWebApp({
+  name: '__APP_NAME__',
+  description: 'A Lua web app',
+  pages: {
+    root: './web',
+    nav: [{ path: '/', label: 'Overview' }],
+  },
+  routes: {
+    'GET /hello': route({
+      description: 'Greets the signed-in person',
+      responses: { 200: z.object({ message: z.string() }) },
+      handler: async ({ auth }) => ({ message: `Hello, ${auth.name ?? auth.email ?? auth.userId}` }),
+    }),
+  },
+});

package/template-web-app/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__APP_NAME__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template-web-app/web/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "__APP_NAME__-web",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@base-ui/react": "~1.8.0",
+    "@lua-ai-global/ui": "~0.2.0",
+    "@phosphor-icons/react": "~2.1.10",
+    "react": "~19.3.0",
+    "react-dom": "~19.3.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "~4.3.3",
+    "@types/react": "~19.3.0",
+    "@types/react-dom": "~19.3.0",
+    "@vitejs/plugin-react": "~6.1.1",
+    "shadcn": "~3.8.5",
+    "tailwindcss": "~4.3.3",
+    "tw-animate-css": "~1.4.0",
+    "typescript": "~5.9.3",
+    "vite": "~8.3.1"
+  }
+}

package/template-web-app/web/src/App.tsx

@@ -0,0 +1,28 @@
+import { useEffect, useState } from 'react';
+import { Button } from '@lua-ai-global/ui/button';
+import { Card } from '@lua-ai-global/ui/card';
+import { lua } from './lua/client';
+
+export function App() {
+  const [message, setMessage] = useState<string>();
+  const [error, setError] = useState<string>();
+
+  const load = () => {
+    setError(undefined);
+    lua
+      .api<{ message: string }>('GET', '/hello')
+      .then((r) => setMessage(r.message))
+      .catch((e: Error) => setError(e.message));
+  };
+  useEffect(load, []);
+
+  return (
+    <main className="min-h-screen bg-background p-6 text-foreground">
+      <Card className="mx-auto max-w-md space-y-4 p-6">
+        <h1 className="text-lg font-semibold">{lua.appName}</h1>
+        <p className="text-muted-foreground">{error ?? message ?? 'Loading…'}</p>
+        <Button onClick={load}>Say hello again</Button>
+      </Card>
+    </main>
+  );
+}

package/template-web-app/web/src/index.css

@@ -0,0 +1,3 @@
+@import '@lua-ai-global/ui/styles.css';
+/* Tailwind scans the design system's compiled components for the classes they use. */
+@source '../node_modules/@lua-ai-global/ui/dist';

package/template-web-app/web/src/lua/client.ts

@@ -0,0 +1,254 @@
+/**
+ * Lua app client — the page side of a Lua web app.
+ *
+ * - Session: the shell opens this app in an iframe with a single-use handoff
+ *   code in the URL fragment (`#code=…`). The client exchanges it with lua-auth
+ *   for a Firebase custom token, signs in (identitytoolkit) and keeps the ID
+ *   token in memory only, refreshing it (securetoken) before it expires. No
+ *   cookie, no localStorage: a reload asks the shell for a new code.
+ * - Bridge (protocol v1): posts `lua:ready` once loaded, takes `lua:init`
+ *   (theme, density, locale, path) from the host, posts `lua:auth:expired`
+ *   when the session cannot be renewed so the shell re-issues a code. Messages
+ *   go only to, and are only accepted from, the shells the gateway lists in
+ *   the bootstrap (`hostOrigins`, the same list as the CSP's frame-ancestors).
+ * - `api(method, path, body?)`: calls a route of this app through the gateway
+ *   (`/_lua/api/<path>`) with the session. A 401 renews the token once and
+ *   retries; only a second 401 ends the session.
+ *
+ * Under `lua apps dev` the bootstrap says `dev: true`: there is no handoff and
+ * the dev server runs routes as the developer.
+ *
+ * Generated by `lua apps new`; yours to edit. (A packaged `@lua-ai-global/app-client`
+ * replaces this file later.)
+ */
+
+export interface LuaBootstrap {
+  v: 1;
+  app: { id: string; name: string; version: string; deployment: number; origin: string };
+  apiBase: string;
+  manifest: string;
+  auth: { origin: string; exchangePath: string; audience: string; firebaseApiKey?: string };
+  embedded: boolean;
+  /** The shells allowed to frame this app; the bridge talks to these only. */
+  hostOrigins?: string[];
+  theme: 'light' | 'dark';
+  density: 'compact' | 'comfortable';
+  preview: boolean;
+  /** Set by `lua apps dev` only. */
+  dev?: boolean;
+}
+
+export interface LuaInit {
+  v: 1;
+  theme?: 'light' | 'dark';
+  density?: 'compact' | 'comfortable';
+  locale?: string;
+  path?: string;
+}
+
+declare global {
+  interface Window {
+    __LUA__?: LuaBootstrap;
+  }
+}
+
+const BRIDGE_VERSION = 1;
+const IDENTITY = 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken';
+const SECURE_TOKEN = 'https://securetoken.googleapis.com/v1/token';
+/** Renew this long before the ID token expires. */
+const REFRESH_MARGIN_MS = 5 * 60_000;
+
+export class LuaApiError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string | undefined,
+    message: string,
+    readonly executionId?: string
+  ) {
+    super(message);
+    this.name = 'LuaApiError';
+  }
+}
+
+interface Tokens {
+  idToken: string;
+  refreshToken: string;
+  expiresInS: number;
+}
+
+const nonEmpty = (v: unknown): v is string => typeof v === 'string' && v.length > 0;
+
+/** A token response is only a session when every field is there; anything else is "no session". */
+function tokensFrom(idToken: unknown, refreshToken: unknown, expiresIn: unknown): Tokens | null {
+  const expiresInS = Number(expiresIn);
+  if (!nonEmpty(idToken) || !nonEmpty(refreshToken) || !Number.isFinite(expiresInS) || expiresInS <= 0) return null;
+  return { idToken, refreshToken, expiresInS };
+}
+
+async function jsonOrNull(response: Response | undefined): Promise<Record<string, unknown> | null> {
+  if (!response?.ok) return null;
+  try {
+    const body = await response.json();
+    return body && typeof body === 'object' ? (body as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+class LuaAppClient {
+  private readonly boot: LuaBootstrap | undefined = window.__LUA__;
+  private idToken: string | undefined;
+  private refreshToken: string | undefined;
+  private refreshTimer: ReturnType<typeof setTimeout> | undefined;
+  private renewing: Promise<boolean> | undefined;
+  private session: Promise<void> | undefined;
+  private readonly initListeners: Array<(init: LuaInit) => void> = [];
+
+  get appName(): string {
+    return this.boot?.app.name ?? document.title;
+  }
+
+  get theme(): 'light' | 'dark' {
+    return this.boot?.theme ?? 'dark';
+  }
+
+  onInit(listener: (init: LuaInit) => void): void {
+    this.initListeners.push(listener);
+  }
+
+  /** Take the handoff code, open the session, tell the host we are ready. */
+  start(): Promise<void> {
+    if (!this.session) {
+      window.addEventListener('message', (event) => {
+        // Only the shell that framed us, from an origin the gateway allows, speaks the bridge.
+        if (event.source !== window.parent || !this.hostOrigins().includes(event.origin)) return;
+        if (event.data?.type !== 'lua:init') return;
+        for (const listener of this.initListeners) listener(event.data as LuaInit);
+      });
+      this.session = this.openSession().finally(() => this.post({ type: 'lua:ready', v: BRIDGE_VERSION }));
+    }
+    return this.session;
+  }
+
+  async api<T>(method: string, path: string, body?: unknown): Promise<T> {
+    await this.start();
+    let response = await this.send(method, path, body);
+    // A 401 usually means the ID token lapsed between refreshes: renew once and retry once.
+    if (response.status === 401 && (await this.renew())) response = await this.send(method, path, body);
+    if (response.status === 401) this.expired();
+    const text = await response.text();
+    let data: any;
+    try {
+      data = text ? JSON.parse(text) : undefined;
+    } catch {
+      data = text;
+    }
+    if (!response.ok) {
+      throw new LuaApiError(
+        response.status,
+        data?.code,
+        data?.message ?? response.statusText,
+        response.headers.get('x-lua-execution-id') ?? undefined
+      );
+    }
+    return data as T;
+  }
+
+  private send(method: string, path: string, body?: unknown): Promise<Response> {
+    const base = this.boot?.apiBase ?? '/_lua/api';
+    const headers: Record<string, string> = { accept: 'application/json' };
+    if (this.idToken) headers.authorization = `Bearer ${this.idToken}`;
+    if (body !== undefined) headers['content-type'] = 'application/json';
+    return fetch(`${base}${path.startsWith('/') ? path : `/${path}`}`, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+  }
+
+  private async openSession(): Promise<void> {
+    const boot = this.boot;
+    if (!boot || boot.dev) return; // `lua apps dev`: the dev server is the caller's session.
+    const code = new URLSearchParams(location.hash.slice(1)).get('code');
+    // The code is single-use: drop it from the URL before anything can copy it.
+    if (code) history.replaceState(null, '', location.pathname + location.search);
+    if (!code || !boot.auth.firebaseApiKey) return this.expired();
+
+    const exchanged = await jsonOrNull(
+      await fetch(`${boot.auth.origin}${boot.auth.exchangePath}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ code, audience: boot.auth.audience }),
+      }).catch(() => undefined)
+    );
+    if (!nonEmpty(exchanged?.token)) return this.expired();
+
+    const signedIn = await jsonOrNull(
+      await fetch(`${IDENTITY}?key=${encodeURIComponent(boot.auth.firebaseApiKey)}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ token: exchanged!.token, returnSecureToken: true }),
+      }).catch(() => undefined)
+    );
+    const tokens = signedIn && tokensFrom(signedIn.idToken, signedIn.refreshToken, signedIn.expiresIn);
+    if (!tokens) return this.expired();
+    this.keep(tokens);
+  }
+
+  private keep(tokens: Tokens): void {
+    this.idToken = tokens.idToken;
+    this.refreshToken = tokens.refreshToken;
+    clearTimeout(this.refreshTimer);
+    this.refreshTimer = setTimeout(
+      () => void this.renew().then((ok) => ok || this.expired()),
+      Math.max(tokens.expiresInS * 1000 - REFRESH_MARGIN_MS, 30_000)
+    );
+  }
+
+  /** Swap the refresh token for a new ID token. One renewal at a time; `false` when it cannot be done. */
+  private renew(): Promise<boolean> {
+    if (!this.renewing) {
+      this.renewing = this.refreshOnce().finally(() => (this.renewing = undefined));
+    }
+    return this.renewing;
+  }
+
+  private async refreshOnce(): Promise<boolean> {
+    const key = this.boot?.auth.firebaseApiKey;
+    if (!key || !this.refreshToken) return false;
+    const r = await jsonOrNull(
+      await fetch(`${SECURE_TOKEN}?key=${encodeURIComponent(key)}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: this.refreshToken }),
+      }).catch(() => undefined)
+    );
+    const tokens = r && tokensFrom(r.id_token, r.refresh_token, r.expires_in);
+    if (!tokens) return false;
+    this.keep(tokens);
+    return true;
+  }
+
+  /** The session is gone: the shell answers with a fresh handoff code. */
+  private expired(): void {
+    this.idToken = undefined;
+    this.refreshToken = undefined;
+    clearTimeout(this.refreshTimer);
+    this.post({ type: 'lua:auth:expired', v: BRIDGE_VERSION });
+  }
+
+  private hostOrigins(): string[] {
+    return this.boot?.hostOrigins ?? [];
+  }
+
+  /**
+   * One post per allowed shell origin: the browser delivers it only when the
+   * framing window really has that origin, so no other page ever receives it.
+   */
+  private post(message: { type: string; v: number }): void {
+    if (window.parent === window) return;
+    for (const origin of this.hostOrigins()) window.parent.postMessage(message, origin);
+  }
+}
+
+export const lua = new LuaAppClient();

package/template-web-app/web/src/main.tsx

@@ -0,0 +1,16 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+import { lua } from './lua/client';
+import './index.css';
+
+// Theme follows the shell: first from the bootstrap, then from the host's `init`.
+document.documentElement.classList.toggle('dark', lua.theme === 'dark');
+lua.onInit((init) => document.documentElement.classList.toggle('dark', init.theme === 'dark'));
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);
+void lua.start();

package/template-web-app/web/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "isolatedModules": true
+  },
+  "include": ["src"]
+}

package/template-web-app/web/vite.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+// `lua push webapp` builds with this config and pins only what the Lua gateway
+// needs on top of it (base '/', assets under assets/, the CSP nonce).
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});