JEV integration

JEV LIVE connects the game to typesafe-ai/jev through the server-side Vercel AI Gateway evaluation endpoint. The browser sends telemetry to the local /api/decide route; it never receives the gateway key.

Enable JEV locally

1. Copy .env.example to .env and set AI_GATEWAY_API_KEY in the local server environment.
2. Run npm run dev, open http://127.0.0.1:4173/, and select JEV LIVE.
3. Confirm PILOT INTELLIGENCE shows JEV LIVE and the JEV responses counter increases. The header's ready state only confirms that a key is configured; it does not prove a successful live response.

The key stays server-side. The public static demo does not run this setup; use the local Node server for live requests.

What is evaluated

Each request contains bounded telemetry for the player, nearest live target, weapons, threats, mission status, and progress. JEV returns:

• one of six maneuvers: pursue, climb, descend, break left/right, or extend
• boolean fire, flare, and afterburner signals
• a 1–10 threat score and maneuver probabilities

Request lifecycle

The browser keeps physics running while one decision request is in flight. It waits at least 600 ms before the next request and accepts only a current source: "jev" decision. If the held decision is more than three seconds old, local control takes over; a response more than four seconds behind its telemetry is discarded.

The server validates telemetry, limits request bodies and client rate, applies an upstream deadline, and returns sanitized errors. Upstream HTTP 429 is represented as upstream_rate_limited; the local API limiter separately returns HTTP 429 with Retry-After.

Local assistance and limits

At startup, during the first response wait, after a failed request, or when a decision is stale, localDecision keeps the aircraft controllable. Three consecutive JEV failures switch the sortie to local mode. A sortie makes at most 120 live calls, and only one request is active at a time.

The static Pages demo cannot run the Node gateway or safely hold a secret. Use it for manual and local AI play; use the local server for JEV.

What live mode does not do

It does not make the browser a credential holder or replace the simulation clock. A successful JEV response is one input to the same bounded flight controller used by local play.

Evidence

The repository's recorded browser run and headless report are historical artifacts. They do not assert current provider availability or quota.