Question Ladder - API

export API="https://api.skillsafe.ai/v1/app-api"
export SKILLSAFE_TOKEN="YOUR_TOKEN"   # "Copy shell export" on /tokens.html sets this for you

# No browser at all? Mint a guest token (this one call sends no Authorization header):
SKILLSAFE_TOKEN=$(curl -s -X POST "$API/guest" \
  -H "Content-Type: application/json" \
  -d '{"slug":"question-ladder"}' | jq -r '.data.token')
# 201 -> {"ok":true,"data":{"token":"...","guest_id":"...","expires_at":"..."}}

# Every later call looks like:
#   curl -s "$API/..." -H "Authorization: Bearer $SKILLSAFE_TOKEN" [-H "Content-Type: application/json" -d @body.json]
# and jq reads fields out of the {"ok":true,"data":{...}} envelope.

import json, os, time, requests

API = "https://api.skillsafe.ai/v1/app-api"
TOKEN = os.environ.get("SKILLSAFE_TOKEN")  # copy it from tokens.html

def api(method, path, body=None, headers=None, auth=True):
    """Send JSON (a dict, or an already-encoded string), unwrap the envelope."""
    h = {"Content-Type": "application/json", **(headers or {})}
    if auth and TOKEN:
        h["Authorization"] = f"Bearer {TOKEN}"
    data = body if isinstance(body, str) or body is None else json.dumps(body)
    res = requests.request(method, API + path, data=data, headers=h, timeout=180)
    payload = res.json()
    if not res.ok or payload.get("ok") is False:
        err = payload.get("error", {})
        raise RuntimeError(f'{res.status_code} {err.get("code")}: {err.get("message")}')
    return payload["data"]

# No browser at all? Mint a guest token (no Authorization header on this call).
if not TOKEN:
    TOKEN = api("POST", "/guest", {"slug": "question-ladder"}, auth=False)["token"]

// Node 18+ (built-in fetch), run as an ES module (top-level await)
const API = "https://api.skillsafe.ai/v1/app-api";
let TOKEN = "YOUR_TOKEN"; // paste it from tokens.html, or load it from your secret store

async function api(method, path, body, extraHeaders = {}, auth = true) {
  const headers = { "Content-Type": "application/json", ...extraHeaders };
  if (auth) headers.Authorization = `Bearer ${TOKEN}`;
  const res = await fetch(API + path, {
    method,
    headers,
    body: body === undefined ? undefined : typeof body === "string" ? body : JSON.stringify(body),
  });
  const json = await res.json().catch(() => ({}));
  if (!res.ok || json.ok === false) {
    const e = json.error ?? {};
    throw Object.assign(new Error(`${res.status} ${e.code}: ${e.message ?? res.statusText}`),
      { status: res.status, code: e.code, details: e.details });
  }
  return json.data;
}

// No browser at all? Mint a guest token (no Authorization header on this call).
if (TOKEN === "YOUR_TOKEN") {
  ({ token: TOKEN } = await api("POST", "/guest", { slug: "question-ladder" }, {}, false));
}

package main

import (
	"bufio"
	"bytes"
	"encoding/json"
	"fmt"
	"hash/fnv"
	"log"
	"net/http"
	"os"
	"strings"
	"time"
)

const API = "https://api.skillsafe.ai/v1/app-api"

var token = os.Getenv("SKILLSAFE_TOKEN") // copy it from tokens.html

type envelope struct {
	OK    bool            `json:"ok"`
	Data  json.RawMessage `json:"data"`
	Error *struct {
		Code    string `json:"code"`
		Message string `json:"message"`
	} `json:"error"`
}

// call sends body (any value, or json.RawMessage for pre-encoded bytes) and
// decodes the envelope's data into out.
func call(method, path string, body any, headers map[string]string, out any) error {
	var buf bytes.Buffer
	if body != nil {
		json.NewEncoder(&buf).Encode(body)
	}
	req, _ := http.NewRequest(method, API+path, &buf)
	req.Header.Set("Content-Type", "application/json")
	if token != "" {
		req.Header.Set("Authorization", "Bearer "+token)
	}
	for k, v := range headers {
		req.Header.Set(k, v)
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	var env envelope
	json.NewDecoder(res.Body).Decode(&env)
	if res.StatusCode >= 400 || env.Error != nil {
		if env.Error != nil {
			return fmt.Errorf("%d %s: %s", res.StatusCode, env.Error.Code, env.Error.Message)
		}
		return fmt.Errorf("HTTP %d", res.StatusCode)
	}
	if out == nil {
		return nil
	}
	return json.Unmarshal(env.Data, out)
}

// No browser at all? Mint a guest token (sent while token is still empty, so no auth header).
func ensureToken() {
	if token != "" {
		return
	}
	var g struct{ Token string `json:"token"` }
	if err := call("POST", "/guest", map[string]string{"slug": "question-ladder"}, nil, &g); err != nil {
		log.Fatal(err)
	}
	token = g.Token
}

// Java 17+, with Jackson (com.fasterxml.jackson.core:jackson-databind) for JSON.
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

public class QuestionLadder {
    static final String API = "https://api.skillsafe.ai/v1/app-api";
    static final ObjectMapper JSON = new ObjectMapper();
    static final HttpClient HTTP = HttpClient.newHttpClient();
    static String token = System.getenv("SKILLSAFE_TOKEN"); // copy it from tokens.html

    /** body: any Jackson-serialisable value, or an already-encoded JSON String. */
    static JsonNode api(String method, String path, Object body, Map<String, String> headers) throws Exception {
        var b = HttpRequest.newBuilder(URI.create(API + path))
            .header("Content-Type", "application/json")
            .method(method, body == null
                ? HttpRequest.BodyPublishers.noBody()
                : HttpRequest.BodyPublishers.ofString(body instanceof String s ? s : JSON.writeValueAsString(body)));
        if (token != null) b.header("Authorization", "Bearer " + token);
        headers.forEach(b::header);
        var res = HTTP.send(b.build(), HttpResponse.BodyHandlers.ofString());
        JsonNode env = JSON.readTree(res.body());
        if (res.statusCode() >= 400 || !env.path("ok").asBoolean(true))
            throw new RuntimeException(res.statusCode() + " " + env.path("error").path("code").asText()
                + ": " + env.path("error").path("message").asText());
        return env.get("data");
    }

    // No browser at all? Mint a guest token (token is null, so no auth header is sent).
    static void ensureToken() throws Exception {
        if (token == null) token = api("POST", "/guest", Map.of("slug", "question-ladder"), Map.of()).get("token").asText();
    }

    // Steps 2-5 below go in main(); the static helpers they define sit beside api().
}

require "net/http"
require "json"

API = "https://api.skillsafe.ai/v1/app-api"
$token = ENV["SKILLSAFE_TOKEN"] # copy it from tokens.html

# body: a Hash, or an already-encoded JSON String
def api(method, path, body = nil, headers = {})
  uri = URI(API + path)
  req = Net::HTTP.const_get(method.capitalize).new(uri)
  req["Content-Type"] = "application/json"
  req["Authorization"] = "Bearer #{$token}" if $token
  headers.each { |k, v| req[k] = v }
  req.body = body.is_a?(String) ? body : body.to_json if body
  res = Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 180) { |h| h.request(req) }
  payload = (JSON.parse(res.body) rescue {})
  unless res.is_a?(Net::HTTPSuccess) && payload["ok"] != false
    err = payload["error"] || {}
    raise "#{res.code} #{err["code"]}: #{err["message"] || res.message}"
  end
  payload["data"]
