LuaDecision declares a decision once, on the agent, instead of repeating its questions at every call site. Each lua push stages a new version, and lua version promote makes it current. The dashboard can write a version too. Decisions.run always uses the current version, so you can sharpen a question or raise the confidence floor without touching the code that runs it, and go back to an earlier version if it gets worse.
Verified against lua-cli 3.48.0.
Quick example
defineDecision(config) does the same as new LuaDecision(config).
lua push reads each decision from your source. Write it as new LuaDecision({...}) or defineDecision({...}) with literal questions, and export it under a name. You can list it in decisions through a named import or a namespace import, as in decisions: [shared.triage]. A decision built by a helper function cannot be read, and listing it fails the compile with an error that names the export. Two decisions with the same name in one project fail the compile too, and the error names both files. A workflow can declare a decision in the same module, because Decisions.odds, Decisions.choice and Decisions.score work at module top level. Decisions.ask and Decisions.run do not, and calling them at the top of a workflow module fails the compile.
Anywhere in the agent’s code:
{ type: 'refused' }, so check type before you read its fields. run types choice as a string, not as the option labels, because the current version is read at run time.
Configuration
The name you run it by. Unique per agent. It must match
^[a-zA-Z0-9_-]{1,64}$: 1 to 64 letters, digits, underscores or hyphens.One to 64 questions built with
Decisions.odds, Decisions.choice and Decisions.score, at most 100,000 characters as JSON. Writing a larger definition answers 400.Decisions.ask is accepted too (provider, model, fallback, region, zeroRetention, minConfidence, timeoutMs, cache, logState) and becomes the version’s default. A call can override any of them.
The constructor throws a DecisionError with code decision_invalid when the name breaks the rule above, when there are no questions, or when a question was not built with the builders or has empty instructions. The builders also refuse a malformed question before anything is sent, as listed in Checks before the call.
Methods
Decisions.run(name, state, options?)
state and returns the same DecisionResult as Decisions.ask. options override the version’s defaults for this call only. The result carries decisionName and decisionVersion, and so does every log row and usage row from run.
A name the agent does not have throws a DecisionError with code decision_not_found. So does a decision you pushed but never made current, because its only version is still staged, and a deleted one. Every error from run carries decisionId, so lua logs --type decisions finds the failed call.
Versions
lua pushstages a new version of every declared decision, andlua push decisionpushes decisions only. A staged version is not current, soDecisions.runkeeps answering with the current one.- The first push of a decision writes version 1.0.1, the same as every other versioned primitive.
lua pushfollows the server. If the decision inlua.skill.yamlwas deleted or renamed on the server, the push says so in one line. It then pushes to the active decision with the name in your code, creates one when there is none, and updateslua.skill.yaml.- A staged version goes live with
lua version createthenlua version promote <version>, withlua decisions publish <name> <version>, or withlua push decision --auto-deploy. Each one reaches running code at once, on every server, even one that missed the update message. - Promoting an agent version takes offline every decision that version does not pin.
Decisions.runthrowsdecision_not_foundfor it, and it shows no current version until you promote an agent version that pins it or publish one of its versions again. A decision that was pushed but never made current is not affected. lua version createpins, for each decision, the newest version pushed from code or the current version, whichever is newer. A dashboard draft saved without publishing is never pinned, so a promote cannot put a draft live. A dashboard edit that was published is the current version, and it is pinned when it is newer than your last push.- A rollback made with
lua decisions publish <name> <older version>survives the nextlua version create. That version is pinned, unless you pushed a newer version from code after the publish. Then the newer push is pinned. - The dashboard’s Decisions section edits the questions, options and confidence floor and saves them as a new version. Versions written there are marked as edited in the dashboard, and the next
lua pushwrites a newer one from code. - To roll back, run
lua decisions publish <name> <older version>or promote an older agent version. Nothing is deleted. - Promoting the agent version that is already active changes nothing. To undo a
lua decisions publish, publish another version or promote a different agent version. lua decisions delete <name>turns the decision off at once and keeps its versions.Decisions.runthen throwsdecision_not_foundfor that name.lua decisions versions <name>still lists its versions, and publishing one of them, for example withlua decisions publish, turns it back on.- A deleted decision takes no new versions. Writing one answers 409 with code
decision_inactive. - Creating or renaming a decision answers 409 when another active decision on the agent already uses the name. Writing a version number that already exists for the decision answers 409 too. So does publishing a deleted decision whose name another decision has taken since.
lua version statusshows a row for each decision with the version in your project, the version live on the server, and the version the active agent version pins. When the live version differs from the pinned one, or the decision was deleted, the row names it, for examplelive 1.5.0, agent version pins 2.0.7.lua logs --type decisionsshows every run with the version that answered and the execution that made the call.lua logs --execution-idand--run-idfind those rows.
The lua decisions command
lua decisions lists, tries and rolls back the decisions on the agent.
run takes --state '<json>' in place of --message, and --provider, --model and --min-confidence override the version for that run. --model liquid/d1 runs it on that model; see the model list. --json prints machine-readable output for list, versions and run. In CI, delete needs --force. A decision that fails under lua test --json reports the same code and decisionId, with the same exit codes as lua decisions run.
Each action has aliases: ls and view for list, history and list-versions for versions, rollback and deploy for publish, try and test for run, and rm, remove and del for delete.
Related
Decisionsfor one-off questions and the question types.

