Drive Core-Hour Check from your own code

{
 "task": "draft",
 "brief": "Freely decaying two-dimensional turbulence in a doubly periodic square box of side 2*pi. Nondimensionalise lengths by L0 = box side / (2*pi) and velocities by U0 = the initial rms velocity, so times are in units of L0/U0. Start from seeded random noise with velo_max 0.5. Viscosity nu_2 = 1e-4 (Re = U0 L0 / nu = 10000). Observables: kinetic energy and enstrophy decay curves, and the energy spectrum at t = 10 and t = 20. I want a small pilot on my laptop first (8 cores, 16 GB RAM, 20 GB free disk, 30 minutes), then a production run at 1024x1024."
}

{
  "task": "draft",
  "headline": "A serial 128x128 doubly periodic ns2d pilot of freely decaying turbulence (seeded noise, nu_2 = 1e-4, t_end = 20), sized for the laptop budget ahead of the 1024x1024 study.",
  "plan": {
    "schema_version": "1.1",
    "solver": "ns2d",
    "parameters": {
      "nu_2": 0.0001,
      "oper": {"nx": 128, "ny": 128, "Lx": 6.283185307179586, "Ly": 6.283185307179586, "coef_dealiasing": 0.6666666666666666},
      "time_stepping": {"USE_CFL": true, "USE_T_END": true, "cfl_coef": 0.5, "deltat0": 0.01, "deltat_max": 0.05, "max_elapsed": "00:25:00", "t_end": 20, "type_time_scheme": "RK4"},
      "init_fields": {"type": "noise", "noise": {"length": 1.0, "velo_max": 0.5}},
      "forcing": {"enable": false, "...": "..."},
      "output": {"HAS_TO_SAVE": true, "ONLINE_PLOT_OK": false, "periods_save": {"phys_fields": 5, "spatial_means": 0.1, "spectra": 10, "...": "..."}, "...": "..."}
    },
    "scientific": {
      "units_or_nondimensionalization": "Lengths by L0 = box side / (2*pi), velocities by U0 = the initial rms velocity, times by L0/U0.",
      "boundary_conditions": "Doubly periodic square box of side 2*pi in x and y; no walls.",
      "...": "seven more statements in the user's physics"
    },
    "resources": {"cpu_cores": 1, "mpi_ranks": 1, "threads_per_rank": 1, "ram_gib": 16, "disk_gib": 20, "wall_time_minutes": 30, "max_output_files": 200},
    "execution": {"mode": "serial", "output_root": "fluidsim-runs", "random_seed": 12345, "script_name": "run_decay2d_pilot.py"},
    "provenance": {"config_id": "replace-with-config-id", "created_utc": "replace-with-created-utc", "dependency_lock_sha256": "replace-with-uv-lock-sha256", "fluidfft": "0.4.5", "fluidsim": "0.9.0", "python": "3.11"}
  },
  "assumptions": [
    {"field": "parameters.oper.nx", "value": "128", "why": "The brief gives no pilot grid; 128 fits a serial laptop run and leaves 1024x1024 for later."},
    {"field": "parameters.init_fields.noise.length", "value": "1.0", "why": "The brief gives velo_max but not the noise length."},
    {"field": "provenance.config_id", "value": "replace-with-config-id", "why": "Unknown provenance; fill before running."},
    "... one entry per chosen value: grid, domain, viscosity, time bounds, save periods, resources"
  ],
  "open_questions": [
    "Which intermediate grids (for example 256x256 and 512x512) should precede the 1024x1024 run?"
  ],
  "changes": []
}

{
 "task": "review",
 "plan": "{\n  \"schema_version\": \"1.1\",\n  \"solver\": \"ns2d.strat\",\n  \"parameters\": {\n    \"nu_2\": 0.001,\n    ... the whole plan: parameters, scientific, resources, execution, provenance ...\n    \"python\": \"3.11\"\n  }\n}",
 "facts": "{\"page\":\"core-hour-check\",\"skill_tools\":\"solver_config_validator.py, grid_resource_estimator.py, simulation_dry_run.py (fluidsim skill, run in the browser)\",\"plan_sha256\":\"0f9e49ad...\",\"validator\":{\"exit\":0,\"ok\":true,\"errors\":[],\"warnings\":[],\"numerical_convergence_established\":false,\"physical_validity_established\":false},\"estimator\":{\"exit\":0,\"ok\":true,\"limits\":{\"files_within_bound\":true,\"memory_within_bound\":true,\"storage_within_bound\":true},\"estimates\":{\"peak_memory_gib\":0.005196,\"storage_gib\":0.005466,\"estimated_output_files\":13,...},\"grid_points\":8192,...},\"dryrun\":{\"exit\":0,\"script_name\":\"run_strat_pilot.py\",\"script_sha256\":\"3475f8d6...\",...,\"job_submitted\":false},\"derived\":{\"solver\":\"ns2d.strat\",\"dimensions\":2,\"grid\":[{\"axis\":\"x\",\"n\":128,\"L\":6.28319,\"dx\":0.04909,\"kmax_after_truncation\":42.67},{\"axis\":\"y\",\"n\":64,\"L\":3.14159,\"dx\":0.04909,\"kmax_after_truncation\":42.67}],\"min_steps\":200,...},\"flags\":[],\"browser_verdict\":\"ready_for_pilot\"}",
 "notes": "Freely evolving internal gravity waves from noise; this pilot comes before a 256x128 run."
}

