lua-cli 3.49.0 → 3.49.2

package/docs/CLI_REFERENCE.md

@@ -619,7 +619,8 @@ lua decisions [command] [name] [version] [options]
 - `--force` - Skip the confirmation (`publish`, `delete`)
 - `--state <json>` - `run`: the state to decide on
 - `--message <text>` - `run`: sent as `{ message: <text> }`; an empty or blank message is a usage error (exit 2)
-- `--provider <jev|openai|auto>` - `run`: override the version's provider
+- `--provider <jev|openai|openrouter|auto>` - `run`: override the version's provider
+- `--model <id>` - `run`: override the version's model; an OpenRouter id such as `liquid/d1` runs on OpenRouter (see [Decisions](api/Decisions.md#other-decision-models-through-openrouter))
 - `--min-confidence <n>` - `run`: override the version's `minConfidence` (0 to 1)
 
 **Example:**

package/docs/README.md

@@ -1,6 +1,6 @@
-# lua-cli v3.49.0
+# lua-cli v3.49.2
 
-Welcome to the comprehensive API documentation for lua-cli v3.49.0. This guide covers every API, class, and function exported by the package.
+Welcome to the comprehensive API documentation for lua-cli v3.49.2. This guide covers every API, class, and function exported by the package.
 
 ## 📚 Documentation Index
 
@@ -263,7 +263,7 @@ Each API doc includes:
 
 ---
 
-**Version:** 3.49.0
+**Version:** 3.49.2
 **Last Updated:** October 2026
 
 ---

package/docs/api/Decisions.md

@@ -120,13 +120,13 @@ Question names and option labels are at most 64 characters. Any name works, incl
 interface DecisionResult {
   decisionId: string;
   answers: { [questionName: string]: DecisionAnswer };
-  provider: 'jev' | 'openai';
+  provider: 'jev' | 'openai' | 'openrouter';
   model: string;
   rule: 'pinned' | 'images' | 'region' | 'zero_retention' | 'default' | 'fallback';
   usage: { inputTokens: number | null };
   durationMs: number;
   cached: boolean;
-  fallback?: { from: 'jev' | 'openai'; reason: string };
+  fallback?: { from: 'jev' | 'openai' | 'openrouter'; reason: string };
 }
 ```
 
@@ -254,20 +254,56 @@ Under `lua test` and through the HTTP API, `decision_timeout`, `decision_unavail
 
 ## Options
 