end

# No browser at all? Mint a guest token ($token is nil, so no auth header is sent).
$token ||= api("POST", "/guest", { slug: "question-ladder" })["token"]

<?php
const API = "https://api.skillsafe.ai/v1/app-api";
$TOKEN = getenv("SKILLSAFE_TOKEN") ?: null; // copy it from tokens.html

// $body: an array, or an already-encoded JSON string
function api(string $method, string $path, $body = null, array $headers = []): array {
    global $TOKEN;
    $h = ["Content-Type: application/json"];
    if ($TOKEN) $h[] = "Authorization: Bearer $TOKEN";
    foreach ($headers as $k => $v) $h[] = "$k: $v";
    $ch = curl_init(API . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => $h,
        CURLOPT_TIMEOUT        => 180,
    ]);
    if ($body !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS,
            is_string($body) ? $body : json_encode($body, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE));
    }
    $payload = json_decode(curl_exec($ch), true) ?? [];
    $status  = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    if ($status >= 400 || ($payload["ok"] ?? true) === false) {
        $e = $payload["error"] ?? [];
        throw new Exception("$status " . ($e["code"] ?? "") . ": " . ($e["message"] ?? "HTTP error"));
    }
    return $payload["data"];
}

// No browser at all? Mint a guest token ($TOKEN is null, so no auth header is sent).
$TOKEN = $TOKEN ?: api("POST", "/guest", ["slug" => "question-ladder"])["token"];

// .NET 8+, Program.cs. Top-level statements come first; the helper class goes at the end of the file.
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

// No browser at all? Mint a guest token (Token is null, so no auth header is sent).
QuestionLadder.Token ??= (await QuestionLadder.ApiAsync(HttpMethod.Post, "/guest",
    new { slug = "question-ladder" })).GetProperty("token").GetString();

// ... steps 2-5 go here ...

static class QuestionLadder
{
    public const string Api = "https://api.skillsafe.ai/v1/app-api";
    public static readonly HttpClient Http = new() { Timeout = TimeSpan.FromMinutes(5) };
    public static string? Token = Environment.GetEnvironmentVariable("SKILLSAFE_TOKEN"); // copy it from tokens.html

    // body: any serialisable object, or an already-encoded JSON string
    public static async Task<JsonElement> ApiAsync(HttpMethod method, string path, object? body = null,
        Dictionary<string, string>? headers = null)
    {
        var req = new HttpRequestMessage(method, Api + path);
        if (Token != null) req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Token);
        foreach (var (k, v) in headers ?? new()) req.Headers.Add(k, v);
        if (body != null)
            req.Content = new StringContent(body as string ?? JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");
        var res = await Http.SendAsync(req);
        var json = JsonDocument.Parse(await res.Content.ReadAsStringAsync()).RootElement;
        if (!res.IsSuccessStatusCode)
        {
            var e = json.GetProperty("error");
            throw new Exception($"{(int)res.StatusCode} {e.GetProperty("code")}: {e.GetProperty("message")}");
        }
        return json.GetProperty("data");
    }
}

curl -s "$API/me" -H "Authorization: Bearer $SKILLSAFE_TOKEN" | jq '.data'
# {"subject_type":"guest","subject_id":"gst_...","credits":2000}

me = api("GET", "/me")
print(me["subject_type"], me["subject_id"], me["credits"], "credits",
      f'(${me["credits"] * 0.0001:.2f})')

const me = await api("GET", "/me");
console.log(me.subject_type, me.subject_id, `${me.credits} credits ($${(me.credits * 0.0001).toFixed(2)})`);

// in main():
ensureToken()
var me struct {
	SubjectType string `json:"subject_type"` // "user" or "guest"
	SubjectID   string `json:"subject_id"`
	Credits     int64  `json:"credits"`
}
if err := call("GET", "/me", nil, nil, &me); err != nil {
	log.Fatal(err)
}
fmt.Printf("%s %s: %d credits ($%.2f)\n", me.SubjectType, me.SubjectID, me.Credits, float64(me.Credits)*0.0001)

ensureToken();
JsonNode me = api("GET", "/me", null, Map.of());
System.out.printf("%s %s: %d credits%n",
    me.get("subject_type").asText(), me.get("subject_id").asText(), me.get("credits").asLong());

me = api("GET", "/me")
puts "#{me["subject_type"]} #{me["subject_id"]}: #{me["credits"]} credits"

$me = api("GET", "/me");
echo "{$me['subject_type']} {$me['subject_id']}: {$me['credits']} credits\n";

var me = await QuestionLadder.ApiAsync(HttpMethod.Get, "/me");
Console.WriteLine($"{me.GetProperty("subject_type")} {me.GetProperty("subject_id")}: {me.GetProperty("credits")} credits");

# The concept map lives on YOUR side: ids, labels, mastery 0-1, and how often each was assessed.
cat > concepts.json <<'JSON'
[
  {"id": "c1", "label": "axial tilt", "mastery": 0, "seen": 0},
  {"id": "c2", "label": "direct vs slanted sunlight", "mastery": 0, "seen": 0},
  {"id": "c3", "label": "day length", "mastery": 0, "seen": 0},
  {"id": "c4", "label": "distance from the Sun", "mastery": 0, "seen": 0},
  {"id": "c5", "label": "opposite hemispheres", "mastery": 0, "seen": 0}
]
JSON

# The first tutor turn. concepts_json must be a STRING, so jq's tojson encodes the array into one.
jq -n --slurpfile c concepts.json '{
  task: "open", topic: "Why does Earth have seasons?", mode: "concept", learner: "teen",
  passage: "", concepts_json: ($c[0] | tojson), transcript: "",
  question: "", focus_concept: "", answer: "", confidence: 0,
  hint_level: 3, scaffold_level: 3, hints_revealed: 0, turn_index: 1, clip_note: ""
}' > open.json

curl -s -X POST "$API/estimate" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" -H "Content-Type: application/json" \
  -d @open.json | jq '.data | {hold_credits, min_credits, model_alias, input_checked, warnings}'

# The concept map lives on YOUR side: ids, labels, mastery 0-1, and how often each was assessed.
labels = ["axial tilt", "direct vs slanted sunlight", "day length",
          "distance from the Sun", "opposite hemispheres"]
concepts = [{"id": f"c{i + 1}", "label": l, "mastery": 0, "seen": 0} for i, l in enumerate(labels)]

def compact(obj):
    return json.dumps(obj, separators=(",", ":"), ensure_ascii=False)

payload = {
    "task": "open",
    "topic": "Why does Earth have seasons?",
    "mode": "concept",
    "learner": "teen",
    "passage": "",
    "concepts_json": compact(concepts),  # a STRING, not an array
    "transcript": "",
    "question": "",
    "focus_concept": "",
    "answer": "",
    "confidence": 0,
    "hint_level": 3,
    "scaffold_level": 3,
    "hints_revealed": 0,
    "turn_index": 1,
    "clip_note": "",
}

