lua-cli 3.45.0 → 3.46.0

package/docs/README.md

@@ -1,4 +1,4 @@
-# lua-cli v3.43.0
+# lua-cli v3.46.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.
 

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/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.46.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",

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.46.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();