@pi-in-go/pigpen-acp 0.1.0

package/extensions/acp/cmd/pig-acp/internal/acp/translate.go

@@ -0,0 +1,352 @@
+package acp
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"unicode"
+)
+
+// This file ports src/acp/translate/{prompt,pi-tools,pi-messages,bash}.ts. Values that come
+// from pi are decoded JSON (map[string]any, []any, string, float64), read the way the original
+// reads them: a wrong type reads as absent, never as an error.
+
+// jsTrim is String.prototype.trim: Unicode white space plus the byte order mark.
+func jsTrim(s string) string {
+	return strings.TrimFunc(s, func(r rune) bool { return unicode.IsSpace(r) || r == '\uFEFF' })
+}
+
+func asObject(v any) map[string]any {
+	m, _ := v.(map[string]any)
+	return m
+}
+
+func strOf(m map[string]any, key string) (string, bool) {
+	s, ok := m[key].(string)
+	return s, ok
+}
+
+// base64ByteLength is Buffer.byteLength(s, 'base64').
+func base64ByteLength(s string) int {
+	n := len(s)
+	if n == 0 {
+		return 0
+	}
+	pad := 0
+	if strings.HasSuffix(s, "==") {
+		pad = 2
+	} else if strings.HasSuffix(s, "=") {
+		pad = 1
+	}
+	return (n*3)>>2 - pad
+}
+
+// PromptToPiMessage turns ACP prompt blocks into pi message text and images.
+func PromptToPiMessage(blocks []ContentBlock) (string, []Image) {
+	var msg strings.Builder
+	images := []Image{}
+	for _, b := range blocks {
+		switch b["type"] {
+		case "text":
+			if s, ok := b["text"].(string); ok {
+				msg.WriteString(s)
+			}
+		case "resource_link":
+			fmt.Fprintf(&msg, "\n[Context] %s", jsString(b["uri"]))
+		case "image":
+			// pi expects base64 image bytes in data without a data-url prefix.
+			images = append(images, Image{"type": "image", "mimeType": b["mimeType"], "data": b["data"]})
+		case "resource":
+			r := asObject(b["resource"])
+			uri := "(unknown)"
+			if s, ok := strOf(r, "uri"); ok {
+				uri = s
+			}
+			if text, ok := strOf(r, "text"); ok {
+				mime := "text/plain"
+				if s, ok := strOf(r, "mimeType"); ok {
+					mime = s
+				}
+				fmt.Fprintf(&msg, "\n[Embedded Context] %s (%s)\n%s", uri, mime, text)
+			} else if blob, ok := strOf(r, "blob"); ok {
+				mime := "application/octet-stream"
+				if s, ok := strOf(r, "mimeType"); ok {
+					mime = s
+				}
+				fmt.Fprintf(&msg, "\n[Embedded Context] %s (%s, %d bytes)", uri, mime, base64ByteLength(blob))
+			} else {
+				fmt.Fprintf(&msg, "\n[Embedded Context] %s", uri)
+			}
+		case "audio":
+			data, _ := b["data"].(string)
+			fmt.Fprintf(&msg, "\n[Audio] (%s, %d bytes) not supported by pig-acp", jsString(b["mimeType"]), base64ByteLength(data))
+		}
+	}
+	return msg.String(), images
+}
+
+// jsString renders a value like a JS template literal would.
+func jsString(v any) string {
+	switch x := v.(type) {
+	case nil:
+		return "undefined"
+	case string:
+		return x
+	case float64:
+		return fmt.Sprint(x)
+	default:
+		return fmt.Sprint(x)
+	}
+}
+
+func textBlocks(content any) string {
+	arr, ok := content.([]any)
+	if !ok {
+		return ""
+	}
+	var b strings.Builder
+	for _, c := range arr {
+		m := asObject(c)
+		if m["type"] == "text" {
+			if s, ok := m["text"].(string); ok {
+				b.WriteString(s)
+			}
+		}
+	}
+	return b.String()
+}
+
+// NormalizePiMessageText joins the text of a user message.
+func NormalizePiMessageText(content any) string {
+	if s, ok := content.(string); ok {
+		return s
+	}
+	return textBlocks(content)
+}
+
+// NormalizePiAssistantText joins the text blocks of an assistant message.
+func NormalizePiAssistantText(content any) string { return textBlocks(content) }
+
+func firstString(pairs ...[2]any) (string, bool) {
+	for _, p := range pairs {
+		if m, ok := p[0].(map[string]any); ok {
+			if s, ok := m[p[1].(string)].(string); ok {
+				return s, true
+			}
+		}
+	}
+	return "", false
+}
+
+// asNumber reads a JSON number (float64 after decoding; Go integers when built by hand).
+func asNumber(v any) (float64, bool) {
+	switch n := v.(type) {
+	case float64:
+		return n, true
+	case float32:
+		return float64(n), true
+	case int:
+		return float64(n), true
+	case int64:
+		return float64(n), true
+	case int32:
+		return float64(n), true
+	}
+	return 0, false
+}
+
+func firstNumber(pairs ...[2]any) (float64, bool) {
+	for _, p := range pairs {
+		if m, ok := p[0].(map[string]any); ok {
+			if n, ok := asNumber(m[p[1].(string)]); ok {
+				return n, true
+			}
+		}
+	}
+	return 0, false
+}
+
+// jsonStringify is JSON.stringify(v, null, 2) apart from key order (Go sorts map keys).
+func jsonStringify(v any) string {
+	var buf bytes.Buffer
+	enc := json.NewEncoder(&buf)
+	enc.SetEscapeHTML(false)
+	enc.SetIndent("", "  ")
+	if err := enc.Encode(v); err != nil {
+		return fmt.Sprint(v)
+	}
+	return strings.TrimSuffix(buf.String(), "\n")
+}
+
+// truthy is JS truthiness for the values a tool result can hold.
+func truthy(v any) bool {
+	switch x := v.(type) {
+	case nil:
+		return false
+	case bool:
+		return x
+	case string:
+		return x != ""
+	case float64:
+		return x != 0
+	}
+	return true
+}
+
+// ToolResultToText renders a pi tool result as text.
+func ToolResultToText(result any) string {
+	if !truthy(result) {
+		return ""
+	}
+	res := asObject(result)
+	details := asObject(res["details"])
+
+	// pi's edit tool returns a terse success message in content and the full unified diff in details.diff.
+	if diff, ok := details["diff"].(string); ok && jsTrim(diff) != "" {
+		return diff
+	}
+	if content, ok := res["content"].([]any); ok {
+		var texts []string
+		for _, c := range content {
+			m := asObject(c)
+			if s, ok := m["text"].(string); ok && m["type"] == "text" && s != "" {
+				texts = append(texts, s)
+			}
+		}
+		if len(texts) > 0 {
+			return strings.Join(texts, "")
+		}
+	}
+
+	stdout, hasOut := firstString([2]any{details, "stdout"}, [2]any{res, "stdout"}, [2]any{details, "output"}, [2]any{res, "output"})
+	stderr, hasErr := firstString([2]any{details, "stderr"}, [2]any{res, "stderr"})
+	exit, hasExit := firstNumber([2]any{details, "exitCode"}, [2]any{res, "exitCode"}, [2]any{details, "code"}, [2]any{res, "code"})
+
+	if (hasOut && jsTrim(stdout) != "") || (hasErr && jsTrim(stderr) != "") {
+		var parts []string
+		if hasOut && jsTrim(stdout) != "" {
+			parts = append(parts, stdout)
+		}
+		if hasErr && jsTrim(stderr) != "" {
+			parts = append(parts, "stderr:\n"+stderr)
+		}
+		if hasExit {
+			parts = append(parts, fmt.Sprintf("exit code: %s", jsNumber(exit)))
+		}
+		return strings.TrimRightFunc(strings.Join(parts, "\n\n"), func(r rune) bool { return unicode.IsSpace(r) || r == '\uFEFF' })
+	}
+	return jsonStringify(result)
+}
+
+func jsNumber(f float64) string {
+	if f == float64(int64(f)) {
+		return fmt.Sprint(int64(f))
+	}
+	return fmt.Sprint(f)
+}
+
+// IsBashTool reports whether a tool name is bash (case-insensitive).
+func IsBashTool(name string) bool { return strings.ToLower(name) == "bash" }
+
+// BashCommand finds the command in tool arguments or a result.
+func BashCommand(v any) (string, bool) {
+	rec := asObject(v)
+	get := func(m map[string]any) (any, bool) {
+		if m == nil {
+			return nil, false
+		}
+		for _, k := range []string{"command", "cmd"} {
+			if x, ok := m[k]; ok && x != nil {
+				return x, true
+			}
+		}
+		return nil, false
+	}
+	// ?? picks the first non-nullish value even when it is not a string.
+	for _, m := range []map[string]any{rec, asObject(rec["args"]), asObject(rec["input"]), asObject(rec["rawInput"]), asObject(rec["toolInput"]), asObject(rec["details"])} {
+		if x, ok := get(m); ok {
+			if s, ok := x.(string); ok && jsTrim(s) != "" {
+				return s, true
+			}
+			return "", false
+		}
+	}
+	return "", false
+}
+
+// BashResultText is the output text of a bash result.
+func BashResultText(result any) string {
+	rec := asObject(result)
+	if content, ok := rec["content"].([]any); ok {
+		var texts []string
+		for _, c := range content {
+			m := asObject(c)
+			if s, ok := m["text"].(string); ok && m["type"] == "text" && s != "" {
+				texts = append(texts, s)
+			}
+		}
+		if len(texts) > 0 {
+			return strings.Join(texts, "")
+		}
+	}
+	details := asObject(rec["details"])
+	stdout, _ := firstString([2]any{details, "stdout"}, [2]any{rec, "stdout"}, [2]any{details, "output"}, [2]any{rec, "output"})
+	stderr, _ := firstString([2]any{details, "stderr"}, [2]any{rec, "stderr"})
+	var parts []string
+	for _, p := range []string{stdout, stderr} {
+		if p != "" {
+			parts = append(parts, p)
+		}
+	}
+	return strings.Join(parts, "\n")
+}
+
+// BashExitCode is the exit code of a bash result (1 for an error without one).
+func BashExitCode(result any, isError bool) int {
+	rec := asObject(result)
+	details := asObject(rec["details"])
+	// details?.exitCode ?? record?.exitCode ?? details?.code ?? record?.code: first non-nullish.
+	for _, p := range [][2]any{{details, "exitCode"}, {rec, "exitCode"}, {details, "code"}, {rec, "code"}} {
+		if m, _ := p[0].(map[string]any); m != nil {
+			if v, ok := m[p[1].(string)]; ok && v != nil {
+				if n, ok := asNumber(v); ok {
+					return int(n)
+				}
+				break
+			}
+		}
+	}
+	if isError {
+		return 1
+	}
+	return 0
+}
+
+// BashOutputDelta is the appended part of the output.
+func BashOutputDelta(previous, next string) string {
+	if strings.HasPrefix(next, previous) {
+		return next[len(previous):]
+	}
+	return next
+}
+
+// BashTerminalContent is the terminal tool-call content.
+func BashTerminalContent(toolCallID string) []any {
+	return []any{map[string]any{"type": "terminal", "terminalId": toolCallID}}
+}
+
+// BashTerminalInfoMeta is the terminal_info _meta.
+func BashTerminalInfoMeta(toolCallID, cwd string) map[string]any {
+	return map[string]any{"terminal_info": map[string]any{"terminal_id": toolCallID, "cwd": cwd}}
+}
+
+// BashTerminalOutputMeta is the terminal_output _meta.
+func BashTerminalOutputMeta(toolCallID, data string) map[string]any {
+	return map[string]any{"terminal_output": map[string]any{"terminal_id": toolCallID, "data": data}}
+}
+
+// BashTerminalExitMeta is the terminal_exit _meta.
+func BashTerminalExitMeta(toolCallID string, exitCode int) map[string]any {
+	return map[string]any{"terminal_exit": map[string]any{"terminal_id": toolCallID, "exit_code": exitCode, "signal": nil}}
+}

