Question protocol
The init and validate HTTP calls between the CLI and a template, through the coordinator proxy - routes, ports, JSON, errors and timeouts.
The problem. The template script runs in a container on the coordinator's Docker network; the CLI runs on a laptop. The two need a request/response contract that carries a whole question loop without the server keeping anything.
The idea. Two POST routes per template, both stateless: init (here are all answers and values so far, what next?) and validate (replay to your next question and judge this text). The CLI reaches them through the coordinator, which forwards each body unchanged to the template's shared container.
The sequence below is one question of web:5, from the CLI to the container and back.
sequenceDiagram
participant CLI as CLI (cyanprompt)
participant CO as coordinator :9000
participant T as cyan-template-e5d07b3a… :5550
CLI->>CO: POST /proxy/template/e5d07b3a-…/api/template/init
CO->>T: POST /api/template/init (same body)
T-->>CO: 200 questionnaire: question port + deterministicState
CO-->>CLI: same status, same body
Note over CLI: prompt shown, user types 3000
CLI->>CO: POST /proxy/template/e5d07b3a-…/api/template/validate
CO->>T: POST /api/template/validate (30 s limit)
T-->>CO: 200 valid: null
CO-->>CLI: 200 valid: null
CLI->>CO: POST …/api/template/init (port added)Routes and ports
The table is every route of the protocol. The coordinator path takes the template's version id with dashes.
| Hop | Method and path | Target | Time limit |
|---|---|---|---|
| CLI → coordinator | POST <coordinator>/proxy/template/<version id>/api/template/init | port 9000 | 30 s (CLI client default) |
| coordinator → template | POST /api/template/init | cyan-template-<version id, no dashes>:5550 | none |
| CLI → coordinator | POST <coordinator>/proxy/template/<version id>/api/template/validate | port 9000 | 30 s (CLI client default) |
| coordinator → template | POST /api/template/validate | cyan-template-<version id, no dashes>:5550 | 30 s |
- The default coordinator is
http://coord.cyanprint.dev:9000(--coordinator-endpoint, envCYANPRINT_COORDINATOR). - The container name has no session id: one shared container per template version serves every user and every session (container name).
- Every SDK also answers
GET /with{"Status":"OK","Message":"OK"}(capital keys); the protocol does not use it. - The CLI starts the question loop while the coordinator is still bootstrapping the session's processors (template run).
Init call
The request carries the answer map in wire spelling and the deterministic state under the plural name. Here is web:5's third init call in step 1 of the shop example:
{"answers": {"node_version": { "type": "string", "answer": "22" },"module_type": { "type": "string", "answer": "esm" },"name": { "type": "string", "answer": "shop" },"port": { "type": "string", "answer": "3000" }},"deterministicStates": { "instance-id": "4f9c2e71-aaaa" }}
A missing answer is a 200 question reply, with the state under the singular name:
{"type": "questionnaire","deterministicState": { "instance-id": "4f9c2e71-aaaa" },"question": { "type": "checkbox", "id": "features", "message": "Features?","desc": null, "options": ["docker", "storybook"] }}
When every question is answered, a 200 final reply with the Cyan and no state:
{"type": "final","cyan": {"processors": [ { "name": "atomi/shop-render:1", "config": { "name": "shop", "port": "3000", "instanceId": "4f9c2e71-aaaa" },"files": [ { "root": null, "glob": "**/*", "exclude": [], "type": "template" } ] } ],"plugins": [ { "name": "atomi/shop-format:1", "config": {} } ]}}
Validate call
The request adds the candidate as a plain string. It has no question id: the answer map decides where the replay stops.
{"answers": {"node_version": { "type": "string", "answer": "22" },"module_type": { "type": "string", "answer": "esm" },"name": { "type": "string", "answer": "shop" }},"deterministicStates": { "instance-id": "4f9c2e71-aaaa" },"validate": "80"}
The reply is always 200 with valid set to null (accepted) or a reason (refused). An empty reason counts as accepted in all three SDKs.
{ "valid": "Use a port from 1024 to 65535" }
If the replay reaches the end instead of a question (the map already answers everything), the SDK throws "Not supposed to reach here for validation!".
Field spellings across SDKs
The CLI's spellings are fixed by its serde models. All three SDKs accept and return them:
| Field | Node | Python | .NET |
|---|---|---|---|
| request state | deterministicStates | deterministic_states, alias camelCase | DeterministicStates, camelCase JSON |
| reply state | deterministicState | deterministic_state, alias camelCase | DeterministicState, camelCase JSON |
| answer type pick | from the value | from the value | from the type tag |
| bad body | no schema check | 400 {"error": "..."} | framework binding error |
Errors
- Coordinator could not read the body: 400
ProblemDetails(title,status,detail,type,trace_id,data; boron's JSON tag istrace_id,bo/model.go:17). - Template unreachable, or its body unreadable: 502
ProblemDetails, titleUpstream failed. - Template answered: its status and body are passed through unchanged.
- On the CLI side, the prompt client never checks the status. It decodes the body as the reply it expects, and the two calls differ:
- Init: the reply is a tagged union, so
typemust bequestionnaireorfinal. AProblemDetails(itstypeis a URL), a Python{"error": …}or an HTML error page fails to decode, and the loop ends with Err holding the decode error, not the server's message. - Validate: the reply is
{ "valid": string or null }and unknown keys are ignored. AProblemDetailsor a Python{"error": …}body has novalidkey, so it decodes asvalid: null, which means accepted. Only a body that is not JSON, or a dead connection, is an error (bug below).
- Init: the reply is a tagged union, so
- The CLI wraps that Err as
🚨 Template Prompting Error(status 400, typelocal) (prompt outcome). There is no retry.
Here is the real code for both ends of the proxy and the CLI client.
- lines 190-214The template endpoint is the coordinator proxy path with the version id; a default reqwest blocking client is used (30 s limit).
cyancoordinator/src/template/executor.rs:190-214rust // Setup Template Enginelet template_endpoint = format!("{coord_endpoint}/proxy/template/{template_id}");let answers_clone = answers.cloned();let states_clone = deterministic_states.cloned();let self_clone = self.clone();let h22 = runtime.spawn_blocking(move || {if headless {// Headless mode prints nothing to stdout here — the single JSON// envelope is the only contract output; progress goes to stderr.eprintln!("🤖 Running headless template Q&A...");} else if answers_clone.is_some() {println!("🤖 Using provided answers...");} else {println!("🤖 Starting interactive template Q&A...");}let c22 = Rc::new(Client::new());let prompter = self_clone.new_template_engine(template_endpoint.as_str(), c22.clone());let state = if headless {// Headless re-derives deterministic state internally; the caller// supplies only answers.prompter.start_headless(answers_clone)} else {prompter.start_with(answers_clone, states_clone)}; - sulfone.iridium/cyanprompt/src/http/client.rs:24-48init and validate: POST JSON, then decode the body; the HTTP status is never checked.
cyanprompt/src/http/client.rs:24-48rust pub fn prompt_template(&self,r: &TemplateAnswerReq,) -> Result<TemplateRes, Box<dyn Error + Send>> {let host = (self.endpoint).to_string().to_owned();let endpoint = host + "/api/template/init".to_string().as_str();self.json_post(endpoint, r).map_err(|x| Box::new(x) as Box<dyn Error + Send>).and_then(|resp| {resp.json().map_err(|e| Box::new(e) as Box<dyn Error + Send>)})}pub fn validate_template(&self,r: &TemplateValidateReq,) -> Result<TemplateValidRes, Box<dyn Error + 'static + Send + Sync>> {let host = (self.endpoint).to_string().to_owned();let endpoint = host + "/api/template/validate".to_string().as_str();self.json_post(endpoint, r).map_err(|x| x.into()).and_then(|resp| resp.json().map_err(|e| e.into()))} - sulfone.boron/server.go:596-607init route: container name from the version id with no session, port 5550.
server.go:596-607rust r.POST("/proxy/template/:cyanId/api/template/init", func(c *gin.Context) {cyanId := c.Param("cyanId")fmt.Println("📇 Cyan ID:", cyanId)d := docker_executor.DockerContainerReference{CyanId: cyanId,CyanType: "template",SessionId: "",}endpoint := "http://" + docker_executor.DockerContainerToString(d) + ":5550/api/template/init"fmt.Println("🌐 Upstream Endpoint:", endpoint) - sulfone.boron/server.go:624-638init forward: the whole body is printed to the log, then sent with http.Post (no time limit); failure is 502.
server.go:624-638rust fmt.Println("📦 Request Body:", string(reqBody))resp, err := http.Post(endpoint, c.GetHeader("Content-Type"), bytes.NewBuffer(reqBody))if err != nil {// Handle errorc.JSON(http.StatusBadGateway, ProblemDetails{Title: "Upstream failed",Status: 502,Detail: "Failed to forward request to upstream template",Type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502",TraceId: nil,Data: []string{err.Error()},})return} - sulfone.boron/server.go:690-694validate forward: only the body size is logged; a client with a 30 s limit.
server.go:690-694rust fmt.Println("📦 Request Body Size:", len(reqBody), "bytes")// Forward the request body directly without reading it firstclient := &http.Client{Timeout: 30 * time.Second}resp, err := client.Post(endpoint, c.GetHeader("Content-Type"), bytes.NewBuffer(reqBody)) - sulfone.boron/server.go:724-725The template's status and body are passed back as they are.
server.go:724-725rust }c.Data(resp.StatusCode, resp.Header.Get("Content-Type"), body) - sulfone.helium/sdks/node/src/main.ts:116-131Node SDK: both routes log the request body and reply 200.
sdks/node/src/main.ts:116-131rust app.post('/api/template/init', async (req: Request, res: Response) => {console.log(req.body);const result = await templateService.template(TemplateInputMapper.answerToDomain(req.body));res.json(TemplateOutputMapper.ToResp(result));res.end();});app.post('/api/template/validate', async (req: Request, res: Response) => {console.log(req.body);const result = await templateService.validate(TemplateInputMapper.validateToDomain(req.body));const r = {valid: result,} satisfies TemplateValidRes;res.json(r);res.end();});
Why it is built this way
Hard cases
- A slow script fails at 30 s. The CLI's client gives up after 30 s on any one call. A template that does slow work (a network call, a large file read) before its first question fails every init call, and each replay repeats that work.
- The status is ignored. A 500 whose body happens to decode as a reply is taken as one; a 200 with a bad body is an error. For validate, any status with a JSON object body that lacks
validcounts as "accepted". - A thrown error in the script. Node: the async handler has no catch and Express 4 does not catch a rejected handler, so the handler sends no reply. Python and .NET: an unhandled exception becomes the framework's error reply, which the CLI cannot decode. Found while reading; not run.
- One container for everyone. Two users' loops on web:5 hit the same container; each request builds its own inquirer and map, so they do not mix, but anything the author keeps in module-level variables is shared.
Questions for the designer
- What set the 30 s limits, and should the init forward have one too?
- Should the prompt client check the HTTP status and show the template's error text?
- Is an OpenAPI file for this contract kept anywhere, as the design note says? No static file is in the clones. The .NET SDK serves a generated one (
StartTemplatecallsAddSwaggerGen,UseSwaggerandUseSwaggerUI,Server.cs:115-125, withSwaggerSubTypeon the answer tags,AnswerReq.cs:9-13); the Node and Python SDKs have none. Is the .NET output the contract? - Should a validate call that returns a non-200 status or a body without
validbe refused instead of accepted?