@pi-in-go/pigpen-ahp 0.1.0

package/extensions/ahp/internal/pi/hydration_test.go

@@ -0,0 +1,209 @@
+package pi_test
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"reflect"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/microsoft/agent-host-protocol/clients/go/ahptypes"
+
+	"github.com/MichaelKinsy/pigpen/ahp/internal/host"
+	"github.com/MichaelKinsy/pigpen/ahp/internal/pi"
+	"github.com/MichaelKinsy/pigpen/ahp/internal/testkit"
+	"github.com/MichaelKinsy/pigpen/ahp/internal/twin"
+	"github.com/MichaelKinsy/pigpen/ahp/internal/wire"
+)
+
+// Twins of upstream test/session-hydration.test.ts: opening a session that only exists on disk.
+// The catalogue is backed by Pi's session files, most of which no live host has ever touched;
+// without lazy loading every session the catalogue advertises would answer NotFound on subscribe.
+
+func snapshotState[T any](t *testing.T, client *testkit.Client, channel string) T {
+	t.Helper()
+	result := client.Subscribe(channel)
+	if result.Snapshot == nil {
+		t.Fatalf("no snapshot for %s", channel)
+	}
+	raw, _ := json.Marshal(result.Snapshot.State)
+	var state T
+	if err := json.Unmarshal(raw, &state); err != nil {
+		t.Fatal(err)
+	}
+	return state
+}
+
+func TestOpeningASessionFromTheCatalogue(t *testing.T) {
+	f := startHydrated(t, hydratedOptions{})
+
+	twin.Run(t, "session-hydration", "hydrates a catalogued session and counts it as active", func(t *testing.T) {
+		state := snapshotState[ahptypes.SessionState](t, f.client, f.session())
+		if state.Lifecycle != ahptypes.SessionLifecycleReady || len(state.Chats) != 1 {
+			t.Fatalf("state = %+v", state)
+		}
+		if state.DefaultChat == nil || *state.DefaultChat != f.chat() {
+			t.Fatalf("defaultChat = %v", state.DefaultChat)
+		}
+		if !reflect.DeepEqual(state.WorkingDirectories, []ahptypes.URI{wire.PathToFileURI(f.workspace)}) {
+			t.Fatalf("workingDirectories = %v", state.WorkingDirectories)
+		}
+		testkit.AssertValid(t, "state", "SessionState", state)
+		if got := f.host.Store().Root(wire.RootChannel).ActiveSessions; got == nil || *got != 1 {
+			t.Fatalf("activeSessions = %v", got)
+		}
+	})
+
+	twin.Run(t, "session-hydration", "rebuilds the transcript onto the chat channel", func(t *testing.T) {
+		chat := snapshotState[ahptypes.ChatState](t, f.client, f.chat())
+		if len(chat.Turns) != 2 || chat.Turns[0].Message.Text != "Read note.txt" || chat.Turns[0].State != ahptypes.TurnStateComplete {
+			t.Fatalf("turns = %+v", turnShapes(chat.Turns))
+		}
+		testkit.AssertValid(t, "state", "ChatState", chat)
+	})
+
+	twin.Run(t, "session-hydration", "pairs each tool call with the result that followed it", func(t *testing.T) {
+		chat := snapshotState[ahptypes.ChatState](t, f.client, f.chat())
+		parts := chat.Turns[0].ResponseParts
+		var kinds []ahptypes.ResponsePartKind
+		for _, p := range parts {
+			raw, _ := json.Marshal(p)
+			var k struct{ Kind ahptypes.ResponsePartKind }
+			_ = json.Unmarshal(raw, &k)
+			kinds = append(kinds, k.Kind)
+		}
+		want := []ahptypes.ResponsePartKind{ahptypes.ResponsePartKindReasoning, ahptypes.ResponsePartKindToolCall, ahptypes.ResponsePartKindMarkdown}
+		if !reflect.DeepEqual(kinds, want) {
+			t.Fatalf("kinds = %v", kinds)
+		}
+		call := parts[1].Value.(*ahptypes.ToolCallResponsePart).ToolCall.Value.(*ahptypes.ToolCallCompletedState)
+		if call.Status != ahptypes.ToolCallStatusCompleted || call.ToolName != "read" {
+			t.Fatalf("toolCall = %+v", call)
+		}
+		sameJSON(t, call.Content, []any{obj{"type": "text", "text": "ALPHA"}}, "tool content")
+	})
+
+	twin.Run(t, "session-hydration", "still answers NotFound for a session that really does not exist", func(t *testing.T) {
+		f.client.ExpectError("subscribe", obj{"channel": wire.SessionURI(newID())}, -32008)
+	})
+
+	twin.Run(t, "session-hydration", "restores images stored in pi user messages", func(t *testing.T) {
+		fresh := startHydrated(t, hydratedOptions{includeImage: true})
+		chat := snapshotState[ahptypes.ChatState](t, fresh.client, fresh.chat())
+		sameJSON(t, chat.Turns[0].Message.Attachments, []any{obj{
+			"type": "embeddedResource", "label": "Image 1", "displayKind": "image", "data": onePixelPNG, "contentType": "image/png",
+		}}, "attachments")
+		testkit.AssertValid(t, "state", "ChatState", chat)
+	})
+
+	twin.Run(t, "session-hydration", "hydrates from either half of the pair", func(t *testing.T) {
+		fresh := startHydrated(t, hydratedOptions{})
+		if r := fresh.client.Subscribe(fresh.chat()); r.Snapshot == nil {
+			t.Fatal("no snapshot")
+		}
+		if !fresh.host.Store().Has(fresh.session()) {
+			t.Fatal("the session must load alongside its chat")
+		}
+	})
+
+	twin.Run(t, "session-hydration", "coalesces concurrent session and chat hydration", func(t *testing.T) {
+		source := startHydrated(t, hydratedOptions{})
+		catalogue := &blockingCatalogue{inner: pi.NewCatalogue(source.root), started: make(chan struct{}), gate: make(chan struct{})}
+		h := testkit.NewHost(host.Options{})
+		var mu sync.Mutex
+		live := map[string]bool{}
+		var adopted []string
+		hydrator := pi.NewHydrator(pi.HydratorOptions{
+			Host: h, Catalogue: catalogue,
+			IsLive:      func(s string) bool { mu.Lock(); defer mu.Unlock(); return live[s] },
+			IsDisposing: func(string) bool { return false },
+			Adopt: func(a pi.AdoptedSession) {
+				mu.Lock()
+				live[a.URI] = true
+				adopted = append(adopted, a.URI)
+				mu.Unlock()
+			},
+		})
+		session, chat := wire.SessionURI(source.sessionID), wire.ChatURI(source.sessionID)
+		results := make(chan bool, 2)
+		go func() { ok, _ := hydrator.Hydrate(context.Background(), session); results <- ok }()
+		<-catalogue.started
+		go func() { ok, _ := hydrator.Hydrate(context.Background(), chat); results <- ok }()
+		time.Sleep(20 * time.Millisecond) // let the second caller reach the coalescing point
+		close(catalogue.gate)
+		if a, b := <-results, <-results; !a || !b {
+			t.Fatalf("hydrate results = %v %v", a, b)
+		}
+		if catalogue.lookupCount() != 1 {
+			t.Fatalf("lookups = %d", catalogue.lookupCount())
+		}
+		if !reflect.DeepEqual(adopted, []string{session}) || !h.Store().Has(session) || !h.Store().Has(chat) {
+			t.Fatalf("adopted %v, session %v chat %v", adopted, h.Store().Has(session), h.Store().Has(chat))
+		}
+	})
+
+	twin.Run(t, "session-hydration", "preserves catalogue modifiedAt when a disk session becomes a live overlay", func(t *testing.T) {
+		fixture := startHydrated(t, hydratedOptions{})
+		file, err := pi.NewCatalogue(fixture.root).FindSessionFile(fixture.sessionID)
+		if err != nil || file == "" {
+			t.Fatalf("file %q err %v", file, err)
+		}
+		stamp := time.Date(2025, 6, 1, 12, 0, 0, 0, time.UTC)
+		if err := os.Chtimes(file, stamp, stamp); err != nil {
+			t.Fatal(err)
+		}
+		iso := "2025-06-01T12:00:00.000Z"
+		listItems := func() []obj {
+			var r struct{ Items []obj }
+			fixture.client.Decode(fixture.client.Must("listSessions", obj{"channel": wire.RootChannel}), &r)
+			return r.Items
+		}
+		if got := listItems(); len(got) != 1 || got[0]["modifiedAt"] != iso {
+			t.Fatalf("before = %v", got)
+		}
+		chat := snapshotState[ahptypes.ChatState](t, fixture.client, fixture.chat())
+		if chat.ModifiedAt != iso {
+			t.Fatalf("chat modifiedAt = %s", chat.ModifiedAt)
+		}
+		if got := listItems(); len(got) != 1 || got[0]["modifiedAt"] != iso {
+			t.Fatalf("after = %v", got)
+		}
+	})
+}
+
+// blockingCatalogue holds the first lookup until the test releases it.
+type blockingCatalogue struct {
+	inner   *pi.Catalogue
+	started chan struct{}
+	gate    chan struct{}
+	once    sync.Once
+	mu      sync.Mutex
+	lookups int
+}
+
+func (b *blockingCatalogue) FindSessionFile(id string) (string, error) {
+	b.mu.Lock()
+	b.lookups++
+	b.mu.Unlock()
+	b.once.Do(func() { close(b.started) })
+	<-b.gate
+	return b.inner.FindSessionFile(id)
+}
+
+func (b *blockingCatalogue) lookupCount() int { b.mu.Lock(); defer b.mu.Unlock(); return b.lookups }
+
+// snapshotStateOf decodes the state of an already-received subscribe result.
+func snapshotStateOf[T any](t *testing.T, result ahptypes.SubscribeResult) T {
+	t.Helper()
+	if result.Snapshot == nil {
+		t.Fatal("no snapshot")
+	}
+	raw, _ := json.Marshal(result.Snapshot.State)
+	var state T
+	if err := json.Unmarshal(raw, &state); err != nil {
+		t.Fatal(err)
+	}
+	return state
+}