-| Option          | Values                          | Default     | Description                                                                                                                               |
-| --------------- | ------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `provider`      | `'auto'`, `'jev'`, `'openai'`   | `'auto'`    | Which provider answers, where `auto` lets the platform pick.                                                                              |
-| `model`         | a model id of that provider     | provider's  | The exact model to use, which must belong to the chosen provider.                                                                         |
-| `fallback`      | `'jev'`, `'openai'`, `'none'`   | other one   | The provider to try when the first one fails, or `none` to never fall back, and a pinned `provider` never falls back unless you set this. |
-| `region`        | `'eu'`                          | none        | Routes the call to OpenAI's EU endpoint.                                                                                                  |
-| `zeroRetention` | `true`, `false`                 | `false`     | Routes the call to OpenAI only, and no retention flag is sent with the request.                                                           |
-| `minConfidence` | 0 to 1                          | `0.7`       | Below this confidence a choice or score answer carries `uncertain: true`.                                                                 |
-| `timeoutMs`     | 100 to 15000                    | `3000`      | How long the whole call may take, fallback included, before it fails with a timeout, and a value outside the range is clamped to it.      |
-| `cache`         | `{ ttlSeconds }`                | none        | Reuses the answer to an identical request for this many seconds.                                                                          |
-| `logState`      | `'summary'`, `'full'`, `'none'` | `'summary'` | How much of the state is kept in the decision log.                                                                                        |
+| Option          | Values                                        | Default     | Description                                                                                                                               |
+| --------------- | --------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`      | `'auto'`, `'jev'`, `'openai'`, `'openrouter'` | `'auto'`    | Which provider answers, where `auto` lets the platform pick between Jev and OpenAI. `openrouter` needs a `model`.                         |
+| `model`         | a model id of that provider                   | provider's  | The exact model to use. `jev-*` runs on Jev, `gpt-*` on OpenAI, and a `vendor/model` id runs on OpenRouter (see below).                   |
+| `fallback`      | `'jev'`, `'openai'`, `'none'`                 | other one   | The provider to try when the first one fails, or `none` to never fall back, and a pinned `provider` never falls back unless you set this. |
+| `region`        | `'eu'`                                        | none        | Routes the call to OpenAI's EU endpoint.                                                                                                  |
+| `zeroRetention` | `true`, `false`                               | `false`     | Routes the call to OpenAI only, and no retention flag is sent with the request.                                                           |
+| `minConfidence` | 0 to 1                                        | `0.7`       | Below this confidence a choice or score answer carries `uncertain: true`.                                                                 |
+| `timeoutMs`     | 100 to 15000                                  | `3000`      | How long the whole call may take, fallback included, before it fails with a timeout, and a value outside the range is clamped to it.      |
+| `cache`         | `{ ttlSeconds }`                              | none        | Reuses the answer to an identical request for this many seconds.                                                                          |
+| `logState`      | `'summary'`, `'full'`, `'none'`               | `'summary'` | How much of the state is kept in the decision log.                                                                                        |
 
 A pinned `provider` overrides the images, `region` and `zeroRetention` rules.
 
+### Other decision models, through OpenRouter
+
+Beyond Jev and OpenAI, you can run a decision on any of the models below by setting `model` to its id. These models are served through OpenRouter, so the result reports `provider: 'openrouter'`.
+
+```typescript
+const r = await Decisions.ask({
+  state: { message: input.text },
+  questions: { refund: Decisions.odds('Is the customer asking for a refund?') },
+  model: 'liquid/d1',
+});
+```
+
+Requests and answers have the same shape for every model, and the result's `model` names the exact model version that answered. `auto` never picks one of these models, and `fallback` cannot name one. A call on one of them falls back to Jev or OpenAI when you set `fallback`. Jev and OpenAI are not reached this way: `typesafe/...` and `openai/...` ids fail with `decision_invalid`, so use `provider: 'jev'` or `'openai'`. Any other `vendor/model` id is accepted locally and checked when the call is made: a misspelt or unknown id fails with `decision_rejected` and the message names it, so check `model` against the list below before you ship.
+
+Available models, October 2026:
+
+| Model id                                | Input        | Context | Typical latency\* | Notes                                                                  |
+| --------------------------------------- | ------------ | ------- | ----------------- | ---------------------------------------------------------------------- |
+| `perplexity/pplx-decider-v1.1-27b`      | text, images | 262k    | 240 ms            | Recommended                                                            |
+| `liquid/d1`                             | text         | 65k     | 270 ms            | Recommended                                                            |
+| `microsoft/microsoft-decision-1`        | text         | 32k     | 280 ms            | Recommended                                                            |
+| `cloudflare/clef-flash`                 | text, images | 65k     | 330 ms            | Recommended                                                            |
+| `inception/mercury-decide`              | text         | 65k     | 340 ms            | Recommended                                                            |
+| `togethercomputer/tev1-4b-experimental` | text         | 32k     | 270 ms            | Recommended. At most 20 options per question and 32 questions per call |
+| `cloudflare/clef`                       | text, images | 65k     | 360 ms            | Recommended                                                            |
+| `upstage/solar-decide-flash`            | text         | 524k    | 1 s               | At most 26 options per question                                        |
+| `upstage/solar-decide`                  | text         | 524k    | 1 to 7 s          | At most 26 options per question. Often slower than the default timeout |
+| `jaredpalmer/kev-4b`                    | text         | 8k      | 1.6 s             |                                                                        |
+| `nace-ai/drex-v1.5`                     | text         | 131k    | 480 ms            |                                                                        |
+
+\* Median response time in Lua's internal benchmarks, October 2026. Jev answers in about 230 ms on the same calls.
+
+Not available, because they keep request data and Lua only runs decisions on models that do not: `openai/gpt-6-luna-decisions` (use `provider: 'openai'`), `cloudflare/clef-omni`, `respan/span-01`, `respan/span-01-lite`, `inception/mercury-decide:free`. A model's own limit, such as too many options, fails with `decision_rejected` and the model's message.
+
+The Input column is what each vendor lists. Images are sent to every model, and a model listed as text-only may still read them or may ignore them, so pick a model that lists images when an answer depends on one.
+
 ## Related APIs
 
 - [LuaDecision](./LuaDecision.md) declares a named, versioned decision that `Decisions.run` runs.

package/docs/api/LuaDecision.md

@@ -24,7 +24,7 @@ type LuaDecisionConfig = {
   name: string;
   description?: string;
   questions: Record<string, OddsQuestion | ChoiceQuestion | ScoreQuestion>;
-  provider?: 'auto' | 'jev' | 'openai';
+  provider?: 'auto' | 'jev' | 'openai' | 'openrouter';
   model?: string;
   fallback?: 'jev' | 'openai' | 'none';
   region?: 'eu';
@@ -89,7 +89,7 @@ The compiler reads each decision from its source, so write it as `new LuaDecisio
 
 `lua push` stages a new version of every decision listed in `decisions`; it does not change what `Decisions.run` asks. `lua push decision --name triage` stages one decision. A staged version becomes current only through `lua version promote` or `lua decisions publish`. Until a decision has a current version, `Decisions.run` throws `decision_not_found` for it.
 