package/extensions/acp/cmd/pig-acp/internal/acp/translate_test.go

@@ -0,0 +1,105 @@
+package acp
+
+// Twins of test/unit/pi-tools.test.ts, prompt-to-pi-message.test.ts, pi-messages.test.ts.
+
+import (
+	"encoding/base64"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+func TestPiTools(t *testing.T) {
+	tw(t, "unit/pi-tools", "toolResultToText: extracts text from content blocks", func(t *testing.T) {
+		got := ToolResultToText(map[string]any{"content": []any{
+			map[string]any{"type": "text", "text": "hello"}, map[string]any{"type": "text", "text": " world"}}})
+		if got != "hello world" {
+			t.Errorf("got %q", got)
+		}
+	})
+	tw(t, "unit/pi-tools", "toolResultToText: prefers details.diff when present", func(t *testing.T) {
+		got := ToolResultToText(map[string]any{
+			"content": []any{map[string]any{"type": "text", "text": "Successfully replaced 2 block(s) in a.txt."}},
+			"details": map[string]any{"diff": "--- a\n+++ b\n"}})
+		if got != "--- a\n+++ b\n" {
+			t.Errorf("got %q", got)
+		}
+	})
+	tw(t, "unit/pi-tools", "toolResultToText: falls back to JSON", func(t *testing.T) {
+		got := ToolResultToText(map[string]any{"a": 1})
+		if !regexp.MustCompile(`"a": 1`).MatchString(got) {
+			t.Errorf("got %q", got)
+		}
+	})
+	tw(t, "unit/pi-tools", "toolResultToText: extracts bash stdout/stderr from details", func(t *testing.T) {
+		got := ToolResultToText(map[string]any{"details": map[string]any{"stdout": "ok\n", "stderr": "warn\n", "exitCode": 0}})
+		for _, want := range []string{"ok", "stderr:", "warn", "exit code: 0"} {
+			if !strings.Contains(got, want) {
+				t.Errorf("%q missing %q", got, want)
+			}
+		}
+	})
+}
+
+func TestPromptToPiMessage(t *testing.T) {
+	tw(t, "unit/prompt-to-pi-message", "promptToPiMessage: concatenates text and resource links", func(t *testing.T) {
+		msg, images := PromptToPiMessage([]ContentBlock{
+			{"type": "text", "text": "Hello"},
+			{"type": "resource_link", "uri": "file:///tmp/foo.txt", "name": "foo"},
+			{"type": "text", "text": " world"}})
+		if msg != "Hello\n[Context] file:///tmp/foo.txt world" || len(images) != 0 {
+			t.Errorf("msg=%q images=%v", msg, images)
+		}
+	})
+	tw(t, "unit/prompt-to-pi-message", "promptToPiMessage: includes embedded resource text as marker", func(t *testing.T) {
+		msg, images := PromptToPiMessage([]ContentBlock{{"type": "resource", "resource": map[string]any{"uri": "file:///tmp/a.txt", "mimeType": "text/plain", "text": "hi"}}})
+		if msg != "\n[Embedded Context] file:///tmp/a.txt (text/plain)\nhi" || len(images) != 0 {
+			t.Errorf("msg=%q", msg)
+		}
+	})
+	tw(t, "unit/prompt-to-pi-message", "promptToPiMessage: includes embedded resource blob as marker", func(t *testing.T) {
+		blob := base64.StdEncoding.EncodeToString([]byte("xyz"))
+		msg, images := PromptToPiMessage([]ContentBlock{{"type": "resource", "resource": map[string]any{"uri": "file:///tmp/a.bin", "mimeType": "application/octet-stream", "blob": blob}}})
+		if msg != "\n[Embedded Context] file:///tmp/a.bin (application/octet-stream, 3 bytes)" || len(images) != 0 {
+			t.Errorf("msg=%q", msg)
+		}
+	})
+	tw(t, "unit/prompt-to-pi-message", "promptToPiMessage: includes audio as marker", func(t *testing.T) {
+		data := base64.StdEncoding.EncodeToString([]byte("abc"))
+		msg, images := PromptToPiMessage([]ContentBlock{{"type": "audio", "mimeType": "audio/wav", "data": data}})
+		// Renamed identity: the marker names pig-acp, where the original names pi-acp.
+		if msg != "\n[Audio] (audio/wav, 3 bytes) not supported by pig-acp" || len(images) != 0 {
+			t.Errorf("msg=%q", msg)
+		}
+	})
+	tw(t, "unit/prompt-to-pi-message", "promptToPiMessage: maps image to pi image content", func(t *testing.T) {
+		b64 := base64.StdEncoding.EncodeToString([]byte("abc"))
+		msg, images := PromptToPiMessage([]ContentBlock{{"type": "text", "text": "see"}, {"type": "image", "mimeType": "image/png", "data": b64, "uri": "img-1"}})
+		if msg != "see" || len(images) != 1 {
+			t.Fatalf("msg=%q images=%v", msg, images)
+		}
+		jsonEqual(t, images[0], map[string]any{"type": "image", "mimeType": "image/png", "data": b64})
+	})
+}
+
+func TestPiMessages(t *testing.T) {
+	tw(t, "unit/pi-messages", "normalizePiMessageText: supports string", func(t *testing.T) {
+		if NormalizePiMessageText("hello") != "hello" {
+			t.Fail()
+		}
+	})
+	tw(t, "unit/pi-messages", "normalizePiMessageText: joins text blocks", func(t *testing.T) {
+		got := NormalizePiMessageText([]any{
+			map[string]any{"type": "text", "text": "a"}, map[string]any{"type": "text", "text": "b"}, map[string]any{"type": "not_text", "x": 1}})
+		if got != "ab" {
+			t.Errorf("got %q", got)
+		}
+	})
+	tw(t, "unit/pi-messages", "normalizePiAssistantText: joins only text blocks", func(t *testing.T) {
+		got := NormalizePiAssistantText([]any{
+			map[string]any{"type": "text", "text": "hi"}, map[string]any{"type": "thinking", "text": "..."}, map[string]any{"type": "text", "text": "!"}})
+		if got != "hi!" {
+			t.Errorf("got %q", got)
+		}
+	})
+}

package/extensions/acp/cmd/pig-acp/internal/acp/twin_test.go

@@ -0,0 +1,28 @@
+package acp
+
+// Twin helpers for a port whose original has tests. Every upstream test case gets one
+// tw(...) call carrying the upstream title unchanged, or one tskip(...) with the reason it
+// cannot be ported. `pigeq twins check` reads these calls and fails on a missing title, an
+// unknown one (a misspelling) or one reason shared by many skips.
+//
+//	pigeq twins list --tests <upstream>/test > port/upstream-tests.json
+//	pigeq twins check --ledger port/upstream-tests.json --go extensions/<name> [--files a,b]
+//
+// Copy this file into the port as twin_test.go and replace acp with the package name (in
+// an external test package use `acp_test`). A parametrized upstream title (it contains
+// `${`) is twinned once, with the template text unchanged.
+
+import "testing"
+
+// tw runs one exact twin: file is the upstream test file (its name without .test.mjs), title
+// the upstream test title, unchanged.
+func tw(t *testing.T, file, title string, fn func(t *testing.T)) {
+	t.Helper()
+	t.Run(title, fn)
+}
+
+// tskip records a named gap: the upstream case has no Go twin, with its own reason.
+func tskip(t *testing.T, file, title, reason string) {
+	t.Helper()
+	t.Run(title, func(t *testing.T) { t.Skip(reason) })
+}

package/extensions/acp/cmd/pig-acp/internal/acp/types.go

@@ -0,0 +1,202 @@
+// Package acp is the Agent Client Protocol side of pig-acp: the translation layer between
+// an ACP client (an editor) and a PiG agent driven over `pig --mode rpc`. It ports the
+// src/acp/* tree of pi-acp (Sergii Kozak, MIT); see the Package's CREDITS.md.
+package acp
+
+import "fmt"
+
+// ProtocolVersion is the only ACP protocol version this adapter speaks. It is pinned to the
+// schema of @agentclientprotocol/sdk 0.26.0 (PROTOCOL_VERSION = 1), the one pi-acp builds on.
+const ProtocolVersion = 1
+
+// Update is one ACP session update (`session/update` params.update). It is a JSON object,
+// so an omitted field and a null field stay distinct, as in the original.
+type Update = map[string]any
+
+// Event is one record pig writes in RPC mode (an agent event or an extension UI request).
+type Event = map[string]any
+
+// ContentBlock is one block of an ACP prompt.
+type ContentBlock = map[string]any
+
+// StopReason is how a prompt turn ended. "error" is internal: ACP has no such stop reason.
+type StopReason string
+
+// Stop reasons.
+const (
+	StopEndTurn   StopReason = "end_turn"
+	StopCancelled StopReason = "cancelled"
+	StopError     StopReason = "error"
+)
+
+// RequestError is a JSON-RPC error with an ACP code (the SDK's RequestError).
+type RequestError struct {
+	Code    int
+	Message string
+	Data    any
+}
+
+func (e *RequestError) Error() string { return e.Message }
+
+func withDetail(base, detail string) string {
+	if detail == "" {
+		return base
+	}
+	return fmt.Sprintf("%s: %s", base, detail)
+}
+
+// ErrParse is JSON-RPC -32700.
+func ErrParse(data any, detail string) *RequestError {
+	return &RequestError{Code: -32700, Message: withDetail("Parse error", detail), Data: data}
+}
+
+// ErrInvalidRequest is JSON-RPC -32600.
+func ErrInvalidRequest(data any, detail string) *RequestError {
+	return &RequestError{Code: -32600, Message: withDetail("Invalid request", detail), Data: data}
+}
+
+// ErrMethodNotFound is JSON-RPC -32601.
+func ErrMethodNotFound(method string) *RequestError {
+	return &RequestError{Code: -32601, Message: fmt.Sprintf("%q: %s", "Method not found", method), Data: map[string]any{"method": method}}
+}
+
+// ErrInvalidParams is JSON-RPC -32602.
+func ErrInvalidParams(data any, detail string) *RequestError {
+	return &RequestError{Code: -32602, Message: withDetail("Invalid params", detail), Data: data}
+}
+
+// ErrInternal is JSON-RPC -32603.
+func ErrInternal(data any, detail string) *RequestError {
+	return &RequestError{Code: -32603, Message: withDetail("Internal error", detail), Data: data}
+}
+
+// ErrAuthRequired is the ACP "authentication required" error, -32000.
+func ErrAuthRequired(data any, detail string) *RequestError {
+	return &RequestError{Code: -32000, Message: withDetail("Authentication required", detail), Data: data}
+}
+
+// PermissionOption is one choice offered in `session/request_permission`.
+type PermissionOption struct {
+	OptionID string `json:"optionId"`
+	Name     string `json:"name"`
+	Kind     string `json:"kind"`
+}
+
+// PermissionRequest is `session/request_permission` params.
+type PermissionRequest struct {
+	SessionID string             `json:"sessionId"`
+	ToolCall  map[string]any     `json:"toolCall"`
+	Options   []PermissionOption `json:"options"`
+}
+
+// PermissionOutcome is the client's answer: Outcome "selected" (with OptionID) or "cancelled".
+type PermissionOutcome struct {
+	Outcome  string `json:"outcome"`
+	OptionID string `json:"optionId,omitempty"`
+}
+
+// PermissionResponse is `session/request_permission` result.
+type PermissionResponse struct {
+	Outcome PermissionOutcome `json:"outcome"`
+}
+
+// Conn is what the adapter needs from the ACP connection to the client
+// (the SDK's AgentSideConnection subset pi-acp uses).
+type Conn interface {
+	// SessionUpdate sends a `session/update` notification.
+	SessionUpdate(sessionID string, update Update) error
+	// RequestPermission sends `session/request_permission` and waits for the answer.
+	RequestPermission(req PermissionRequest) (PermissionResponse, error)
+}
+
+// Proc is the pi RPC child process as the session sees it (pirpc.Process implements it).
+type Proc interface {
+	OnEvent(handler func(Event)) (unsubscribe func())
+	Prompt(message string, images []Image) error
+	Abort() error
+	GetState() (map[string]any, error)
+	GetAvailableModels() (map[string]any, error)
+	SetModel(provider, modelID string) error
+	GetAvailableThinkingLevels() ([]string, error)
+	SetThinkingLevel(level string) error
+	SetFollowUpMode(mode string) error
+	SetSteeringMode(mode string) error
+	// Compact runs manual compaction; customInstructions "" sends none.
+	Compact(customInstructions string) (map[string]any, error)
+	SetAutoCompaction(enabled bool) error
+	// GetSessionStats asks for get_session_stats; timeout 0 waits without a limit.
+	GetSessionStats(timeoutMs int) (SessionStats, error)
+	SetSessionName(name string) error
+	// ExportHTML returns the path pig wrote; outputPath "" lets pig choose.
+	ExportHTML(outputPath string) (string, error)
+	GetMessages() (map[string]any, error)
+	GetCommands() (map[string]any, error)
+	SendExtensionUIResponse(resp map[string]any) error
+	Dispose()
+}
+
+// Image is a pi image attachment: {type:"image", mimeType, data}.
+type Image = map[string]any
+
+// SessionStats is `get_session_stats` data, kept as a JSON object.
+type SessionStats = map[string]any
+
+// SessionStatsTimeoutMs bounds the auxiliary context-usage request.
+const SessionStatsTimeoutMs = 1000
+
+// SpawnParams are the options for starting a pi child.
+type SpawnParams struct {
+	Cwd string
+	// PiCommand overrides the executable ("" = default).
+	PiCommand string
+	// SessionPath makes pi persist to this exact session file (--session).
+	SessionPath string
+}
+
+// SpawnFunc starts a pi RPC child. The agent uses pirpc.Spawn unless a test injects another.
+type SpawnFunc func(SpawnParams) (Proc, error)
+
+// TurnResult is the outcome of one prompt turn.
+type TurnResult struct {
+	Reason StopReason
+	Err    error
+}
+
+// ActiveSession is a live session as the agent uses it (Session implements it).
+type ActiveSession interface {
+	ID() string
+	Cwd() string
+	Proc() Proc
+	// Prompt starts the turn now, or queues it behind the running one.
+	Prompt(message string, images []Image) <-chan TurnResult
+	Cancel() error
+	WasCancelRequested() bool
+	PublishContextUsage()
+	SetStartupInfo(text string)
+	SendStartupInfoIfPending()
+}
+
+// SessionCreateParams describe a session to create or restore.
+type SessionCreateParams struct {
+	Cwd          string
+	McpServers   []any
+	Conn         Conn
+	FileCommands []FileSlashCommand
+	PiCommand    string
+	// Proc is set when restoring around an already started child.
+	Proc Proc
+}
+
+// SessionRegistry is the SessionManager of the original.
+type SessionRegistry interface {
+	Create(p SessionCreateParams) (ActiveSession, error)
+	MaybeGet(sessionID string) ActiveSession
+	Get(sessionID string) (ActiveSession, error)
+	GetOrCreate(sessionID string, p SessionCreateParams) ActiveSession
+	Close(sessionID string)
+	CloseAllExcept(keepSessionID string)
+	DisposeAll()
+}
+
+// RPCError implements jsonrpc.Coded.
+func (e *RequestError) RPCError() (int, string, any) { return e.Code, e.Message, e.Data }