package/extensions/ahp/internal/pi/hydrator.go

@@ -0,0 +1,212 @@
+package pi
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"strings"
+	"sync"
+
+	"github.com/microsoft/agent-host-protocol/clients/go/ahptypes"
+
+	"github.com/MichaelKinsy/pigpen/ahp/internal/channels"
+	"github.com/MichaelKinsy/pigpen/ahp/internal/host"
+	"github.com/MichaelKinsy/pigpen/ahp/internal/mapper"
+	"github.com/MichaelKinsy/pigpen/ahp/internal/pisession"
+	"github.com/MichaelKinsy/pigpen/ahp/internal/wire"
+)
+
+// FileFinder locates the file behind a session id ("" when there is none).
+type FileFinder interface {
+	FindSessionFile(sessionID string) (string, error)
+}
+
+// HydratorOptions configure a [Hydrator].
+type HydratorOptions struct {
+	Host      *host.Host
+	Catalogue FileFinder
+	IsLive    func(sessionChannel string) bool
+	// IsDisposing reports a disposal in flight, which must not be raced by a load.
+	IsDisposing       func(sessionChannel string) bool
+	FallbackSelection func() *ahptypes.ModelSelection
+	// Adopt registers the loaded session with the registry, without a backend.
+	Adopt func(AdoptedSession)
+	// WrapStore may replace the store a session file was opened into (the running session's
+	// store reads the host's live mirror instead of the file); nil keeps the file-backed store.
+	WrapStore func(sessionID string, opened SessionStore) SessionStore
+	Log       func(format string, args ...any)
+}
+
+// Hydrator loads a session that exists only on disk into protocol state, on first subscription
+// (port of src/pi/session-hydrator.ts). A chat and its session share one id, so either URI loads
+// the pair. The session becomes ready, since its transcript is genuinely available; it simply has
+// no agent attached until someone starts a turn.
+type Hydrator struct {
+	opts HydratorOptions
+
+	mu         sync.Mutex
+	hydrations map[string]chan struct{}
+}
+
+// NewHydrator creates a hydrator.
+func NewHydrator(opts HydratorOptions) *Hydrator {
+	return &Hydrator{opts: opts, hydrations: map[string]chan struct{}{}}
+}
+
+func (h *Hydrator) logf(format string, args ...any) {
+	if h.opts.Log != nil {
+		h.opts.Log(format, args...)
+	}
+}
+
+// Hydrate makes channel exist in the store if a session file backs it; it reports whether the
+// channel now exists.
+func (h *Hydrator) Hydrate(_ context.Context, channel string) (bool, error) {
+	var sessionID string
+	var ok bool
+	if wire.IsChatChannel(channel) {
+		sessionID, ok = wire.ChatIDFromURI(channel)
+	} else {
+		// The provider alias is explicit: an unknown channel scheme must not become a session
+		// merely because its path resembles one.
+		sessionID, ok = wire.SessionIDFromURI(channel, Provider)
+	}
+	if !ok || sessionID == "" {
+		return false, nil
+	}
+	// Register the session under the URI the client actually used, so a non-standard scheme
+	// resolves to the same channel it subscribed to.
+	session := channel
+	if wire.IsChatChannel(channel) {
+		session = wire.SessionURI(sessionID)
+	}
+	if h.opts.IsLive(session) {
+		return h.opts.Host.Store().Has(channel), nil
+	}
+	if h.opts.IsDisposing(session) {
+		return false, nil
+	}
+
+	h.mu.Lock()
+	if pending, ok := h.hydrations[sessionID]; ok {
+		h.mu.Unlock()
+		<-pending
+		return h.opts.Host.Store().Has(channel), nil
+	}
+	done := make(chan struct{})
+	h.hydrations[sessionID] = done
+	h.mu.Unlock()
+	h.hydrateSession(sessionID, session)
+	h.mu.Lock()
+	delete(h.hydrations, sessionID)
+	h.mu.Unlock()
+	close(done)
+	return h.opts.Host.Store().Has(channel), nil
+}
+
+func firstUserText(turns []ahptypes.Turn) string {
+	for _, t := range turns {
+		if strings.TrimSpace(t.Message.Text) != "" {
+			return t.Message.Text
+		}
+	}
+	return ""
+}
+
+func (h *Hydrator) hydrateSession(sessionID, session string) {
+	chat := wire.ChatURI(sessionID)
+	file, err := h.opts.Catalogue.FindSessionFile(sessionID)
+	if err != nil {
+		h.logf("cannot search for session %s: %v", sessionID, err)
+		return
+	}
+	if file == "" {
+		return
+	}
+	manager, err := pisession.Open(file)
+	if err != nil {
+		h.logf("cannot open %s: %v", file, err)
+		return
+	}
+
+	turns := RebuildHistoryFromSession(manager, RebuildOptions{TurnIDPrefix: sessionID}).Turns
+	// Present only when the window really is a tail: its presence is the protocol's signal that
+	// more history can be paged in.
+	nextCursor := InitialTurnsCursor(manager, sessionID, turns)
+	modifiedAt := nowISO()
+	if len(turns) > 0 && turns[len(turns)-1].StartedAt != nil {
+		modifiedAt = *turns[len(turns)-1].StartedAt
+	}
+	if info, err := os.Stat(file); err == nil {
+		// The file may disappear after it was located; the reconstructed transcript timestamp
+		// remains a valid fallback for this snapshot.
+		modifiedAt = info.ModTime().UTC().Format("2006-01-02T15:04:05.000Z")
+	}
+	workingDirectory := manager.Cwd()
+	title := mapper.SessionDisplayTitle(manager.SessionName(), firstUserText(turns))
+
+	// Another create/adopt or disposal may have won during file I/O: live state must not be
+	// replaced by this disk snapshot.
+	if h.opts.IsLive(session) || h.opts.IsDisposing(session) {
+		return
+	}
+
+	// Read, for the same reason the catalogue reports read; the reducer still clears the bit if a
+	// turn starts.
+	status := ahptypes.SessionStatusIdle | ahptypes.SessionStatusIsRead
+
+	// Which model this conversation was last using. The agent starts only on the first new turn,
+	// so without seeding it here the client's model picker is empty until the user has already
+	// sent something. The recorded model is checked field by field: a session file can carry a
+	// partially populated entry, and the wire id needs both halves of Pi's (provider, modelId).
+	level, provider, modelID := manager.ContextSettings()
+	var selection *ahptypes.ModelSelection
+	if provider != "" && modelID != "" {
+		thinking, _ := json.Marshal(level)
+		selection = &ahptypes.ModelSelection{Id: ModelSelectionID(provider, modelID), Config: map[string]json.RawMessage{ThinkingConfigKey: thinking}}
+	} else if h.opts.FallbackSelection != nil {
+		selection = h.opts.FallbackSelection()
+	}
+
+	chatState := &ahptypes.ChatState{Resource: chat, Title: title, Status: status, ModifiedAt: modifiedAt, Turns: turns}
+	if nextCursor != "" {
+		chatState.TurnsNextCursor = &nextCursor
+	}
+	if selection != nil {
+		chatState.Draft = &ahptypes.Message{Text: "", Origin: ahptypes.MessageOrigin{Kind: ahptypes.MessageKindUser}, Model: selection}
+	}
+	if err := h.opts.Host.Store().Create(chat, chatState); err != nil {
+		h.logf("cannot create %s: %v", chat, err)
+		return
+	}
+	fileMeta, _ := json.Marshal(file)
+	sessionState := &ahptypes.SessionState{
+		Provider: Provider, Title: title, Status: status,
+		// The transcript is genuinely available, so the session is ready.
+		Lifecycle: ahptypes.SessionLifecycleReady, ActiveClients: []ahptypes.SessionActiveClient{},
+		Chats: []ahptypes.ChatSummary{channels.ChatSummaryOf(chatState)}, DefaultChat: &chat,
+		Meta: map[string]json.RawMessage{"piSessionFile": fileMeta, "hydrated": json.RawMessage("true")},
+	}
+	if workingDirectory != "" {
+		sessionState.WorkingDirectories = []ahptypes.URI{wire.PathToFileURI(workingDirectory)}
+	}
+	if err := h.opts.Host.Store().Create(session, sessionState, wire.KindSession); err != nil {
+		h.logf("cannot create %s: %v", session, err)
+		return
+	}
+	createdAt := modifiedAt
+	if len(turns) > 0 && turns[0].StartedAt != nil {
+		createdAt = *turns[0].StartedAt
+	}
+	var store SessionStore = manager
+	if h.opts.WrapStore != nil {
+		store = h.opts.WrapStore(sessionID, store)
+	}
+	if h.opts.Adopt != nil {
+		h.opts.Adopt(AdoptedSession{
+			URI: session, SessionID: sessionID, WorkingDirectory: workingDirectory, SessionManager: store,
+			ChatChannel: chat, CreatedAt: createdAt,
+		})
+	}
+	h.logf("hydrated %s with %d turns", session, len(turns))
+}