-A staged version goes live with the agent version that includes it: run `lua version create`, then `lua version promote <version>`. Promoting an older agent version brings back the decision versions it included, which is how you roll back a pushed decision.
+A staged version goes live with the agent version that includes it: run `lua version create`, then `lua version promote <version>`. Promoting an older agent version brings back the decision versions it included, which is how you roll back a pushed decision. A decision that the promoted agent version does not include stops answering (`decision_not_found`) and keeps its versions, and promoting an agent version that includes it makes it current again.
 
 A version saved from the dashboard goes live when you publish it, and publishing an older version there rolls back too.
 
@@ -99,11 +99,11 @@ Each lua-core pod caches the current version. A promote, a publish, a rename or
 
 `lua decisions` lists the named decisions on the agent with their current version. `lua decisions versions triage` shows each version newest first, with its questions, provider and `minConfidence`.
 
-`lua decisions run triage --message 'I want a refund'` runs the current version and prints one line per answer, then the provider, rule, model, duration, tokens and fallback. Pass `--state '<json>'` to decide on structured state instead, and `--provider` or `--min-confidence` to override the version's options for that run.
+`lua decisions run triage --message 'I want a refund'` runs the current version and prints one line per answer, then the provider, rule, model, duration, tokens and fallback. Pass `--state '<json>'` to decide on structured state instead, and `--provider`, `--model` or `--min-confidence` to override the version's options for that run. `--model liquid/d1` runs it on that model; see the model list in [Decisions](Decisions.md#other-decision-models-through-openrouter).
 
 The first push of a decision writes 1.0.1, as for every versioned primitive: a push bumps the version in `lua.skill.yaml` (1.0.0 for a new entry) before it writes.
 
-`lua decisions publish triage 1.0.1` makes 1.0.1 the current version straight away, which is the quickest rollback. Promoting a different agent version sets it back to what that version pins; promoting the agent version that is already active changes nothing.
+`lua decisions publish triage 1.0.1` makes 1.0.1 the current version straight away, which is the quickest rollback. The next `lua version create` keeps 1.0.1 unless you push a newer version of the decision after publishing. Promoting a different agent version sets it back to what that version pins; promoting the agent version that is already active changes nothing.
 
 `lua decisions delete triage` deactivates the decision after asking and keeps its versions. From then on `Decisions.run('triage', ...)` throws `decision_not_found`. `lua decisions versions triage` still lists its versions, and publishing one of them turns it back on.
 

package/docs/api/LuaWorkflow.md

@@ -48,7 +48,23 @@ A typed code step. `inputSchema` / `outputSchema` / `resumeSchema` are zod schem
 
 `createWorkflow(cfg)` opens a fluent builder; `.commit()` freezes it into the compiled graph. `defineWorkflow(cfg, (wf) => …)` is sugar for the same thing.
 
