run: guard empty text part in runAgent + drop cross-repo doc ref (gadfly #16)

Every reviewer flagged that runAgent appended llm.Text(input) unconditionally, so
an image-only run (blank prompt) emitted an empty TextPart — inconsistent with the
sibling runSession.AttachImages which guards it. Mirror that guard
(strings.TrimSpace(input) != ""). Also:
- copy opts before appending (variadic backing array can have spare capacity; avoid
  aliasing a caller's slice).
- reword the doc comment to drop the mort-agentexec reference (executus is a
  standalone lib; a consumer name doesn't belong in its godoc).

Tests: image+text are co-located in ONE user message; an image-only run emits no
blank TextPart.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

run/executor.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"strings"
 	"time"
 
 	"gitea.stevedudenhoeffer.com/steve/majordomo/agent"
@@ -445,16 +446,23 @@ func detach(ctx context.Context) context.Context {
 // input arg, so when the invocation carries images they're folded into the first
 // user message (text + image parts) via WithHistory and Run is called with an
 // empty input — the model then sees a multimodal opening turn. The image-less path
-// passes the prompt straight through. Mirrors mort agentexec's multimodal seeding.
+// passes the prompt straight through.
+//
+// The text part is omitted when input is blank (image-only run), matching
+// runSession.AttachImages so no empty TextPart is sent.
 func runAgent(ctx context.Context, ag *agent.Agent, input string, images []llm.ImagePart, opts ...agent.RunOption) (*agent.Result, error) {
 	if len(images) == 0 {
 		return ag.Run(ctx, input, opts...)
 	}
 	parts := make([]llm.Part, 0, len(images)+1)
+	if strings.TrimSpace(input) != "" {
 		parts = append(parts, llm.Text(input))
+	}
 	for _, img := range images {
 		parts = append(parts, img)
 	}
-	opts = append(opts, agent.WithHistory([]llm.Message{llm.UserParts(parts...)}))
+	// Copy opts before appending so a caller-supplied backing array is never
+	// mutated/aliased (the variadic slice can have spare capacity).
+	opts = append(opts[:len(opts):len(opts)], agent.WithHistory([]llm.Message{llm.UserParts(parts...)}))
 	return ag.Run(ctx, "", opts...)
 }

run/images_test.go

@@ -36,9 +36,11 @@ func TestExecutorFoldsInitialImages(t *testing.T) {
 	if len(calls) == 0 {
 		t.Fatal("no model calls recorded")
 	}
-	// The first request must carry a user message bearing the image bytes + prompt.
-	sawImage, sawText := false, false
+	// The text + image must be CO-LOCATED in a single user message (not split
+	// across two), so the model reads them as one multimodal turn.
+	coLocated := false
 	for _, msg := range calls[0].Request.Messages {
+		sawImage, sawText := false, false
 		for _, p := range msg.Parts {
 			switch pp := p.(type) {
 			case llm.ImagePart:
@@ -51,12 +53,38 @@ func TestExecutorFoldsInitialImages(t *testing.T) {
 				}
 			}
 		}
+		if sawImage && sawText {
+			coLocated = true
+		}
+	}
+	if !coLocated {
+		t.Error("image + prompt text were not folded into the SAME user message")
+	}
+}
+
+// TestExecutorImageOnlyNoBlankText: an image-only run (blank prompt) must NOT emit
+// an empty TextPart — the message carries just the image, matching
+// runSession.AttachImages's guard.
+func TestExecutorImageOnlyNoBlankText(t *testing.T) {
+	fp := fake.New("fake")
+	fp.Enqueue("m", fake.Reply("saw it"))
+	m, _ := fp.Model("m")
+
+	inv := tool.Invocation{RunID: "r3", Images: []llm.ImagePart{{MIME: "image/png", Data: []byte("IMG")}}}
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+	})
+	res := ex.Run(context.Background(), run.RunnableAgent{ModelTier: "m"}, inv, "   ")
+	if res.Err != nil {
+		t.Fatalf("run error: %v", res.Err)
+	}
+	for _, msg := range fp.Calls()[0].Request.Messages {
+		for _, p := range msg.Parts {
+			if tp, ok := p.(llm.TextPart); ok && strings.TrimSpace(tp.Text) == "" {
+				t.Error("image-only run emitted a blank TextPart")
 			}
-	if !sawImage {
-		t.Error("initial image was not folded into the first model request (dropped)")
 		}
-	if !sawText {
-		t.Error("prompt text missing from the multimodal first message")
 	}
 }