{
  "task": "review",
  "verdict": "ready_for_pilot",
  "headline": "The plan passes the validator with wide resource margins; it can go to its one tiny serial pilot, but it names no benchmark to interpret results against.",
  "flag_responses": [],
  "gate": [
    {"item": "units", "status": "addressed", "evidence": "Lengths scaled by Ly/pi and time by 1/N with N = 1", "note": "Tied to parameters.N and parameters.oper.Ly."},
    {"item": "boundaries", "status": "addressed", "evidence": "Periodic in x and y", "note": "Matches the solver's periodic box."},
    {"item": "initial_conditions", "status": "addressed", "evidence": "Seeded low-amplitude noise, velo_max=0.01, seed 12345", "note": "Matches parameters.init_fields.noise.velo_max and execution.random_seed."},
    {"item": "forcing", "status": "addressed", "evidence": "Unforced", "note": "Matches parameters.forcing.enable = false."},
    {"item": "resolution", "status": "addressed", "evidence": "128x64 pilot with cubic 2/3 truncation", "note": "facts.derived gives dx 0.04909 and kmax_after_truncation 42.67 on both axes."},
    {"item": "timestep", "status": "addressed", "evidence": "Adaptive CFL 0.3 with deltat_max 0.01", "note": "facts.derived.min_steps 200 is a floor; the CFL may take smaller steps."},
    {"item": "budgets", "status": "addressed", "evidence": "check the residual in spatial means", "note": "periods_save.spatial_means 0.01 is on."},
    {"item": "refinement", "status": "addressed", "evidence": "Repeat at 256x128 and with half deltat_max", "note": "Concrete refinement targets."},
    {"item": "benchmark", "status": "missing", "evidence": "", "note": "No analytical, manufactured, published or independent comparison is named."},
    {"item": "acceptance", "status": "addressed", "evidence": "Energy residual trend below 1 percent", "note": "Quantified and tied to the refinement run."},
    {"item": "resources", "status": "addressed", "evidence": "peak_memory_gib 0.005196 vs ram_gib 4.0", "note": "Storage 0.005466 GiB vs disk_gib 2.0 and 13 files vs 64 also fit."},
    {"item": "provenance", "status": "addressed", "evidence": "config_id strat-pilot-2026-09-27", "note": "No placeholder ids; fluidsim 0.9.0 and fluidfft 0.4.5 pinned."}
  ],
  "concerns": [
    {"severity": "medium", "issue": "No benchmark comparison appears in any scientific statement.", "fix": "Name the comparison target in scientific.convergence_and_refinement before results are interpreted."}
  ],
  "pilot_checks": [
    "CFL and deltat history against deltat_max 0.01.",
    "Energy budget residual from spatial_means, divergence, spectral tail near kmax 42.67, file count against 13, NaN/Inf."
  ],
  "questions": ["Which benchmark should the 256x128 results be compared with?"],
  "not_established": ["Numerical convergence.", "Physical validity.", "Any runtime: facts.estimator.runtime_estimated is false."]
}

// make-body.js - build the exact body the page sends, with the page's own code.
//   node make-body.js review plan.json "notes" "question"             > body.json
//   node make-body.js draft  brief.txt "notes" "question"             > body.json
//   node make-body.js draft  brief.txt "review text" "" plan.json     > body.json   (revise plan.json)
const fs = require("fs");
const K = require("./deskkit.js");                     // runs fluidkit.js: validator, estimator, dry run
const [lane, file, notes = "", question = "", revisePlan = ""] = process.argv.slice(2);
const read = (p) => (p ? fs.readFileSync(p, "utf8") : "");
let A = null;
const set = { notes, question };
if (lane === "review") {
  A = K.analyze(read(file), { name: "config.json" });
} else {
  set.brief = read(file);
  if (revisePlan) { A = K.analyze(read(revisePlan), { name: "config.json" }); set.revise = true; }
}
const body = K.buildInput(lane, A, set);
if (!body) throw new Error("nothing to send: review needs a plan, draft a brief or a plan (plans up to 40,000 characters)");
K.mustBeObject(body);
if (A) console.error("browser verdict:", A.verdict, "| flags:", A.flags.map((f) => f.id + " " + f.kind).join(", ") || "none");
console.error("idempotency key: core-hour-check:" + body.task + ":" + K.hashInput(body) + ":a1");
process.stdout.write(JSON.stringify(body));

