Skip to main content
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

Every answer can also be { 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)

string | string[] | object
required
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.
Record<string, DecisionQuestion>
required
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.
{ data: string, mimeType: string }[]
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' | 'jev' | 'openai' | 'openrouter'
default:"auto"
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.
string
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.
'jev' | 'openai' | 'none'
default:"the other provider"
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.
'eu'
Routes the call to OpenAI’s EU endpoint.
boolean
default:"false"
Routes the call to OpenAI. No retention setting is sent with the call.
number
default:"0.7"
Choice and score answers below this confidence come back with uncertain: true so your code can escalate instead of acting.
number
default:"3000"
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.
{ ttlSeconds: number }
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.
'summary' | 'full' | 'none'
default:"summary"
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.
Returns a DecisionResult.

ask(state, question, options?)

The single-question form. 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)

Two to 64 options. Each key is a label the answer can return and each value describes when it applies.

score(instructions, levels)

Two to 10 levels, ordered from low to high.

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

A pre-processor that throws lets the message through, and 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

OpenAI can refuse to judge an image, so handle 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 setting model to its id. These models are served through OpenRouter, so the result reports provider: 'openrouter'.
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: * 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.
  • LuaDecision declares a named, versioned decision on the agent and runs it with Decisions.run.
  • AI for free-text generation.