package/extensions/ahp/internal/pi/imageinput.go

@@ -0,0 +1,224 @@
+package pi
+
+import (
+	"bytes"
+	"encoding/base64"
+	"encoding/binary"
+	"errors"
+	"fmt"
+	"image"
+	"image/color"
+	"image/draw"
+	"image/gif"
+	"image/jpeg"
+	"image/png"
+
+	"github.com/MichaelKinsy/pigpen/ahp/internal/mapper"
+)
+
+// Port of image-input.ts. Upstream calls Pi's convertToPng / resizeImage (WASM codecs); those are
+// not part of the PiG SDK, so the standard library's PNG, JPEG and GIF codecs plus a small BMP
+// decoder stand in. WebP cannot be decoded here: it passes through unchanged when the header is
+// valid and is never resized (see PORT.md).
+
+const (
+	maxImageDimension = 2000
+	maxImageBytes     = 4_500_000
+)
+
+var supportedInlineTypes = map[string]bool{"image/png": true, "image/jpeg": true, "image/gif": true, "image/webp": true}
+
+// PrepareImagesForPi validates, converts and (when autoResize) bounds client images before they
+// enter the agent. It returns nil for no images.
+func PrepareImagesForPi(images []mapper.Image, autoResize bool) ([]mapper.Image, error) {
+	if len(images) == 0 {
+		return nil, nil
+	}
+	out := make([]mapper.Image, 0, len(images))
+	for i, img := range images {
+		prepared, err := prepareImage(img, autoResize, i)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, prepared)
+	}
+	return out, nil
+}
+
+func prepareImage(img mapper.Image, autoResize bool, index int) (mapper.Image, error) {
+	data := img.Data
+	mimeType := mapper.NormalizeImageMimeType(img.MimeType)
+	if mimeType == "" {
+		return mapper.Image{}, fmt.Errorf("Image %d has an invalid MIME type: %s", index+1, img.MimeType)
+	}
+	if !supportedInlineTypes[mimeType] {
+		converted, err := convertToPNG(data, mimeType)
+		if err != nil {
+			return mapper.Image{}, fmt.Errorf("Image %d could not be converted from %s: %w", index+1, mimeType, err)
+		}
+		data, mimeType = converted, "image/png"
+	}
+	if !autoResize {
+		return mapper.Image{Type: "image", Data: data, MimeType: mimeType}, nil
+	}
+	resized, resizedType, err := resizeImage(data, mimeType)
+	if err != nil {
+		return mapper.Image{}, fmt.Errorf("Image %d could not be prepared for inline model input: %w", index+1, err)
+	}
+	return mapper.Image{Type: "image", Data: resized, MimeType: resizedType}, nil
+}
+
+func decodeAny(raw []byte, mimeType string) (image.Image, error) {
+	switch mimeType {
+	case "image/png":
+		return png.Decode(bytes.NewReader(raw))
+	case "image/jpeg":
+		return jpeg.Decode(bytes.NewReader(raw))
+	case "image/gif":
+		return gif.Decode(bytes.NewReader(raw))
+	case "image/bmp", "image/x-ms-bmp":
+		return decodeBMP(raw)
+	}
+	return nil, fmt.Errorf("no decoder for %s", mimeType)
+}
+
+func encodePNG(img image.Image) (string, error) {
+	var buf bytes.Buffer
+	if err := png.Encode(&buf, img); err != nil {
+		return "", err
+	}
+	return base64.StdEncoding.EncodeToString(buf.Bytes()), nil
+}
+
+func convertToPNG(data, mimeType string) (string, error) {
+	raw, err := base64.StdEncoding.DecodeString(data)
+	if err != nil {
+		return "", err
+	}
+	img, err := decodeAny(raw, mimeType)
+	if err != nil {
+		return "", err
+	}
+	return encodePNG(img)
+}
+
+func resizeImage(data, mimeType string) (string, string, error) {
+	raw, err := base64.StdEncoding.DecodeString(data)
+	if err != nil {
+		return "", "", err
+	}
+	if mimeType == "image/webp" {
+		if len(raw) < 12 || string(raw[:4]) != "RIFF" || string(raw[8:12]) != "WEBP" {
+			return "", "", errors.New("not a WebP image")
+		}
+		return data, mimeType, nil
+	}
+	img, err := decodeAny(raw, mimeType)
+	if err != nil {
+		return "", "", err
+	}
+	b := img.Bounds()
+	if b.Dx() <= maxImageDimension && b.Dy() <= maxImageDimension && len(raw) <= maxImageBytes {
+		return data, mimeType, nil
+	}
+	scale := 1.0
+	if b.Dx() > maxImageDimension {
+		scale = float64(maxImageDimension) / float64(b.Dx())
+	}
+	if s := float64(maxImageDimension) / float64(b.Dy()); s < scale {
+		scale = s
+	}
+	w, h := max(1, int(float64(b.Dx())*scale)), max(1, int(float64(b.Dy())*scale))
+	for {
+		small := boxResize(img, w, h)
+		if mimeType == "image/jpeg" {
+			var buf bytes.Buffer
+			if err := jpeg.Encode(&buf, small, &jpeg.Options{Quality: 85}); err != nil {
+				return "", "", err
+			}
+			if buf.Len() <= maxImageBytes || w <= 1 {
+				return base64.StdEncoding.EncodeToString(buf.Bytes()), "image/jpeg", nil
+			}
+		} else {
+			encoded, err := encodePNG(small)
+			if err != nil {
+				return "", "", err
+			}
+			if base64.StdEncoding.DecodedLen(len(encoded)) <= maxImageBytes || w <= 1 {
+				return encoded, "image/png", nil
+			}
+		}
+		w, h = max(1, w*3/4), max(1, h*3/4)
+	}
+}
+
+// boxResize averages source pixels into each destination pixel.
+func boxResize(src image.Image, w, h int) image.Image {
+	b := src.Bounds()
+	dst := image.NewNRGBA(image.Rect(0, 0, w, h))
+	for y := 0; y < h; y++ {
+		y0, y1 := b.Min.Y+y*b.Dy()/h, b.Min.Y+(y+1)*b.Dy()/h
+		if y1 <= y0 {
+			y1 = y0 + 1
+		}
+		for x := 0; x < w; x++ {
+			x0, x1 := b.Min.X+x*b.Dx()/w, b.Min.X+(x+1)*b.Dx()/w
+			if x1 <= x0 {
+				x1 = x0 + 1
+			}
+			var r, g, bl, a, n uint64
+			for yy := y0; yy < y1; yy++ {
+				for xx := x0; xx < x1; xx++ {
+					pr, pg, pb, pa := src.At(xx, yy).RGBA()
+					r, g, bl, a, n = r+uint64(pr), g+uint64(pg), bl+uint64(pb), a+uint64(pa), n+1
+				}
+			}
+			dst.Set(x, y, color.RGBA64{uint16(r / n), uint16(g / n), uint16(bl / n), uint16(a / n)})
+		}
+	}
+	return dst
+}
+
+// decodeBMP reads uncompressed 24- and 32-bit BMPs (BITMAPINFOHEADER), the shapes clients send.
+func decodeBMP(raw []byte) (image.Image, error) {
+	if len(raw) < 54 || raw[0] != 'B' || raw[1] != 'M' {
+		return nil, errors.New("not a BMP")
+	}
+	offset := int(binary.LittleEndian.Uint32(raw[10:14]))
+	width := int(int32(binary.LittleEndian.Uint32(raw[18:22])))
+	height := int(int32(binary.LittleEndian.Uint32(raw[22:26])))
+	bpp := int(binary.LittleEndian.Uint16(raw[28:30]))
+	compression := binary.LittleEndian.Uint32(raw[30:34])
+	topDown := height < 0
+	if topDown {
+		height = -height
+	}
+	if width <= 0 || height <= 0 || width > 1<<15 || height > 1<<15 || (compression != 0 && compression != 3) || (bpp != 24 && bpp != 32) {
+		return nil, fmt.Errorf("unsupported BMP (bpp=%d compression=%d)", bpp, compression)
+	}
+	stride := (width*bpp/8 + 3) &^ 3
+	if offset < 0 || offset+stride*height > len(raw) {
+		return nil, errors.New("truncated BMP")
+	}
+	img := image.NewNRGBA(image.Rect(0, 0, width, height))
+	draw.Draw(img, img.Bounds(), image.Transparent, image.Point{}, draw.Src)
+	for y := 0; y < height; y++ {
+		row := y
+		if !topDown {
+			row = height - 1 - y
+		}
+		line := raw[offset+row*stride:]
+		for x := 0; x < width; x++ {
+			p := line[x*bpp/8:]
+			a := uint8(255)
+			if bpp == 32 {
+				a = p[3]
+				if a == 0 && compression == 0 {
+					a = 255 // BI_RGB 32-bit files rarely carry a real alpha channel
+				}
+			}
+			img.SetNRGBA(x, y, color.NRGBA{R: p[2], G: p[1], B: p[0], A: a})
+		}
+	}
+	return img, nil
+}

