@pi-in-go/pigpen-ahp 0.1.0

package/extensions/ahp/third_party/agent-host-protocol-go/ahptypes/version.generated.go

@@ -0,0 +1,31 @@
+// Generated from types/*.ts — do not edit.
+//
+// Regenerate with: npm run generate:go
+
+package ahptypes
+
+// ProtocolVersion is the current protocol version (SemVer
+// MAJOR.MINOR.PATCH) that this generated source speaks.
+const ProtocolVersion = "0.9.0"
+
+// supportedProtocolVersions backs [SupportedProtocolVersions] — held
+// in an unexported slice so callers cannot accidentally mutate the
+// shared backing array.
+var supportedProtocolVersions = []string{
+	"0.9.0",
+	"0.8.0",
+	"0.7.0",
+	"0.6.0",
+	"0.5.2",
+	"0.5.1",
+}
+
+// SupportedProtocolVersions returns every protocol version this client
+// is willing to negotiate, ordered most-preferred-first. The first
+// entry always equals [ProtocolVersion]. The returned slice is a fresh
+// copy on every call so callers may mutate it freely.
+func SupportedProtocolVersions() []string {
+	out := make([]string, len(supportedProtocolVersions))
+	copy(out, supportedProtocolVersions)
+	return out
+}

package/extensions/ahp/third_party/agent-host-protocol-go/go.mod

@@ -0,0 +1,3 @@
+module github.com/microsoft/agent-host-protocol/clients/go
+
+go 1.22

package/extensions/ahp/twins_test.go

