lua-cli 3.45.0 → 3.47.0

package/docs/README.md

@@ -1,6 +1,6 @@
-# lua-cli v3.43.0
+# lua-cli v3.47.0
 
-Welcome to the comprehensive API documentation for lua-cli v3.43.0. This guide covers every API, class, and function exported by the package.
+Welcome to the comprehensive API documentation for lua-cli v3.47.0. This guide covers every API, class, and function exported by the package.
 
 ## 📚 Documentation Index
 
@@ -263,8 +263,8 @@ Each API doc includes:
 
 ---
 
-**Version:** 3.29.1
-**Last Updated:** August 2026
+**Version:** 3.47.0
+**Last Updated:** October 2026
 
 ---
 

package/docs/api/Agents.md

@@ -81,6 +81,8 @@ await Agents.workflows('base_agent-tp').deploy('wf_123', '1.4.0', { expectActive
 await Agents.versions('base_agent-tp').delete(5);
 ```
 
+> **Experimental.** `Agents.jobs(agentId).register({ versionId, jobId })` registers job `jobId`, defined in the staged version `versionId`, on the target. It is available in a deployed agent only once the platform serves `jobs.register`, and needs the `supervision:register-job` grant (given per supervisor and target by an org owner or admin, scoped to jobs defined in the staged `versionId`). Without it the call is refused with `supervision_not_granted`. Under `lua test` / `lua dev` it is always refused with `supervision_release_offline_refused`, with no network call. An empty `versionId` or `jobId` is refused with `supervision_bad_args`, and an empty agent id with `supervision_no_target`.
+
 - A workflow deploy also records a new active agent version. Read `versions.list` again before a later `promote`.
 - `commitHash` on `workflows.deploy` is optional and forwarded unchanged. A call without it behaves as before, and the platform may fill it from the Job workspace.
 
@@ -115,7 +117,7 @@ await Agents.versions('base_agent-tp').delete(5);
 ### Offline (`lua test`, `lua dev`)
 
 - **Read members** call the developer API with **your** credential and mirror the projections above: env keys only, and logs without user ids or message bodies.
-- **Refused offline:** `versions.promote`, `persona.activate`, `versions.delete`, `workflows.create`, `workflows.push`, `workflows.deploy`, `versions.preview` and `data`. A local test never changes a live agent, and readable collections live on the grant.
+- **Refused offline:** `versions.promote`, `persona.activate`, `versions.delete`, `workflows.create`, `workflows.push`, `workflows.deploy`, `jobs.register` (experimental), `versions.preview` and `data`. A local test never changes a live agent, and readable collections live on the grant.
 - **Not available offline:** `Agents.list`, `Agents.get`, `source.get` and `Agents.deployed` (`supervision_offline_unsupported`).
 
 ### Errors
@@ -123,6 +125,9 @@ await Agents.versions('base_agent-tp').delete(5);
 Every error is a `SupervisionError` with a `code`:
 
 - `supervision_not_granted`
+- `supervision_release_offline_refused`, for a release op (or the experimental `jobs.register`) run offline
+- `supervision_bad_args`, a local check of the experimental `jobs.register`: an empty `versionId` or `jobId`
+- `supervision_no_target`, a local check: no agent id is given
 - `supervision_not_found`, for another org or an unknown agent
 - `supervision_self_refused`
 - `supervision_release_binding_required` and `supervision_release_binding_refused`

package/docs/api/User.md

@@ -266,7 +266,7 @@ await user.send([
 
 #### `user.clear()`
 
-Clears all user data.
+Clears all user data, including the user's My work list.
 
 **Returns:** `Promise<{ success: boolean }>` - `{ success: true }` once the data is cleared. Throws if the clear fails.
 
@@ -277,6 +277,57 @@ const user = await User.get();
 await user.clear();
 ```
 
+#### `user.setWorkItems(items)`
+
+Publishes this user's **My work** list: the open work an agent lists for them (a ticket they raised or hold, an approval waiting on them). Their client shows it beside the conversation, for example Frontline's "My work" tab. Each call replaces the whole list.
+
+**Parameters:** `items: WorkItem[]`, at most 100.
+
+| Field         | Type             | Notes                                                                   |
+| ------------- | ---------------- | ----------------------------------------------------------------------- |
+| `id`          | `string`         | Unique in the list, ≤ 200 chars (e.g. a ticket number)                  |
+| `title`       | `string`         | One line the user recognises, ≤ 120 chars                               |
+| `group`       | `string`         | Display group you choose, ≤ 40 chars ("Waiting on you", "Your tickets") |
+| `needsAction` | `boolean?`       | The user's own action is needed; listed first and highlighted           |
+| `status`      | `string?`        | Short label, ≤ 40 chars ("In progress")                                 |
+| `updatedAt`   | `string \| Date` | When this work last changed                                             |
+| `action`      | `string`         | Message the client sends when the item is tapped, ≤ 200 chars           |
+
+**Returns:** `Promise<void>`. Throws an error naming the first invalid item before anything is written, or `Failed to set work items` if the write fails.
+
+**Rules:**
+
+- **`action` is a show/open request, never a decision.** Use "Show MNT-00123", not "Approve MNT-00123". A tap must not act on a list that may be minutes old; ask for decisions in the conversation instead.
+- **Publish whenever the work changes, for everyone it affects.** That means the raiser, the assignee and the next approver. Use `User.get({ phone })` or `User.get(userId)` to address each of them.
+- **Add a scheduled job (every ~30 min)** that rebuilds the lists of recently active users. It catches any write that failed.
+- **Leave closed or cancelled work out.** An empty list (`[]`) means "nothing waiting".
+- **The list is kept out of `user.data`.** `update()`, `save()` and `patch()` never write it, so a stale read can't overwrite a newer list. `user.clear()` removes it.
+
+**Example:**
+
+```typescript
+import { User } from 'lua-cli';
+
+// After assigning MNT-00123 to a technician:
+const technician = await User.get({ phone: '+254700000000' });
+await technician?.setWorkItems([
+  {
+    id: 'MNT-00123',
+    title: 'MNT-00123 · Fryer not heating',
+    group: 'Assigned to you',
+    status: 'In progress',
+    updatedAt: new Date(),
+    action: 'Show MNT-00123',
+  },
+]);
+```
+
+#### `user.clearWorkItems()`
+
+Removes this user's My work list. Their client then shows no list from this agent.
+
+**Returns:** `Promise<void>`
+
 #### `user.save()`
 
 Saves current user data state.

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

@@ -14,6 +14,8 @@ _Source of truth: workflows-spec 05 §5.17 (D19-r1/r2). This page is the develop
 
 **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 (168 h at most once the ceiling is enabled). 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.
 
+**Storage is metered.** A Job-tier workspace volume, and every worktree-arm clone volume, is metered as GiB-hours (`sizeGb` × hours held, summed over the clones) on a `workflow:storage` usage record written when the volume is deleted; a held volume counts until its TTL expiry. The record is attributed to your organization and is for visibility only: it does not charge credits or touch the wallet, and whether storage is billed is a separate platform decision.
+
 **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.
 
 ## Commands from a code step — `ctx.exec` / `ctx.$`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.45.0",
+  "version": "3.47.0",
   "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",
@@ -116,9 +116,9 @@
     "tsup": "^8.5.1",
     "@lua/sandbox-runtime": "0.0.1",
     "@lua/shared-sandbox": "0.0.1",
+    "@lua/workflow-graph": "0.0.1",
     "@lua/shared-source-sync": "0.0.1",
-    "@lua/shared-types": "0.0.1",
-    "@lua/workflow-graph": "0.0.1"
+    "@lua/shared-types": "0.0.1"
   },
   "scripts": {
     "clean": "rm -rf dist temp",

package/template/package.json

@@ -20,7 +20,7 @@
     "inquirer": "^12.9.6",
     "stripe": "^17.5.0",
     "js-yaml": "^4.1.0",
-    "lua-cli": "^3.45.0",
+    "lua-cli": "^3.47.0",
     "openai": "^5.23.0",
     "uuid": "^13.0.0",
     "zod": "^3.24.1"

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

@@ -8,6 +8,7 @@
   },
   "dependencies": {
     "@base-ui/react": "~1.8.0",
+    "@lua-ai-global/app-client": "~0.0.2",
     "@lua-ai-global/ui": "~0.2.0",
     "@phosphor-icons/react": "~2.1.10",
     "react": "~19.3.0",

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

@@ -1,7 +1,7 @@
 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';
+import { lua } from '@lua-ai-global/app-client';
 
 export function App() {
   const [message, setMessage] = useState<string>();

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

@@ -1,7 +1,7 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
 import { App } from './App';
-import { lua } from './lua/client';
+import { lua } from '@lua-ai-global/app-client';
 import './index.css';
 
 // Theme follows the shell: first from the bootstrap, then from the host's `init`.

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

@@ -1,269 +0,0 @@
-/**
- * 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.
-   *
-   * A shell on a custom scheme (lua-desktop's `tauri://localhost`) is not a
-   * valid postMessage target origin: WebKit throws "Invalid target origin",
-   * which aborted the loop and the session ("Could not load" in lua-desktop),
-   * and skipping it would leave the desktop shell without `lua:ready`.
-   * Such an origin is posted with '*': the messages carry only {type, v}, and
-   * the CSP's frame-ancestors already limits who can frame the app. Each post
-   * is isolated so one origin can never stop the others.
-   */
-  private post(message: { type: string; v: number }): void {
-    if (window.parent === window) return;
-    const targets = new Set(this.hostOrigins().map((origin) => (/^https?:\/\//i.test(origin) ? origin : '*')));
-    for (const target of targets) {
-      try {
-        window.parent.postMessage(message, target);
-      } catch {
-        // An origin this browser will not target: skip it, keep the rest.
-      }
-    }
-  }
-}
-
-export const lua = new LuaAppClient();