# Or build the body in any language. Only a draft from a brief needs no facts;
# every plan must travel with the facts the page computed for it, as a STRING.
import json

body = {
    "task": "draft",
    "brief": open("brief.txt").read(),
    "notes": "Laptop first; production later.",
}
json.dump(body, open("body.json", "w"))

{"ok": true, "data": {"job_id": "job_...", "status": "queued"}}
{"ok": false, "error": {"code": "payment_required", "message": "..."}}

# Every call is the same three things: the base URL, your bearer token,
# and a JSON body. Keep the token in a shell variable.
BASE="https://api.skillsafe.ai/v1/app-api"
SLUG="core-hour-check"
TOKEN="$SKILLSAFE_TOKEN"   # from https://core-hour-check.skillsafe.ai/tokens.html

call() {                  # call <path> [json-body]
  if [ -n "$2" ]; then
    curl -sS -X POST "$BASE/$1" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d "$2"
  else
    curl -sS "$BASE/$1" -H "Authorization: Bearer $TOKEN"
  fi
}

# The token page is the shortest path. It shows the token this browser holds and
# hands you a ready-made shell export:
#
#   https://core-hour-check.skillsafe.ai/tokens.html
#   export SKILLSAFE_TOKEN="..."
#
# To mint a guest token from the command line instead. A guest token is enough
# for /me and /estimate; a run needs a personal token from signing in.
curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/guest" \
  -H "Content-Type: application/json" -d '{"slug":"core-hour-check"}'
# {"ok":true,"data":{"token":"...","subject_type":"guest"}}

call me
# {"ok":true,"data":{"subject_type":"user","username":"you","credits":51234}}

# body.json is the input object itself - no {"input": ...} wrapper. Build it with
# make-body.js above, or by hand. estimate does not validate it, so check the shape first:
python3 -c '
import json
b = json.load(open("body.json"))
assert isinstance(b, dict) and b.get("task") in ("draft", "review")
assert all(isinstance(v, str) for v in b.values())
if b["task"] == "review" or b.get("plan"):
    assert b.get("plan", "").strip() and isinstance(json.loads(b.get("facts", "")), dict)
else:
    assert b.get("brief", "").strip()
'
INPUT=$(cat body.json)

call estimate "$INPUT"
# {"ok":true,"data":{"model":"...","model_alias":"gpt-terra",
#   "markup_bps":1000,"hold_credits":...,"min_credits":...,"sponsor_enabled":false,
#   "warnings":[]}}
#
# estimate creates no job and charges nothing. hold_credits is RESERVED, not the
# price; charged_credits after the run is the actual cost, usually far lower.

# Always send an Idempotency-Key derived from the input. A retried request with
# the same key returns the SAME job instead of billing a second run.
LANE=$(printf '%s' "$INPUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["task"])')   # draft or review
KEY="core-hour-check:$LANE:$(printf '%s' "$INPUT" | shasum -a 256 | cut -c1-16):a1"

JOB=$(curl -sS -X POST "$BASE/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d "$INPUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["job_id"])')

while :; do
  OUT=$(call "jobs/$JOB")
  STATUS=$(printf '%s' "$OUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["status"])')
  [ "$STATUS" = "succeeded" ] && break
  [ "$STATUS" = "failed" ] && echo "$OUT" && exit 1
  sleep 2
done

# {"ok":true,"data":{"job_id":"job_...","status":"succeeded",
#   "output":{"output":"{\"task\":\"review\",\"verdict\":\"ready_for_pilot\",\"headline\":\"...\", ...}"},
#   "charged_credits":...,"truncated":false}}
printf '%s' "$OUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["output"]["output"])' > reply.json

# Server-sent events. `delta` events carry chunks of the reply; `done` carries the
# status, charged_credits and the truncated flag. Ignore `tick` heartbeats.
curl -N -X POST "$BASE/run-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -H "Accept: text/event-stream" \
  -d "$INPUT"

# event: job    {"job_id":"job_..."}
# event: delta  {"text":"{\"task\":\"review\",\"verdict\":\"ready_for_pilot\",\"headline\":\"The"}
# event: done   {"status":"succeeded","charged_credits":...,"truncated":false}

# The reply is a JSON string inside data.output.output. Pull it out and parse it:
printf '%s' "$OUT" | python3 -c 'import sys,json;r=json.loads(json.load(sys.stdin)["data"]["output"]["output"]);print(r["task"],r.get("verdict",""),r["headline"])'
# A draft: save the plan and re-check it with the skill's own tools.
python3 -c 'import json;r=json.load(open("reply.json"));json.dump(r["plan"],open("config.json","w"),indent=2)'
python3 scripts/solver_config_validator.py --config config.json