chore: repin gadfly reusable to @5007597 (structured findings + consensus + inline review)

Adopts gadfly's review-representation overhaul: one ranked consensus comment
across the swarm + an advisory COMMENT-state inline PR review, on image
sha-3095ebf. Swarm config still rides the owner variables.

[skip ci]

.gitea/workflows/adversarial-review.yml

@@ -1,12 +1,8 @@
-# Gadfly — agentic adversarial PR reviewer (https://gitea.stevedudenhoeffer.com/steve/gadfly).
-#
-# Runs the published Gadfly image (pinned to an immutable :sha- tag — act_runner
-# caches :latest, and this build is what carries foreman provider-type support)
-# as a specialist swarm and posts
-# ONE consolidated review comment as gitea-actions. Advisory only — never blocks a
-# merge. This reviews majordomo PRs with 9 ollama-cloud models + the M5 Mac
-# (3-lens suite). Gadfly is a simple system — findings are advisory; always
-# double-check before acting.
+# Gadfly adversarial review — subscribes to steve/gadfly's reusable workflow and
+# INHERITS its default swarm. This stub holds only the triggers, the actor gate,
+# secret forwarding, and the allow-list; the swarm config (models, lenses,
+# concurrency, timeouts) lives centrally in gadfly's review-reusable.yml so it is
+# tuned in ONE place. Advisory only — never blocks a merge.
 
 name: Adversarial Review (Gadfly)
 
@@ -33,60 +29,26 @@ concurrency:
 jobs:
   review:
     # Security: only trusted users may trigger a secret-bearing run via a PR
-    # comment (pull_request + workflow_dispatch are already trusted). Mirrors
-    # GADFLY_ALLOWED_USERS, the in-container belt-and-suspenders check.
+    # comment (pull_request + workflow_dispatch are already trusted). Mirrors the
+    # allowed_users input below (the in-container belt-and-suspenders check) — both
+    # lists must stay in sync; a workflow if: can't read a workflow_call input.
     if: >-
       github.event_name != 'issue_comment'
       || (github.event.issue.pull_request
           && (github.actor == 'steve'
               || github.actor == 'fizi'
               || github.actor == 'dazed'))
