fix(media): drop oldest images on over-count instead of refusing the request

media.Normalize refused (ErrUnsupported) when a request carried more images than
the target's MaxImagesPerReq, on the theory that a failover chain would try a
roomier target. In practice the chain's targets share the same cap — an agent loop
that accumulates a preview image per iteration (e.g. scaddy's write_scad) blows
past the cap, EVERY target rejects ("9 images, target allows at most 8"), and the
run dies. Observed live on ollama-cloud (cap 8).

Now: over-count keeps the most-recent MaxImagesPerReq images and replaces each
older one with a short text placeholder ("[earlier image omitted to fit this
model's per-request image limit]"), preserving each message's turn structure and
telling the model an image was elided. The most-recent images are the relevant
ones in an iterative run. Copy-on-write; the input request is never mutated. The
per-model threshold stays configurable via Capabilities.MaxImagesPerReq (0 still
means no image support); SupportsImages / MIME / byte-budget / dimension behavior
is unchanged, and the provider-side count backstop remains.

Test: TestNormalizeTooManyImages_DropsOldest — 3 images, cap 2 → 2 kept (the most
recent), 1 placeholder, no error, oldest dropped, input unmutated.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

media/media_test.go

@@ -149,18 +149,50 @@ func TestNormalizeImagesUnsupported(t *testing.T) {
 	}
 }
 
-func TestNormalizeTooManyImages(t *testing.T) {
-	img := llm.Image("image/png", encPNG(t, gradient(4, 4)))
+func TestNormalizeTooManyImages_DropsOldest(t *testing.T) {
+	// 3 distinguishable images across 2 messages; cap = 2. Overflow 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.
+	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("drop-oldest overflow 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 strings.Contains(v.Text, "omitted") {
+					placeholders++
+				}
+			}
+		}
+	}
+	if len(imgs) != 2 {
+		t.Fatalf("kept %d images, want 2 (the cap)", len(imgs))
+	}
+	if placeholders != 1 {
+		t.Errorf("placeholders = %d, want 1 for the dropped oldest image", placeholders)
+	}
+	for _, im := range imgs {
+		if bytes.Equal(im.Data, a.Data) {
+			t.Errorf("oldest image was kept; the most-recent two should survive")
+		}
+	}
+	// The input request must be untouched (copy-on-write).
+	if len(req.Messages[0].Parts) != 2 {
+		t.Errorf("input request was mutated: %+v", req.Messages[0].Parts)
 	}
 }