Roofline Walk - 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":"roofline-walk"}' | 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 @input.json]
# jq pulls fields out of the {"ok":true,"data":{...}} envelope

import json, os, 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": "roofline-walk"}, 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: "roofline-walk" }, {}, 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": "roofline-walk"}, 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 java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Map;

public class RooflineWalk {
    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", "roofline-walk"), Map.of()).get("token").asText();
    }
}

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: "roofline-walk" })["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" => "roofline-walk"])["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).
RooflineWalk.Token ??= (await RooflineWalk.ApiAsync(HttpMethod.Post, "/guest",
    new { slug = "roofline-walk" })).GetProperty("token").GetString();

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

static class RooflineWalk
{
    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)})`);

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 RooflineWalk.ApiAsync(HttpMethod.Get, "/me");
Console.WriteLine($"{me.GetProperty("subject_type")} {me.GetProperty("subject_id")}: {me.GetProperty("credits")} credits");

# items.json holds the items array (see "Worked examples" below).
# cover_json and items_json must be STRINGS, so jq's tojson encodes them.
jq -n --slurpfile i items.json '{
  task: "report",
  template: "storm",
  template_name: "After a hail or wind storm",
  cover_json: ({title: "After the 14 Sept hail storm", place: "12 Elm Street",
                walked_on: "2026-09-23", inspector: "Corvin Ashdale",
                purpose: "Decide whether to file a hail claim", audience: "insurer",
                details: {"Storm date": "2026-09-14"}} | tojson),
  items_json: ($i[0] | tojson)
}' > input.json

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

with open("items.json", encoding="utf-8") as fh:
    items = json.load(fh)  # [{id, section, item, status, note, photos, default_severity, who}, ...]

cover = {
    "title": "After the 14 Sept hail storm", "place": "12 Elm Street",
    "walked_on": "2026-09-23", "inspector": "Corvin Ashdale",
    "purpose": "Decide whether to file a hail claim", "audience": "insurer",
    "details": {"Storm date": "2026-09-14"},
}
enc = lambda v: json.dumps(v, separators=(",", ":"), ensure_ascii=False)

payload = {
    "task": "report",
    "template": "storm",
    "template_name": "After a hail or wind storm",
    "cover_json": enc(cover),   # a STRING
    "items_json": enc(items),   # a STRING
}

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

import { readFileSync } from "node:fs";

const items = JSON.parse(readFileSync("items.json", "utf8"));
const cover = {
  title: "After the 14 Sept hail storm", place: "12 Elm Street",
  walked_on: "2026-09-23", inspector: "Corvin Ashdale",
  purpose: "Decide whether to file a hail claim", audience: "insurer",
  details: { "Storm date": "2026-09-14" },
};

const payload = {
  task: "report",
  template: "storm",
  template_name: "After a hail or wind storm",
  cover_json: JSON.stringify(cover), // a STRING, not an object
  items_json: JSON.stringify(items), // a STRING, not an array
};

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

raw, err := os.ReadFile("items.json")
if err != nil {
	log.Fatal(err)
}
var items []map[string]any
if err := json.Unmarshal(raw, &items); err != nil {
	log.Fatal(err)
}
itemsJSON, _ := json.Marshal(items)
coverJSON, _ := json.Marshal(map[string]any{
	"title": "After the 14 Sept hail storm", "place": "12 Elm Street",
	"walked_on": "2026-09-23", "inspector": "Corvin Ashdale",
	"purpose": "Decide whether to file a hail claim", "audience": "insurer",
	"details": map[string]string{"Storm date": "2026-09-14"},
})

payload := map[string]any{
	"task":          "report",
	"template":      "storm",
	"template_name": "After a hail or wind storm",
	"cover_json":    string(coverJSON), // a STRING, not an object
	"items_json":    string(itemsJSON), // a STRING, not an array
}

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

var items = JSON.readTree(java.nio.file.Files.readString(java.nio.file.Path.of("items.json")));
var cover = JSON.createObjectNode()
    .put("title", "After the 14 Sept hail storm").put("place", "12 Elm Street")
    .put("walked_on", "2026-09-23").put("inspector", "Corvin Ashdale")
    .put("purpose", "Decide whether to file a hail claim").put("audience", "insurer");
cover.putObject("details").put("Storm date", "2026-09-14");

var payload = JSON.createObjectNode()
    .put("task", "report")
    .put("template", "storm")
    .put("template_name", "After a hail or wind storm")
    .put("cover_json", JSON.writeValueAsString(cover))  // a STRING, not an object
    .put("items_json", JSON.writeValueAsString(items)); // a STRING, not an array

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

items = JSON.parse(File.read("items.json"))
cover = {
  title: "After the 14 Sept hail storm", place: "12 Elm Street",
  walked_on: "2026-09-23", inspector: "Corvin Ashdale",
  purpose: "Decide whether to file a hail claim", audience: "insurer",
  details: { "Storm date" => "2026-09-14" }
}

payload = {
  task: "report",
  template: "storm",
  template_name: "After a hail or wind storm",
  cover_json: cover.to_json, # a STRING, not an object
  items_json: items.to_json  # a STRING, not an array
}

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

$items = json_decode(file_get_contents("items.json"), true);
$cover = [
    "title" => "After the 14 Sept hail storm", "place" => "12 Elm Street",
    "walked_on" => "2026-09-23", "inspector" => "Corvin Ashdale",
    "purpose" => "Decide whether to file a hail claim", "audience" => "insurer",
    "details" => ["Storm date" => "2026-09-14"],
];
$enc = fn($v) => json_encode($v, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

$payload = [
    "task"          => "report",
    "template"      => "storm",
    "template_name" => "After a hail or wind storm",
    "cover_json"    => $enc($cover), // a STRING
    "items_json"    => $enc($items), // a STRING
];

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

var items = JsonDocument.Parse(await File.ReadAllTextAsync("items.json")).RootElement;
var cover = new Dictionary<string, object>
{
    ["title"] = "After the 14 Sept hail storm", ["place"] = "12 Elm Street",
    ["walked_on"] = "2026-09-23", ["inspector"] = "Corvin Ashdale",
    ["purpose"] = "Decide whether to file a hail claim", ["audience"] = "insurer",
    ["details"] = new Dictionary<string, string> { ["Storm date"] = "2026-09-14" },
};

var payload = new Dictionary<string, object>
{
    ["task"] = "report",
    ["template"] = "storm",
    ["template_name"] = "After a hail or wind storm",
    ["cover_json"] = JsonSerializer.Serialize(cover), // a STRING, not an object
    ["items_json"] = JsonSerializer.Serialize(items), // a STRING, not an array
};

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

BODY=$(jq -c . input.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="roofline-walk:report:$HASH:a1"

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 == "meta") | "\(.verdict): \(.headline)"' reply.jsonl
jq -r 'select(.k == "finding") | "  \(.item) [\(.severity)/\(.urgency)] \(.do) -> \(.who)"' reply.jsonl
jq -r 'select(.k == "recheck") | "  \(.item) \(.outcome): \(.next)"' reply.jsonl
jq -r 'select(.k == "question") | "  ask \(.to): \(.q)"' reply.jsonl
jq -r 'select(.k == "verdict") | .text' reply.jsonl

import time

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(task, body, attempt=1):
    return f"roofline-walk:{task}:{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 = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)  # hash exactly what you send
job_id = api("POST", "/run", body,
             headers={"Idempotency-Key": idem_key(payload["task"], 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"])
meta = next((l for l in lines if l["k"] == "meta"), {})
print(f'{meta.get("verdict")}: {meta.get("headline")} ({job["charged_credits"]} credits'
      + (", truncated)" if job.get("truncated") else ")"))
for l in lines:
    if l["k"] == "finding":
        print(f'  {l["item"]:<4} [{l["severity"]}/{l["urgency"]}] {l["do"]} -> {l["who"]}')
    elif l["k"] == "recheck":
        print(f'  {l["item"]:<4} {l["outcome"]}: {l["next"]}')
    elif l["k"] == "question":
        print(f'  ask {l["to"]}: {l["q"]}')
    elif l["k"] == "verdict":
        print(l["text"])
if not any(l["k"] == "end" for l in lines):
    print("(reply was cut short - every whole line above is still usable)")

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");
}
const idemKey = (input, attempt = 1) =>
  `roofline-walk:${input.task}:${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 meta = lines.find((l) => l.k === "meta") ?? {};
console.log(`${meta.verdict}: ${meta.headline} (${job.charged_credits} credits${job.truncated ? ", truncated" : ""})`);
for (const l of lines) {
  if (l.k === "finding") console.log(`  ${l.item.padEnd(4)} [${l.severity}/${l.urgency}] ${l.do} -> ${l.who}`);
  else if (l.k === "recheck") console.log(`  ${l.item.padEnd(4)} ${l.outcome}: ${l.next}`);
  else if (l.k === "question") console.log(`  ask ${l.to}: ${l.q}`);
  else if (l.k === "verdict") console.log(l.text);
}
if (!lines.some((l) => l.k === "end")) console.log("(reply was cut short - every whole line above is still usable)");

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

// ... in main(), after building payload in 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("report", 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")
}

