Doc system test

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.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/prompting
  • durian.cloud/cyanprint/authoring
type
algorithm
code
  • sulfone.iridium/cyanprompt/src/domain/services/template/engine.rs
  • sulfone.iridium/cyanprompt/src/domain/services/template/states.rs
  • sulfone.iridium/cyanprompt/src/http/client.rs
  • sulfone.iridium/cyanprint/src/headless.rs
  • sulfone.helium/sdks/node/src/domain/template/service.ts
  • sulfone.helium/sdks/node/src/domain/service/stateless_inquirer.ts
  • sulfone.helium/sdks/node/src/domain/service/stateless_determinism.ts

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):

  1. Send { answers, deterministic_state } to POST /api/template/init on the template, through the coordinator's proxy (client.rs:24-36; the URL is {coordinator}/proxy/template/{version id}).
  2. 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.
  3. On a question reply: show the question in the terminal. Before it accepts an answer, the prompt calls POST /api/template/validate with the answers so far and the typed value (validate.rs). The template replays to that question and runs its validator.
  4. Store the answer under the question id. Replace the deterministic state with the one from the reply (engine.rs:74-77). Go to 1.
  5. 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 for key, or calls make() 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:

OutcomeMeaning
QnAstill asking (the loop continues)
Completethe Cyan and the final answer map
NeedInputheadless only: the first question with no supplied answer
Erra transport or validation failure

Worked example

The author's script:

typescripttypescript
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: [] };
});
StepCLI sends (answers)Script stops atReply
1{}namequestion name
2name=shopdockerquestion docker
3name=shop, docker=trueport (after d.get made project-id)question port, state project-id=7c…
4all three, state project-id=7c…endfinal 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.get values. 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 NeedInput at 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.