polish: friendlier error messages with provider and HTTP context

[JNK234]

Roadmap priority: B15

Summary

Surface provider and HTTP context in error messages so modelers can diagnose failures without reading extension source.

Why it matters

Errors currently reach the modeler as generic ExtensionException text. A student whose key is wrong, whose Ollama server is down, or who is being rate limited sees roughly the same unhelpful message and has no next step.

This is a small change with outsized effect in classroom and workshop settings, which is where most first-time failures happen.

What needs to be done

1. Audit current error paths in BaseHttpProvider and each provider's parseProviderResponse — catalogue what the modeler actually sees today for: bad key, no key, wrong model name, 429, 5xx, timeout, Ollama not running, network unreachable.
2. For each, produce a message naming the provider, the HTTP status where relevant, and a concrete next action ("check llm:provider-status", "run ollama serve", "the model name is not in the registry — try llm:list-models").
3. Never leak the API key into an error string.
4. Reuse the per-provider helpText already in ProviderDescriptor rather than duplicating setup guidance.
5. Rate-limit exhaustion after retries already has a decent message (executeWithRetry) — use it as the template.

Open questions

• How much detail is too much for a NetLogo dialog box? Possibly a one-line message plus fuller detail to stderr.

[JNK234]

Concrete repro (28 Jul 2026)

Setting a retired Gemini model and calling llm:chat surfaces the provider's raw JSON envelope straight into the NetLogo error dialog:

Extension exception: LLM chat failed: HTTP request failed: {
  "error": {
    "code": 404,
    "message": "This model models/gemini-2.5-flash is no longer available to new users. Please update your code to use a newer model for the latest features and improvements.",
    "status": "NOT_FOUND"
  }
}

Cause

BaseHttpProvider.executeWithRetry has a decent message for rate limits but a catch-all for everything else that interpolates the response body verbatim (BaseHttpProvider.scala:194):

case Left(error) if isRateLimited(response.code, error) =>
  Future.failed(new RuntimeException(
    s"HTTP request failed after ${MaxRetries + 1} attempts " +
    s"(rate limited, HTTP ${response.code.code}): $error"))
case Left(error) =>
  Future.failed(new RuntimeException(s"HTTP request failed: $error"))   // <-- raw body

So 404, 401, 400, and all 5xx responses reach the modeler as unparsed provider JSON. Note the status code is available in response.code and is already used on the rate-limit path — it is simply dropped on the general path.

What a good message would look like

Gemini rejected model 'gemini-2.5-flash' (HTTP 404): no longer available
to new users. Run llm:list-models to see available models.

Provider name, status code, the provider's own explanation, and a next action.

Implementation note

Each provider wraps errors differently, so this likely wants a parseErrorMessage(body: String): Option[String] hook alongside the existing parseProviderResponse:

• Gemini / OpenAI / OpenRouter / Together — error.message
• Anthropic — error.message
• Ollama — plain-string error field

Since OpenAICompatibleProvider is shared by three providers, one default implementation there plus Gemini/Anthropic/Ollama overrides covers all six. Fall back to the raw body when parsing fails, so no error is ever swallowed.

Related

#62 — three provider defaults are missing from the bundled registry, which makes a model-not-found error the first thing a new user hits. That bug and this one compound: a wrong default produces the worst-formatted error in the codebase.