for _, line := range strings.Split(job.Output.Output, "\n") {
	var l map[string]any
	if json.Unmarshal([]byte(line), &l) != nil || l["k"] == nil {
		continue // not a JSON line: ignore
	}
	switch l["k"] {
	case "meta":
		fmt.Printf("%v: %v (%d credits, truncated=%v)\n", l["verdict"], l["headline"], job.ChargedCredits, job.Truncated)
	case "finding":
		fmt.Printf("  %-4v [%v/%v] %v -> %v\n", l["item"], l["severity"], l["urgency"], l["do"], l["who"])
	case "recheck":
		fmt.Printf("  %-4v %v: %v\n", l["item"], l["outcome"], l["next"])
	case "question":
		fmt.Printf("  ask %v: %v\n", l["to"], l["q"])
	case "verdict":
		fmt.Println(l["text"])
	}
}

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(String task, String body, int attempt) {
    return "roofline-walk:" + task + ":" + fnv1a(body) + ":a" + attempt;
}

// ... after building payload in step 3:
String body = JSON.writeValueAsString(payload); // hash exactly what you send
String jobId = api("POST", "/run", body,
    Map.of("Idempotency-Key", idemKey("report", 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"));

for (String line : job.path("output").path("output").asText("").split("\\R")) {
    JsonNode l;
    try { l = JSON.readTree(line); } catch (Exception e) { continue; } // not JSON: ignore
    if (l == null || !l.has("k")) continue;
    switch (l.get("k").asText()) {
        case "meta" -> System.out.println(l.path("verdict").asText() + ": " + l.path("headline").asText()
            + " (" + job.get("charged_credits") + " credits, truncated=" + job.path("truncated").asBoolean() + ")");
        case "finding" -> System.out.printf("  %-4s [%s/%s] %s -> %s%n", l.path("item").asText(),
            l.path("severity").asText(), l.path("urgency").asText(), l.path("do").asText(), l.path("who").asText());
        case "recheck" -> System.out.printf("  %-4s %s: %s%n", l.path("item").asText(),
            l.path("outcome").asText(), l.path("next").asText());
        case "question" -> System.out.println("  ask " + l.path("to").asText() + ": " + l.path("q").asText());
        case "verdict" -> System.out.println(l.path("text").asText());
        default -> { }
    }
}

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(task, body, attempt = 1)
  "roofline-walk:#{task}:#{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[:task], 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"))
meta = lines.find { |l| l["k"] == "meta" } || {}
puts "#{meta["verdict"]}: #{meta["headline"]} (#{job["charged_credits"]} credits#{job["truncated"] ? ", truncated" : ""})"
lines.each do |l|
  case l["k"]
  when "finding"  then puts format("  %-4s [%s/%s] %s -> %s", l["item"], l["severity"], l["urgency"], l["do"], l["who"])
  when "recheck"  then puts format("  %-4s %s: %s", l["item"], l["outcome"], l["next"])
  when "question" then puts "  ask #{l["to"]}: #{l["q"]}"
  when "verdict"  then puts l["text"]
  end
end

function idem_key(string $task, string $body, int $attempt = 1): string {
    return "roofline-walk:$task:" . hash("fnv1a32", $body) . ":a$attempt"; // built-in 32-bit FNV-1a
}

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["task"], $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");

foreach (parse_lines($job["output"]["output"] ?? "") as $l) {
    switch ($l["k"]) {
        case "meta":
            echo "{$l['verdict']}: {$l['headline']} ({$job['charged_credits']} credits)\n"; break;
        case "finding":
            printf("  %-4s [%s/%s] %s -> %s\n", $l["item"], $l["severity"], $l["urgency"], $l["do"], $l["who"]); break;
        case "recheck":
            printf("  %-4s %s: %s\n", $l["item"], $l["outcome"], $l["next"]); break;
        case "question":
            echo "  ask {$l['to']}: {$l['q']}\n"; break;
        case "verdict":
            echo $l["text"], "\n"; break;
    }
}

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(string task, string body, int attempt = 1) =>
    $"roofline-walk:{task}:{Fnv1a(body)}:a{attempt}";

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

JsonElement job;
string status;
do
{
    await Task.Delay(1500);
    job = await RooflineWalk.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");

string S(JsonElement e, string name) => e.TryGetProperty(name, out var v) ? v.ToString() : "";
foreach (var line in job.GetProperty("output").GetProperty("output").GetString()!.Split('\n'))
{
    JsonElement l;
    try { l = JsonDocument.Parse(line).RootElement; } catch (JsonException) { continue; } // not JSON
    if (l.ValueKind != JsonValueKind.Object || !l.TryGetProperty("k", out var k)) continue;
    switch (k.GetString())
    {
        case "meta": Console.WriteLine($"{S(l, "verdict")}: {S(l, "headline")} ({job.GetProperty("charged_credits")} credits)"); break;
        case "finding": Console.WriteLine($"  {S(l, "item"),-4} [{S(l, "severity")}/{S(l, "urgency")}] {S(l, "do")} -> {S(l, "who")}"); break;
        case "recheck": Console.WriteLine($"  {S(l, "item"),-4} {S(l, "outcome")}: {S(l, "next")}"); break;
        case "question": Console.WriteLine($"  ask {S(l, "to")}: {S(l, "q")}"); break;
        case "verdict": Console.WriteLine(S(l, "text")); break;
    }
}

# a new attempt (:a2); re-sending step 4's :a1 key with the same body replays that run
curl -N -s -X POST "$API/run-stream" \
  -H "Authorization: Bearer $SKILLSAFE_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: roofline-walk:report:$HASH:a2" \
  -d "$BODY"

# event: job
# data: {"job_id":"job_..."}
#
# event: tick
# data: {"t":4}
#
# event: delta
# data: {"text":"{\"k\":\"meta\",\"task\":\"report\",\"verdict\":\"repair_soon\",..."}
#
# event: done
# data: {"job_id":"job_...","status":"succeeded","charged_credits":...,"truncated":false,"output":{"output":"...JSON Lines..."}}

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(payload["task"], body, attempt=2),  # :a1 would replay step 4
})
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 == "tick":
            pass                                     # heartbeat: data["t"] seconds so far
        elif event == "done":
            job = data.get("job", data)
        elif event == "error":
            raise RuntimeError(data.get("message", data))

