@pi-in-go/pigpen-acp 0.1.0

package/CREDITS.md

@@ -0,0 +1,23 @@
+# Credits
+
+`extensions/acp/cmd/pig-acp` is a Go port of **pi-acp**, https://github.com/svkozak/pi-acp, by
+**Sergii Kozak** (MIT, Copyright (c) 2025 Sergii Kozak): the Agent Client Protocol adapter for the Pi
+coding agent, which the port adapts to PiG.
+
+- Original: `src/` and `test/` of pi-acp 0.0.34, commit `b0581c9c1d675e634234674484247008b03d69b4`.
+- The unmodified original, with its README, `package.json` and license, is kept at
+  [`port/oracle/pi-acp`](port/oracle/pi-acp) as the oracle the Go tests were ported from. Its license is at
+  [`port/oracle/pi-acp/LICENSE`](port/oracle/pi-acp/LICENSE).
+- What was modified: nothing of the original is modified in place. The port is a separate Go implementation with the
+  same structure (`agent`, `session`, `translate`, `pi-rpc`), PiG's directories and executable in place of Pi's,
+  the adapter's own JSON-RPC transport in place of the ACP SDK, and the additions listed in
+  [`port/PORT.md`](port/PORT.md). The ported tests keep the original test names.
+
+The protocol is the **Agent Client Protocol**, https://agentclientprotocol.com. The JSON schema in
+[`port/schema/schema.json`](port/schema/schema.json) is `schema/schema.json` of
+`@agentclientprotocol/sdk` 0.26.0 by **Zed Industries** (Apache-2.0, https://github.com/agentclientprotocol/typescript-sdk,
+tag `v0.26.0`, commit `73bc30649b650de320340c782733bf69a545bd28`), unmodified, with its license at
+[`port/schema/LICENSE`](port/schema/LICENSE). It is used only to check the adapter's messages in tests.
+
+The Go code, the scenarios and the tests were written for this Package by Michael Kinsy and are MIT
+licensed like the rest of Pigpen.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Sergii Kozak
+Copyright (c) 2026 Michael Kinsy (the Go port)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# acp: Agent Client Protocol for PiG
+
+Lets an editor that speaks the [Agent Client Protocol](https://agentclientprotocol.com) (ACP), such as
+[Zed](https://zed.dev), drive a PiG agent: sessions, streamed answers, tool calls with diffs and terminal output,
+cancel, model and thinking-level selection, context usage, and permission requests for extension dialogs.
+
+It is a Go port of [pi-acp](https://github.com/svkozak/pi-acp) by Sergii Kozak (MIT). See [CREDITS.md](CREDITS.md)
+and the port record, [port/PORT.md](port/PORT.md). **Pinned protocol: ACP version 1, schema of
+`@agentclientprotocol/sdk` 0.26.0.** Built against PiG 0.4.0 (Pi 1.0.0); the numbers under Evidence were first recorded on PiG 0.3.0, and the end-to-end scenarios, the ACP reference client run and the Go tests pass again on 0.4.0.
+
+The Package has two parts:
+
+| Part | What it is |
+|---|---|
+| [`extensions/acp/cmd/pig-acp`](extensions/acp/cmd/pig-acp) | **The protocol entrypoint**, a separate executable with no dependency (not even the PiG SDK). The editor starts it and speaks ACP on its stdin and stdout; it starts `pig --mode rpc` for each session. It is not the TUI and shares nothing with it. |
+| [`extensions/acp`](extensions/acp) | A small Go extension on the public SDK. `/acp` prints the editor configuration for the running agent and the limits below. |
+
+An extension cannot speak ACP itself: a fused extension must not write protocol bytes to the host's stdout. So
+**installing this Package, or building the `acp` Piglet, does not make the Piglet Binary an ACP server.** The editor
+runs `pig-acp`, and `pig-acp --pig <your pig or Piglet Binary>` runs the agent. There is no one-command Binary yet
+(see [RELEASE-BLOCKERS.md](../../RELEASE-BLOCKERS.md)).
+
+## Use
+
+Build the companion (Go 1.26 or later) and put it on your `PATH`:
+
+```sh
+cd components/acp/extensions/acp/cmd/pig-acp
+go build -trimpath -o pig-acp .
+pig-acp --version        # pig-acp 0.1.0 (ACP protocol version 1)
+```
+
+Zed, `settings.json` (`/acp` prints this with your paths filled in):
+
+```json
+{
+  "agent_servers": {
+    "PiG": { "type": "custom", "command": "pig-acp", "args": ["--pig", "/path/to/pig"], "env": {} }
+  }
+}
+```
+
+Other ACP clients run `pig-acp --pig <pig>` and speak newline-delimited JSON-RPC on stdio. `--pig` also takes a built Piglet
+Binary (`--pig ./acp`). `--piglet <name-or-file>` starts pig with `--piglet ...`, and `--pig-arg <arg>` (repeatable) passes any
+other argument. Without `--pig`, `PIG_ACP_PIG_COMMAND` (or `PI_ACP_PI_COMMAND`) is used, then `pig`.
+
+Signing in: if pig has no model or key, `session/new` fails with the ACP "authentication required" error (-32000) and one
+terminal auth method, `pig-acp --terminal-login`, which starts pig interactively in the editor's terminal.
+
+| Flag or variable | Meaning |
+|---|---|
+| `--pig <command>` | the pig executable or Piglet Binary to drive |
+| `--piglet <value>`, `--pig-arg <arg>` | extra pig arguments |
+| `--terminal-login` | start pig interactively (sign in, configure keys) and exit with its status |
+| `--version`, `--help` | print and exit |
+| `PIG_ACP_PIG_COMMAND` | the pig executable when `--pig` is not given |
+| `PIG_ACP_ENABLE_EMBEDDED_CONTEXT=true` | advertise embedded-context prompts (off by default) |
+| `PIG_HOME`, `PIG_CODING_AGENT_DIR`, `PIG_CODING_AGENT_SESSION_DIR`, `PIG_USE_PI_DIRS=1` | pig's own directories are used as pig uses them (a leading `~` is expanded) |
+
+The session map (ACP session id to pig session file) is `<PIG_HOME>/pig-acp/session-map.json`. Sessions are pig's own session
+files, so they show up in `pig` too. `pig-acp` reads prompt templates from `<agent dir>/prompts` and `<cwd>/.pig/prompts` and
+settings from `<agent dir>/settings.json` and `<cwd>/.pig/settings.json`. It never reads `auth.json` for itself; like pi-acp, it
+reads a file that pig's `edit` or `write` tool changes, before and after, to send the diff to the editor.
+
+## What is implemented
+
+Advertised in `initialize`, and only these: `loadSession`, prompt `image` (embedded context only by the variable above; no
+audio), `sessionCapabilities` `list` and `delete`, MCP `http` and `sse` **false**.
+
+- `session/new`, `session/load` (history replayed, including tool results), `session/list` (paged by 50, scoped to the last
+  cwd), `session/delete` (idempotent), `session/prompt`, `session/cancel`, `session/set_mode` (thinking level),
+  `session/set_config_option` (model, thinking level), `session/set_model`, `authenticate`.
+- Streaming: `agent_message_chunk`, `agent_thought_chunk`, `tool_call` and `tool_call_update` with locations, structured
+  diffs for edit and write, `execute` calls with terminal output for bash, `usage_update`, `available_commands_update`,
+  `config_option_update`, `current_mode_update`, `session_info_update`.
+- Adapter-side slash commands that never reach the model: `/compact`, `/autocompact`, `/session`, `/name`, `/steering`,
+  `/follow-up`, `/changelog`, `/export`. Prompt template files expand as `/name args`.
+- **Permissions.** An extension `select` or `confirm` dialog becomes `session/request_permission`; the editor's answer is
+  sent back to the extension. A client that fails or cancels means "cancelled". Nothing is ever executed locally in place of an
+  editor's answer. `input` and `editor` dialogs are cancelled with a visible notice; `notify` becomes a chunk with its level.
+- One live pig child per ACP connection: a new session or load closes the previous child. Closing stdin (or SIGINT/SIGTERM)
+  stops every child and exits 0. Nothing but protocol messages is written to stdout.
+
+## Not supported (by design, as upstream)
+
+- File system and terminal delegation: `pig-acp` never calls `fs/*` or `terminal/*` on the editor; pig reads and writes files itself.
+- MCP servers passed by the editor are accepted and stored, never started (PiG's own MCP support is configured in PiG).
+- Extension slash commands (`/name` of an extension is not advertised, and as a prompt it runs without ending a turn: drive
+  extensions through tools). `session/fork`, `session/resume`, `session/close` are Method not found.
+- The npm "New version available" notice: PiG has no npm package (`pig update` uses a signed manifest).
+
+## Evidence
+
+Everything below was first run on PiG 0.3.0 and re-run on 0.4.0 (the 11 end-to-end scenarios, the reference client's 30 checked messages, the Go tests) with a temporary `HOME`, `PIG_HOME` and agent directories.
+
+- **Twins of the upstream tests:** 124 exact twins with their upstream titles plus 1 named skip, checked by
+  `pigeq twins check` against the upstream ledger (`port/upstream-tests.json`). Two more skipped tests name the remaining gaps (the npm update notice, the compaction event names); see `port/PORT.md`.
+- **Unit and protocol tests:** `go test -race ./...` in both modules (a scripted ACP client over pipes against `Serve`).
+- **End to end:** 11 scenarios (streaming, bash, diff, cancel, load/list/delete across two adapter runs, config options, a real
+  permission round trip through a Go extension tool, no-model auth error, missing pig, MCP accepted, exit on stdin close) pass against
+  a real `pig` **and against the built `acp` Piglet Binary** (`PIG_ACP_E2E_PIG=<binary> go test -run E2E`).
+- **Reference client:** `components/acp/port/interop` runs the ACP SDK's `ClientSideConnection` 0.26.0 against `pig-acp` and the
+  Piglet Binary and validates every message against the pinned schema: `npm ci --ignore-scripts` in `port/interop`, then
+  `PIG_ACP=<pig-acp> PIG=<pig or Binary> PIGEQ=<pigeq> npm run test:acp-interop`. The run needs the `pigeq` built from
+  this repository (`PIG_BIN=<pig> npm run build:pigeq` writes `dist/bin/pigeq`), which has the `llm` command; so does the twin
+  ledger check (`pigeq twins check`).
+- **Mutations:** 105 deliberate defects (`port/mutations.json`, `node components/acp/port/mutate.mjs`), 104 killed and 1 documented
+  equivalent; results in `port/mutation-results.txt`.
+
+**Not verified:** Zed and JetBrains themselves (no editor could be run here). The reference client is the interop evidence.

package/extensions/acp/cmd/pig-acp/e2e_llm_test.go

@@ -0,0 +1,168 @@
+package main
+
+// A scripted OpenAI-compatible chat-completions server, so the end-to-end tests drive a real
+// `pig --mode rpc` without credentials or a network (the same idea as the equivalence harness).
+
+import (
+	"encoding/json"
+	"fmt"
+	"net"
+	"net/http"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+type llmCall struct {
+	Name string
+	Args map[string]any
+}
+
+// llmTurn is one scripted model reply.
+type llmTurn struct {
+	Text  string
+	Calls []llmCall
+	// Chunks streams Text in this many pieces (default 1).
+	Chunks int
+	// Hold blocks the reply after its first chunk until the channel closes or the client disconnects.
+	Hold chan struct{}
+	// Started is closed when the first chunk of this turn has been sent.
+	Started chan struct{}
+}
+
+type fakeLLM struct {
+	t     *testing.T
+	ln    net.Listener
+	srv   *http.Server
+	mu    sync.Mutex
+	turns []llmTurn
+	next  int
+	// requests records the last user text of each request.
+	requests []string
+}
+
+func startFakeLLM(t *testing.T, turns ...llmTurn) *fakeLLM {
+	t.Helper()
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	f := &fakeLLM{t: t, ln: ln, turns: turns}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1/chat/completions", f.handle)
+	f.srv = &http.Server{Handler: mux}
+	go func() { _ = f.srv.Serve(ln) }()
+	t.Cleanup(func() { _ = f.srv.Close() })
+	return f
+}
+
+func (f *fakeLLM) baseURL() string { return "http://" + f.ln.Addr().String() + "/v1" }
+
+func (f *fakeLLM) seen() []string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return append([]string(nil), f.requests...)
+}
+
+func (f *fakeLLM) handle(w http.ResponseWriter, r *http.Request) {
+	var req struct {
+		Messages []struct {
+			Role    string          `json:"role"`
+			Content json.RawMessage `json:"content"`
+		} `json:"messages"`
+	}
+	_ = json.NewDecoder(r.Body).Decode(&req)
+	last := ""
+	for _, m := range req.Messages {
+		if m.Role == "user" {
+			var s string
+			if json.Unmarshal(m.Content, &s) == nil {
+				last = s
+			} else {
+				var parts []struct {
+					Text string `json:"text"`
+				}
+				_ = json.Unmarshal(m.Content, &parts)
+				if len(parts) > 0 {
+					last = parts[0].Text
+				}
+			}
+		}
+	}
+	f.mu.Lock()
+	f.requests = append(f.requests, last)
+	i := f.next
+	f.next++
+	f.mu.Unlock()
+	if i >= len(f.turns) {
+		http.Error(w, "llm script exhausted", http.StatusInternalServerError)
+		return
+	}
+	turn := f.turns[i]
+	w.Header().Set("Content-Type", "text/event-stream")
+	flusher, _ := w.(http.Flusher)
+	send := func(delta map[string]any, finish any) {
+		b, _ := json.Marshal(map[string]any{"id": fmt.Sprintf("acp-%d", i), "object": "chat.completion.chunk", "created": 1, "model": "acp-1",
+			"choices": []any{map[string]any{"index": 0, "delta": delta, "finish_reason": finish}}})
+		fmt.Fprintf(w, "data: %s\n\n", b)
+		flusher.Flush()
+	}
+	send(map[string]any{"role": "assistant", "content": ""}, nil)
+	chunks := turn.Chunks
+	if chunks < 1 {
+		chunks = 1
+	}
+	if turn.Text != "" {
+		pieces := splitText(turn.Text, chunks)
+		for n, p := range pieces {
+			send(map[string]any{"content": p}, nil)
+			if n == 0 && turn.Started != nil {
+				close(turn.Started)
+			}
+			if n == 0 && turn.Hold != nil {
+				select {
+				case <-turn.Hold:
+				case <-r.Context().Done():
+					return
+				}
+			}
+		}
+	} else if turn.Started != nil {
+		close(turn.Started)
+	}
+	finish := "stop"
+	for j, c := range turn.Calls {
+		args, _ := json.Marshal(c.Args)
+		send(map[string]any{"tool_calls": []any{map[string]any{"index": j, "id": fmt.Sprintf("call_%d_%d", i, j), "type": "function",
+			"function": map[string]any{"name": c.Name, "arguments": string(args)}}}}, nil)
+		finish = "tool_calls"
+	}
+	send(map[string]any{}, finish)
+	usage, _ := json.Marshal(map[string]any{"id": fmt.Sprintf("acp-%d", i), "object": "chat.completion.chunk", "created": 1, "model": "acp-1", "choices": []any{},
+		"usage": map[string]any{"prompt_tokens": 1234, "completion_tokens": 5, "total_tokens": 1239}})
+	fmt.Fprintf(w, "data: %s\n\ndata: [DONE]\n\n", usage)
+	flusher.Flush()
+}
+
+func splitText(s string, n int) []string {
+	if n <= 1 || len(s) < n {
+		return []string{s}
+	}
+	words := strings.SplitAfter(s, " ")
+	if len(words) < n {
+		return []string{s}
+	}
+	per := (len(words) + n - 1) / n
+	var out []string
+	for i := 0; i < len(words); i += per {
+		end := i + per
+		if end > len(words) {
+			end = len(words)
+		}
+		out = append(out, strings.Join(words[i:end], ""))
+	}
+	return out
+}
+
+var _ = time.Second