est = api("POST", "/estimate", payload)  # the input object itself, never {"input": ...}
print(est["hold_credits"], "credits held at most;", est["min_credits"], "needed to start")
for w in est["warnings"]:
    print("warning:", w)

// The concept map lives on YOUR side: ids, labels, mastery 0-1, and how often each was assessed.
const labels = ["axial tilt", "direct vs slanted sunlight", "day length",
  "distance from the Sun", "opposite hemispheres"];
const concepts = labels.map((label, i) => ({ id: `c${i + 1}`, label, mastery: 0, seen: 0 }));

const payload = {
  task: "open",
  topic: "Why does Earth have seasons?",
  mode: "concept",
  learner: "teen",
  passage: "",
  concepts_json: JSON.stringify(concepts), // a STRING, not an array
  transcript: "",
  question: "",
  focus_concept: "",
  answer: "",
  confidence: 0,
  hint_level: 3,
  scaffold_level: 3,
  hints_revealed: 0,
  turn_index: 1,
  clip_note: "",
};

const est = await api("POST", "/estimate", payload); // the input object itself, never { input: ... }
console.log(`${est.hold_credits} credits held at most, ${est.min_credits} needed to start`);
for (const w of est.warnings) console.log("warning:", w);

// at package level: the concept map lives on YOUR side.
type Concept struct {
	ID      string  `json:"id"`
	Label   string  `json:"label"`
	Mastery float64 `json:"mastery"` // 0-1
	Seen    int     `json:"seen"`    // times assessed
}

// ... in main():
labels := []string{"axial tilt", "direct vs slanted sunlight", "day length",
	"distance from the Sun", "opposite hemispheres"}
concepts := make([]Concept, len(labels))
for i, l := range labels {
	concepts[i] = Concept{ID: fmt.Sprintf("c%d", i+1), Label: l}
}
cj, _ := json.Marshal(concepts)

payload := map[string]any{
	"task":           "open",
	"topic":          "Why does Earth have seasons?",
	"mode":           "concept",
	"learner":        "teen",
	"passage":        "",
	"concepts_json":  string(cj), // a STRING, not an array
	"transcript":     "",
	"question":       "",
	"focus_concept":  "",
	"answer":         "",
	"confidence":     0,
	"hint_level":     3,
	"scaffold_level": 3,
	"hints_revealed": 0,
	"turn_index":     1,
	"clip_note":      "",
}

var est struct {
	HoldCredits int64  `json:"hold_credits"`
	MinCredits  int64  `json:"min_credits"`
	ModelAlias  string `json:"model_alias"`
	Warnings    []any  `json:"warnings"`
}
if err := call("POST", "/estimate", payload, nil, &est); err != nil {
	log.Fatal(err)
}
fmt.Println(est.HoldCredits, "credits held at most;", est.MinCredits, "needed to start")
for _, w := range est.Warnings {
	fmt.Println("warning:", w)
}

// The concept map lives on YOUR side: ids, labels, mastery 0-1, and how often each was assessed.
var labels = List.of("axial tilt", "direct vs slanted sunlight", "day length",
    "distance from the Sun", "opposite hemispheres");
ArrayNode concepts = JSON.createArrayNode();
for (int i = 0; i < labels.size(); i++)
    concepts.addObject().put("id", "c" + (i + 1)).put("label", labels.get(i)).put("mastery", 0).put("seen", 0);

ObjectNode payload = JSON.createObjectNode()
    .put("task", "open")
    .put("topic", "Why does Earth have seasons?")
    .put("mode", "concept")
    .put("learner", "teen")
    .put("passage", "")
    .put("concepts_json", JSON.writeValueAsString(concepts)) // a STRING, not an array
    .put("transcript", "")
    .put("question", "")
    .put("focus_concept", "")
    .put("answer", "")
    .put("confidence", 0)
    .put("hint_level", 3)
    .put("scaffold_level", 3)
    .put("hints_revealed", 0)
    .put("turn_index", 1)
    .put("clip_note", "");

JsonNode est = api("POST", "/estimate", payload, Map.of());
System.out.println(est.get("hold_credits") + " credits held at most; "
    + est.get("min_credits") + " needed to start");
est.get("warnings").forEach(w -> System.out.println("warning: " + w));

# The concept map lives on YOUR side: ids, labels, mastery 0-1, and how often each was assessed.
labels = ["axial tilt", "direct vs slanted sunlight", "day length",
          "distance from the Sun", "opposite hemispheres"]
concepts = labels.each_with_index.map { |l, i| { "id" => "c#{i + 1}", "label" => l, "mastery" => 0, "seen" => 0 } }

payload = {
  "task" => "open",
  "topic" => "Why does Earth have seasons?",
  "mode" => "concept",
  "learner" => "teen",
  "passage" => "",
  "concepts_json" => concepts.to_json, # a STRING, not an array
  "transcript" => "",
  "question" => "",
  "focus_concept" => "",
  "answer" => "",
  "confidence" => 0,
  "hint_level" => 3,
  "scaffold_level" => 3,
  "hints_revealed" => 0,
  "turn_index" => 1,
  "clip_note" => ""
}

est = api("POST", "/estimate", payload)
puts "#{est["hold_credits"]} credits held at most; #{est["min_credits"]} needed to start"
est["warnings"].each { |w| puts "warning: #{w}" }

// The concept map lives on YOUR side: ids, labels, mastery 0-1, and how often each was assessed.
$labels = ["axial tilt", "direct vs slanted sunlight", "day length",
           "distance from the Sun", "opposite hemispheres"];
$concepts = [];
foreach ($labels as $i => $l) $concepts[] = ["id" => "c" . ($i + 1), "label" => $l, "mastery" => 0, "seen" => 0];

$payload = [
    "task"           => "open",
    "topic"          => "Why does Earth have seasons?",
    "mode"           => "concept",
    "learner"        => "teen",
    "passage"        => "",
    "concepts_json"  => json_encode($concepts, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE), // a STRING
    "transcript"     => "",
    "question"       => "",
    "focus_concept"  => "",
    "answer"         => "",
    "confidence"     => 0,
    "hint_level"     => 3,
    "scaffold_level" => 3,
    "hints_revealed" => 0,
    "turn_index"     => 1,
    "clip_note"      => "",
];

$est = api("POST", "/estimate", $payload);
echo "{$est['hold_credits']} credits held at most; {$est['min_credits']} needed to start\n";
foreach ($est["warnings"] as $w) echo "warning: " . json_encode($w) . "\n";

// The concept map lives on YOUR side: ids, labels, mastery 0-1, and how often each was assessed.
var labels = new[] { "axial tilt", "direct vs slanted sunlight", "day length",
    "distance from the Sun", "opposite hemispheres" };
var concepts = labels.Select((l, i) => new Dictionary<string, object>
    { ["id"] = $"c{i + 1}", ["label"] = l, ["mastery"] = 0.0, ["seen"] = 0 }).ToList();

