Stateless replay
How the CLI asks a template's questions - the script reruns from the top on every call with every answer so far; a 3-question script runs 4 times.
The problem. The template's script is ordinary linear code (ask name, ask port, …) but it runs in a shared container on a server, and the person answering is at a terminal elsewhere. The server cannot pause the script mid-function and wait, for minutes, on an HTTP request.
The idea. Never pause: rerun. Each call sends every answer so far; the script runs from the top, reads answers by id, and stops by throwing at the first question it has no answer for. The CLI asks that question and calls again with one more answer. With N questions the script runs N+1 times.
The loop below is the whole algorithm: CLI on the left, template on the right.
flowchart TD
S["CLI: answers = saved + preset + carried<br/>state = spec's map"] --> I["init call: all answers, state"]
I --> R["SDK: new inquirer(answers), new determinism(state)<br/>run the author's script from the top"]
R --> Q{"script asks an id<br/>not in answers?"}
Q -->|yes| X["checkpoint exception<br/>→ question reply + state"]
Q -->|no, script returns| F["final reply: Cyan"]
Q -->|other exception| ERR["no usable reply → Err"]
X --> P["CLI: prompt (validate calls<br/>for text, password, date)"]
P -->|answer| U["answers[id] = value<br/>state = reply's state"]
P -->|Esc| K["skip: remove current id<br/>(empty map: exit 0)"]
U --> I
K --> I
F --> C["Complete(Cyan, answers)"]How it works
CLI side (TemplateEngine::start_with):
- Start from the answers the caller passes (saved answers, preset answers, answers carried from earlier nodes) and the caller's deterministic state.
- Send both in an init call to
/proxy/template/<version id>/api/template/init(question protocol). - On a question reply: remember its id, build the prompt, and for text, password and date attach a validator that makes a validate call with the answers and state as they were before this reply.
- Show the prompt. An answer is stored under the id and the state is replaced by the reply's state. Esc is a skip. A prompt or mapping error ends the loop with Err.
- Go to 2.
- On a final reply: end with
Complete(Cyan, answers). The state is dropped.
Template side (the template service of each SDK, per request):
- Map the request; build a new
StatelessInquirerover the answers and a newStatelessDeterminismover the state map. - Call the author's function from its first line.
- Each
i.text,i.select, … looks up its question id. Present: return the value (wrong type: ordinary error). Absent: throwOutOfAnswerExceptionholding the question, the checkpoint exception. - Catch it and reply
questionnairewith the question and the determinism helper's map. - If the function returns, reply
finalwith its Cyan. - Any other exception is not caught by the service.
Cost. A script with N questions takes N+1 init calls. Each typed attempt at a text, password or date question adds one validate call, which is one more full replay. Everything the script does before a question runs again on every call.
Here is the real code, CLI loop first, then the SDK side in all three languages.
- lines 35-47The loop: every init call carries the whole answer map and the current state.
cyanprompt/src/domain/services/template/engine.rs:35-47rust let mut answers: HashMap<String, Answer> = initial_answers.unwrap_or_default();let mut state_data: HashMap<String, String> = initial_states.clone().unwrap_or_default();let mut last_question_id: Option<String> = None;while state.cont() {let input = TemplateAnswerInput {answers: answers.clone(),deterministic_state: state_data.clone(),};let result = self.client.prompt_template(input).and_then(|resp| match resp { - lines 48-62Question reply: remember the id, map it to a prompt, attach a validator built with the pre-question maps, prompt.
cyanprompt/src/domain/services/template/engine.rs:48-62rust TemplateOutput::QnA(q) => {// Get ID from the Question struct using pattern matchinglet question_id = &q.question.id();last_question_id = Some(question_id.clone());let ans = prompt_mapper(&q.question).map(|p| {add_template_validator(p,Rc::clone(&self.client),answers.clone(),state_data.clone(),)}).and_then(|p| prompt(p)) - lines 64-78Esc removes the current id (or exits on an empty map); an answer is stored and the reply's state taken.
cyanprompt/src/domain/services/template/engine.rs:64-78rust .map(|x| match x {// if skippedNone => {if answers.is_empty() {println!("User aborted! Exiting...");exit(0)} else if let Some(last_id) = &last_question_id {answers.remove(last_id);}}Some(val) => {answers.insert(question_id.clone(), val);state_data = q.deterministic_state;}}); - lines 84-93Final reply → Complete with the answers; any error → Err with its text.
cyanprompt/src/domain/services/template/engine.rs:84-93rust TemplateOutput::Final(c) => {Ok(TemplateState::Complete(c.cyan, answers.clone()))}});state = match result {Ok(ok) => ok,Err(err) => TemplateState::Err(err.to_string()),};} - sulfone.helium/sdks/node/src/domain/template/service.ts:16-35Node: fresh helpers per request; OutOfAnswerException becomes the question reply; return becomes the final reply.
sdks/node/src/domain/template/service.ts:16-35rust async template(answer: TemplateInput): Promise<TemplateOutput> {const i = new StatelessInquirer(answer.answers);const d = new StatelessDeterminism(answer.deterministicState);try {const r = await this._template.template(i, d);return {data: r,} satisfies TemplateFinalOutput;} catch (e) {if (e instanceof OutOfAnswerException) {const q: Question = e.question;return {deterministicState: d.states,question: q,} satisfies TemplateQnAOutput;}throw e;}} - sulfone.helium/sdks/node/src/domain/service/stateless_inquirer.ts:15-21The checkpoint: an absent id throws with the question.
sdks/node/src/domain/service/stateless_inquirer.ts:15-21rust private getAnswer(q: Question): Answer {if (!this.#answers[q.id]) {throw new OutOfAnswerException('', q);}return this.#answers[q.id];} - sulfone.helium/sdks/python/cyanprintsdk/domain/template/service.py:20-31Python: the same shape.
sdks/python/cyanprintsdk/domain/template/service.py:20-31rust async def template(self, answer: TemplateInput) -> TemplateOutput:i = StatelessInquirer(answer.answers)d = StatelessDeterminism(answer.deterministic_state)try:r = await self._template.template(i, d)return TemplateFinalOutput(data=r)except OutOfAnswerException as e:q: Question = e.questionreturn TemplateQnAOutput(deterministic_state=d.states, question=q)except Exception as e:raise e - sulfone.helium/sdks/dotnet/sulfone-helium/Domain/Template/Service.cs:8-21.NET: the same shape.
sdks/dotnet/sulfone-helium/Domain/Template/Service.cs:8-21rust public async Task<ITemplateOutput> Template(TemplateInput answer){var i = new StatelessInquirer(answer.Answers);var d = new StatelessDeterminism(answer.DeterministicState);try{var r = await template.Template(i, d);return new TemplateFinalOutput(r);}catch (OutOfAnswerException e){return new TemplateQnAOutput(d.States, e.Question);}}
Worked example: web:5's three questions
web:5's script, as its author wrote it (Node SDK):
StartTemplateWithLambda(async (i, d) => {const instanceId = d.get('instance-id', () => crypto.randomUUID());const name = await i.text('Project name?', 'name');const port = await i.text({ type: QuestionType.Text, id: 'port', message: 'Port?',desc: 'Port the dev server listens on', default: '3000',validate: v => (Number(v) >= 1024 && Number(v) <= 65535 ? null : 'Use a port from 1024 to 65535') });const features = await i.checkbox('Features?', ['docker', 'storybook'], 'features');return { processors: [/* atomi/shop-render:1 with { name, port, instanceId } */],plugins: [/* atomi/shop-format:1 */] };});
In step 1 of the shop example, web:5 is the last of four nodes, so its answer map starts with node_version: 22 (from docker:7) and module_type: esm (node-base:3's preset). Step through the four runs of the script.
- Run 1
d.get has no value and makes A. i.text('name') has no answer: it throws.
answers sent node_version, module_typestate sent {}lines run d.get → A, name?reply question name, state {instance-id: A} - User types shop
One validate call replays to name with the old state {}, so it makes a throw-away value; name has no validator: valid. The answer is stored and the CLI takes the reply's state.
answers + name=shopstate {instance-id: A} - Run 2
d.get returns A. name is answered. i.text('port') has no answer: it throws.
answers sent node_version, module_type, namestate sent {instance-id: A}lines run d.get → A, name ✓, port?reply question port, state {instance-id: A} - User types 80, then 3000
Two validate calls, two more replays, both with A. 80 is refused, 3000 is accepted.
answers + port=3000state {instance-id: A} - Run 3
d.get returns A. i.checkbox('features') has no answer: it throws. No validate call for a checkbox.
answers sent … + portstate sent {instance-id: A}lines run d.get → A, name ✓, port ✓, features?reply question features - Run 4
Every question is answered; the script returns its Cyan with instanceId A.
answers sent … + features=[docker]state sent {instance-id: A}lines run allreply final, Cyan only - Totals
Four init calls and three validate calls: the first line of the script ran seven times. The outcome is Complete with five answers.
init calls 4validate calls 3outcome Complete
Why it is built this way
Hard cases
- The script must be repeatable. Anything before a question runs on every call. A question whose options, default or order depend on the clock or a random value, without
d.get, can change between calls; the CLI will then store an answer for a question the next run does not ask. - Side effects repeat. A network call, a log line or a temp file before the last question happens N+1 times plus once per validation, in a container that every user shares.
- Answers already in the map are never prompted or validated. Saved answers in an update and preset answers go straight through; the validator never sees them (headless is different: see answer validation).
- Values made after the last question are lost, because the final reply has no state (deterministic state).
- No bound. The interactive loop runs while the outcome is
QnA; a template that never finishes never ends the loop. The headless walks stop at 1000 calls each. - Each call has 30 s, the CLI client's default limit; the script's work before the stop counts on every call.
- A real exception is not a question. A wrong answer type or a bug in the script ends the loop with Err; Node gives no reply from the handler at all.
- Branches are fine. Because each call starts over, a script may ask different questions for different earlier answers; the CLI only ever sees the next one.
Questions for the designer
- Should the interactive loop have a call limit like the headless walks?
- Should the CLI detect a template that asks a question it has already answered (a sign of non-repeatable code)?
- The design lists going back to change answers as a benefit; should the CLI offer it?