Stateless replay
How the CLI asks a template's questions one at a time by re-running the template script from the top with every answer so far.
The prompt engine never keeps a conversation open. Each step, the CLI sends all answers so far and the deterministic state to the template container. The container runs the template script from the top. The script reads answers from the map; at the first question with no answer it stops and replies with that question. When every question has an answer, the script runs to the end and replies with the final Cyan (the processors and plugins to run).
How it works
The loop (CLI side)
TemplateEngine::start_with (engine.rs:26-95):
- Send
{ answers, deterministic_state }toPOST /api/template/initon the template, through the coordinator's proxy (client.rs:24-36; the URL is{coordinator}/proxy/template/{version id}). - The reply is one of two kinds (
template/output.rs):- question reply: a question, plus the deterministic state the script built so far;
- final reply: the Cyan.
- On a question reply: show the question in the terminal. Before it accepts an answer, the prompt calls
POST /api/template/validatewith the answers so far and the typed value (validate.rs). The template replays to that question and runs its validator. - Store the answer under the question id. Replace the deterministic state with the one from the reply (
engine.rs:74-77). Go to 1. - On a final reply: stop with the outcome complete and the answer map (
engine.rs:84-86).
Going back: an empty answer (Esc) removes the last answer, so the next replay asks it again (engine.rs:66-73). An empty answer on the first question ends the program.
The replay (template side)
The SDK runs the author's script with two helpers (service.ts:16-35):
- a stateless inquirer: each
text,select,confirm, … call looks up its question id in the answer map. Missing id: it throws "out of answers" with the question (stateless_inquirer.ts:15-21). - a stateless determinism helper:
d.get(key, make)returns the stored value forkey, or callsmake()once and stores it (stateless_determinism.ts:6-17).
"Out of answers" becomes a question reply carrying the helper's current state. Reaching the end becomes a final reply. The final reply carries no deterministic state (service.ts:21-24).
Prompt outcomes
TemplateState (states.rs:7-18) is the outcome of one engine run:
| Outcome | Meaning |
|---|---|
QnA | still asking (the loop continues) |
Complete | the Cyan and the final answer map |
NeedInput | headless only: the first question with no supplied answer |
Err | a transport or validation failure |
Worked example
The author's script:
StartTemplateWithLambda(async (i, d) => {const name = await i.text('Project name?', 'name');const docker = await i.confirm('Add Docker?', 'docker');const id = d.get('project-id', () => crypto.randomUUID());if (docker) await i.text('Port?', 'port');return { processors: [/* ... */], plugins: [] };});
| Step | CLI sends (answers) | Script stops at | Reply |
|---|---|---|---|
| 1 | {} | name | question name |
| 2 | name=shop | docker | question docker |
| 3 | name=shop, docker=true | port (after d.get made project-id) | question port, state project-id=7c… |
| 4 | all three, state project-id=7c… | end | final Cyan |
The script ran four times. Its code before each stop ran every time, so it must give the same result for the same answers. d.get is how a random value stays the same across replays.
Rules worth knowing
- A template script must be a pure function of its answers and
d.getvalues. Side effects before a question run once per replay. - A missing answer is "no value" in the map. The inquirer checks
!answers[id](stateless_inquirer.ts:16). - Headless mode does the same walk with supplied answers and stops with
NeedInputat the first gap; the CLI prints it as JSON and exits with code 2 (headless.rs:9,engine.rs:115-260). It starts from an empty deterministic state. - Deterministic state lives only for one run. It is not in the final reply and not in the state file (see three-way merge).
Why this way
- No session in the template. Inferred: a template container can be shared by many users and runs (see proxy routing), and any step can be retried, because each request carries the whole input.
- The same replay serves create, update and headless. Replaying with saved answers is how an update rebuilds the base.