var payload = new Dictionary<string, object>
{
    ["task"] = "open",
    ["topic"] = "Why does Earth have seasons?",
    ["mode"] = "concept",
    ["learner"] = "teen",
    ["passage"] = "",
    ["concepts_json"] = JsonSerializer.Serialize(concepts), // a STRING, not an array
    ["transcript"] = "",
    ["question"] = "",
    ["focus_concept"] = "",
    ["answer"] = "",
    ["confidence"] = 0,
    ["hint_level"] = 3,
    ["scaffold_level"] = 3,
    ["hints_revealed"] = 0,
    ["turn_index"] = 1,
    ["clip_note"] = "",
};

var est = await QuestionLadder.ApiAsync(HttpMethod.Post, "/estimate", payload);
Console.WriteLine($"{est.GetProperty("hold_credits")} credits held at most; {est.GetProperty("min_credits")} needed to start");
foreach (var w in est.GetProperty("warnings").EnumerateArray()) Console.WriteLine($"warning: {w}");

BODY=$(jq -c . open.json)
# The app hashes the body with FNV-1a; from a shell any stable hash of the exact body works.
HASH=$(printf %s "$BODY" | shasum | cut -c1-8)
KEY="question-ladder:open:t1:$HASH:a1"   # <slug>:<task>:t<turn_index>:<hash>:a<attempt>

JOB_ID=$(curl -s -X POST "$API/run" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d "$BODY" | jq -r '.data.job_id')

while :; do
  JOB=$(curl -s "$API/jobs/$JOB_ID" -H "Authorization: Bearer $SKILLSAFE_TOKEN")
  STATUS=$(echo "$JOB" | jq -r '.data.status')
  [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ] && break
  sleep 2
done
echo "$JOB" | jq '.data | {status, charged_credits, truncated}'

# The reply is JSON Lines: keep every line that parses as an object with "k", drop the rest.
echo "$JOB" | jq -r '.data.output.output' \
  | jq -R -c 'fromjson? | select(type == "object" and has("k"))' > reply.jsonl

jq -r 'select(.k == "turn") | "Tutor [\(.concept)]: \(.say)"' reply.jsonl
jq -r 'select(.k == "hint") | "  hint \(.level), hidden until asked: \(.text)"' reply.jsonl
tail -n 1 reply.jsonl   # {"k":"end"} - anything else means the reply was cut short

def fnv1a(s):
    """The app's 32-bit FNV-1a (it hashes UTF-16 code units; identical for ASCII)."""
    h = 0x811C9DC5
    for ch in s:
        h ^= ord(ch)
        h = (h * 0x01000193) & 0xFFFFFFFF
    return f"{h:08x}"

def idem_key(inp, body, attempt=1):
    return f'question-ladder:{inp["task"]}:t{inp["turn_index"]}:{fnv1a(body)}:a{attempt}'

def parse_lines(text):
    """JSON Lines -> list of dicts; anything that is not a JSON object with "k" is ignored."""
    out = []
    for line in (text or "").splitlines():
        try:
            obj = json.loads(line)
        except ValueError:
            continue
        if isinstance(obj, dict) and "k" in obj:
            out.append(obj)
    return out

body = compact(payload)  # hash exactly what you send
job_id = api("POST", "/run", body, headers={"Idempotency-Key": idem_key(payload, body)})["job_id"]

while True:
    job = api("GET", f"/jobs/{job_id}")
    if job["status"] in ("succeeded", "failed"):
        break
    time.sleep(1.5)
if job["status"] == "failed":
    raise RuntimeError(job.get("error") or "run failed")

lines = parse_lines(job["output"]["output"])
if not lines or lines[0]["k"] != "turn":
    raise RuntimeError("no turn line: re-ask once with a retry_note")
turn = lines[0]
hints = [l for l in lines if l["k"] == "hint"]  # show one at a time, only when the learner asks
scaffold = next((l for l in lines if l["k"] == "scaffold"), {"level": payload["scaffold_level"]})
if lines[-1]["k"] != "end" or job.get("truncated"):
    print("warning: the reply was cut short")

print(f'Tutor [{turn["concept"]}]: {turn["say"]}')
print(f'{len(hints)} hints ready, support level {scaffold["level"]}, {job["charged_credits"]} credits')

function fnv1a(s) { // the app's own 32-bit FNV-1a
  let h = 0x811c9dc5;
  for (let i = 0; i < s.length; i++) {
    h ^= s.charCodeAt(i);
    h = Math.imul(h, 0x01000193) >>> 0;
  }
  return h.toString(16).padStart(8, "0");
}
// <slug>:<task>:t<turn_index>:<hash of the body>:a<attempt>
const idemKey = (input, attempt = 1) =>
  `question-ladder:${input.task}:t${input.turn_index}:${fnv1a(JSON.stringify(input))}:a${attempt}`;

function parseLines(text) { // JSON Lines -> objects; anything else is ignored
  const out = [];
  for (const line of String(text ?? "").split(/\r?\n/)) {
    try {
      const o = JSON.parse(line);
      if (o && typeof o === "object" && o.k) out.push(o);
    } catch { /* not JSON */ }
  }
  return out;
}

const { job_id } = await api("POST", "/run", payload, { "Idempotency-Key": idemKey(payload) });

let job;
do {
  await new Promise((r) => setTimeout(r, 1500));
  job = await api("GET", `/jobs/${job_id}`);
} while (job.status !== "succeeded" && job.status !== "failed");
if (job.status === "failed") throw new Error(job.error ?? "run failed");

const lines = parseLines(job.output.output);
const turn = lines[0];
if (!turn || turn.k !== "turn") throw new Error("no turn line: re-ask once with a retry_note");
const hints = lines.filter((l) => l.k === "hint"); // show one at a time, only when the learner asks
const scaffold = lines.find((l) => l.k === "scaffold") ?? { level: payload.scaffold_level };
if (lines.at(-1).k !== "end" || job.truncated) console.warn("the reply was cut short");

console.log(`Tutor [${turn.concept}]: ${turn.say}`);
console.log(`${hints.length} hints ready, support level ${scaffold.level}, ${job.charged_credits} credits`);

// at package level:
func idemKey(task string, turnIndex int, body []byte, attempt int) string {
	h := fnv.New32a() // the same 32-bit FNV-1a the app uses
	h.Write(body)
	return fmt.Sprintf("question-ladder:%s:t%d:%08x:a%d", task, turnIndex, h.Sum32(), attempt)
}

func parseLines(text string) []map[string]any { // anything that is not a JSON object with "k" is ignored
	var out []map[string]any
	for _, line := range strings.Split(text, "\n") {
		var l map[string]any
		if json.Unmarshal([]byte(strings.TrimSpace(line)), &l) == nil && l["k"] != nil {
			out = append(out, l)
		}
	}
	return out
}

// ... in main(), after step 3:
body, _ := json.Marshal(payload) // hash exactly the bytes you send
var started struct{ JobID string `json:"job_id"` }
err := call("POST", "/run", json.RawMessage(body),
	map[string]string{"Idempotency-Key": idemKey("open", 1, body, 1)}, &started)
if err != nil {
	log.Fatal(err)
}