lines = parse_lines(job["output"]["output"])  # parse the final text, not the deltas

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

const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buf = "", job = null;
for (;;) {
  const { value, done } = await reader.read();
  if (done) 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 === "tick") { /* heartbeat: d.t seconds so far */ }
    else if (name === "done") job = d.job ?? d;
    else if (name === "error") throw new Error(d.message ?? "stream error");
  }
}

const lines = parseLines(job.output.output); // parse the final text, not the deltas

req, _ := http.NewRequest("POST", API+"/run-stream", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", idemKey("report", body, 2)) // :a1 would replay step 4

res, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer res.Body.Close()

var done struct {
	Status         string `json:"status"`
	ChargedCredits int64  `json:"charged_credits"`
	Truncated      bool   `json:"truncated"`
	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":
			var d struct{ Text string `json:"text"` }
			json.Unmarshal(data, &d)
			fmt.Print(d.Text) // progress only
		case "done":
			json.Unmarshal(data, &done)
		case "error":
			log.Fatalf("stream error: %s", data)
		}
	}
}
// done.Output.Output is the JSON Lines reply: parse it as in step 4

String body = JSON.writeValueAsString(payload);
var req = HttpRequest.newBuilder(URI.create(API + "/run-stream"))
    .header("Authorization", "Bearer " + token)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", idemKey("report", body, 2)) // :a1 would replay step 4
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
var res = HTTP.send(req, HttpResponse.BodyHandlers.ofLines());

