lua-cli 3.44.0 → 3.45.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/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,14 @@ 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);
 ```
 
 - 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 +94,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
 
@@ -109,7 +116,7 @@ await Agents.versions('base_agent-tp').delete(5);
 
 - **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`.
+- **Not available offline:** `Agents.list`, `Agents.get`, `source.get` and `Agents.deployed` (`supervision_offline_unsupported`).
 
 ### Errors
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.44.0",
+  "version": "3.45.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.45.0",
     "openai": "^5.23.0",
     "uuid": "^13.0.0",
     "zod": "^3.24.1"

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

@@ -244,18 +244,23 @@ class LuaAppClient {
   /**
    * 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.
+   *
+   * 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;
-    for (const origin of this.hostOrigins()) {
+    const targets = new Set(this.hostOrigins().map((origin) => (/^https?:\/\//i.test(origin) ? origin : '*')));
+    for (const target of targets) {
       try {
-        window.parent.postMessage(message, origin);
+        window.parent.postMessage(message, target);
       } catch {
-        // Not addressable from this browser; the shell that framed us has one of the others.
+        // An origin this browser will not target: skip it, keep the rest.
       }
     }
   }