var job struct {
	Status         string `json:"status"`
	ChargedCredits int64  `json:"charged_credits"`
	Truncated      bool   `json:"truncated"`
	Output         struct {
		Output string `json:"output"`
	} `json:"output"`
}
for {
	if err := call("GET", "/jobs/"+started.JobID, nil, nil, &job); err != nil {
		log.Fatal(err)
	}
	if job.Status == "succeeded" || job.Status == "failed" {
		break
	}
	time.Sleep(1500 * time.Millisecond)
}
if job.Status == "failed" {
	log.Fatal("run failed")
}

var turn map[string]any
hints, scaffoldLevel := 0, 3.0
for _, l := range parseLines(job.Output.Output) {
	switch l["k"] {
	case "turn":
		turn = l
	case "hint":
		hints++ // show one at a time, only when the learner asks
	case "scaffold":
		if v, ok := l["level"].(float64); ok {
			scaffoldLevel = v
		}
	}
}
if turn == nil {
	log.Fatal("no turn line: re-ask once with a retry_note")
}
fmt.Printf("Tutor [%v]: %v\n%d hints ready, support level %v, %d credits\n",
	turn["concept"], turn["say"], hints, scaffoldLevel, job.ChargedCredits)

static String fnv1a(String s) { // the app's own 32-bit FNV-1a
    int h = 0x811c9dc5;
    for (int i = 0; i < s.length(); i++) {
        h ^= s.charAt(i);
        h *= 0x01000193;
    }
    return String.format("%08x", h);
}

static String idemKey(JsonNode input, String body, int attempt) {
    return "question-ladder:" + input.get("task").asText() + ":t" + input.get("turn_index").asInt()
        + ":" + fnv1a(body) + ":a" + attempt;
}

static List<JsonNode> parseLines(String text) { // anything that is not a JSON object with "k" is ignored
    var out = new ArrayList<JsonNode>();
    for (String line : text.split("\\R")) {
        try {
            JsonNode l = JSON.readTree(line);
            if (l != null && l.isObject() && l.has("k")) out.add(l);
        } catch (Exception e) { /* not JSON */ }
    }
    return out;
}

// ... in main(), after step 3:
String body = JSON.writeValueAsString(payload); // hash exactly what you send
String jobId = api("POST", "/run", body, Map.of("Idempotency-Key", idemKey(payload, body, 1)))
    .get("job_id").asText();

JsonNode job;
do {
    Thread.sleep(1500);
    job = api("GET", "/jobs/" + jobId, null, Map.of());
} while (!job.get("status").asText().matches("succeeded|failed"));
if (job.get("status").asText().equals("failed")) throw new RuntimeException("run failed: " + job.get("error"));

List<JsonNode> lines = parseLines(job.path("output").path("output").asText(""));
if (lines.isEmpty() || !lines.get(0).get("k").asText().equals("turn"))
    throw new RuntimeException("no turn line: re-ask once with a retry_note");
JsonNode turn = lines.get(0);
int hints = 0, scaffoldLevel = 3;
for (JsonNode l : lines) {
    if (l.get("k").asText().equals("hint")) hints++; // show one at a time, only when the learner asks
    if (l.get("k").asText().equals("scaffold")) scaffoldLevel = l.get("level").asInt();
}
System.out.println("Tutor [" + turn.get("concept").asText() + "]: " + turn.get("say").asText());
System.out.println(hints + " hints ready, support level " + scaffoldLevel + ", "
    + job.get("charged_credits") + " credits");

def fnv1a(s) # the app's own 32-bit FNV-1a, over UTF-16 code units
  h = 0x811c9dc5
  s.encode("UTF-16LE").unpack("v*").each { |u| h = ((h ^ u) * 0x01000193) & 0xffffffff }
  format("%08x", h)
end

def idem_key(input, body, attempt = 1)
  "question-ladder:#{input["task"]}:t#{input["turn_index"]}:#{fnv1a(body)}:a#{attempt}"
end

def parse_lines(text) # JSON Lines -> hashes; anything else is ignored
  text.to_s.each_line.filter_map do |line|
    obj = (JSON.parse(line) rescue nil)
    obj if obj.is_a?(Hash) && obj["k"]
  end
end

body = payload.to_json # hash exactly what you send
job_id = api("POST", "/run", body, { "Idempotency-Key" => idem_key(payload, body) })["job_id"]

job = nil
loop do
  job = api("GET", "/jobs/#{job_id}")
  break if %w[succeeded failed].include?(job["status"])
  sleep 1.5
end
raise "run failed: #{job["error"]}" if job["status"] == "failed"

lines = parse_lines(job.dig("output", "output"))
turn = lines.first
raise "no turn line: re-ask once with a retry_note" unless turn && turn["k"] == "turn"
hints = lines.select { |l| l["k"] == "hint" } # show one at a time, only when the learner asks
scaffold = lines.find { |l| l["k"] == "scaffold" } || { "level" => payload["scaffold_level"] }
warn "the reply was cut short" if lines.last["k"] != "end" || job["truncated"]

puts "Tutor [#{turn["concept"]}]: #{turn["say"]}"
puts "#{hints.size} hints ready, support level #{scaffold["level"]}, #{job["charged_credits"]} credits"

function idem_key(array $input, string $body, int $attempt = 1): string {
    // <slug>:<task>:t<turn_index>:<hash>:a<attempt>, with PHP's built-in 32-bit FNV-1a
    return "question-ladder:{$input['task']}:t{$input['turn_index']}:" . hash("fnv1a32", $body) . ":a$attempt";
}

function parse_lines(?string $text): array { // JSON Lines -> arrays; anything else is ignored
    $out = [];
    foreach (preg_split('/\r?\n/', $text ?? "") as $line) {
        $o = json_decode($line, true);
        if (is_array($o) && isset($o["k"])) $out[] = $o;
    }
    return $out;
}

$body  = json_encode($payload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE); // hash what you send
$jobId = api("POST", "/run", $body, ["Idempotency-Key" => idem_key($payload, $body)])["job_id"];

do {
    usleep(1500000);
    $job = api("GET", "/jobs/$jobId");
} while (!in_array($job["status"], ["succeeded", "failed"], true));
if ($job["status"] === "failed") throw new Exception("run failed");

$lines = parse_lines($job["output"]["output"] ?? "");
$turn  = $lines[0] ?? null;
if (!$turn || $turn["k"] !== "turn") throw new Exception("no turn line: re-ask once with a retry_note");
$hints = array_values(array_filter($lines, fn($l) => $l["k"] === "hint")); // reveal on request only
$scaffoldLevel = $payload["scaffold_level"];
foreach ($lines as $l) if ($l["k"] === "scaffold") $scaffoldLevel = $l["level"];

echo "Tutor [{$turn['concept']}]: {$turn['say']}\n";
echo count($hints) . " hints ready, support level $scaffoldLevel, {$job['charged_credits']} credits\n";

static string Fnv1a(string s) // the app's own 32-bit FNV-1a
{
    uint h = 0x811c9dc5;
    foreach (char ch in s) { h ^= ch; h = unchecked(h * 0x01000193); }
    return h.ToString("x8");
}
static string IdemKey(Dictionary<string, object> input, string body, int attempt = 1) =>
    $"question-ladder:{input["task"]}:t{input["turn_index"]}:{Fnv1a(body)}:a{attempt}";

