Decisions.ask sends some state and one or more typed questions to a decision model and returns typed answers with probabilities. It never returns free text, so there is nothing to parse. Jev answers by default. OpenAI answers when the call carries images, asks for EU processing or zero retention, or when Jev is down. Any other decision model can be chosen by its id. Available in tools, jobs, webhooks, triggers, processors and workflow code steps.
Verified against lua-cli 3.48.0.
Quick example
{ type: 'refused' }, so check type before you read its fields.
A single question returns its answer directly instead of a map.
Question types
Each question type is named after the field its answer carries.options is an object of label to description, and the answer’s choice is typed to those labels. levels is an ordered list from low to high, either strings or { label, description }. score is a position along the levels and can fall between two of them; level is the nearest one. probabilities holds one entry per option or level and they sum to 1.
Any answer can also be { type: 'refused' } when the provider declines to judge the content. Only OpenAI returns refused. Jev never does, but a call reaches OpenAI through images, region, zeroRetention or a fallback, so handle it on every call.
Methods
ask(request)
What the questions are about. Use an object with descriptive keys for anything beyond one piece of text, and refer to the keys in the instructions. An empty state (
"", a blank string, [] or {}) fails with decision_invalid and is never sent or billed.One to 64 questions built with
Decisions.odds, Decisions.choice and Decisions.score, at most 100,000 characters as JSON. The answer keys match the question keys. A question name is at most 64 characters, and any name works, including constructor or toString.Up to 4 base64 images (
image/png, image/jpeg, image/webp, image/gif), 5 MB each and 6 MB in total per call. Over the total, the call fails with decision_invalid and the message names the total. On auto, images route the call to OpenAI. A model chosen by id is sent the images too; a model its vendor lists as text-only may read or ignore them.auto picks Jev unless the call carries images, sets region: 'eu' or sets zeroRetention. When provider is not set, a model picks its own provider and counts as a pin: model: 'gpt-6-luna' runs on OpenAI, and model: 'liquid/d1' runs on OpenRouter. A pinned provider is never switched silently. It also overrides the image, region and zero-retention rules: provider: 'jev' with images fails with decision_rejected, and provider: 'jev' with region: 'eu' runs on Jev. Jev takes about 32,000 tokens of input. On auto, a larger state falls back to OpenAI and is charged at OpenAI’s price. Pinned to Jev, it fails with decision_rejected and Jev’s own message. openrouter needs a model; see Other decision models.A model of the chosen provider:
jev-latest or jev-preview on Jev, gpt-6-luna on OpenAI, or a vendor/model id such as liquid/d1 on OpenRouter. Defaults to the provider’s current model. Without provider, the model chooses the provider. With a pinned provider, a model of another provider fails with decision_invalid. A model of no provider fails with decision_invalid too. A model the provider does not know, such as an unknown OpenAI model, fails with decision_rejected (422), not as an outage. After a fallback, the other provider uses its own default model.The provider to try once when the first one times out or is unavailable. It defaults to the other provider, and to none when
provider is pinned. none keeps the call on one provider. Calls with images, region: 'eu' or zeroRetention never fall back to Jev. Only Jev or OpenAI can be a fallback; a call on a model chosen by id falls back to the one you name here.Choice and score answers below this confidence come back with
uncertain: true so your code can escalate instead of acting.The budget for the whole call, in milliseconds. When the first provider fails and a fallback runs, the fallback gets the time that is left. With under 100 ms left, there is no fallback. A value outside 100 to 15000 is clamped to that range, not rejected. A short timeout on your call does not affect other calls.
Caches identical calls per agent for up to a day. A longer
ttlSeconds is capped at 86400. A cache hit costs nothing, carries cached: true and reports usage.inputTokens: 0. Identical cacheable calls made at the same time share one provider call across the whole platform, and the calls that joined it come back with cached: true. A call that waits longer than its own timeoutMs for that answer fails with decision_timeout.How much of
state the log row keeps. summary records its size and top-level keys. full records the first 8,000 characters of the state as sent, with no redaction, and sets truncated when the state was longer. none records nothing.DecisionResult.
ask(state, question, options?)
options takes every field above except state, questions and images, and the promise resolves to that one answer.
odds(instructions, criteria?)
criteria spells out what counts as yes and what counts as no when the instruction alone is ambiguous.
choice(instructions, options)
score(instructions, levels)
Checks before the call
The builders check each question before anything is sent.Decisions.odds, Decisions.choice and Decisions.score throw decision_invalid for empty instructions, instructions over 4,000 characters, fewer than 2 or more than 64 options, fewer than 2 or more than 10 levels, or criteria that is not an object. An option label is at most 64 characters.
At module top level
Decisions.odds, Decisions.choice and Decisions.score only build a question, so they work at module top level. That includes a workflow module, which can declare a LuaDecision beside the workflow. Decisions.ask and Decisions.run call a provider and do not work at top level. In a workflow module, calling them there fails the compile.
Examples
Route a message before the agent sees it
lua test preprocessor reports proceed with a warning, the same as live. To block the message when the decision fails, return { action: 'block', response } from the catch yourself.
Gate a webhook on a yes-or-no
Judge an image
damaged.type === 'refused' too.
Errors
Decisions.ask and Decisions.run throw a DecisionError with these fields.
message starts with the code, as in decision_timeout: openai did not answer in time. The text a model or a log shows carries the code.
These codes are the same in deployed code, under
lua test and through the HTTP API. A timeout, an outage or a disabled provider arrives with its own code, message and provider everywhere. lua test --json reports the code and decisionId, with the same exit codes as lua decisions run.
A webhook whose Decisions.ask or Decisions.run throws, and does not catch it, answers with the HTTP status of the code above instead of a 500. The body is { code, message, decisionId }.
When a cacheable call shares its provider call with identical calls, a caller that goes away stops waiting with decision_cancelled, and the shared call goes on for the others.
Other decision models, through OpenRouter
Beyond Jev and OpenAI, you can run a decision on any of the models below by settingmodel to its id. These models are served through OpenRouter, so the result reports provider: 'openrouter'.
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:
* Median response time in Lua’s internal benchmarks, October 2026. Jev answers in about 230 ms on the same calls.
scaledown/classify-1 takes one image, png or jpeg, as the document it reads with the text. A second image, or another format, fails with decision_rejected before the call is made.
Not available, because they retain request data: openai/gpt-6-luna-decisions (use provider: 'openai' instead), 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.
Limits and cost
A decision costs 0.005 actions when Jev answers and 0.01 actions when OpenAI or a model on OpenRouter answers. A call that falls back is charged once, at the price of the provider that answered. Cached hits, failed calls and cancelled calls cost nothing. Usage rows for decisions are written durably, so a charged call is never missing from usage.
Every call writes one row to the agent’s logs under the
decisions source, visible with lua logs --type decisions. The row carries the provider, the routing rule, every answer with its probabilities, the tokens, costUsd and any fallback. costUsd is the provider’s token-based cost estimate, not what you are charged. A failed call’s row records the model and the questions that were requested. A row leaves out runId when the call has none.
The row also names the execution that made the call: the channel of the turn, the execution id, the primitive and, for a tool, the tool name. A workflow code step’s row names the workflow and the step. lua logs --execution-id <id> and lua logs --run-id <id> find decision rows. Calls made by lua test are logged with channel lua-test and the primitive under test, so you can tell them apart from real traffic. They are still billed.
Related
LuaDecisiondeclares a named, versioned decision on the agent and runs it withDecisions.run.AIfor free-text generation.