-    runs-on: ubuntu-latest
-    # Fleet: 9 cloud (lens fan-out) + the M5 Mac via foreman. The slow local
-    # lane dominates wall time, so allow plenty of headroom. (M1 was dropped —
-    # consistently slow for zero real findings.)
-    timeout-minutes: 90
-    steps:
-      - uses: docker://gitea.stevedudenhoeffer.com/steve/gadfly:sha-d7f364d
-        env:
-          GITEA_API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
-          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
-          OLLAMA_CLOUD_API_KEY: ${{ secrets.OLLAMA_CLOUD_API_KEY }}
-          # Local Mac, reached through its foreman queue (native Ollama on the
-          # wire). GADFLY_ENDPOINT_M5 registers provider "m5", a foreman-preset
-          # Ollama client at the secret's URL, of the form:
-          #   foreman|https://<foreman-host>|<token>
-          # Needs an image with foreman provider-type support (this one). If the Mac
-          # is offline that model's comment shows an error and the others still post.
-          # (Gitea secrets aren't auto-exposed — map each explicitly.)
-          GADFLY_ENDPOINT_M5: ${{ secrets.GADFLY_ENDPOINT_M5 }}
-          # Fleet: 9 cloud + M5 Max. Cloud concurrency lives in the LENSES: cloud
-          # models run a few at a time (ollama-cloud=3) with their 3 lenses
-          # concurrent (LENS ollama-cloud=3) so comments land sooner; the Mac runs
-          # one model, lenses serial (its foreman queue serializes anyway). Both
-          # provider lanes run parallel.
-          GADFLY_MODELS: "minimax-m3:cloud,glm-5.2:cloud,glm-5.1:cloud,kimi-k2.7-code:cloud,deepseek-v4-pro:cloud,nemotron-3-super:cloud,gpt-oss:120b-cloud,qwen3-coder:480b-cloud,gemma4:cloud,m5/qwen3.6:35b-mlx"
-          GADFLY_PROVIDER_CONCURRENCY: "ollama-cloud=3,m5=1"
-          GADFLY_PROVIDER_LENS_CONCURRENCY: "ollama-cloud=3"
-          # Default => the 3-lens suite (security, correctness, error-handling).
-          # Set the repo var GADFLY_SPECIALISTS to override (csv / "all" / "auto").
-          GADFLY_SPECIALISTS: ${{ vars.GADFLY_SPECIALISTS || 'security,correctness,error-handling' }}
-          # Per-lens deadline + bounded steps so the slow local models stay sane.
-          GADFLY_TIMEOUT_SECS: "600"
-          GADFLY_MAX_STEPS: "14"
-          # Allow-list for the comment trigger (mirrors the job-level if: guard).
-          GADFLY_ALLOWED_USERS: "steve,fizi,dazed"
-          # --- findings telemetry: POST runs + findings to the gadfly-reports store ---
-          # Advisory & off unless GADFLY_FINDINGS_URL is set; failures only log to
-          # stderr and never affect the review. GADFLY_REPO / GADFLY_PR are derived
-          # in-container; the URL + token are user-scope secrets.
-          GADFLY_FINDINGS_URL: ${{ secrets.GADFLY_FINDINGS_URL }}
-          GADFLY_FINDINGS_TOKEN: ${{ secrets.GADFLY_FINDINGS_TOKEN }}
-          # --- event context (leave as-is) ---
-          EVENT_NAME: ${{ github.event_name }}
-          PR: ${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
-          PR_BRANCH: ${{ github.head_ref }}
-          IS_DRAFT: ${{ github.event.pull_request.draft }}
-          COMMENT_BODY: ${{ github.event.comment.body }}
-          COMMENT_ID: ${{ github.event.comment.id }}
-          ACTOR: ${{ github.actor }}
+    # Tracks gadfly's v1 release tag — a curated pointer re-moved on each release
+    # (unlike @main, which moves on every push). Central swarm tuning propagates
+    # here automatically; the tradeoff vs a full sha pin is that v1 is mutable.
+    uses: steve/gadfly/.gitea/workflows/review-reusable.yml@5007597cf921dc3f0a83c708878facfe65fd8e8b
+    # Least privilege: forward only the review secrets (not `secrets: inherit`,
+    # which would expose every repo secret). GITEA_TOKEN is the automatic token.
+    secrets:
+      OLLAMA_CLOUD_API_KEY:    ${{ secrets.OLLAMA_CLOUD_API_KEY }}
+      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+      GADFLY_FINDINGS_URL:     ${{ secrets.GADFLY_FINDINGS_URL }}
+      GADFLY_FINDINGS_TOKEN:   ${{ secrets.GADFLY_FINDINGS_TOKEN }}
+    with:
+      # Consumer-specific allow-list; everything else is inherited.
+      allowed_users: "steve,fizi,dazed"

CLAUDE.md

@@ -32,6 +32,8 @@ mort-agnostic: no mort types, no Discord, no mort config.
 majordomo        Registry, Parse, env-DSN loading, chain executor, re-exports
   llm/           canonical contract: Message/Part/Request/Response/Option,
                  Tool/Toolbox, Capabilities, Stream, Model, Provider, errors
+  imagegen/      canonical text-to-image contract: Request/Result/Model/
+                 Provider (separate from llm; Image = llm.ImagePart)  (ADR-0016)
   health/        clock-injected health tracker (bench/backoff)
   media/         image normalization to target capabilities (sniff real
                  format, downscale, transcode, byte ladder; ErrUnsupported
@@ -41,6 +43,8 @@ majordomo        Registry, Parse, env-DSN loading, chain executor, re-exports
   provider/anthropic/ Messages API client (+ Anthropic-compat targets)
   provider/ollama/    one native /api/chat client serving the ollama,
                       ollama-cloud, and foreman built-ins via presets
+  provider/llamaswap/ llama-swap proxy: chat delegates to provider/openai,
+                      plus management methods + imagegen image client (ADR-0015)
   provider/google/    Gemini on google.golang.org/genai (the one approved
                       dependency; lazy client, raw-JSON-schema tools,
                       ThinkingLevel reasoning, iter.Pull2 streaming)
@@ -75,10 +79,13 @@ alias   := bare token (no slash), expands INLINE, recursively, cycle-checked
 `LLM_<NAME>=scheme://[token@]host[/path]` — e.g.
 `LLM_M5=foreman://token@foreman-m5.example` defines provider `m5`; then
 `m5/qwen3:30b` works in Parse, chains, and aliases. Scheme ∈ {foreman,
-ollama, ollama-cloud, openai, anthropic, google, gemini} ∪ RegisterScheme.
-Token = credential; base URL = `https://host` always. `New()` scans the
-process env eagerly; unknown names also resolve lazily at Parse time
-(`my-prov` → `LLM_MY_PROV`). Malformed entries fail on use, not at startup.
+ollama, ollama-cloud, openai, anthropic, google, gemini, llama-swap,
+llama-swaps} ∪ RegisterScheme. Token = credential; base URL = `https://host`
+always — **except `llama-swap`, which builds `http://host` (local-first);
+`llama-swaps` is its TLS twin (`https://host`), mirroring redis/rediss
+(ADR-0015).** `New()` scans the process env eagerly; unknown names also resolve
+lazily at Parse time (`my-prov` → `LLM_MY_PROV`). Malformed entries fail on use,
+not at startup.
 
 ## Health & failover (ADR-0006, ADR-0008)
 
@@ -135,9 +142,11 @@ Ship work through PRs and let Gadfly review it before merge:
 
 - **Push to a PR, never straight to `main`.** Branch, push, open a PR.
   `.gitea/workflows/adversarial-review.yml` runs Gadfly (the standalone
-  agentic adversarial reviewer) — a full fleet of 9 ollama-cloud models +
-  the M1/M5 Macs via foreman, each running the 3-lens suite (security,
-  correctness, error-handling). Advisory only; it never blocks the merge.
+  agentic adversarial reviewer) by subscribing to gadfly's reusable workflow
+  and inheriting its default swarm — 3 cloud models + the Claude Code engine
+  (sonnet/opus/opus:max), each running the 5-lens suite (security, correctness,
+  maintainability, performance, error-handling). The swarm is tuned centrally
+  in gadfly, not here. Advisory only; it never blocks the merge.
 - **Wait for Gadfly to finish, then read its output.** Don't merge while the
   review is still running. Each model posts one consolidated comment; weigh
   every finding on its merits and fix the real ones (Gadfly is a simple

README.md

@@ -126,6 +126,7 @@ Chains are health-tracked per target:
 | Ollama Cloud | `ollama-cloud` | `OLLAMA_API_KEY` | https://ollama.com |
 | Ollama (local) | `ollama` | — | `OLLAMA_HOST` or http://localhost:11434 |
 | foreman | `foreman` | — (token via DSN) | requires an LLM_* DSN or `ollama.Foreman(url, token)` |
+| llama-swap | `llama-swap` | — (token via DSN) | requires an LLM_* DSN or `llamaswap.New(...)` |
 
 OpenAI-compatible / Anthropic-compatible endpoints: construct the provider
 with a name and base URL and register it —
@@ -158,11 +159,25 @@ m, _ := reg.Parse("m5/qwen3:30b,m1/qwen3:30b,thinking")
 ```
 
 DSN format: `scheme://[token@]host[/path]`, scheme ∈ `foreman`, `ollama`,
-`ollama-cloud`, `openai`, `anthropic`, `google`/`gemini`, or any scheme you
-add with `RegisterScheme`. The token is the credential (bearer token / API
-key); the base URL is always `https://host[/path]`. `New()` loads `LLM_*`
-vars eagerly; unknown provider names also resolve lazily at Parse time
-(`my-prov/x` → `LLM_MY_PROV`).
+`ollama-cloud`, `openai`, `anthropic`, `google`/`gemini`, `llama-swap`,
+`llama-swaps`, or any scheme you add with `RegisterScheme`. The token is the
+credential (bearer token / API key); the base URL is always `https://host[/path]`
+— except `llama-swap`, which builds `http://host[:port]` since it's local-first
+(`llama-swaps` is the TLS twin → `https://host`, mirroring redis/rediss). `New()`
+loads `LLM_*` vars eagerly; unknown provider names also resolve lazily at Parse
+time (`my-prov/x` → `LLM_MY_PROV`).
+
+```
+LLM_LS=llama-swap://token@box.local:8080    # http  → "ls/qwen3:14b" parses
+LLM_LS=llama-swaps://token@swap.example.com # https → TLS-fronted instance
+```
+
+[llama-swap](https://github.com/mostlygeek/llama-swap) is a model-swapping proxy
+over llama.cpp. Its chat API is OpenAI-compatible (majordomo reuses the openai
+client), and the `*llamaswap.Provider` adds management methods
+(`ListModels`/`Running`/`Unload`) plus image generation (see below). A cold
+model swap can take many seconds — bound calls with a context deadline, not a
+client timeout.
 
 ### Custom providers
 
@@ -191,6 +206,27 @@ resp, err := m.Generate(ctx, majordomo.Request{
 })
 ```
 
+## Image generation
+
+Text-to-image is a separate contract (`imagegen`) from chat, because it shares
+none of the message/tool/stream machinery. Generated images come back as
+`llm.ImagePart`, so they drop straight back into a chat turn. The first backend
+is llama-swap (OpenAI `/v1/images/generations` → a stable-diffusion.cpp
+upstream).
+
+```go
+ls := llamaswap.New(llamaswap.WithBaseURL("http://box.local:8080"))
+im, _ := ls.ImageModel("sd-xl")
+
+res, err := im.Generate(ctx, imagegen.Request{Prompt: "a red bicycle"},
+    imagegen.WithSize("1024x1024"))
+// res.Images[0] is an llm.ImagePart (bytes + MIME) — feed it back into chat:
+// majordomo.UserParts(majordomo.Text("describe this"), res.Images[0])
+```
+
+`*llamaswap.Provider` also exposes management methods: `ListModels` (what
+llama-swap can serve), `Running` (what's loaded), and `Unload` (free a model).
+
 ## Tool calls
 
 ```go
@@ -312,12 +348,19 @@ to build one.
 | Ollama Cloud | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Ollama (local) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | foreman | ✅ | ✅ | ✅¹ | ✅ | ✅ | ✅ | ✅ |
+| llama-swap | ✅ | ✅ | ✅ | ✅² | ✅² | ✅² | ✅ |
 | fake (testing) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
 
 ¹ foreman's daemon currently buffers sync chat responses (no token-by-token
 streaming); majordomo's stream API works against it and delivers the
 response as a single delta plus final event.
 
+² llama-swap's chat is OpenAI-compatible and reuses the openai client, so these
+capabilities are present at the client level; whether a given call succeeds
+depends on the llama.cpp model llama-swap loads. llama-swap also provides
+**image generation** (a separate `imagegen` axis, not shown above) and
+management methods on `*llamaswap.Provider`.
+
 Notes: Ollama has no native tool_choice — `"none"` drops the tools;
 `"required"`/named choices are best-effort ignored there. Ollama Cloud
 ignores the `format` field (verified live), so the provider also states

builtin.go

@@ -6,6 +6,7 @@ import (
 	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
 	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/anthropic"
 	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/google"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/llamaswap"
 	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/ollama"
 	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/openai"
 )
@@ -18,6 +19,13 @@ const (
 	ProviderOllama      = "ollama"
 	ProviderOllamaCloud = "ollama-cloud"
 	ProviderForeman     = "foreman"
+	ProviderLlamaSwap   = "llama-swap"
+	// ProviderLlamaSwapTLS is the DSN scheme for a TLS-fronted llama-swap
+	// (https base URL). It is a scheme only, not a default built-in provider
+	// name. Why a separate scheme rather than auto-detecting: a DSN carries no
+	// reliable signal for http vs https, so the choice is explicit
+	// (llama-swap = http local-first, llama-swaps = https), mirroring rediss.
+	ProviderLlamaSwapTLS = "llama-swaps"
 )
 
 // registerBuiltins installs the built-in providers and env-DSN scheme
@@ -66,6 +74,31 @@ func registerBuiltins(r *Registry, httpClient *http.Client) {
 		)...), nil
 	}
 