static List<JsonElement> ParseLines(string? text) // anything that is not a JSON object with "k" is ignored
{
    var output = new List<JsonElement>();
    foreach (var line in (text ?? "").Split('\n'))
    {
        try
        {
            var l = JsonDocument.Parse(line).RootElement;
            if (l.ValueKind == JsonValueKind.Object && l.TryGetProperty("k", out _)) output.Add(l);
        }
        catch (JsonException) { /* not JSON */ }
    }
    return output;
}

var body = JsonSerializer.Serialize(payload); // hash exactly what you send
var started = await QuestionLadder.ApiAsync(HttpMethod.Post, "/run", body,
    new() { ["Idempotency-Key"] = IdemKey(payload, body) });
var jobId = started.GetProperty("job_id").GetString();

JsonElement job;
string status;
do
{
    await Task.Delay(1500);
    job = await QuestionLadder.ApiAsync(HttpMethod.Get, $"/jobs/{jobId}");
    status = job.GetProperty("status").GetString()!;
} while (status is not ("succeeded" or "failed"));
if (status == "failed") throw new Exception("run failed");

var lines = ParseLines(job.GetProperty("output").GetProperty("output").GetString());
if (lines.Count == 0 || lines[0].GetProperty("k").GetString() != "turn")
    throw new Exception("no turn line: re-ask once with a retry_note");
var turn = lines[0];
var hints = lines.Count(l => l.GetProperty("k").GetString() == "hint"); // reveal on request only
var scaffoldLevel = lines.Where(l => l.GetProperty("k").GetString() == "scaffold")
    .Select(l => l.GetProperty("level").GetInt32()).DefaultIfEmpty(3).First();

Console.WriteLine($"Tutor [{turn.GetProperty("concept")}]: {turn.GetProperty("say")}");
Console.WriteLine($"{hints} hints ready, support level {scaffoldLevel}, {job.GetProperty("charged_credits")} credits");

# Turn 2: the learner answers the tutor's question. Build the next stateless body from open.json.
TURN=$(jq -c 'select(.k == "turn")' reply.jsonl)
jq -c --argjson t "$TURN" --slurpfile c concepts.json '. + {
  task: "answer",
  concepts_json: ($c[0] | tojson),
  transcript: ("T1 TUTOR question [" + $t.concept + "]: " + $t.say),
  question: $t.say,
  focus_concept: $t.concept,
  answer: "I think in summer the Earth is closer to the Sun, so more heat reaches us.",
  confidence: 4,
  hints_revealed: 0,
  turn_index: 3
}' open.json > answer.json

BODY=$(cat answer.json)
HASH=$(printf %s "$BODY" | shasum | cut -c1-8)
curl -N -s -X POST "$API/run-stream" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: question-ladder:answer:t3:$HASH:a1" \
  -d "$BODY" | tee stream.txt
# event: job
# data: {"job_id":"job_..."}
#
# event: tick
# data: {"t":4}
#
# event: done
# data: {"job_id":"job_...","status":"succeeded","charged_credits":...,"output":{"output":"...JSON Lines..."}}

# Parse the reply from the done event, never from the deltas.
sed -n '/^event: done/{n;s/^data: *//p;}' stream.txt | jq -r '(.job // .) | .output.output' \
  | jq -R -c 'fromjson? | select(type == "object" and has("k"))' > reply2.jsonl
jq -r 'select(.k == "turn") | "Tutor: \(.say)"' reply2.jsonl

# Apply assess mastery to concepts already on the map (unknown ids change nothing).
jq --slurpfile r reply2.jsonl 'map(. as $c
  | ([$r[] | select(.k == "assess" and .concept == $c.id)] | first) as $a
  | if $a then .mastery = $a.mastery | .seen += 1 else . end)' concepts.json > concepts.next.json \
  && mv concepts.next.json concepts.json
# suggest lines are shown to the learner, never added to the map automatically
jq -r 'select(.k == "suggest") | "Suggested concept (not added): \(.concept_label) - \(.why)"' reply2.jsonl

# Turn 2: the learner answers. Every field is re-sent; the server keeps nothing between turns.
nxt = dict(payload,
    task="answer",
    concepts_json=compact(concepts),
    transcript=f'T1 TUTOR question [{turn["concept"]}]: {turn["say"]}',
    question=turn["say"],
    focus_concept=turn["concept"],
    answer="I think in summer the Earth is closer to the Sun, so more heat reaches us.",
    confidence=4,                     # the learner's 1-5 self-rating
    scaffold_level=scaffold["level"],
    hints_revealed=0,                 # hints the learner opened before answering
    turn_index=3,                     # T2 is the learner's line, T3 the tutor's reply
)
body = compact(nxt)
res = requests.post(API + "/run-stream", data=body, stream=True, timeout=300, headers={
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
    "Idempotency-Key": idem_key(nxt, body),
})
res.raise_for_status()

event, job = None, None
for raw in res.iter_lines(decode_unicode=True):
    if raw.startswith("event:"):
        event = raw[6:].strip()
    elif raw.startswith("data:"):
        data = json.loads(raw[5:].strip())
        if event == "delta":
            print(data["text"], end="", flush=True)  # progress only
        elif event == "done":
            job = data.get("job", data)
        elif event == "error":
            raise RuntimeError(data.get("message", data))
        # "job" carries {job_id}; "tick" is a heartbeat

# Apply the reply to YOUR map: only ids that already exist move.
by_id = {c["id"]: c for c in concepts}
for l in parse_lines(job["output"]["output"]):  # parse the final text, not the deltas
    if l["k"] == "turn":
        print("\nTutor:", l["say"])
    elif l["k"] == "assess" and l.get("concept") in by_id:
        c = by_id[l["concept"]]
        c["mastery"], c["seen"] = round(float(l["mastery"]), 2), c["seen"] + 1
        print(f'  {c["label"]}: {l["verdict"]}, mastery now {c["mastery"]}')
    elif l["k"] == "misconception":
        print("  misconception:", l["belief"])
    elif l["k"] == "suggest":
        print(f'  suggested concept (not added): {l["concept_label"]} - {l["why"]}')

// Turn 2: the learner answers. Every field is re-sent; the server keeps nothing between turns.
const next = {
  ...payload,
  task: "answer",
  concepts_json: JSON.stringify(concepts),
  transcript: `T1 TUTOR question [${turn.concept}]: ${turn.say}`,
  question: turn.say,
  focus_concept: turn.concept,
  answer: "I think in summer the Earth is closer to the Sun, so more heat reaches us.",
  confidence: 4,                  // the learner's 1-5 self-rating
  scaffold_level: scaffold.level,
  hints_revealed: 0,              // hints the learner opened before answering
  turn_index: 3,                  // T2 is the learner's line, T3 the tutor's reply
};

const res = await fetch(API + "/run-stream", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idemKey(next),
  },
  body: JSON.stringify(next),
});
if (!res.ok) throw new Error(`run-stream: HTTP ${res.status}`);