@@ -0,0 +1,91 @@
+package ahp_test
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// TestEveryUpstreamCaseHasATwin is the Skill's "exact 1:1 case mapping" gate. Every leaf case of
+// the upstream test suite (testdata/upstream-tests.json, produced by running the pinned oracle) must
+// have a twin(twin.Run) or a named skipped twin (twin.Skip) with the same file and title.
+func TestEveryUpstreamCaseHasATwin(t *testing.T) {
+	raw, err := os.ReadFile(filepath.Join("testdata", "upstream-tests.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var upstream []struct {
+		File  string `json:"file"`
+		Title string `json:"title"`
+	}
+	if err := json.Unmarshal(raw, &upstream); err != nil {
+		t.Fatal(err)
+	}
+
+	call := regexp.MustCompile(`twin\.(Run|Skip)\(\s*t,\s*"((?:[^"\\]|\\.)*)",\s*"((?:[^"\\]|\\.)*)"(?:,\s*"((?:[^"\\]|\\.)*)")?`)
+	have := map[string]string{} // "file\x00title" -> "run" | "skip: reason"
+	err = filepath.Walk(".", func(path string, info os.FileInfo, err error) error {
+		if err != nil || info.IsDir() || !strings.HasSuffix(path, "_test.go") || strings.Contains(path, "third_party") {
+			return err
+		}
+		src, err := os.ReadFile(path)
+		if err != nil {
+			return err
+		}
+		for _, m := range call.FindAllStringSubmatch(string(src), -1) {
+			file, _ := strconv.Unquote(`"` + m[2] + `"`)
+			title, _ := strconv.Unquote(`"` + m[3] + `"`)
+			key := file + "\x00" + title
+			if _, dup := have[key]; dup {
+				t.Errorf("duplicate twin for %s: %q", file, title)
+			}
+			if m[1] == "Skip" {
+				reason, _ := strconv.Unquote(`"` + m[4] + `"`)
+				if strings.TrimSpace(reason) == "" {
+					t.Errorf("skipped twin without a reason: %s: %q", file, title)
+				}
+				have[key] = "skip: " + reason
+			} else {
+				have[key] = "run"
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	want := map[string]bool{}
+	var missing []string
+	for _, c := range upstream {
+		key := c.File + "\x00" + c.Title
+		want[key] = true
+		if _, ok := have[key]; !ok {
+			missing = append(missing, c.File+": "+c.Title)
+		}
+	}
+	var extra []string
+	skipped := 0
+	for key, status := range have {
+		if !want[key] {
+			extra = append(extra, strings.ReplaceAll(key, "\x00", ": "))
+		}
+		if strings.HasPrefix(status, "skip") {
+			skipped++
+		}
+	}
+	sort.Strings(missing)
+	sort.Strings(extra)
+	t.Logf("upstream cases: %d, twins: %d run + %d skipped, missing: %d", len(upstream), len(have)-skipped, skipped, len(missing))
+	if len(missing) > 0 {
+		t.Errorf("%d upstream cases have no twin:\n  %s", len(missing), strings.Join(missing, "\n  "))
+	}
+	if len(extra) > 0 {
+		t.Errorf("%d twins name no upstream case:\n  %s", len(extra), strings.Join(extra, "\n  "))
+	}
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@pi-in-go/pigpen-ahp",
+  "version": "0.1.0",
+  "description": "Go port of pi-ahp: serves the running PiG session to remote Microsoft Agent Host Protocol clients over WebSocket, with reconnect and auth. No listener unless you ask; no remote filesystem or terminal unless you opt in",
+  "keywords": [
+    "pig-package",
+    "ahp",
+    "agent-host-protocol",
+    "remote",
+    "extension",
+    "pigpen"
+  ],
+  "license": "MIT",
+  "author": "Michael Kinsy",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MichaelKinsy/pigpen.git",
+    "directory": "components/ahp"
+  },
+  "homepage": "https://github.com/MichaelKinsy/pigpen/tree/main/components/ahp#readme",
+  "bugs": {
+    "url": "https://github.com/MichaelKinsy/pigpen/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "extensions",
+    "proof",
+    "README.md",
+    "LICENSE",
+    "CREDITS.md",
+    "provenance.json"
+  ],
+  "pi": {
+    "extensions": [
+      "extensions/ahp"
+    ]
+  }
+}

package/proof/PORT.md

@@ -0,0 +1,121 @@
+# Port record: ahp
+
+(This directory is `proof/`, not the Skill's usual `port/`: the repository's port-layout test and
+`test:port` treat every `port/` as a scenario/golden-trace port recorded with `pigeq`, which needs the
+original to be a Pi extension. pi-ahp is a standalone host, so its proof is the twin gate, the real-pig
+scenarios and the mutation list `proof/mutations.json`.)
+
+| Input | Identity |
+|---|---|
+| Original | pi-ahp (`src/`, `test/`), https://github.com/Qusic/pi-ahp, commit `4065e98309b03c1d2d916300856c3c21a9c10674`, MIT (Bang Lee) |
+| Protocol | Microsoft Agent Host Protocol 0.9.0, https://github.com/microsoft/agent-host-protocol, commit `296b25e7b698a4a84a0ee5a28d9573e70048a0bf`, MIT. Types and reducers vendored byte for byte (`extensions/ahp/third_party/agent-host-protocol-go`) |
+| Oracle | pi-ahp under Node 24 with Pi 0.87.1: 420 of its 430 leaf cases pass here; the 10 `resource-watch` "lifetime" cases time out in this environment (they mock `setTimeout`) and are red upstream too |
+| Target | PiG 0.3.0 + Pi 0.87.1 (a pre-release build, `63c6ba456`), go1.27.1, public Go SDK only |
+
+## What kind of port this is
+
+pi-ahp is not a Pi extension: it is a standalone Node host that embeds Pi (`createAgentSession`) and
+runs many sessions itself. The Go port is an **extension inside one PiG session**, so the
+protocol host, the mapping from Pi events to AHP actions, the catalogue and the services are ported
+faithfully, and the agent side is an adapter over the Go SDK that serves exactly the running
+session. The equivalence method is therefore three layers, not the scenario harness alone:
+
+1. **Twins.** Every one of the 430 upstream test cases has a Go test named after it
+   (`internal/twin`; the gate `extensions/ahp/twins_test.go` fails when a case has neither a test nor
+   a named skip). **375 run, 55 are named skips** (below). Upstream inputs and expectations are kept;
+   where the Go form had to differ the test says why.
+2. **Real host.** `extensions/ahp/realpig_test.go` builds the extension with a real `pig`, serves a real PiG
+   session backed by a scripted local model (`tools/fakellm`), and drives it with a WebSocket AHP
+   client: token and Origin refusal, nothing exposed by default, catalogue, remote turn, local
+   prompt mirrored, opt-in filesystem and terminal, resumed session history, remote cancel,
+   non-loopback without token, listener off unless asked, session replacement. The same eight
+   scenarios pass against a Piglet Binary with the extension fused in (`PIGPEN_AHP_FUSED=1`).
+3. **Mutation.** `proof/mutations.json` (run with `pigeq mutate --unit-only`) lists mutants of the
+   security and reconciliation checks. Each one is killed by a unit test. **No protocol differential
+   against pi-ahp under Pi, and no interop run with Microsoft's Go client, has been done.** Both are
+   open.
+
+## Mapping
+
+| Upstream | Go | Twins |
+|---|---|---|
+| `src/protocol/*`, `core/channels.ts`, `core/uri.ts` | `internal/wire` | handshake, uri, protocol-surface |
+| `core/host.ts`, `sequencer.ts`, `client-workarounds.ts` | `internal/host` (+ `internal/ws`, an RFC 6455 server on `net/http` Hijack) | handshake 14, subscriptions 9, reconnect 9, client-workarounds 14, schema 4, upstream-workarounds 2 |
+| `pi/event-mapper.ts`, `activity.ts`, `user-message.ts`, `message-input.ts`, `session-title.ts` | `internal/mapper` | event-mapper 27, activity 14, message-input 12, mapper-fixtures 25 |
+| `channels/*` | `internal/channels` | session-summary 13 |
+| `pi/chat-driver.ts` | `internal/pi/chatdriver.go` | chat-driver 13 |
+| `pi/session-registry.ts`, `session-catalogue.ts`, `session-hydrator.ts`, `history.ts`, `turn-paging`, `delete-session.ts` | `internal/pi` | session-lifecycle 17, disposal 6, client-actions 6, catalogue 11, hydration 8, hydrated lifecycle 9, fetch-turns 4, truncate 5, delete-session 6, active-turn-reconnect 3, session-storage 1, reconnect-after-restart 1 |
+| `pi/models.ts`, `session-config.ts`, `completions.ts`, `project-trust.ts` | `internal/pi` | models 10, session-config 8, completions 22, project-trust 6 |
+| Pi `SessionManager` (JSONL v3) | `internal/pisession` | used by the above |
+| `pi/resource-*.ts` | `internal/svc` (`resource.go`, `watch.go`, `glob.go`, `watchpolicy.go`) | resource 23, resource-watch 28, policy 9, watch-events 4 |
+| `host/terminal-service.ts` | `internal/svc` (`terminal.go`, `pty*.go`) | terminal-service 14, pty 2 |
+| `pi/image-input.ts` | `internal/pi/imageinput.go` | image-input 2 |
+| `host/pi-host.ts` | `internal/compose` | pi-host 1 |
+| `host/direct-settings.ts` | `internal/settings` | direct-settings 3 |
+| `pi/in-process-backend.ts` | `internal/live` (adapter over the SDK; not a port) | real-pig scenarios |
+| (none) | root package: flags, `/ahp`, listener lifecycle | real-pig scenarios |
+
+## Named skipped twins (55)
+
+| Family | Count | Why |
+|---|---|---|
+| `tunnel` | 20 | The dev tunnel (Microsoft `devtunnel` CLI management) is not bundled: owner decision, ACP, AHP and A2A are separate extensions |
+| `pi-replay` | 15 | Replays provider streams through a live embedded Pi agent loop. Covered by the recorded-stream twins (`mapper-fixtures`) and the real-pig scenarios |
+| `changeset`, `changeset-lifecycle`, `changeset-uri` | 15 | The git changeset service (`git-changes.ts`, `changeset-service.ts`) is not ported in this release; the host advertises no changeset channels. Documented gap, candidate for the next release |
+| `image-session` | 1 | Needs Pi's `InProcessPiBackend` and a faux model |
+| `model-discovery` | 2 | Needs an embedded Pi model registry with extension providers; the adapter reads models through the SDK |
+| `live-turn` | 1 | Upstream skips it itself without a real model |
+| `project-trust` | 1 | "applies the decision before pi loads project extensions": the extension cannot gate what PiG loaded |
+
+## Deviations from upstream (deliberate)
+
+1. **One session.** Only the running PiG session has an agent. Other sessions in the catalogue are
+   read from their files (browse, history); starting a turn on one fails with a clear error.
+   Clients cannot create sessions, and `chat/truncated`, fork and tree navigation are refused: the
+   SDK offers `NewSession`, `Fork` and `NavigateTree` to commands only.
+2. **Session replacement.** Contexts retained from `session_start` belong to their runtime. On
+   `new`, `resume`, `fork` and `reload`, PiG emits `session_shutdown` and runs the extension factory
+   again, so the listener is stopped. With `--ahp` the new session's `session_start` opens it again
+   on the same port. After `/ahp start` it stays closed, and a warning tells the user
+   (`TestRealPigSessionReplacement`, review fix).
+3. **Nothing on by default.** Upstream's standalone process is the listener; the extension opens none
+   without `--ahp` or `/ahp start`. Upstream's resource service is unrestricted without roots; here
+   the filesystem is off, then confined to the working directory, and only `unrestricted: true`
+   lifts that. Terminals and session deletion are opt-in settings. Non-loopback needs a token.
+4. **Foreign turns.** A prompt typed into the session locally is mirrored into the chat
+   (`AdoptForeignTurns`); upstream owns its agent and never sees one.
+5. **Steering.** PiG has no `queue_update` event; the adapter synthesises it from the delivered user
+   message so pending-steering reconciliation works.
+6. **Newer spec, older client library.** The pinned spec has `chat/isArchivedChanged` and
+   `session/mcpServerBackgroundRequested`, which npm 0.9.0 lacks; both are refused and the
+   client-actions twin expects that. The spec has no `Conflict` error code; -32011 is kept from npm 0.9.0.
+7. **Polling watches.** No portable file notification exists in the standard library, so a resource
+   watch diffs a snapshot (default every second, excluded directories pruned) where chokidar uses
+   native events. Batching, filters, grace and disposal are upstream's.
+8. **PTY.** A stdlib-only PTY (`/dev/ptmx` + ioctl) on linux and darwin. Windows has none; the terminal
+   service refuses to start there. A signalled child reports `128+signal`.
+9. **Images.** Pi's `convertToPng`/`resizeImage` are not in the SDK: PNG, JPEG, GIF decode with the
+   standard library, BMP with a small decoder, resizing is a box filter, WebP passes through unvalidated
+   beyond its header.
+10. **MIME table** is the subset of the `mime` package that matters for source trees.
+11. **Async side effects.** Registry and driver effects run on goroutines where upstream runs them in
+    the same tick; a few twins wait for the backend call before the next step. `host.drain` defers
+    re-entrant listener callbacks; the driver serialises events (`evMu`).
+12. **JS artefacts.** Echoed tool arguments have alphabetical key order (events arrive decoded); UTF-16
+    cuts at a lone surrogate yield U+FFFD; `localeCompare` is approximated (`localeLess`); terminal trimming counts runes.
+13. **Vendored client library.** Its reconnect results marshal without the `type` discriminator, so the
+    host has its own structs; its `SnapshotState` cannot decode a terminal snapshot (tests read the raw result).
+14. **Tests written with the code.** From the third layer on, tests and implementation were committed
+    together (failing runs observed before fixes) rather than as a separate red commit.
+15. **403 for a bad token.** A missing or wrong `token`/`tkn` is refused at the upgrade with 403 Forbidden, as VS Code's
+    agent host (the AHP reference host, `src/vs/platform/agentHost/node/webSocketTransport.ts`) answers a bad `tkn`; pi-ahp
+    writes 401. The AHP spec leaves endpoint access to the transport, upstream's twin only asserts the refusal, and no
+    client tells the two apart (a browser WebSocket reports either as one error); a 401 would also owe a `WWW-Authenticate`
+    challenge that a query token has no scheme for. A browser `Origin` that is not allowed is 403 as before.
+
+## Build notes
+
+- A fused Piglet Binary ignores `replace` directives of the extension's `go.mod`; a `go.work` beside it
+  (`use . ./third_party/agent-host-protocol-go`) is how the vendored module is found.
+- PiG 0.4.0 (Pi 0.99.1): re-check `session_start` retained contexts across session replacement, whether
+  `Fork`/`NewSession` become callable from events, any `queue_update` event, and the SDK's image helpers.

package/proof/mutations.json

@@ -0,0 +1,152 @@
+[
+ {
+  "name": "ws-token-check-dropped",
+  "file": "internal/ws/ws.go",
+  "find": "if !ok || subtle.ConstantTimeCompare([]byte(presented), []byte(s.opts.Token)) != 1 {",
+  "replace": "if false && (!ok || subtle.ConstantTimeCompare([]byte(presented), []byte(s.opts.Token)) != 1) {"
+ },
+ {
+  "name": "ws-token-any-accepted",
+  "file": "internal/ws/ws.go",
+  "find": "subtle.ConstantTimeCompare([]byte(presented), []byte(s.opts.Token)) != 1",
+  "replace": "subtle.ConstantTimeCompare([]byte(presented), []byte(presented)) != 1"
+ },
+ {
+  "name": "ws-origin-not-enforced",
+  "file": "internal/ws/ws.go",
+  "find": "origin != \"\" && !s.originAllowed(origin)",
+  "replace": "origin != \"\" && false"
+ },
+ {
+  "name": "ws-origin-allowlist-inverted",
+  "file": "internal/ws/ws.go",
+  "find": "if strings.EqualFold(allowed, origin) {\n\t\t\treturn true",
+  "replace": "if !strings.EqualFold(allowed, origin) {\n\t\t\treturn true"
+ },
+ {
+  "name": "paths-prefix-check-loose",
+  "file": "internal/svc/paths.go",
+  "find": "if candidate == root || strings.HasPrefix(candidate, prefix) {",
+  "replace": "if candidate == root || strings.HasPrefix(candidate, strings.TrimSuffix(prefix, string(filepath.Separator))) {"
+ },
+ {
+  "name": "paths-roots-ignored",
+  "file": "internal/svc/paths.go",
+  "find": "\tif len(p.roots) == 0 {\n\t\treturn path, nil\n\t}",
+  "replace": "\tif true {\n\t\treturn path, nil\n\t}"
+ },
+ {
+  "name": "resource-ifmatch-ignored",
+  "file": "internal/svc/resource.go",
+  "find": "if !exists || *p.IfMatch != current {",
+  "replace": "if !exists || (false && *p.IfMatch != current) {"
+ },
+ {
+  "name": "terminal-claim-not-checked",
+  "file": "internal/svc/terminal.go",
+  "find": "if !ok || claim.ClientId != clientID {\n\t\treturn \"This terminal is claimed by another client\"",
+  "replace": "if !ok || (false && claim.ClientId != clientID) {\n\t\treturn \"This terminal is claimed by another client\""
+ },
+ {
+  "name": "terminal-claim-must-match-initialized-client",
+  "file": "internal/svc/terminal.go",
+  "find": "if clientID == \"\" || claim.ClientId != clientID {",
+  "replace": "if clientID == \"\" || (false && claim.ClientId != clientID) {"
+ },
+ {
+  "name": "compose-unrestricted-implied",
+  "file": "internal/compose/compose.go",
+  "find": "if len(fs.Roots) == 0 && !fs.Unrestricted {",
+  "replace": "if false {"
+ },
+ {
+  "name": "compose-roots-dropped",
+  "file": "internal/compose/compose.go",
+  "find": "\t\tif !fs.Unrestricted {\n\t\t\troots = fs.Roots\n\t\t}",
+  "replace": "\t\tif false {\n\t\t\troots = fs.Roots\n\t\t}"
+ },
+ {
+  "name": "driver-foreign-turn-while-cancelling",
+  "file": "internal/pi/chatdriver.go",
+  "find": "\tif d.quiesced || d.cancellation != nil || d.mapper != nil {\n\t\td.mu.Unlock()\n\t\treturn nil\n\t}",
+  "replace": "\tif d.quiesced || d.mapper != nil {\n\t\td.mu.Unlock()\n\t\treturn nil\n\t}"
+ },
+ {
+  "name": "driver-foreign-turn-any-role",
+  "file": "internal/pi/chatdriver.go",
+  "find": "if message == nil || message[\"role\"] != \"user\" {",
+  "replace": "if message == nil {"
+ },
+ {
+  "name": "host-replay-window-off-by-one",
+  "file": "internal/host/host.go",
+  "find": "return len(h.buf) > 0 && h.buf[0].ServerSeq <= lastSeen+1",
+  "replace": "return len(h.buf) > 0 && h.buf[0].ServerSeq <= lastSeen+2"
+ },
+ {
+  "name": "host-replay-always",
+  "file": "internal/host/host.go",
+  "find": "\tif lastSeen >= h.seq {\n\t\treturn true\n\t}\n\treturn len(h.buf) > 0 && h.buf[0].ServerSeq <= lastSeen+1",
+  "replace": "\treturn true"
+ },
+ {
+  "name": "store-update-without-lock",
+  "file": "internal/host/store.go",
+  "find": "func (s *Store) UpdateChat(uri string, fn func(*ahptypes.ChatState) bool) bool {\n\ts.mu.Lock()\n\tdefer s.mu.Unlock()",
+  "replace": "func (s *Store) UpdateChat(uri string, fn func(*ahptypes.ChatState) bool) bool {"
+ },
+ {
+  "name": "watch-racy-hash-off",
+  "file": "internal/svc/watch.go",
+  "find": "if recent || (seen && old.hash != \"\" && old.sig == entry.sig) {",
+  "replace": "if false && (recent || (seen && old.hash != \"\" && old.sig == entry.sig)) {"
+ },
+ {
+  "name": "delete-refused-unless-allowed",
+  "file": "runtime.go",
+  "find": "if !allow {",
+  "replace": "if false {"
+ },
+ {
+  "name": "delete-live-file-allowed",
+  "file": "runtime.go",
+  "find": "filepath.Clean(live) == filepath.Clean(path)",
+  "replace": "false && filepath.Clean(live) == filepath.Clean(path)"
+ },
+ {
+  "name": "nonloopback-without-token-allowed",
+  "file": "runtime.go",
+  "find": "if !isLoopback(host) && token == \"\" {",
+  "replace": "if false {"
+ },
+ {
+  "name": "loopback-localhost-only",
+  "file": "runtime.go",
+  "find": "if host == \"localhost\" {\n\t\treturn true\n\t}",
+  "replace": "if host == \"localhost\" {\n\t\treturn false\n\t}"
+ },
+ {
+  "name": "runtime-default-root-widened",
+  "file": "runtime.go",
+  "find": "roots = []string{cwd}",
+  "replace": "roots = []string{filepath.Dir(cwd)}"
+ },
+ {
+  "name": "runtime-terminals-always",
+  "file": "runtime.go",
+  "find": "if access.Terminals.Enabled {",
+  "replace": "if true || access.Terminals.Enabled {"
+ },
+ {
+  "name": "runtime-filesystem-always",
+  "file": "runtime.go",
+  "find": "if access.Filesystem.Enabled {",
+  "replace": "if true || access.Filesystem.Enabled {"
+ },
+ {
+  "name": "runtime-replacement-silent",
+  "file": "runtime.go",
+  "find": "if !running || restarts || reason == \"quit\" {",
+  "replace": "if true || !running || restarts || reason == \"quit\" {"
+ }
+]

package/proof/oracle/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bang Lee
+
+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/proof/oracle/README.md

@@ -0,0 +1,120 @@
+# pi-ahp
+
+[![CI](https://github.com/Qusic/pi-ahp/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/Qusic/pi-ahp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/pi-ahp)](https://www.npmjs.com/package/pi-ahp)
+[![pi](https://img.shields.io/npm/dependency-version/pi-ahp/@earendil-works/pi-coding-agent?label=pi)](https://github.com/earendil-works/pi)
+[![AHP](https://img.shields.io/npm/dependency-version/pi-ahp/@microsoft/agent-host-protocol?label=AHP)](https://github.com/microsoft/agent-host-protocol)
+[![License](https://img.shields.io/npm/l/pi-ahp)](LICENSE)
+
+`pi-ahp` is an [Agent Host Protocol](https://github.com/microsoft/agent-host-protocol) host for the [pi coding agent](https://github.com/earendil-works/pi).
+
+It embeds pi and makes its sessions available to AHP clients over WebSocket. Interoperability is primarily tested with [Agent Host support in Visual Studio Code](https://code.visualstudio.com/docs/agents/concepts/agent-host) and [Agent Console for iPhone and iPad](https://qusic.github.io/agent-console/), but the host is not limited to either client.
+
+The project is under active development; expect rough edges and occasional instability. Contributions are welcome.
+
+## Requirements
+
+- Node.js 24 or later
+- At least one model provider configured for pi
+
+## Usage
+
+```sh
+npm install --global pi-ahp
+```
+
+`pi-ahp` starts a direct WebSocket listener and prints its connection URL:
+
+```sh
+pi-ahp
+```
+
+On first run, it creates `~/.pi/ahp/settings.json` with a free port and a random token, for example:
+
+```json
+{
+  "host": "127.0.0.1",
+  "port": 32145,
+  "token": "<generated token>"
+}
+```
+
+The token is optional and may be set to `null`. The host and port can also be overridden for one run:
+
+```sh
+pi-ahp --host 127.0.0.1 --port 31546
+```
+
+Enter the printed URL in any AHP client. The direct listener is bring-your-own-network: reach it through Tailscale, SSH port forwarding, a reverse proxy, or any other network you manage. Keep the connection token enabled whenever the listener is reachable beyond localhost.
+
+`pi-ahp-tunnel` instead creates or reuses a Microsoft Dev Tunnel for clients that support it, including VS Code and Agent Console. It requires the [`devtunnel` CLI](https://aka.ms/devtunnels/download) and does not use the direct-listener settings:
+
+```sh
+devtunnel user login
+pi-ahp-tunnel
+```
+
+Run either command with `--help` for all available options.
+
+### Visual Studio Code
+
+VS Code exposes remote Agent Host setup only in its dedicated Agents window, not in a regular editor window. From a regular window, run **Chat: Open Agents Window**.
+
+If the remote-host commands are unavailable, or if you want to use a direct connection without signing in to GitHub, add these settings to VS Code's user `settings.json` before opening the Agents window:
+
+```json
+{
+  "chat.remoteAgentHostsEnabled": true,
+  "chat.agentHost.allowSignedOutWhenUsable": true
+}
+```
+
+The signed-out option is currently experimental and desktop-only. When prompted, choose **Continue Without Signing In**; you do not need to preconfigure a host manually.
+
+- **Direct WebSocket:** run **Agents: Add Remote Agent Host...** and paste the URL printed by `pi-ahp`.
+- **Dev Tunnel:** sign in to the same account in VS Code, then run **Agents: Connect to Remote Agent Host via Dev Tunnel**. Tunnel discovery requires sign-in.
+
+### iPhone and iPad
+
+I also make [Agent Console](https://qusic.github.io/agent-console/), a paid native AHP client for iPhone and iPad. Purchasing it helps support continued work on both Agent Console and `pi-ahp`.
+
+Agent Console connects with the direct URL printed by `pi-ahp`, or through a tunnel created by `pi-ahp-tunnel` when signed in to the same Dev Tunnels account. pi and its model credentials remain on the host, and Agent Console has no hosted backend. See the [Agent Console setup guide for Pi Coding Agent](https://qusic.github.io/agent-console/docs/pi-coding-agent/) for details.
+
+## AHP support
+
+The following is a high-level mapping to the [official AHP specification](https://microsoft.github.io/agent-host-protocol/specification/overview).
+
+Currently supported protocol versions: **0.9.0**
+
+🟢 Supported · 🟡 Planned · 🔴 Out of scope
+
+| Feature | Status | Notes |
+| --- | :---: | --- |
+| Connection lifecycle and reconnect | 🟢 | Active work survives a temporary connection loss, but not a host restart |
+| Durable sessions and history | 🟢 | Completed history for the active conversation branch recovers after restart |
+| Streaming chat and pi tool calls | 🟢 | One chat per session |
+| Steering, queues, drafts, and truncation | 🟢 | Drafts and unconsumed queues do not survive a host restart |
+| Models, session setup, and completions | 🟢 | Model and thinking-level selection, working directory, and `@` file completions |
+| Text attachments | 🟢 | Client-provided text, local file references, and embedded UTF-8 text |
+| Files and watches | 🟢 | Host-local `file:` resources only |
+| Interactive terminals | 🟢 | Client-owned; terminals and scrollback end when the host stops |
+| Images and vision | 🟢 | Embedded image attachments for vision-capable pi models |
+| Changeset views | 🟢 | Latest commit and uncommitted changes in Git workspaces |
+| Tool catalogue and client tools | 🟡 | Show available pi tools and let connected clients contribute tools |
+| pi customizations | 🟡 | Show and configure loaded extensions, skills, and prompt templates |
+| Terminal command detection | 🟡 | Group terminal output by command and exit status |
+| Persistent read and archive controls | 🔴 | pi sessions do not store this metadata |
+| Multiple chats or working directories | 🔴 | A pi session has one active branch and cwd; branches are not simultaneous AHP chats |
+| Custom agents | 🔴 | pi sub-agents are extension tools rather than selectable agents |
+| Elicitation | 🔴 | pi extension dialogs are not persisted as turn input |
+| Tool input and result confirmation | 🔴 | pi has no built-in permission policy |
+| Errored-turn resume | 🔴 | pi cannot reopen a finalized turn |
+| MCP lifecycle and Apps | 🔴 | pi has no built-in MCP runtime; extension implementations are opaque |
+| Annotations | 🔴 | There is no corresponding pi session state |
+| Automations and automation runs | 🔴 | pi has no scheduler or automation-run model |
+| AHP protected-resource authentication | 🔴 | pi manages model-provider credentials itself |
+| OTLP telemetry channels | 🔴 | pi does not provide host telemetry as OTLP |
+
+## License
+
+[MIT](LICENSE)

package/proof/oracle/UPSTREAM.md

@@ -0,0 +1,7 @@
+# Oracle: pi-ahp
+
+Unmodified copy of `src/`, `test/` and the package metadata of https://github.com/Qusic/pi-ahp
+(Bang Lee, MIT, see `LICENSE`) at commit `4065e98309b03c1d2d916300856c3c21a9c10674`. It is the
+equivalence oracle: 430 leaf test cases (`../upstream-tests.json`), each with a Go twin or a named
+skipped twin (`../PORT.md`). To run it: install with `pnpm install` in a checkout of upstream, then
+`AHP_SPEC_PATH=<agent-host-protocol checkout at 296b25e7b698a4a84a0ee5a28d9573e70048a0bf> node --test test/<file>.test.ts`.

package/proof/oracle/package.json

@@ -0,0 +1,68 @@
+{
+	"name": "pi-ahp",
+	"version": "0.0.0",
+	"description": "Agent Host Protocol server for Pi coding agent",
+	"keywords": [
+		"agent-host-protocol",
+		"ahp",
+		"agent-host",
+		"pi",
+		"pi-coding-agent",
+		"coding-agent",
+		"ai-agent",
+		"agent",
+		"ai",
+		"llm",
+		"cli",
+		"json-rpc",
+		"websocket",
+		"vscode"
+	],
+	"homepage": "https://github.com/Qusic/pi-ahp#readme",
+	"bugs": {
+		"url": "https://github.com/Qusic/pi-ahp/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Qusic/pi-ahp.git"
+	},
+	"license": "MIT",
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"bin": {
+		"pi-ahp": "dist/bin/cli.js",
+		"pi-ahp-tunnel": "dist/bin/tunnel.js"
+	},
+	"engines": {
+		"node": ">=24.0.0"
+	},
+	"scripts": {
+		"start": "node src/bin/cli.ts",
+		"test": "node --test \"test/**/*.test.ts\" && node --test --test-concurrency=1 \"test/**/*.test.serial.ts\"",
+		"check": "tsc",
+		"lint": "biome check",
+		"format": "biome check --write",
+		"build": "rm -rf dist && tsc -p tsconfig.build.json",
+		"release": "semantic-release",
+		"prepack": "pnpm run build"
+	},
+	"dependencies": {
+		"@earendil-works/pi-ai": "0.87.1",
+		"@earendil-works/pi-coding-agent": "0.87.1",
+		"@microsoft/agent-host-protocol": "0.9.0",
+		"chokidar": "^5.0.0",
+		"mime": "^4.1.0",
+		"node-pty": "^1.2.0-beta.15",
+		"ws": "^8.21.3"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.14",
+		"@types/node": "^24.13.6",
+		"@types/ws": "^8.18.1",
+		"ajv": "^8.20.0",
+		"semantic-release": "^25.0.9",
+		"typescript": "^7.0.2"
+	}
+}