+	// llama-swap: OpenAI-compatible chat + image generation + management
+	// endpoints over a model-swapping proxy. Chat reuses the openai client
+	// (provider/llamaswap delegates). Two schemes: "llama-swap" builds an
+	// http:// base URL (local-first default), "llama-swaps" builds https://
+	// for a TLS-fronted instance (mirrors redis/rediss). The no-DSN built-in
+	// errors on use with a clear message, mirroring foreman.
+	llamaSwapOpts := func(extra ...llamaswap.Option) []llamaswap.Option {
+		if httpClient != nil {
+			extra = append(extra, llamaswap.WithHTTPClient(httpClient))
+		}
+		return extra
+	}
+	llamaSwapScheme := func(urlScheme string) SchemeFactory {
+		return func(name string, dsn DSN) (llm.Provider, error) {
+			return llamaswap.New(llamaSwapOpts(
+				llamaswap.WithName(name),
+				llamaswap.WithBaseURL(urlScheme+"://"+dsn.Host),
+				llamaswap.WithToken(dsn.Token),
+			)...), nil
+		}
+	}
+	r.providers[ProviderLlamaSwap] = llamaswap.New(llamaSwapOpts(llamaswap.WithName(ProviderLlamaSwap))...)
+	r.schemes[ProviderLlamaSwap] = llamaSwapScheme("http")
+	r.schemes[ProviderLlamaSwapTLS] = llamaSwapScheme("https")
+
 	// Anthropic and Anthropic-compatible endpoints.
 	anthropicOpts := func(extra ...anthropic.Option) []anthropic.Option {
 		if httpClient != nil {

builtin_llamaswap_test.go

@@ -0,0 +1,87 @@
+package majordomo
+
+import (
+	"testing"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/imagegen"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/llamaswap"
+)
+
+// TestLlamaSwapScheme covers the env-DSN wiring: a llama-swap:// DSN defines a
+// named provider that builds an http:// base URL (local-first, unlike the
+// https-always default), is first-class in Parse, and satisfies both the chat
+// (llm.Provider) and image (imagegen.Provider) contracts.
+func TestLlamaSwapScheme(t *testing.T) {
+	r := newTestRegistry(t)
+	if err := r.LoadEnv(map[string]string{
+		"LLM_LS": "llama-swap://tok@box.local:8080",
+	}); err != nil {
+		t.Fatalf("LoadEnv: %v", err)
+	}
+
+	p, ok := r.Provider("ls")
+	if !ok {
+		t.Fatal("provider \"ls\" not registered")
+	}
+	lp, ok := p.(*llamaswap.Provider)
+	if !ok {
+		t.Fatalf("provider is %T, want *llamaswap.Provider", p)
+	}
+	if lp.Name() != "ls" {
+		t.Errorf("name = %q, want ls", lp.Name())
+	}
+	// Local-first: http, not the DSN's https-always BaseURL.
+	if want := "http://box.local:8080"; lp.BaseURL() != want {
+		t.Errorf("baseURL = %q, want %q", lp.BaseURL(), want)
+	}
+
+	// Satisfies the image-generation contract too.
+	var _ imagegen.Provider = lp
+	if _, err := lp.ImageModel("sd"); err != nil {
+		t.Errorf("ImageModel: %v", err)
+	}
+
+	// First-class chain element.
+	m, err := r.Parse("ls/qwen3:14b")
+	if err != nil {
+		t.Fatalf("Parse: %v", err)
+	}
+	if got := targetsOf(t, m); len(got) != 1 || got[0] != "ls/qwen3:14b" {
+		t.Errorf("targets = %v", got)
+	}
+}
+
+// TestLlamaSwapsScheme: the "llama-swaps" scheme builds an https base URL for a
+// TLS-fronted instance (vs "llama-swap" which is http local-first).
+func TestLlamaSwapsScheme(t *testing.T) {
+	r := newTestRegistry(t)
+	if err := r.LoadEnv(map[string]string{
+		"LLM_LST": "llama-swaps://tok@swap.example.com",
+	}); err != nil {
+		t.Fatalf("LoadEnv: %v", err)
+	}
+	p, ok := r.Provider("lst")
+	if !ok {
+		t.Fatal("provider \"lst\" not registered")
+	}
+	lp, ok := p.(*llamaswap.Provider)
+	if !ok {
+		t.Fatalf("provider is %T, want *llamaswap.Provider", p)
+	}
+	if want := "https://swap.example.com"; lp.BaseURL() != want {
+		t.Errorf("baseURL = %q, want %q", lp.BaseURL(), want)
+	}
+}
+
+// TestLlamaSwapBuiltinNoURL: the no-DSN built-in resolves but errors clearly on
+// use (mirrors foreman), rather than silently hitting a wrong host.
+func TestLlamaSwapBuiltinNoURL(t *testing.T) {
+	r := newTestRegistry(t)
+	p, ok := r.Provider(ProviderLlamaSwap)
+	if !ok {
+		t.Fatal("built-in llama-swap provider not registered")
+	}
+	if _, err := p.Model("m"); err == nil {
+		t.Error("expected error from no-URL built-in Model")
+	}
+}

docs/adr/0015-llama-swap-provider.md

@@ -0,0 +1,60 @@
+# ADR-0015: llama-swap provider
+
+**Status:** Accepted — 2026-06-27
+
+## Context
+
+llama-swap (https://github.com/mostlygeek/llama-swap) is an on-demand
+model-swapping proxy in front of llama.cpp (and stable-diffusion.cpp) servers:
+it extracts the `model` from each request, loads/hot-swaps the matching
+upstream, and serves it. It is what foreman reached for, but more robust
+(groups, TTL unload, health checks, a management API). We want it as a
+first-class majordomo target — `llama-swap://token@host:port` in the DSN — and
+the user explicitly asked for a *tailored* provider, not a bare alias of the
+OpenAI client.
+
+The tension: llama-swap's **chat** API is byte-for-byte OpenAI Chat
+Completions. A new hand-rolled chat wire client would duplicate
+`provider/openai` for zero behavioral gain, which ADR-0007 forbids. But the
+"more robust" surface (model discovery, running list, unload) does not fit the
+canonical `llm.Provider`/`llm.Model` interface (anti-creep: no provider-specific
+features leak into the canonical API).
+
+## Decision
+
+- A dedicated `provider/llamaswap` package, but its chat path **delegates to
+  `provider/openai`** pointed at `{baseURL}/v1` — no duplicated wire client.
+  `Provider.Model` returns `openai.New(...).Model(id)`.
+- Chat construction specifics: `WithLegacyMaxTokens()` (llama.cpp's OpenAI shim
+  honors `max_tokens`, not `max_completion_tokens`); a placeholder `Bearer
+  no-key` when no token is set (the openai client treats a blank key as a
+  synthetic 401, but a local keyless llama-swap ignores a bearer it didn't ask
+  for); the injected HTTP client carries **no timeout** — a cold model swap
+  blocks up to llama-swap's `healthCheckTimeout` (≥15s), so callers bound work
+  with a context deadline, never a client timeout.
+- The "tailored" surface lives as **concrete methods** on `*llamaswap.Provider`,
+  outside the canonical interface: `ListModels` (GET `/v1/models`), `Running`
+  (GET `/running`, returned as raw JSON — its shape is not a stable contract),
+  `Unload` (POST `/api/models/unload[/:model]`). A small `doJSON` helper shares
+  bearer auth + error mapping; non-2xx → `*llm.APIError` (so `llm.Classify`
+  applies), transport errors wrapped raw.
+- DSN: two schemes share one factory. `llama-swap` builds an **http://** base
+  URL from the host (llama-swap is local-first), deliberately *not* the DSN's
+  https-always `BaseURL()`; `llama-swaps` builds **https://** for a TLS-fronted
+  instance (mirrors redis/rediss). Why a second scheme rather than auto-detect:
+  a DSN carries no reliable http-vs-https signal, so the choice stays explicit.
+  Only `llama-swap` registers a no-DSN built-in provider (errors on use, mirrors
+  foreman); `llama-swaps` is a scheme only.
+- Image generation is implemented here too, against the new `imagegen`
+  interface (see ADR-0016).
+
+## Consequences
+
+- No new dependency, no duplicated chat client; the chat path inherits every
+  openai feature/fix automatically.
+- Management methods are reachable only by holding the concrete
+  `*llamaswap.Provider` (e.g. mort), not through `Parse`/`llm.Provider` — the
+  correct boundary for non-canonical features.
+- `Running`'s raw-JSON return is honest about llama-swap not publishing a stable
+  schema; a typed shape can be added later without breaking callers that ignore
+  it.

docs/adr/0016-imagegen-interface.md

@@ -0,0 +1,54 @@
+# ADR-0016: imagegen — a canonical text-to-image interface
+
+**Status:** Accepted — 2026-06-27
+
+## Context
+
+mort needs to generate images (via llama-swap's stable-diffusion.cpp backend),
+and majordomo had no image-generation surface. Image generation does not fit
+the chat contract: there are no conversation messages, tools, streaming, or
+failover-chain semantics — forcing it through `llm.Request`/`llm.Response`/
+`llm.Model` would overload that contract with mostly-unused fields. The user
+asked for "a new ai image interface as opposed to llm".
+
+## Decision
+
+- A new canonical **leaf package `imagegen`**, parallel to `llm`, re-exported
+  from the root (`ImageModel`, `ImageProvider`, `ImageRequest`, `ImageResult`,
+  `ImageOption`, plus `WithImageCount`/`WithImageSize`). Providers import
+  `imagegen`; mort codes to the interface, not to llama-swap.
+- Minimal v1 surface (text-to-image only):
+  - `Request{ Prompt string; N int; Size string }` — zero values mean provider
+    default (N=0 → backend default count; "" Size → backend default).
+  - `Result{ Images []Image; Raw any }`.
+  - `Model.Generate(ctx, Request, ...Option) (*Result, error)` and
+    `Provider.ImageModel(id, ...ModelOption) (Model, error)`.
+  - Functional options + `Request.Apply`, mirroring `llm`.
+- **`type Image = llm.ImagePart`** (bytes + MIME). Reusing the chat content type
+  means a generated image drops straight back into a chat turn
+  (`llm.UserParts(res.Images[0])`) with no conversion — the key interop win.
+- Out of scope for v1 (designed-for, deferred): image edits / img2img, the raw
+  A1111 SDAPI, masks/seeds/steps, streaming, and registry-level image-model DSN
+  resolution (construct the provider directly for now).
+- First implementation: `provider/llamaswap`, targeting OpenAI
+  `/v1/images/generations` with `response_format: "b64_json"` (bytes inline; we
+  never fetch remote URLs — mirrors `ImagePart`'s bytes-only contract).
+
+## Consequences
+
+- Image generation is provider-agnostic from day one; a future OpenAI DALL·E or
+  Gemini image backend implements the same interface.
+- The narrow interface keeps the door open for richer requests without breaking
+  callers (additive fields/options).
+- No health/failover for image models yet; if needed it can be added as a
+  separate chain type rather than retrofitting the chat chain.
+
+## Update — optional per-request settings
+
+`Request` gained additive optional overrides — `Steps *int`, `CFGScale *float64`,
+`NegativePrompt string`, `Sampler string`, `Seed *int64` — with mirror options
+(`WithSteps`, …). nil/"" means "leave the backend's per-model default", so the v1
+contract is unchanged for callers that don't set them. `provider/llamaswap`
+forwards them to sd-server as `steps`/`cfg_scale`/`negative_prompt`/`sample_method`/
+`seed` (omitempty). This realizes the "seeds/steps … additive fields" note above;
+img2img/masks/streaming remain deferred.

docs/adr/README.md

@@ -18,3 +18,5 @@ One decision per file, append-only; supersede rather than rewrite.
 | [0012](0012-agent-loop.md) | Agent run loop | Accepted |
 | [0013](0013-skill-model.md) | Skill model — additive instruction+tool bundles | Accepted |
 | [0014](0014-conversion-driven-extensions.md) | Conversion-driven extensions (resolvers, typed tools, hooks, ops controls) | Accepted |
+| [0015](0015-llama-swap-provider.md) | llama-swap provider — reuse openai for chat, tailored management + image | Accepted |
+| [0016](0016-imagegen-interface.md) | imagegen — a canonical text-to-image interface | Accepted |

imagegen/imagegen.go

@@ -0,0 +1,143 @@
+// Package imagegen is majordomo's canonical text-to-image surface. It is a
+// deliberately separate contract from the llm package: image generation does
+// not fit the chat Request/Response shape (no messages, tools, streaming, or
+// failover chains in v1), so it gets its own small Provider/Model interface
+// rather than overloading llm.Model.
+//
+// Generated images are carried as llm.ImagePart (bytes + MIME), so a result
+// drops straight back into a chat turn:
+//
+//	res, _ := im.Generate(ctx, imagegen.Request{Prompt: "a red bicycle"})
+//	msg := llm.UserParts(llm.Text("describe this"), res.Images[0])
+//
+// The first implementation is provider/llamaswap, which targets the OpenAI
+// /v1/images/generations endpoint routed to a stable-diffusion.cpp backend.
+package imagegen
+
+import (
+	"context"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+)
+
+// Image is one generated image: raw bytes plus a MIME type. Aliased to
+// llm.ImagePart so generated images are interchangeable with chat content and
+// can be fed into llm.UserParts without conversion.
+type Image = llm.ImagePart
+
+// Request is a text-to-image generation request. Pointer-free zero values mean
+// "provider default": N == 0 yields the backend's default count (usually one),
+// and an empty Size leaves the backend's default resolution.
+type Request struct {
+	// Prompt is the text description of the image to generate.
+	Prompt string
+
+	// N is the number of images to generate; 0 = provider default.
+	N int
+
+	// Size is the requested resolution, e.g. "512x512" or "1024x1024";
+	// "" = provider default.
+	Size string
+
+	// The fields below are optional per-request overrides. Their zero value
+	// (nil pointer or empty string) means "leave the backend's own default" —
+	// for stable-diffusion.cpp that is the per-model default baked into the
+	// llama-swap launch flags. A caller overrides only what it explicitly sets.
+
+	// Steps is the number of diffusion steps; nil = backend default.
+	Steps *int
+
+	// CFGScale is the classifier-free-guidance scale; nil = backend default.
+	// Architecture-sensitive (SDXL likes ~7, Flux wants 1), so prefer leaving
+	// it nil unless the caller knows the target model.
+	CFGScale *float64
+
+	// NegativePrompt steers generation away from concepts; "" = none.
+	NegativePrompt string
+
+	// Sampler selects the sampling method (e.g. "euler", "euler_a");
+	// "" = backend default.
+	Sampler string
+
+	// Seed fixes the RNG seed for reproducible output; nil = random.
+	Seed *int64
+}
+
+// Result is the canonical image-generation result.
+type Result struct {
+	// Images are the generated images, in the order the backend returned them.
+	Images []Image
+
+	// Raw is the provider-native response object, an escape hatch for
+	// provider-specific fields. May be nil; never required for normal use.
+	Raw any
+}
+
+// Option mutates a Request before it is sent. Options passed to Generate are
+// applied to a copy of the request, so a Request value can be reused.
+type Option func(*Request)
+
+// WithN sets the number of images to generate.
+func WithN(n int) Option { return func(r *Request) { r.N = n } }
+
+// WithSize sets the requested resolution (e.g. "1024x1024").
+func WithSize(size string) Option { return func(r *Request) { r.Size = size } }
+
+// WithSteps overrides the number of diffusion steps.
+func WithSteps(n int) Option { return func(r *Request) { r.Steps = &n } }
+
+// WithCFGScale overrides the classifier-free-guidance scale.
+func WithCFGScale(s float64) Option { return func(r *Request) { r.CFGScale = &s } }
+
+// WithNegativePrompt sets a negative prompt.
+func WithNegativePrompt(s string) Option { return func(r *Request) { r.NegativePrompt = s } }
+
+// WithSampler overrides the sampling method (e.g. "euler", "euler_a").
+func WithSampler(s string) Option { return func(r *Request) { r.Sampler = s } }
+
+// WithSeed fixes the RNG seed for reproducible output.
+func WithSeed(seed int64) Option { return func(r *Request) { r.Seed = &seed } }
+
+// Apply returns a copy of the request with all options applied. Providers call
+// this once at the top of Generate.
+func (r Request) Apply(opts ...Option) Request {
+	for _, opt := range opts {
+		opt(&r)
+	}
+	return r
+}
+
+// Model generates images from a text prompt. It is intentionally narrower than
+// llm.Model — no Stream, no Capabilities, no tool calls.
+type Model interface {
+	// Generate produces one or more images for the request's prompt.
+	Generate(ctx context.Context, req Request, opts ...Option) (*Result, error)
+}
+
+// ModelOption configures a Model at construction time (Provider.ImageModel).
+// Reserved for future per-model settings (e.g. a default size); present now so
+// the interface is forward-compatible.
+type ModelOption func(*ModelConfig)
+
+// ModelConfig carries per-model construction settings.
+type ModelConfig struct{}
+
+// ApplyModelOptions folds options into a config.
+func ApplyModelOptions(opts []ModelOption) ModelConfig {
+	var cfg ModelConfig
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+	return cfg
+}
+
+// Provider mints image Models bound to one backend. It mirrors llm.Provider
+// but for image generation.
+type Provider interface {
+	// Name is the registry identifier for the provider.
+	Name() string
+
+	// ImageModel returns a Model bound to the given id (passed through to the
+	// backend verbatim; no catalog validation).
+	ImageModel(id string, opts ...ModelOption) (Model, error)
+}

imagegen/imagegen_test.go

@@ -0,0 +1,42 @@
+package imagegen
+
+import (
+	"testing"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+)
+
+func TestRequestApply(t *testing.T) {
+	base := Request{Prompt: "a red bicycle"}
+	got := base.Apply(WithN(3), WithSize("1024x1024"))
+
+	if got.Prompt != "a red bicycle" {
+		t.Errorf("Prompt = %q, want %q", got.Prompt, "a red bicycle")
+	}
+	if got.N != 3 {
+		t.Errorf("N = %d, want 3", got.N)
+	}
+	if got.Size != "1024x1024" {
+		t.Errorf("Size = %q, want %q", got.Size, "1024x1024")
+	}
+
+	// Apply must not mutate the receiver (options apply to a copy).
+	if base.N != 0 || base.Size != "" {
+		t.Errorf("base mutated: %+v", base)
+	}
+}
+
+func TestApplyModelOptions(t *testing.T) {
+	// No options yet; just verify it returns a usable zero config.
+	_ = ApplyModelOptions(nil)
+}
+
+// TestImageIsImagePart pins the alias so generated images stay interchangeable
+// with chat content.
+func TestImageIsImagePart(t *testing.T) {
+	var img Image = llm.ImagePart{MIME: "image/png", Data: []byte{0x89, 'P', 'N', 'G'}}
+	var part llm.Part = img // must satisfy llm.Part for use in messages
+	if _, ok := part.(llm.ImagePart); !ok {
+		t.Fatalf("Image does not round-trip as llm.ImagePart")
+	}
+}

majordomo.go

@@ -26,6 +26,7 @@ import (
 	"encoding/json"
 	"sync"
 
+	"gitea.stevedudenhoeffer.com/steve/majordomo/imagegen"
 	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
 )
 
@@ -56,6 +57,18 @@ type (
 	ErrorClass   = llm.ErrorClass
 )
 
+// Re-exported canonical image-generation types. See the imagegen package for
+// documentation. Image generation is a separate contract from llm (no chat
+// messages, tools, or streaming); the first backend is provider/llamaswap.
+type (
+	ImageModel       = imagegen.Model
+	ImageProvider    = imagegen.Provider
+	ImageRequest     = imagegen.Request
+	ImageResult      = imagegen.Result
+	ImageOption      = imagegen.Option
+	ImageModelOption = imagegen.ModelOption
+)
+
 // Re-exported role and finish-reason constants.
 const (
 	RoleSystem    = llm.RoleSystem
@@ -106,6 +119,10 @@ func WithPromptCaching() Option                             { return llm.WithPro
 // calls made through this package.
 func WithModelCapabilities(caps Capabilities) ModelOption { return llm.WithCapabilities(caps) }
 
+// Re-exported image-generation request options (see the imagegen package).
+func WithImageCount(n int) ImageOption   { return imagegen.WithN(n) }
+func WithImageSize(s string) ImageOption { return imagegen.WithSize(s) }
+
 // Classify re-exports llm.Classify.
 func Classify(err error) ErrorClass { return llm.Classify(err) }
 

media/media.go

@@ -5,10 +5,16 @@
 // already satisfies the target's llm.Capabilities. Images that do not fit
 // are decoded, downscaled (never upscaled), and re-encoded into an allowed
 // format and byte budget. Anything that cannot honestly be made to fit —
-// undecodable formats, impossible byte budgets, too many images, images for
-// a text-only target — fails with an error wrapping llm.ErrUnsupported so a
-// failover chain can advance to a more capable target without a health
-// penalty.
+// undecodable formats, impossible byte budgets, images for a text-only
+// target — fails with an error wrapping llm.ErrUnsupported so a failover
+// chain can advance to a more capable target without a health penalty.
+//
+// Over-count is the exception: a request carrying more images than
+// MaxImagesPerReq does NOT fail — the oldest images are replaced with a short
+// text placeholder and the most-recent MaxImagesPerReq are kept, because a hard
+// refuse exhausts a chain whose targets share the same cap (e.g. an agent loop
+// accumulating a preview image per iteration). MaxImagesPerReq remains the
+// per-model knob (0 = no image support).
 //
 // Why a separate package: every provider would otherwise duplicate the same
 // decode/scale/encode pipeline. Providers keep only a cheap capability
@@ -52,15 +58,21 @@ func Normalize(req llm.Request, caps llm.Capabilities) (llm.Request, error) {
 	if !caps.SupportsImages() {
 		return llm.Request{}, fmt.Errorf("media: %w: target does not accept image input (request carries %d image(s))", llm.ErrUnsupported, total)
 	}
-	// Why error instead of dropping the overflow: silently removing an image
-	// changes the question the caller asked; the honest move is to refuse and
-	// let a chain try a roomier target.
+	// Over-cap images are elided in the same copy-on-write pass below: the
+	// OLDEST excess are replaced with a placeholder and the most-recent
+	// MaxImagesPerReq kept (see the package doc for why we elide rather than
+	// refuse). toElide is how many of the first images, front-to-back, to drop.
+	toElide := 0
 	if total > caps.MaxImagesPerReq {
-		return llm.Request{}, fmt.Errorf("media: %w: request carries %d images, target allows at most %d per request", llm.ErrUnsupported, total, caps.MaxImagesPerReq)
+		toElide = total - caps.MaxImagesPerReq
 	}
 
+	// Single copy-on-write pass: for each image, the first toElide become a text
+	// placeholder; the rest are size-normalized against caps. The Messages slice
+	// and an affected message's Parts slice are copied at most once.
 	out := req
 	copiedMessages := false
+	seen := 0
 	for mi := range req.Messages {
 		copiedParts := false
 		for pi, part := range req.Messages[mi].Parts {
@@ -68,13 +80,22 @@ func Normalize(req llm.Request, caps llm.Capabilities) (llm.Request, error) {
 			if !ok {
 				continue
 			}
-			norm, changed, err := normalizeImage(ip, caps)
-			if err != nil {
-				return llm.Request{}, fmt.Errorf("media: message %d, part %d: %w", mi, pi, err)
-			}
-			if !changed {
-				continue
+			seen++
+
+			var replacement llm.Part
+			if seen <= toElide {
+				replacement = llm.Text(imageOverflowPlaceholder)
+			} else {
+				norm, changed, err := normalizeImage(ip, caps)
+				if err != nil {
+					return llm.Request{}, fmt.Errorf("media: message %d, part %d: %w", mi, pi, err)
+				}
+				if !changed {
+					continue
+				}
+				replacement = norm
 			}
+
 			if !copiedMessages {
 				out.Messages = make([]llm.Message, len(req.Messages))
 				copy(out.Messages, req.Messages)
@@ -86,12 +107,17 @@ func Normalize(req llm.Request, caps llm.Capabilities) (llm.Request, error) {
 				out.Messages[mi].Parts = parts
 				copiedParts = true
 			}
-			out.Messages[mi].Parts[pi] = norm
+			out.Messages[mi].Parts[pi] = replacement
 		}
 	}
 	return out, nil
 }
 
+// imageOverflowPlaceholder replaces an image elided to fit a target's
+// per-request image cap. It keeps the message turn intact and tells the model
+// an earlier image was omitted rather than silently changing the conversation.
+const imageOverflowPlaceholder = "[earlier image omitted to fit this model's per-request image limit]"
+
 // Info reports an image part's sniffed format ("jpeg", "png", "gif", or
 // "webp") and pixel dimensions. It is a cheap metadata read — the pixels are
 // never decoded. webp is recognized by signature but not decodable with the

media/media_test.go

@@ -149,18 +149,48 @@ func TestNormalizeImagesUnsupported(t *testing.T) {
 	}
 }
 
-func TestNormalizeTooManyImages(t *testing.T) {
-	img := llm.Image("image/png", encPNG(t, gradient(4, 4)))
+func TestNormalizeOverCount(t *testing.T) {
+	// 3 distinguishable images across 2 messages; cap = 2. Over-count no longer
+	// errors — the OLDEST image is replaced with a placeholder and the most-recent
+	// two (the relevant ones in an iterative run) are kept, in order.
+	a := llm.Image("image/png", encPNG(t, gradient(2, 2))).(llm.ImagePart)
+	b := llm.Image("image/png", encPNG(t, gradient(4, 4))).(llm.ImagePart)
+	c := llm.Image("image/png", encPNG(t, gradient(8, 8))).(llm.ImagePart)
 	req := llm.Request{Messages: []llm.Message{
-		llm.UserParts(img, img),
-		llm.UserParts(img),
+		llm.UserParts(a, b),
+		llm.UserParts(c),
 	}}
-	_, err := Normalize(req, llm.Capabilities{MaxImagesPerReq: 2})
-	if !errors.Is(err, llm.ErrUnsupported) {
-		t.Fatalf("err = %v, want ErrUnsupported", err)
+	caps := llm.Capabilities{MaxImagesPerReq: 2, MaxImageDimension: 64, MaxImageBytes: 1 << 20, AllowedImageMIME: []string{"image/png"}}
+	out, err := Normalize(req, caps)
+	if err != nil {
+		t.Fatalf("over-count should not error: %v", err)
 	}
-	if !strings.Contains(err.Error(), "3 images") || !strings.Contains(err.Error(), "at most 2") {
-		t.Errorf("err message %q lacks the counts", err)
+	var imgs []llm.ImagePart
+	placeholders := 0
+	for _, m := range out.Messages {
+		for _, p := range m.Parts {
+			switch v := p.(type) {
+			case llm.ImagePart:
+				imgs = append(imgs, v)
+			case llm.TextPart:
+				if v.Text == imageOverflowPlaceholder {
+					placeholders++
+				}
+			}
+		}
+	}
+	// The exact survivors are the most-recent two, in order: b then c (a elided).
+	if len(imgs) != 2 || !bytes.Equal(imgs[0].Data, b.Data) || !bytes.Equal(imgs[1].Data, c.Data) {
+		t.Fatalf("kept %d images; want exactly [b, c] (the most-recent two)", len(imgs))
+	}
+	if placeholders != 1 {
+		t.Errorf("placeholders = %d, want 1 for the elided oldest image", placeholders)
+	}
+	// Input request untouched (copy-on-write): the first part is still image a,
+	// not a placeholder — a len check alone wouldn't catch in-place substitution.
+	first, ok := req.Messages[0].Parts[0].(llm.ImagePart)
+	if !ok || !bytes.Equal(first.Data, a.Data) {
+		t.Errorf("input request was mutated; first part = %+v", req.Messages[0].Parts[0])
 	}
 }
 

progress.md

@@ -1,5 +1,34 @@
 # progress
 
+## 2026-06-27 — llama-swaps (TLS) DSN scheme
+
+Follow-up to the llama-swap provider: added the `llama-swaps` DSN scheme (https
+base URL) alongside `llama-swap` (http, local-first), mirroring redis/rediss, so
+a TLS-fronted instance is first-class instead of being pushed to the `openai://`
+scheme. Scheme-only (no default built-in); shares one factory in builtin.go.
+
+## 2026-06-27 — llama-swap provider + canonical image-gen interface
+
+**Landed (ADR-0015, ADR-0016).** New `provider/llamaswap`: chat **delegates to
+`provider/openai`** at `{base}/v1` (no duplicated wire client per ADR-0007), with
+legacy `max_tokens`, a `Bearer no-key` placeholder for keyless local instances,
+and a timeout-free client (swap cold starts → use context deadlines). Tailored
+management methods on the concrete type — `ListModels`, `Running` (raw JSON),
+`Unload`. DSN scheme `llama-swap://token@host:port` builds an **http** base URL
+(local-first), registered in `builtin.go` alongside a no-URL built-in that errors
+on use (mirrors foreman).
+
+New canonical `imagegen` package (text-to-image), separate from `llm`:
+`Request`/`Result`/`Model`/`Provider`, `Image = llm.ImagePart` so generated
+images feed back into chat. First backend is llama-swap via OpenAI
+`/v1/images/generations` (`b64_json`, bytes-only). Re-exported from root
+(`ImageModel`, `ImageRequest`, `WithImageSize`, ...). v1 is txt2img only; edits/
+img2img and registry image-DSN resolution deferred.
+
+Hermetic `httptest` tests for chat delegation, management endpoints, image
+decode, and scheme wiring. Gates green. README support matrix + image-gen
+section, CLAUDE.md package map, and ADR index updated in the same change.
+
 ## 2026-06-10 — Phase 9b: mort converted, PR open
 
 **Done.** mort fully re-based on majordomo on branch

provider/llamaswap/image.go

@@ -0,0 +1,121 @@
+package llamaswap
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/imagegen"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+)
+
+// ImageModel implements imagegen.Provider, binding an image-generation model
+// served by llama-swap (routed to a stable-diffusion.cpp upstream). The id is
+// passed through verbatim and selects which upstream llama-swap loads.
+func (p *Provider) ImageModel(id string, opts ...imagegen.ModelOption) (imagegen.Model, error) {
+	if p.baseURL == "" {
+		return nil, fmt.Errorf("llama-swap provider %q: no base URL configured (set one via WithBaseURL or an LLM_* env DSN)", p.name)
+	}
+	_ = imagegen.ApplyModelOptions(opts)
+	return &imageModel{p: p, id: id}, nil
+}
+
+type imageModel struct {
+	p  *Provider
+	id string
+}
+
+// imageRequest is the OpenAI /v1/images/generations request shape, plus the
+// stable-diffusion.cpp extras llama-swap forwards to sd-server. We always
+// request b64_json so the bytes come back inline (no second fetch). The
+// optional fields are pointers/omitempty so an unset value is omitted entirely
+// and sd-server falls back to the model's own default (a field name a given
+// sd-server build doesn't recognize is simply ignored — harmless).
+type imageRequest struct {
+	Model          string   `json:"model"`
+	Prompt         string   `json:"prompt"`
+	N              int      `json:"n,omitempty"`
+	Size           string   `json:"size,omitempty"`
+	ResponseFormat string   `json:"response_format"`
+	Steps          *int     `json:"steps,omitempty"`
+	CFGScale       *float64 `json:"cfg_scale,omitempty"`
+	NegativePrompt string   `json:"negative_prompt,omitempty"`
+	SampleMethod   string   `json:"sample_method,omitempty"`
+	Seed           *int64   `json:"seed,omitempty"`
+}
+
+type imageResponse struct {
+	Created int64 `json:"created"`
+	Data    []struct {
+		B64JSON string `json:"b64_json"`
+		URL     string `json:"url"`
+	} `json:"data"`
+}
+
+// Generate implements imagegen.Model via POST {base}/v1/images/generations.
+func (m *imageModel) Generate(ctx context.Context, req imagegen.Request, opts ...imagegen.Option) (*imagegen.Result, error) {
+	req = req.Apply(opts...)
+	if strings.TrimSpace(req.Prompt) == "" {
+		return nil, fmt.Errorf("%w: image generation requires a prompt", llm.ErrUnsupported)
+	}
+	if req.N < 0 {
+		return nil, fmt.Errorf("%w: image count N must be >= 0, got %d", llm.ErrUnsupported, req.N)
+	}
+
+	wire := imageRequest{
+		Model:          m.id,
+		Prompt:         req.Prompt,
+		N:              req.N,
+		Size:           req.Size,
+		ResponseFormat: "b64_json",
+		Steps:          req.Steps,
+		CFGScale:       req.CFGScale,
+		NegativePrompt: req.NegativePrompt,
+		SampleMethod:   req.Sampler,
+		Seed:           req.Seed,
+	}
+
+	var resp imageResponse
+	if err := m.p.doJSON(ctx, http.MethodPost, "/v1/images/generations", m.id, &wire, &resp); err != nil {
+		return nil, err
+	}
+
+	out := &imagegen.Result{Raw: &resp}
+	for i, d := range resp.Data {
+		if d.B64JSON == "" {
+			// Why error rather than skip: a url-only entry means the backend
+			// ignored response_format; we don't fetch remote content (mirrors
+			// llm.ImagePart's bytes-only contract), so surface it.
+			return nil, &llm.APIError{
+				Provider: m.p.name,
+				Model:    m.id,
+				Message:  fmt.Sprintf("image %d returned no inline b64_json data", i),
+			}
+		}
+		raw, err := base64.StdEncoding.DecodeString(d.B64JSON)
+		if err != nil {
+			return nil, fmt.Errorf("llama-swap: decode image %d: %w", i, err)
+		}
+		out.Images = append(out.Images, llm.ImagePart{MIME: sniffImageMIME(raw), Data: raw})
+	}
+	if len(out.Images) == 0 {
+		return nil, &llm.APIError{
+			Provider: m.p.name,
+			Model:    m.id,
+			Message:  "image response contained no images",
+		}
+	}
+	return out, nil
+}
+
+// sniffImageMIME identifies the image format from its leading bytes, defaulting
+// to image/png (stable-diffusion.cpp emits PNG) when detection is inconclusive.
+func sniffImageMIME(data []byte) string {
+	mime := http.DetectContentType(data)
+	if !strings.HasPrefix(mime, "image/") {
+		return "image/png"
+	}
+	return mime
+}

provider/llamaswap/llamaswap.go

@@ -0,0 +1,261 @@
+// Package llamaswap implements majordomo's provider contract for llama-swap
+// (https://github.com/mostlygeek/llama-swap), an on-demand model-swapping
+// proxy that fronts llama.cpp (and stable-diffusion.cpp) servers, loading and
+// hot-swapping the requested model per request.
+//
+// Chat is OpenAI Chat Completions, byte-for-byte: this package does NOT carry
+// its own chat wire client. Provider.Model delegates to provider/openai
+// pointed at {baseURL}/v1 (ADR-0007: reuse, don't duplicate). What this
+// package adds beyond a bare OpenAI-compat endpoint is the "tailored" surface:
+//
+//   - llama-swap management endpoints exposed as concrete methods — ListModels
+//     (GET /v1/models), Running (GET /running), Unload (POST /api/models/unload)
+//     — which have no place on the canonical llm.Provider interface;
+//   - image generation via the imagegen interface (see image.go); and
+//   - swap-aware defaults: the HTTP client carries NO timeout, because the
+//     first request to an unloaded model blocks while llama-swap spawns the
+//     upstream (its healthCheckTimeout is at least 15s). Bound a call with a
+//     context deadline, never a client timeout.
+//
+// DSN form (registered as the "llama-swap" scheme): llama-swap://token@host:port
+// builds an http:// base URL (llama-swap is local-first; a TLS-fronted instance
+// can use the openai:// scheme for chat instead).
+package llamaswap
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/openai"
+)
+
+// DefaultName is the registry name used when WithName is not given.
+const DefaultName = "llama-swap"
+
+// maxResponseBytes caps the JSON body read on the success path. Generous
+// enough for a multi-image b64 payload, bounded so a hostile/buggy upstream
+// can't make a decode allocate without limit.
+const maxResponseBytes = 64 << 20
+
+// Provider is a llama-swap client. It satisfies llm.Provider (chat, delegated
+// to provider/openai) and imagegen.Provider (image generation), and exposes
+// llama-swap's management endpoints as concrete methods.
+type Provider struct {
+	name    string
+	baseURL string // no trailing slash, no /v1 suffix; e.g. "http://host:port"
+	token   string // bearer credential; empty = no auth (local)
+	client  *http.Client
+}
+
+// Option configures the provider.
+type Option func(*Provider)
+
+// WithName overrides the registry name (default "llama-swap").
+func WithName(name string) Option { return func(p *Provider) { p.name = name } }
+
+// WithBaseURL sets the llama-swap base URL (scheme://host[:port]); the /v1 and
+// management paths are appended internally. A trailing slash is trimmed.
+func WithBaseURL(u string) Option {
+	return func(p *Provider) { p.baseURL = strings.TrimRight(u, "/") }
+}
+
+// WithToken sets the bearer token (llama-swap API key). Empty means no
+// Authorization header.
+func WithToken(token string) Option { return func(p *Provider) { p.token = token } }
+
+// WithHTTPClient overrides the HTTP client. Prefer context deadlines over a
+// client timeout: a cold model swap can legitimately take many seconds.
+func WithHTTPClient(c *http.Client) Option {
+	return func(p *Provider) {
+		if c != nil {
+			p.client = c
+		}
+	}
+}
+
+// New creates a llama-swap provider. Construction never fails; a missing base
+// URL surfaces at request time. The default client has no timeout (swap cold
+// starts); bound calls with a context deadline.
+func New(opts ...Option) *Provider {
+	p := &Provider{name: DefaultName, client: &http.Client{}}
+	for _, opt := range opts {
+		opt(p)
+	}
+	return p
+}
+
+// Name implements llm.Provider and imagegen.Provider.
+func (p *Provider) Name() string { return p.name }
+
+// BaseURL reports the configured base URL (diagnostics).
+func (p *Provider) BaseURL() string { return p.baseURL }
+
+// Model implements llm.Provider via llama-swap's OpenAI-compatible chat
+// endpoint, delegating to provider/openai. The id is passed through verbatim
+// and selects which upstream llama-swap loads.
+func (p *Provider) Model(id string, opts ...llm.ModelOption) (llm.Model, error) {
+	if p.baseURL == "" {
+		return nil, fmt.Errorf("llama-swap provider %q: no base URL configured (set one via WithBaseURL or an LLM_* env DSN)", p.name)
+	}
+	return p.chatProvider().Model(id, opts...)
+}
+
+// chatProvider builds the OpenAI-compatible client for llama-swap's chat API.
+// Why a placeholder key when token is empty: the openai client treats a blank
+// key as a synthetic 401, but a local llama-swap may require no auth at all —
+// a bearer it ignores is harmless. Why legacy max_tokens: llama.cpp's OpenAI
+// shim honors "max_tokens", not "max_completion_tokens".
+func (p *Provider) chatProvider() *openai.Provider {
+	key := p.token
+	if key == "" {
+		key = "no-key"
+	}
+	return openai.New(
+		openai.WithName(p.name),
+		openai.WithBaseURL(p.baseURL+"/v1"),
+		openai.WithAPIKey(key),
+		openai.WithLegacyMaxTokens(),
+		openai.WithHTTPClient(p.client),
+	)
+}
+
+// --- management endpoints ---
+
+// ModelInfo is one entry from llama-swap's GET /v1/models (the OpenAI model
+// list shape). Fields llama-swap adds beyond these are ignored.
+type ModelInfo struct {
+	ID      string `json:"id"`
+	Object  string `json:"object"`
+	OwnedBy string `json:"owned_by"`
+}
+
+// ListModels returns the models llama-swap is configured to serve (GET
+// /v1/models). Unlisted models are excluded by llama-swap itself.
+func (p *Provider) ListModels(ctx context.Context) ([]ModelInfo, error) {
+	var out struct {
+		Data []ModelInfo `json:"data"`
+	}
+	if err := p.doJSON(ctx, http.MethodGet, "/v1/models", "", nil, &out); err != nil {
+		return nil, err
+	}
+	return out.Data, nil
+}
+
+// Running returns llama-swap's currently-loaded models as the raw GET /running
+// payload. Why raw: llama-swap's /running shape is not a stable, OpenAI-style
+// contract, so this exposes the endpoint without pinning a schema this package
+// would have to guess.
+func (p *Provider) Running(ctx context.Context) (json.RawMessage, error) {
+	var out json.RawMessage
+	if err := p.doJSON(ctx, http.MethodGet, "/running", "", nil, &out); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// Unload unloads a running model to free its resources (POST
+// /api/models/unload/:model). An empty model unloads all running models (POST
+// /api/models/unload).
+func (p *Provider) Unload(ctx context.Context, model string) error {
+	path := "/api/models/unload"
+	if model != "" {
+		// Why reject rather than percent-escape: llama-swap model ids legitimately
+		// contain ":" (e.g. "qwen3:14b"), which is path-legal and must reach the
+		// server verbatim; only path-structure characters are dangerous (they'd
+		// redirect the request to another endpoint), and those never appear in a
+		// real model id.
+		if strings.ContainsAny(model, "/?#") {
+			return fmt.Errorf("llama-swap: invalid model id %q for unload (contains a path separator)", model)
+		}
+		path += "/" + model
+	}
+	return p.doJSON(ctx, http.MethodPost, path, "", nil, nil)
+}
+
+// --- shared HTTP helper for management + image endpoints ---
+
+// doJSON performs a request to a llama-swap endpoint relative to baseURL,
+// optionally encoding body and decoding into out (either may be nil). model
+// labels the failing target in any *llm.APIError ("" for endpoints that aren't
+// model-specific). Transport failures are wrapped raw so llm.Classify still
+// sees the underlying net error; non-2xx responses become *llm.APIError.
+func (p *Provider) doJSON(ctx context.Context, method, path, model string, body, out any) error {
+	if p.baseURL == "" {
+		return fmt.Errorf("llama-swap provider %q: no base URL configured (set one via WithBaseURL or an LLM_* env DSN)", p.name)
+	}
+	var rdr io.Reader
+	if body != nil {
+		b, err := json.Marshal(body)
+		if err != nil {
+			return fmt.Errorf("llama-swap: encode request: %w", err)
+		}
+		rdr = bytes.NewReader(b)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, p.baseURL+path, rdr)
+	if err != nil {
+		return fmt.Errorf("llama-swap: build request: %w", err)
+	}
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	if p.token != "" {
+		req.Header.Set("Authorization", "Bearer "+p.token)
+	}
+	resp, err := p.client.Do(req)
+	if err != nil {
+		return fmt.Errorf("llama-swap: do request: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode/100 != 2 {
+		return p.apiError(resp, model)
+	}
+	if out != nil {
+		if err := json.NewDecoder(io.LimitReader(resp.Body, maxResponseBytes)).Decode(out); err != nil {
+			return fmt.Errorf("llama-swap: decode response: %w", err)
+		}
+	} else {
+		// Drain (bounded) so the connection can be reused.
+		_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, maxResponseBytes))
+	}
+	return nil
+}
+
+// apiError converts a non-2xx response into *llm.APIError, tolerating the
+// OpenAI {"error":{"message",...}} envelope, the Ollama-style {"error":"..."}
+// string form, and a raw body.
+func (p *Provider) apiError(resp *http.Response, model string) error {
+	e := &llm.APIError{Provider: p.name, Model: model, Status: resp.StatusCode}
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+
+	var env struct {
+		Error json.RawMessage `json:"error"`
+	}
+	if json.Unmarshal(body, &env) == nil && len(env.Error) > 0 {
+		var obj struct {
+			Message string `json:"message"`
+			Type    string `json:"type"`
+			Code    string `json:"code"`
+		}
+		if json.Unmarshal(env.Error, &obj) == nil && (obj.Message != "" || obj.Code != "" || obj.Type != "") {
+			e.Message = obj.Message
+			e.Code = obj.Code
+			if e.Code == "" {
+				e.Code = obj.Type
+			}
+			return e
+		}
+		var msg string
+		if json.Unmarshal(env.Error, &msg) == nil && msg != "" {
+			e.Message = msg
+			return e
+		}
+	}
+	e.Message = strings.TrimSpace(string(body))
+	return e
+}

provider/llamaswap/llamaswap_test.go

@@ -0,0 +1,277 @@
+package llamaswap
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/imagegen"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+)
+
+// 1x1 transparent PNG, base64 (used to assert image decoding end-to-end).
+const onePixelPNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
+
+func TestChatDelegatesToOpenAI(t *testing.T) {
+	var gotPath, gotAuth string
+	var gotBody map[string]any
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		gotAuth = r.Header.Get("Authorization")
+		_ = json.NewDecoder(r.Body).Decode(&gotBody)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"role":"assistant","content":"hi"},"finish_reason":"stop"}]}`))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithToken("test-token"), WithHTTPClient(srv.Client()))
+	m, err := p.Model("qwen3:14b")
+	if err != nil {
+		t.Fatalf("Model: %v", err)
+	}
+	resp, err := m.Generate(context.Background(), llm.Request{
+		Messages:  []llm.Message{llm.UserText("hello")},
+		MaxTokens: 64,
+	})
+	if err != nil {
+		t.Fatalf("Generate: %v", err)
+	}
+	if resp.Text() != "hi" {
+		t.Errorf("Text = %q, want %q", resp.Text(), "hi")
+	}
+	if gotPath != "/v1/chat/completions" {
+		t.Errorf("path = %q, want /v1/chat/completions", gotPath)
+	}
+	if gotAuth != "Bearer test-token" {
+		t.Errorf("auth = %q, want Bearer test-token", gotAuth)
+	}
+	// llama.cpp's OpenAI shim wants the legacy max_tokens field.
+	if _, ok := gotBody["max_tokens"]; !ok {
+		t.Errorf("request missing max_tokens (legacy); body=%v", gotBody)
+	}
+	if _, ok := gotBody["max_completion_tokens"]; ok {
+		t.Errorf("request used max_completion_tokens; want legacy max_tokens")
+	}
+}
+
+func TestChatNoTokenSendsPlaceholder(t *testing.T) {
+	var gotAuth string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotAuth = r.Header.Get("Authorization")
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"},"finish_reason":"stop"}]}`))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client())) // no token
+	m, _ := p.Model("m")
+	if _, err := m.Generate(context.Background(), llm.Request{Messages: []llm.Message{llm.UserText("x")}}); err != nil {
+		t.Fatalf("Generate: %v", err)
+	}
+	// Keyless local llama-swap: a placeholder bearer it ignores, never a blank
+	// that the openai client would reject as a synthetic 401.
+	if gotAuth != "Bearer no-key" {
+		t.Errorf("auth = %q, want Bearer no-key", gotAuth)
+	}
+}
+
+func TestModelNoBaseURL(t *testing.T) {
+	if _, err := New().Model("m"); err == nil {
+		t.Fatal("expected error for missing base URL")
+	}
+	if _, err := New().ImageModel("m"); err == nil {
+		t.Fatal("expected error for missing base URL (image)")
+	}
+}
+
+func TestListModels(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/models" {
+			t.Errorf("path = %q", r.URL.Path)
+		}
+		_, _ = w.Write([]byte(`{"object":"list","data":[{"id":"qwen3:14b","object":"model","owned_by":"llama-swap"},{"id":"sd","object":"model"}]}`))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	models, err := p.ListModels(context.Background())
+	if err != nil {
+		t.Fatalf("ListModels: %v", err)
+	}
+	if len(models) != 2 || models[0].ID != "qwen3:14b" {
+		t.Fatalf("models = %+v", models)
+	}
+}
+
+func TestUnload(t *testing.T) {
+	var gotPath, gotMethod string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath, gotMethod = r.URL.Path, r.Method
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	if err := p.Unload(context.Background(), "qwen3:14b"); err != nil {
+		t.Fatalf("Unload: %v", err)
+	}
+	if gotMethod != http.MethodPost || gotPath != "/api/models/unload/qwen3:14b" {
+		t.Errorf("got %s %s", gotMethod, gotPath)
+	}
+
+	if err := p.Unload(context.Background(), ""); err != nil {
+		t.Fatalf("Unload all: %v", err)
+	}
+	if gotPath != "/api/models/unload" {
+		t.Errorf("unload-all path = %q", gotPath)
+	}
+
+	// A model id with a path separator is rejected before any request.
+	if err := p.Unload(context.Background(), "../admin"); err == nil {
+		t.Error("expected error for model id with path separator")
+	}
+}
+
+func TestManagementNoBaseURL(t *testing.T) {
+	p := New() // no base URL
+	if _, err := p.ListModels(context.Background()); err == nil {
+		t.Error("ListModels: expected error for missing base URL")
+	}
+	if _, err := p.Running(context.Background()); err == nil {
+		t.Error("Running: expected error for missing base URL")
+	}
+	if err := p.Unload(context.Background(), "m"); err == nil {
+		t.Error("Unload: expected error for missing base URL")
+	}
+}
+
+func TestRunningRaw(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(`{"running":["qwen3:14b"]}`))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	raw, err := p.Running(context.Background())
+	if err != nil {
+		t.Fatalf("Running: %v", err)
+	}
+	if string(raw) != `{"running":["qwen3:14b"]}` {
+		t.Errorf("raw = %s", raw)
+	}
+}
+
+func TestImageGenerate(t *testing.T) {
+	var gotBody map[string]any
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/images/generations" {
+			t.Errorf("path = %q", r.URL.Path)
+		}
+		_ = json.NewDecoder(r.Body).Decode(&gotBody)
+		_, _ = w.Write([]byte(`{"created":1,"data":[{"b64_json":"` + onePixelPNG + `"}]}`))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	im, err := p.ImageModel("sd")
+	if err != nil {
+		t.Fatalf("ImageModel: %v", err)
+	}
+	res, err := im.Generate(context.Background(), imagegen.Request{Prompt: "a red bicycle"}, imagegen.WithSize("512x512"))
+	if err != nil {
+		t.Fatalf("Generate: %v", err)
+	}
+	if len(res.Images) != 1 {
+		t.Fatalf("images = %d, want 1", len(res.Images))
+	}
+	if res.Images[0].MIME != "image/png" {
+		t.Errorf("MIME = %q, want image/png", res.Images[0].MIME)
+	}
+	if len(res.Images[0].Data) == 0 {
+		t.Error("decoded image has no bytes")
+	}
+	// response_format must be forced to b64_json, and options applied.
+	if gotBody["response_format"] != "b64_json" {
+		t.Errorf("response_format = %v, want b64_json", gotBody["response_format"])
+	}
+	if gotBody["size"] != "512x512" {
+		t.Errorf("size = %v, want 512x512", gotBody["size"])
+	}
+}
+
+func TestImageGenerateSettings(t *testing.T) {
+	var gotBody map[string]any
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_ = json.NewDecoder(r.Body).Decode(&gotBody)
+		_, _ = w.Write([]byte(`{"created":1,"data":[{"b64_json":"` + onePixelPNG + `"}]}`))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	im, _ := p.ImageModel("sd")
+
+	// Unset overrides must be omitted entirely so sd-server keeps its own
+	// per-model defaults.
+	if _, err := im.Generate(context.Background(), imagegen.Request{Prompt: "x"}); err != nil {
+		t.Fatalf("Generate: %v", err)
+	}
+	for _, k := range []string{"steps", "cfg_scale", "negative_prompt", "sample_method", "seed"} {
+		if v, ok := gotBody[k]; ok {
+			t.Errorf("unset request sent %q = %v, want omitted", k, v)
+		}
+	}
+
+	// Set overrides are forwarded with the sd-server-friendly field names.
+	gotBody = nil
+	_, err := im.Generate(context.Background(), imagegen.Request{Prompt: "x"},
+		imagegen.WithSteps(8),
+		imagegen.WithCFGScale(3.5),
+		imagegen.WithNegativePrompt("blurry"),
+		imagegen.WithSampler("euler"),
+		imagegen.WithSeed(42),
+	)
+	if err != nil {
+		t.Fatalf("Generate: %v", err)
+	}
+	want := map[string]any{"steps": float64(8), "cfg_scale": 3.5, "negative_prompt": "blurry", "sample_method": "euler", "seed": float64(42)}
+	for k, w := range want {
+		if gotBody[k] != w {
+			t.Errorf("%s = %v, want %v", k, gotBody[k], w)
+		}
+	}
+}
+
+func TestImageGenerateEmptyPrompt(t *testing.T) {
+	p := New(WithBaseURL("http://example.invalid"))
+	im, _ := p.ImageModel("sd")
+	_, err := im.Generate(context.Background(), imagegen.Request{Prompt: "  "})
+	if !errors.Is(err, llm.ErrUnsupported) {
+		t.Errorf("err = %v, want ErrUnsupported", err)
+	}
+}
+
+func TestAPIErrorClassifies(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusTooManyRequests)
+		_, _ = w.Write([]byte(`{"error":{"message":"slow down","code":"rate_limited"}}`))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	_, err := p.ListModels(context.Background())
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	var apiErr *llm.APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("err type = %T, want *llm.APIError", err)
+	}
+	if apiErr.Status != http.StatusTooManyRequests || apiErr.Code != "rate_limited" {
+		t.Errorf("apiErr = %+v", apiErr)
+	}
+	if llm.Classify(err) != llm.ClassTransient {
+		t.Errorf("429 should classify transient")
+	}
+}