-Config: `name`, `description?`, `inputSchema`, `outputSchema?`, `budget?` (`maxCredits`, `maxDurationSeconds`, `maxJobSeconds?`), `schedule?` (`{ type:'cron', expression, timezone }`), `scheduleInput?`, `concurrencyPolicy?` (`'allow'|'forbid'`), `concurrencyKey?` (`'correlationKey'`, requires `concurrencyPolicy:'forbid'`), `workspace?`, `outputVisibility?` (see [Output visibility](../workflows/output-visibility.md)), `env.template()` overlays (see [Env overlays](../workflows/env-overlays.md)).
+Config: `name`, `description?`, `inputSchema`, `outputSchema?`, `budget?` (`maxCredits`, `maxDurationSeconds`, `maxJobSeconds?`), `schedule?` (`{ type:'cron', expression, timezone }`), `scheduleInput?`, `concurrencyPolicy?` (`'allow'|'forbid'`), `concurrencyKey?` (`'correlationKey'`, requires `concurrencyPolicy:'forbid'`, see [Concurrency](#concurrency)), `workspace?`, `outputVisibility?` (see [Output visibility](../workflows/output-visibility.md)), `env.template()` overlays (see [Env overlays](../workflows/env-overlays.md)).
+
+### Concurrency
+
+`concurrencyPolicy: 'forbid'` alone is workflow-wide: one in-flight run blocks every other start of that workflow. `concurrencyKey: 'correlationKey'` narrows the guard to runs that share a `correlationKey`:
+
+- A start is refused only while a **non-terminal** run of the same workflow carries the **same** `correlationKey`. Starts with different keys run in parallel.
+- Starts with **no** `correlationKey` share one null bucket: a second keyless start is refused while a keyless run is in flight. A keyless start and a keyed start never block each other.
+- `concurrencyKey` requires `concurrencyPolicy: 'forbid'`; otherwise the push is a 400 `VALIDATION_FAILED` (`concurrency-key-requires-forbid`).
+
+The refusal is a 409 `RUNS_IN_FLIGHT` whose body carries `blockingRunId`, `blockingStatus`, `concurrencyKey` and the colliding `correlationKey` (absent for the null bucket). `lua workflows start` prints it:
+
+```
+❌ "outreach" has concurrencyPolicy:'forbid' and run `wfr_0` is in flight for correlationKey "release-agent-42" — wait for it or cancel it: lua workflows cancel wfr_0
+```
+
+For the null bucket it says the in-flight run was started without a `correlationKey` and that `--correlation-key <key>` starts in parallel. A 409 with no key fields (workflow-wide `forbid`) prints the message without the key part. `--json` always carries the full error body. See [Workflows](./Workflows.md#concurrency-per-correlation-key).
 
 ### Builder verbs and the placement rule
 

package/docs/api/Workflows.md

@@ -14,7 +14,7 @@ Inside a sandbox (tools, jobs, webhooks, workflow code steps) `Workflows` is als
 
 - `start` **never awaits execution** — it returns `{ runId, status }` immediately. `waitSeconds` (≤ 55) asks the server to hold the response for early terminal state; it changes the response, never the execution model.
 - Runs are idempotent on `idempotencyKey` — re-sending the same key returns the existing run instead of a duplicate.
-- A workflow with `concurrencyPolicy: 'forbid'` refuses a second start while one is in flight with a thrown `WorkflowApiError { code: 'RUNS_IN_FLIGHT', blockingRunId }` — never a 429, never a gate.
+- A workflow with `concurrencyPolicy: 'forbid'` refuses a second start while one is in flight with a thrown `WorkflowApiError { code: 'RUNS_IN_FLIGHT', blockingRunId }` — never a 429, never a gate. A per-key refusal also carries `concurrencyKey` and the colliding `correlationKey`, and `lua workflows start` prints that key (see [Concurrency](./LuaWorkflow.md#concurrency)).
 - `status: 'gated'` means the run is parked (quota, billing or consent) and holds no slot. A **consent** gate is cleared by a person resolving its approval — from the desktop, or through the approvals API / inbox. `lua workflows approve` cannot clear one: it requires an `--approval wfa_…` id, which belongs to a workflow `approval` node, and a consent gate has no such id. `lua workflows status <runId>` reports a gated run, and exits 6 under `--strict`.
 - `nameOrId` resolves the workflow **name on the calling agent first**, then a workflow id.
 - `get` / `list` honour output visibility: a restricted run comes back with `restricted: true` and no `output` — never an error.
@@ -30,6 +30,7 @@ Inside a sandbox (tools, jobs, webhooks, workflow code steps) `Workflows` is als
 - Without `concurrencyKey` nothing changes: the guard stays workflow-wide.
 - `concurrencyKey` requires `concurrencyPolicy: 'forbid'`; otherwise `lua compile` / `lua push` fail with `concurrency-key-requires-forbid`, and a push that reaches the server is a 400 `VALIDATION_FAILED` (`concurrency-key-requires-forbid`). Any value other than `'correlationKey'` also fails the compile.
 - The refusal is a 409 `RUNS_IN_FLIGHT` whose body carries `blockingRunId`, `blockingStatus`, `concurrencyKey` and the colliding `correlationKey` (absent for the null bucket).
+- `lua workflows start` names the colliding `correlationKey` in its error line (and says so when the in-flight run is the keyless one); the body is unchanged under `--json`.
 - A scheduled fire that collides on its rendered `correlationKeyTemplate` key records `skipped_overlap`; a fire with a different key dispatches.
 
 ## Methods

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.49.0",
+  "version": "3.49.2",
   "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",
@@ -115,9 +115,9 @@
     "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
     "@lua/sandbox-runtime": "0.0.1",
+    "@lua/shared-sandbox": "0.0.1",
     "@lua/shared-source-sync": "0.0.1",
     "@lua/shared-types": "0.0.1",
-    "@lua/shared-sandbox": "0.0.1",
     "@lua/workflow-graph": "0.0.1"
   },
   "scripts": {

package/template/package.json

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