const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buf = "", done = null;
for (;;) {
  const { value, done: end } = await reader.read();
  if (end) break;
  buf += value.replace(/\r\n/g, "\n");
  let i;
  while ((i = buf.indexOf("\n\n")) >= 0) {
    const frame = buf.slice(0, i);
    buf = buf.slice(i + 2);
    const name = /^event:\s*(.+)$/m.exec(frame)?.[1];
    const data = /^data:\s?(.*)$/m.exec(frame)?.[1];
    if (!name || data === undefined) continue;
    const d = JSON.parse(data);
    if (name === "delta") console.log("+", d.text.length, "chars"); // progress only
    else if (name === "done") done = d.job ?? d;
    else if (name === "error") throw new Error(d.message ?? "stream error");
    // "job" carries {job_id}; "tick" is a heartbeat
  }
}

// Apply the reply to YOUR map: only ids that already exist move.
const byId = new Map(concepts.map((c) => [c.id, c]));
for (const l of parseLines(done.output.output)) { // parse the final text, not the deltas
  if (l.k === "turn") console.log("Tutor:", l.say);
  else if (l.k === "assess" && byId.has(l.concept)) {
    const c = byId.get(l.concept);
    c.mastery = Math.round(Number(l.mastery) * 100) / 100;
    c.seen += 1;
    console.log(`  ${c.label}: ${l.verdict}, mastery now ${c.mastery}`);
  } else if (l.k === "misconception") console.log("  misconception:", l.belief);
  else if (l.k === "suggest") console.log(`  suggested concept (not added): ${l.concept_label} - ${l.why}`);
}

// Turn 2: the learner answers. Every field is re-sent; the server keeps nothing between turns.
next := map[string]any{}
for k, v := range payload {
	next[k] = v
}
cj, _ = json.Marshal(concepts)
say, _ := turn["say"].(string)
focus, _ := turn["concept"].(string)
next["task"] = "answer"
next["concepts_json"] = string(cj)
next["transcript"] = "T1 TUTOR question [" + focus + "]: " + say
next["question"] = say
next["focus_concept"] = focus
next["answer"] = "I think in summer the Earth is closer to the Sun, so more heat reaches us."
next["confidence"] = 4      // the learner's 1-5 self-rating
next["scaffold_level"] = int(scaffoldLevel)
next["hints_revealed"] = 0  // hints the learner opened before answering
next["turn_index"] = 3      // T2 is the learner's line, T3 the tutor's reply
nextBody, _ := json.Marshal(next)

req, _ := http.NewRequest("POST", API+"/run-stream", bytes.NewReader(nextBody))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", idemKey("answer", 3, nextBody, 1))
res, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer res.Body.Close()

var done struct {
	Status string `json:"status"`
	Output struct {
		Output string `json:"output"`
	} `json:"output"`
}
event := ""
sc := bufio.NewScanner(res.Body)
sc.Buffer(make([]byte, 1<<20), 1<<22) // done carries the whole reply on one line
for sc.Scan() {
	line := sc.Text()
	switch {
	case strings.HasPrefix(line, "event:"):
		event = strings.TrimSpace(line[6:])
	case strings.HasPrefix(line, "data:"):
		data := []byte(strings.TrimSpace(line[5:]))
		switch event {
		case "delta":
			fmt.Print(".") // progress only
		case "done":
			json.Unmarshal(data, &done)
		case "error":
			log.Fatalf("stream error: %s", data)
		} // "job" carries {job_id}; "tick" is a heartbeat
	}
}

// Apply the reply to YOUR map: only ids that already exist move.
for _, l := range parseLines(done.Output.Output) {
	switch l["k"] {
	case "turn":
		fmt.Println("\nTutor:", l["say"])
	case "assess":
		for i := range concepts {
			if concepts[i].ID == l["concept"] {
				if m, ok := l["mastery"].(float64); ok {
					concepts[i].Mastery = m
				}
				concepts[i].Seen++
				fmt.Printf("  %s: %v, mastery now %.2f\n", concepts[i].Label, l["verdict"], concepts[i].Mastery)
			}
		}
	case "suggest":
		fmt.Printf("  suggested concept (not added): %v - %v\n", l["concept_label"], l["why"])
	}
}

// Turn 2: the learner answers. Every field is re-sent; the server keeps nothing between turns.
ObjectNode next = payload.deepCopy()
    .put("task", "answer")
    .put("concepts_json", JSON.writeValueAsString(concepts))
    .put("transcript", "T1 TUTOR question [" + turn.get("concept").asText() + "]: " + turn.get("say").asText())
    .put("question", turn.get("say").asText())
    .put("focus_concept", turn.get("concept").asText())
    .put("answer", "I think in summer the Earth is closer to the Sun, so more heat reaches us.")
    .put("confidence", 4)               // the learner's 1-5 self-rating
    .put("scaffold_level", scaffoldLevel)
    .put("hints_revealed", 0)           // hints the learner opened before answering
    .put("turn_index", 3);              // T2 is the learner's line, T3 the tutor's reply
String nextBody = JSON.writeValueAsString(next);

var req = HttpRequest.newBuilder(URI.create(API + "/run-stream"))
    .header("Authorization", "Bearer " + token)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", idemKey(next, nextBody, 1))
    .POST(HttpRequest.BodyPublishers.ofString(nextBody))
    .build();
var res = HTTP.send(req, HttpResponse.BodyHandlers.ofLines());

String event = "";
JsonNode done = null;
for (String line : (Iterable<String>) res.body()::iterator) {
    if (line.startsWith("event:")) event = line.substring(6).trim();
    else if (line.startsWith("data:")) {
        JsonNode d = JSON.readTree(line.substring(5).trim());
        switch (event) {
            case "delta" -> System.out.print("."); // progress only
            case "done"  -> done = d.has("job") ? d.get("job") : d;
            case "error" -> throw new RuntimeException(d.toString());
            default      -> { } // job, tick
        }
    }
}

// Apply the reply to YOUR map: only ids that already exist move.
for (JsonNode l : parseLines(done.path("output").path("output").asText(""))) {
    switch (l.get("k").asText()) {
        case "turn" -> System.out.println("\nTutor: " + l.get("say").asText());
        case "assess" -> {
            for (JsonNode c : concepts) {
                if (!c.get("id").asText().equals(l.path("concept").asText())) continue;
                ((ObjectNode) c).put("mastery", l.get("mastery").asDouble()).put("seen", c.get("seen").asInt() + 1);
                System.out.println("  " + c.get("label").asText() + ": " + l.get("verdict").asText()
                    + ", mastery now " + c.get("mastery").asDouble());
            }
        }
        case "suggest" -> System.out.println("  suggested concept (not added): "
            + l.get("concept_label").asText() + " - " + l.get("why").asText());
        default -> { }
    }
}

# Turn 2: the learner answers. Every field is re-sent; the server keeps nothing between turns.
nxt = payload.merge(
  "task" => "answer",
  "concepts_json" => concepts.to_json,
  "transcript" => "T1 TUTOR question [#{turn["concept"]}]: #{turn["say"]}",
  "question" => turn["say"],
  "focus_concept" => turn["concept"],
  "answer" => "I think in summer the Earth is closer to the Sun, so more heat reaches us.",
  "confidence" => 4,                      # the learner's 1-5 self-rating
  "scaffold_level" => scaffold["level"],
  "hints_revealed" => 0,                  # hints the learner opened before answering
  "turn_index" => 3                       # T2 is the learner's line, T3 the tutor's reply
)
body = nxt.to_json