package/extensions/ahp/internal/pi/imageinput_test.go

@@ -0,0 +1,57 @@
+package pi
+
+import (
+	"bytes"
+	"encoding/base64"
+	"strings"
+	"testing"
+
+	"github.com/MichaelKinsy/pigpen/ahp/internal/mapper"
+	"github.com/MichaelKinsy/pigpen/ahp/internal/twin"
+)
+
+// Twins of upstream test/image-input.test.ts (support/images.ts fixtures).
+
+const twoPixelBMP = "Qk1GAAAAAAAAADYAAAAoAAAAAgAAAAIAAAABABgAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAD/AAD/AAAAAP8AAP8AAA=="
+
+const onePixelPNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
+
+func TestImageInput(t *testing.T) {
+	twin.Run(t, "image-input", "converts an unsupported image type even when auto-resize is disabled", func(t *testing.T) {
+		prepared, err := PrepareImagesForPi([]mapper.Image{{Type: "image", Data: twoPixelBMP, MimeType: "image/bmp"}}, false)
+		if err != nil || len(prepared) != 1 {
+			t.Fatalf("%v %v", prepared, err)
+		}
+		if prepared[0].MimeType != "image/png" {
+			t.Fatalf("mime %s", prepared[0].MimeType)
+		}
+		raw, _ := base64.StdEncoding.DecodeString(prepared[0].Data)
+		if !bytes.HasPrefix(raw, []byte("\x89PNG\r\n\x1a\n")) {
+			t.Fatalf("not a PNG: %x", raw[:8])
+		}
+	})
+
+	twin.Run(t, "image-input", "fails when image bytes cannot be prepared", func(t *testing.T) {
+		_, err := PrepareImagesForPi([]mapper.Image{{Type: "image", Data: base64.StdEncoding.EncodeToString([]byte("not an image")), MimeType: "image/png"}}, true)
+		if err == nil || !strings.Contains(err.Error(), "could not be prepared") {
+			t.Fatalf("%v", err)
+		}
+	})
+}
+
+func TestImageInputAdditions(t *testing.T) {
+	// Additions: the resize and validation paths the standard-library codecs stand in for.
+	if got, err := PrepareImagesForPi(nil, true); got != nil || err != nil {
+		t.Fatalf("no images: %v %v", got, err)
+	}
+	same, err := PrepareImagesForPi([]mapper.Image{{Type: "image", Data: onePixelPNG, MimeType: "IMAGE/PNG; charset=x"}}, true)
+	if err != nil || same[0].Data != onePixelPNG || same[0].MimeType != "image/png" {
+		t.Fatalf("a small PNG must pass through: %+v %v", same, err)
+	}
+	if _, err := PrepareImagesForPi([]mapper.Image{{Type: "image", Data: onePixelPNG, MimeType: "text/plain"}}, true); err == nil {
+		t.Fatal("a non-image MIME type must be rejected")
+	}
+	if _, err := PrepareImagesForPi([]mapper.Image{{Type: "image", Data: "!!!", MimeType: "image/tiff"}}, false); err == nil {
+		t.Fatal("an undecodable conversion must fail")
+	}
+}