lua-cli 3.44.0 → 3.46.0

package/docs/API_REFERENCE.md

@@ -717,7 +717,7 @@ if (Lua.request.webhook) {
 
 **Properties:**
 
-- `Lua.request.channel` - Channel type (`'whatsapp'`, `'web'`, `'api'`)
+- `Lua.request.channel` - Channel type (`'whatsapp'`, `'pop'` for the embeddable chat widget, `'phone'` for voice, `'web'` for the Lua web workspace (not the widget), `'api'`, and others; unrecognised channels arrive as plain strings)
 - `Lua.request.webhook` - Webhook info (if running in webhook)
 - `Lua.request.agentId` - The agent handling this turn
 - `Lua.request.orgId` - The agent's organization, on deployed runtimes that know it (absent offline in `lua test`

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

@@ -40,7 +40,7 @@ Supervision lets one agent observe, preview or release another agent in the same
 
 | Action            | Allows                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observe`         | `logs` (without message bodies), `runs`, `data` (only the collections named on the grant), `versions.list/get/diff`, `persona.versions`, `source`, `env.keys`, `workflows.get`                                                                                                                                                                                                                                                                                                          |
+| `observe`         | `logs` (without message bodies), `runs`, `data` (only the collections named on the grant), `versions.list/get/diff`, `persona.versions`, `source`, `env.keys`, `workflows.get`, `deployed`                                                                                                                                                                                                                                                                                              |
 | `observe-content` | Log message bodies in `logs`                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `preview`         | `versions.preview`: chat a staged version                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `release`         | `versions.promote`, `persona.activate`, `versions.delete` (a `superseded` version only), `workflows.create` (an inert, inactive workflow with no human author, so it cannot carry a schedule), `workflows.push` (a new, never-activated version of an existing workflow) and `workflows.deploy`. Promote, activate and deploy always need `expectActive`. Every release op runs only from a live workflow step of the supervisor whose workflow the grant names (`releaseWorkflowIds`). |
@@ -55,6 +55,10 @@ const errors = await Agents.logs('base_agent-tp', { level: 'error', limit: 20 })
 const runs = await Agents.runs('base_agent-tp').list({ status: 'failed' });
 const state = await Agents.data('base_agent-tp').get('pilot_state', 'config'); // collection named on the grant
 const keys = await Agents.env('base_agent-tp').keys(); // names only, never values
+// What it serves right now, even with no promoted agent version (activeAgentVersion: null): live skills and tools,
+// the published persona and processors, each with the version id an agent version snapshot would pin, and the
+// live model (live.model; compare with a version's snapshot.model, since a promote applies it).
+const live = await Agents.deployed('base_agent-tp');
 
 const versions = await Agents.versions('base_agent-tp').list();
 const diff = await Agents.versions('base_agent-tp').diff(7, 8);
@@ -71,12 +75,16 @@ await Agents.workflows('base_agent-tp').push('wf_123', definition); // the body
 // A workflow the target does not have yet: create it (inert), push, then deploy with expectActive: null.
 // const { workflowId } = await Agents.workflows('base_agent-tp').create('nightly-digest');
 await Agents.workflows('base_agent-tp').deploy('wf_123', '1.4.0', { expectActive: wf.activeVersionId });
+// Optionally name the source commit the version was built from: deploy(wf, v, { expectActive, commitHash? })
 
 // Clean up: only a superseded version can be deleted.
 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.
 
 ### Platform switches
 
@@ -88,13 +96,14 @@ await Agents.versions('base_agent-tp').delete(5);
 
 ### What a supervisor can and cannot see
 
-| Surface | What is returned                                                                                                                                                                                                            |
-| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Logs    | Timestamp, level, log source and primitive or tool name. No user ids. The window is at most 7 days and at most 100 rows. The message (truncated to 2,000 characters) is included only with `observe-content`.               |
-| Runs    | Metadata only: id, workflow, status, reason, trigger and times. No inputs or outputs.                                                                                                                                       |
-| Data    | Read-only. Only the collections the org admin named on the grant (`dataCollections`).                                                                                                                                       |
-| Env     | Variable names only.                                                                                                                                                                                                        |
-| Source  | The files in the target's source backup, each up to 512 KB. Backup exclusions and credential-like paths are never listed or returned: dotfiles, `.env*`, `*.pem`, `*.key`, `id_rsa*`, `.npmrc`, `credentials*`, `*secret*`. |
+| Surface  | What is returned                                                                                                                                                                                                            |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Logs     | Timestamp, level, log source and primitive or tool name. No user ids. The window is at most 7 days and at most 100 rows. The message (truncated to 2,000 characters) is included only with `observe-content`.               |
+| Runs     | Metadata only: id, workflow, status, reason, trigger and times. No inputs or outputs.                                                                                                                                       |
+| Data     | Read-only. Only the collections the org admin named on the grant (`dataCollections`).                                                                                                                                       |
+| Env      | Variable names only.                                                                                                                                                                                                        |
+| Deployed | Live skills (tool names, bundle hashes, whether source is attached), the published persona (id, version, content hash) and processors, with version ids. No code, tool source or persona text.                              |
+| Source   | The files in the target's source backup, each up to 512 KB. Backup exclusions and credential-like paths are never listed or returned: dotfiles, `.env*`, `*.pem`, `*.key`, `id_rsa*`, `.npmrc`, `credentials*`, `*secret*`. |
 
 ### Guarantees
 
@@ -108,14 +117,17 @@ 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.
-- **Not available offline:** `Agents.list`, `Agents.get` and `source.get`.
+- **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
 
 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/Baskets.md

@@ -32,10 +32,13 @@ The Baskets API enables:
 enum BasketStatus {
   ACTIVE = 'active',
   CHECKED_OUT = 'checked_out',
-  ABANDONED = 'abandoned'
+  ABANDONED = 'abandoned',
+  EXPIRED = 'expired'
 }
 ```
 
+`Baskets.get(status)` and `basket.updateStatus(status)` reject any other value (including a different letter case) with HTTP 400 `Invalid basket status '<value>'. Allowed: active, checked_out, abandoned, expired`, before anything is read or persisted. A missing basket is HTTP 404 and a failure inside the commerce service is a generic HTTP 500 (503 when it is unreachable). The SDK surfaces each as a thrown `Error`; there is no `success: false` body to branch on.
+
 ## BasketInstance Methods
 
 Once you have a basket instance, you can call these methods:
@@ -112,6 +115,13 @@ Updates the basket's status.
 
 **Returns:** `Promise<Basket>` - Updated basket data
 
+**Errors:**
+- An unknown status is rejected with HTTP 400 `Invalid basket status '<value>'. Allowed: active, checked_out, abandoned, expired`; nothing is persisted.
+- A missing basket is HTTP 404.
+- A failure inside the commerce service is a generic HTTP 500 (503 when the commerce service itself is down or unreachable).
+
+The SDK surfaces each of these as a thrown `Error`; there is no `success: false` body to branch on.
+
 **Example:**
 ```typescript
 await basket.updateStatus(BasketStatus.ABANDONED);

package/docs/api/Workflows.md

@@ -76,7 +76,7 @@ Returns the run summary (status, counts, gate, lineage, `output` when readable).
 
 ### `Workflows.list(opts?)`
 
-`opts`: `{ limit?, status?, workflow?, correlationKey?, tags?, sort? }` — `tags` are AND-ed; `sort` is one of `-createdAt | createdAt | -durationMs | durationMs`.
+`opts`: `{ limit?, status?, workflow?, correlationKey?, tags?, sort? }` — `tags` are AND-ed; `sort` is one of `-createdAt | createdAt | -durationMs | durationMs`. `workflow` is a name or an id; an id (UUID, `wf_…`, `wfc_…`) is queried as-is. Under `lua test` a name that matches no workflow definition returns `[]`, and a failed definition lookup throws a typed `WorkflowApiError`; deployed, the bridge matches runs by recorded name or id. A `workflow` filter never widens to every run in either runtime.
 
 ### `Workflows.cancel(runId, opts?)`
 
@@ -90,6 +90,12 @@ Resumes a step suspended with `ctx.suspend(...)`. The loser of a resume race rec
 
 Delivers a named signal to a run waiting on `waitForSignal(name)`. `opts.dedupeKey` makes a re-send a no-op (`{ accepted: true, duplicate: true }`). Returns `{ accepted, reason?: 'source_not_accepted' | 'duplicate' | 'parked' }`. The waiting step completes with `{ payload, source: { kind, id, principalId? }, signalId, receivedAt }` — read the payload as `stepResults.<id>.payload`.
 
+### `Workflows.raiseBudget(runId, patch)`
+
+Raises the caps of one of the calling agent's runs. `patch` is `{ maxCredits?, maxSteps?, maxJobSeconds?, maxDurationSeconds?, note? }` — at least one cap, increases only, each at or under the org cap. Returns `{ raised: true, budget, runStatus, resumed }`, or the idempotent `{ raised: false, reason: 'already_raised' }` when the same raise was already applied.
+
+Only a run parked on its budget gate, or still queued/running, is raisable; any other state (including a terminal run, or a run past its per-run raise limit) throws `BUDGET_NOT_RAISABLE` (409). Only the run's creator/holder or an org admin may raise it (`NOT_RUN_CREATOR`, 403 — so a call from a job or workflow step with no user fails closed). A run that is not the calling agent's throws `RUN_NOT_FOUND` (404). An over-cap value throws `CAP_EXCEEDED` (400, with `cap`, `value`, `ceiling`); a malformed patch throws `VALIDATION_FAILED` (400). Behaviour is the same under `lua test` and deployed.
+
 #### Reserved payload keys
 
 The run ledger redacts by **key name**, not by value: a payload member whose key is one of
@@ -100,14 +106,16 @@ is persisted as `[REDACTED]` whatever it holds. A key matches when one of those
 
 This is by design (a credential must never land in a run), so the placeholder is what `stepResults.<id>.payload`, the run output, `lua workflows status --steps`, exports and the chat run card show — a workflow cannot read a data field with one of these names back. Name data fields otherwise (`ticketRef`, `handle`, `code`, `verifier`). The same rule applies to every step output and suspend payload. A `waitForSignal` whose `schema` declares a property with a reserved name draws the non-blocking `signal-reserved-key` warning at push / compose (the property, the placeholder it would read as, the rename), and `lua workflows signal` warns before sending a payload that carries a reserved key (the signal is still delivered).
 
-### Reserved members
+### Other members
 
-`startBatch`, `signalByKey`, `raiseBudget`, `setGoal` and `goals.{list,get,pause,resume,close}` are part of the API surface (the member list is frozen) and throw `WorkflowApiError { code: 'WORKFLOWS_API_UNAVAILABLE' }` until their server routes ship. For `startBatch`: from an agent turn, prefer the `startWorkflowRunBatch` tool (one consent card for the whole batch, D23-r5).
+`startBatch`, `signalByKey`, `setGoal` and `goals.{list,get,pause,resume,close}` are part of the API surface (the member list is frozen). For `startBatch`: from an agent turn, prefer the `startWorkflowRunBatch` tool (one consent card for the whole batch, D23-r5).
 
 ## Errors
 
 All failures throw `WorkflowApiError` with `code` (the server discriminator — `RUNS_IN_FLIGHT`, `SUSPENDED_CAP`, `WORKFLOW_NOT_FOUND`, `CONTROL_UNAVAILABLE`, …), `statusCode`, and any extra fields the server returned (for example `blockingRunId`).
 
+- `WORKFLOW_INACTIVE` (409): the workflow was deactivated (`lua workflows deactivate`), so `Workflows.start` by name or by id starts no new run. Runs already going keep going; activate the workflow to start again.
+
 ```typescript
 try {
   await Workflows.start('nightly-sync', {});
@@ -130,7 +138,7 @@ lua test workflow outreach --input @leads.json \
 
 - `--step-output <id>=@file|<json>` completes a step without running it (validated against its `outputSchema`) — this is how a predicate over an agent output gets both truth values under the default `--agents fake`.
 - `--approve <id>[=@payload]` / `--deny <id>[=@reason]` pre-answer approvals; `--signal <name>=<json>` pre-supplies `waitForSignal` payloads in order.
-- `--fixtures <dir>` replays recorded agent/tool outputs (`--record <dir>` writes them); a missing fixture exits **5** — never a silent fake.
+- `--fixtures <dir>` replays recorded fixtures (`--record <dir>` writes each live agent reply — requires `--agents live`; tool steps never run offline, so nothing else is recorded); a missing fixture exits **5** — never a silent fake.
 - `--from-run <runId>` seeds every completed step from a real run and restarts at the first non-completed one.
 - `--ledger-out <file>` writes the in-memory ledger; `lua workflows replay <runId> --local` re-evaluates a real run's predicates and mappings against your compiled artifact and reports `LEDGER_DIVERGENCE`.
 - `--park <id>` simulates a platform-fault park of a `sideEffects:'external'` step (retry / skip / complete / fail, same verbs as production); `--fast-retries` collapses retry backoff to 0; `--real-time` actually waits instead of fast-forwarding the virtual clock; `--artefacts-dir <dir>` backs `ctx.artefacts.*` on disk.

package/docs/workflows/approvals.md

@@ -46,6 +46,8 @@ Offline, `lua workflows run --approve <id>` completes the node with `decidedBy:
 
 `timeoutHours` runs on **business time** when `businessHours: { tz, calendar }` is set. `onTimeout` is a chain: each `{ escalateTo, timeoutHours }` hop re-prompts the next audience; the terminal `'deny'` (or `'cancel-run'`/`'continue'`) completes the node — e.g. `{approved:false, timedOut:true, escalations:2}`.
 
+A numeric `timeoutHours` (on `approval` and `waitForSignal`) must be in 1..720: outside that range `lua compile` and `lua push` refuse it as `timeout-hours-out-of-range`. A `waitForSignal` signal name must match `[a-zA-Z0-9_.-]{1,64}` or it is refused as `signal-name-invalid`. The run's own wall (7 days by default) still caps the live deadline, so a window longer than the run wall is clamped at runtime (the `deadline-clamped` warning).
+
 ## Reminders
 
 `remindAfterHours: 24` re-sends the approval push to the approvers who still have to decide, every 24 hours while the approval is pending: at most **3 reminders** per ask (an escalation hop is a new ask, so its count starts again), and never at or after the deadline. The reminder replaces the earlier notification in place (same collapse key) and reads "Reminder: …". It takes a plain number of hours in `1..720` (no binding); anything else is refused as `remind-after-invalid`, and a value at or above the first deadline pushes with the `remind-after-exceeds-timeout` warning, because it can never fire. The first deadline is the first escalation hop's `timeoutHours` when `onTimeout` starts with a hop, otherwise `timeoutHours` (168 hours when you leave it out). Reminders ride the approval **push**, so they reach the approvers an agent's approval routing names (shared-agent approvers); an approval with no routing gets the inbox row and the channel fallback but no push, and so no reminder. They are sent on the platform's sweep cadence, so a reminder can arrive a few minutes after it is due, and quiet hours and do-not-disturb drop it like any other push.

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.44.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",
@@ -87,7 +87,7 @@
     "dotenv": "^17.2.3",
     "esbuild": "^0.28.1",
     "inquirer": "^12.9.6",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^4.3.2",
     "open": "^10.1.0",
     "posthog-node": "^5.26.0",
     "ts-evaluator": "^2.0.0",

package/template/package.json

@@ -20,7 +20,7 @@
     "inquirer": "^12.9.6",
     "stripe": "^17.5.0",
     "js-yaml": "^4.1.0",
-    "lua-cli": "^3.44.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,264 +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 browser refuses some shell origins as a target outright (a web browser
-   * throws on the desktop app's `tauri://localhost`), so each post stands
-   * alone: one origin this browser cannot address must not stop the others,
-   * or fail the session that posts `lua:ready` when it opens.
-   */
-  private post(message: { type: string; v: number }): void {
-    if (window.parent === window) return;
-    for (const origin of this.hostOrigins()) {
-      try {
-        window.parent.postMessage(message, origin);
-      } catch {
-        // Not addressable from this browser; the shell that framed us has one of the others.
-      }
-    }
-  }
-}
-
-export const lua = new LuaAppClient();