uri = URI(API + "/run-stream")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{$token}"
req["Content-Type"] = "application/json"
req["Idempotency-Key"] = idem_key(nxt, body)
req.body = body

done = nil
Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 300) do |http|
  http.request(req) do |res|
    buf = +""
    event = nil
    res.read_body do |chunk|
      buf << chunk
      while (i = buf.index("\n"))
        line = buf.slice!(0..i).strip
        if line.start_with?("event:")
          event = line.delete_prefix("event:").strip
        elsif line.start_with?("data:")
          d = JSON.parse(line.delete_prefix("data:").strip)
          case event
          when "delta" then print "." # progress only
          when "done"  then done = d["job"] || d
          when "error" then raise d.to_s
          end # "job" carries {job_id}; "tick" is a heartbeat
        end
      end
    end
  end
end

# Apply the reply to YOUR map: only ids that already exist move.
parse_lines(done.dig("output", "output")).each do |l|
  case l["k"]
  when "turn" then puts "\nTutor: #{l["say"]}"
  when "assess"
    c = concepts.find { |x| x["id"] == l["concept"] } or next
    c["mastery"] = l["mastery"].to_f.round(2)
    c["seen"] += 1
    puts "  #{c["label"]}: #{l["verdict"]}, mastery now #{c["mastery"]}"
  when "suggest" then puts "  suggested concept (not added): #{l["concept_label"]} - #{l["why"]}"
  end
end

// Turn 2: the learner answers. Every field is re-sent; the server keeps nothing between turns.
$next = array_merge($payload, [
    "task"           => "answer",
    "concepts_json"  => json_encode($concepts, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE),
    "transcript"     => "T1 TUTOR question [{$turn['concept']}]: {$turn['say']}",
    "question"       => $turn["say"],
    "focus_concept"  => $turn["concept"],
    "answer"         => "I think in summer the Earth is closer to the Sun, so more heat reaches us.",
    "confidence"     => 4,              // the learner's 1-5 self-rating
    "scaffold_level" => $scaffoldLevel,
    "hints_revealed" => 0,              // hints the learner opened before answering
    "turn_index"     => 3,              // T2 is the learner's line, T3 the tutor's reply
]);
$body = json_encode($next, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

$buf = ""; $event = null; $done = null; $err = null;
$ch = curl_init(API . "/run-stream");
curl_setopt_array($ch, [
    CURLOPT_POST          => true,
    CURLOPT_POSTFIELDS    => $body,
    CURLOPT_TIMEOUT       => 300,
    CURLOPT_HTTPHEADER    => [
        "Authorization: Bearer $TOKEN",
        "Content-Type: application/json",
        "Idempotency-Key: " . idem_key($next, $body),
    ],
    CURLOPT_WRITEFUNCTION => function ($ch, $chunk) use (&$buf, &$event, &$done, &$err) {
        $buf .= $chunk;
        while (($i = strpos($buf, "\n")) !== false) {
            $line = trim(substr($buf, 0, $i));
            $buf  = substr($buf, $i + 1);
            if (str_starts_with($line, "event:")) {
                $event = trim(substr($line, 6));
            } elseif (str_starts_with($line, "data:")) {
                $d = json_decode(trim(substr($line, 5)), true);
                if ($event === "delta") echo ".";                  // progress only
                elseif ($event === "done") $done = $d["job"] ?? $d;
                elseif ($event === "error") $err = $d;              // "job" and "tick" are skipped
            }
        }
        return strlen($chunk);
    },
]);
curl_exec($ch);
curl_close($ch);
if ($err) throw new Exception(json_encode($err));

// Apply the reply to YOUR map: only ids that already exist move.
foreach (parse_lines($done["output"]["output"] ?? "") as $l) {
    if ($l["k"] === "turn") echo "\nTutor: {$l['say']}\n";
    if ($l["k"] === "assess") {
        foreach ($concepts as &$c) {
            if ($c["id"] !== ($l["concept"] ?? null)) continue;
            $c["mastery"] = round((float) $l["mastery"], 2);
            $c["seen"]++;
            echo "  {$c['label']}: {$l['verdict']}, mastery now {$c['mastery']}\n";
        }
        unset($c);
    }
    if ($l["k"] === "suggest") echo "  suggested concept (not added): {$l['concept_label']} - {$l['why']}\n";
}

// Turn 2: the learner answers. Every field is re-sent; the server keeps nothing between turns.
var next = new Dictionary<string, object>(payload)
{
    ["task"] = "answer",
    ["concepts_json"] = JsonSerializer.Serialize(concepts),
    ["transcript"] = $"T1 TUTOR question [{turn.GetProperty("concept")}]: {turn.GetProperty("say")}",
    ["question"] = turn.GetProperty("say").GetString()!,
    ["focus_concept"] = turn.GetProperty("concept").GetString()!,
    ["answer"] = "I think in summer the Earth is closer to the Sun, so more heat reaches us.",
    ["confidence"] = 4,               // the learner's 1-5 self-rating
    ["scaffold_level"] = scaffoldLevel,
    ["hints_revealed"] = 0,           // hints the learner opened before answering
    ["turn_index"] = 3,               // T2 is the learner's line, T3 the tutor's reply
};
var nextBody = JsonSerializer.Serialize(next);

var req = new HttpRequestMessage(HttpMethod.Post, QuestionLadder.Api + "/run-stream")
{
    Content = new StringContent(nextBody, Encoding.UTF8, "application/json"),
};
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", QuestionLadder.Token);
req.Headers.Add("Idempotency-Key", IdemKey(next, nextBody));

using var res = await QuestionLadder.Http.SendAsync(req, HttpCompletionOption.ResponseHeadersRead);
using var reader = new StreamReader(await res.Content.ReadAsStreamAsync());
string? evt = null, done = null;
while (await reader.ReadLineAsync() is { } line)
{
    if (line.StartsWith("event:")) evt = line[6..].Trim();
    else if (line.StartsWith("data:"))
    {
        var data = line[5..].Trim();
        if (evt == "delta") Console.Write("."); // progress only
        else if (evt == "done") done = data;
        else if (evt == "error") throw new Exception(data);
    }   // "job" carries {job_id}; "tick" is a heartbeat
}

var final = JsonDocument.Parse(done!).RootElement;
if (final.TryGetProperty("job", out var wrapped)) final = wrapped;

// Apply the reply to YOUR map: only ids that already exist move.
foreach (var l in ParseLines(final.GetProperty("output").GetProperty("output").GetString()))
{
    var k = l.GetProperty("k").GetString();
    if (k == "turn") Console.WriteLine($"\nTutor: {l.GetProperty("say")}");
    else if (k == "assess")
    {
        var c = concepts.FirstOrDefault(x => (string)x["id"] == l.GetProperty("concept").GetString());
        if (c == null) continue;
        c["mastery"] = Math.Round(l.GetProperty("mastery").GetDouble(), 2);
        c["seen"] = (int)c["seen"] + 1;
        Console.WriteLine($"  {c["label"]}: {l.GetProperty("verdict")}, mastery now {c["mastery"]}");
    }
    else if (k == "suggest")
        Console.WriteLine($"  suggested concept (not added): {l.GetProperty("concept_label")} - {l.GetProperty("why")}");
}