String event = "";
JsonNode job = 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(d.get("text").asText()); // progress only
            case "done"  -> job = d;
            case "error" -> throw new RuntimeException(d.toString());
            default      -> { } // job, tick
        }
    }
}
String reply = job.path("output").path("output").asText(); // parse it as in step 4

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(payload[:task], body, 2) # :a1 would replay step 4
req.body = body

job = 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 d["text"] # progress only
          when "done"  then job = d
          when "error" then raise d.to_s
          end
        end
      end
    end
  end
end

lines = parse_lines(job.dig("output", "output")) # parse the final text, not the deltas

$buf = ""; $event = null; $job = 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($payload["task"], $body, 2), // :a1 would replay step 4
    ],
    CURLOPT_WRITEFUNCTION => function ($ch, $chunk) use (&$buf, &$event, &$job, &$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 $d["text"];      // progress only
                elseif ($event === "done") $job = $d;
                elseif ($event === "error") $err = $d;
            }
        }
        return strlen($chunk);
    },
]);
curl_exec($ch);
curl_close($ch);
if ($err) throw new Exception(json_encode($err));

$lines = parse_lines($job["output"]["output"] ?? ""); // parse the final text, not the deltas

var req = new HttpRequestMessage(HttpMethod.Post, RooflineWalk.Api + "/run-stream")
{
    Content = new StringContent(body, Encoding.UTF8, "application/json"),
};
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", RooflineWalk.Token);
req.Headers.Add("Idempotency-Key", IdemKey("report", body, 2)); // :a1 would replay step 4

using var res = await RooflineWalk.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(JsonDocument.Parse(data).RootElement.GetProperty("text").GetString());
        else if (evt == "done") done = data;
        else if (evt == "error") throw new Exception(data);
    }
}

var final = JsonDocument.Parse(done!).RootElement;
var reply = final.GetProperty("output").GetProperty("output").GetString(); // parse it as in step 4