@pi-in-go/pigpen-ahp 0.1.0

package/CREDITS.md

@@ -0,0 +1,27 @@
+# Credits
+
+`extensions/ahp` is a Go port of **pi-ahp**, https://github.com/Qusic/pi-ahp, by **Bang Lee**
+(Qusic; MIT, Copyright (c) 2026 Bang Lee).
+
+- Original: the `src/` tree of pi-ahp, a standalone host that embeds Pi and serves it over
+  Microsoft's Agent Host Protocol; npm package `pi-ahp`.
+- Revision: commit `4065e98309b03c1d2d916300856c3c21a9c10674`.
+- The unmodified `src/`, `test/` and metadata are kept in [`proof/oracle`](proof/oracle) as the
+  equivalence oracle, with the upstream license at [`proof/oracle/LICENSE`](proof/oracle/LICENSE).
+  The 430 leaf test cases of the original are listed in
+  [`upstream-tests.json`](extensions/ahp/testdata/upstream-tests.json); each has a Go twin or a named skipped
+  twin ([`proof/PORT.md`](proof/PORT.md)).
+
+The protocol is **Agent Host Protocol** (AHP) by **Microsoft Corporation**,
+https://github.com/microsoft/agent-host-protocol (MIT, Copyright (c) Microsoft Corporation),
+protocol 0.9.0, commit `296b25e7b698a4a84a0ee5a28d9573e70048a0bf`. Its Go types and reducers
+(`clients/go`, `ahp` and `ahptypes`) are vendored byte for byte, tests excluded, in
+[`extensions/ahp/third_party/agent-host-protocol-go`](extensions/ahp/third_party/agent-host-protocol-go)
+with the Microsoft license. The five protocol JSON schemas used by the tests are copied from the
+same commit into `extensions/ahp/internal/testkit/schema`, and the recorded Pi event streams in
+`extensions/ahp/internal/mapper/testdata/fixtures` come from pi-ahp's test fixtures.
+
+The Go code, the scenarios and the tests were written for this Package by Michael Kinsy. The
+behavior, wording and structure of the host follow the original. Modified paths: none of the
+originals is modified; the port is a separate implementation, and its deviations are listed in
+[`proof/PORT.md`](proof/PORT.md).

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Bang Lee
+Copyright (c) Microsoft Corporation. All rights reserved.
+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,148 @@
+# ahp (Go port of pi-ahp)
+
+A Go extension for PiG that serves the **running session** to remote clients over Microsoft's
+[Agent Host Protocol](https://github.com/microsoft/agent-host-protocol) (AHP, protocol 0.9.0,
+pinned): a WebSocket host with multi-client state, reconnect with replay or fresh snapshots,
+token authentication, an origin check, model and session-config discovery, `@`-mentions, the
+session catalogue with history paging, and live mirroring of the agent's turns, including prompts
+typed locally.
+
+It is a port of **pi-ahp** by Bang Lee (see [CREDITS.md](CREDITS.md)). pi-ahp is a standalone
+host that embeds Pi and runs many sessions; a PiG extension lives inside one session, so this port
+serves that session (and reads other sessions from their files). See [proof/PORT.md](proof/PORT.md)
+for every deviation and gap.
+
+## Safe by default
+
+- **No listener** exists unless you start one: `pig --ahp`, or `/ahp start`. Installing the
+  extension opens nothing and creates no file.
+- Starting creates `<pig home>/ahp/settings.json` (mode 0600) with a free loopback port and a random
+  token, if it is missing. Clients connect to `ws://127.0.0.1:<port>/?token=<token>`; the listener also
+  takes the token as `?tkn=`, the spelling Visual Studio Code uses (see below).
+  A non-loopback `host` without a token is refused; a browser `Origin` is refused unless listed in
+  `allowedOrigins`.
+- **Remote filesystem, watches, terminals and session deletion are separate opt-ins** in the same
+  file, all off unless set:
+
+```json
+{
+  "port": 41234, "token": "…", "host": "127.0.0.1",
+  "allowedOrigins": [],
+  "filesystem": { "enabled": true, "roots": [], "unrestricted": false },
+  "terminals": { "enabled": false },
+  "allowSessionDeletion": false
+}
+```
+
+With `filesystem.enabled` and no `roots`, access is confined to the session's working directory;
+`unrestricted: true` must be said explicitly. A terminal is a shell as you, claimed by the client
+that started it. The dev tunnel of pi-ahp is not bundled.
+
+**What a connected client can always do.** The opt-ins above cover the host's own filesystem,
+watch, terminal and deletion services. They do not limit the agent. Anyone who holds the token
+can do all of the following, so treat the token like a shell login:
+
+- Send prompts to the running session. The agent answers with the session's tools (for example
+  `bash`, `read`, `write`, `edit`), as you, in its working directory. Slash commands typed by a
+  client are sent to the model as text and are not run.
+- Switch the session's model and thinking level.
+- List and read the stored history of **every** PiG session under the session directory, from all
+  projects, not only the running one.
+- Get `@` completions, which list file names under the working directory.
+
+The token is shown in the `/ahp` status and in the "listening" notice.
+
+## Commands and flags
+
+| | |
+|---|---|
+| `--ahp` | start the listener when the session starts |
+| `--ahp-settings <file>` | settings file (default `<pig home>/ahp/settings.json`) |
+| `/ahp [status]` `/ahp start` `/ahp stop` | inspect, start or stop the listener |
+
+If the PiG session is replaced (new, resume, fork, reload), the listener closes with it and connected
+clients are dropped. With `--ahp` it opens again for the new session on the same port. After
+`/ahp start` it stays closed, a warning says so, and `/ahp start` serves the new session.
+
+## Visual Studio Code
+
+**Not verified with a live VS Code.** The listener is tested with the messages VS Code's client sends, as read from VS Code's
+source for 1.140.0 and main (the handshake, the `tkn` token, text frames, a dash-free provider id;
+`internal/ws/vscode_test.go`), not against VS Code itself. Until the owner has tried it, treat the steps below as the intended path.
+
+VS Code's Agents window (**Chat: Open Agents Window**) can connect to any WebSocket AHP host:
+
+1. Start the listener in the session you want to serve: `pig --ahp`, or `/ahp start`. The notice (and `/ahp status`) starts with
+   the address in the form VS Code takes, `ws://127.0.0.1:<port>?tkn=<token>`, then gives the `/?token=` form for other clients.
+2. In the Agents window's Command Palette run **Agents: Add Remote Agent Host...** (`sessions.remoteAgentHost.add`), paste that
+   address, and name the host. VS Code moves the token out of the address into the entry's `connectionToken`. Or add it to your
+   user `settings.json` by hand:
+
+   ```json
+   "chat.remoteAgentHosts": [
+     { "name": "pig", "address": "ws://127.0.0.1:41234", "connectionToken": "<token>" }
+   ]
+   ```
+
+3. `chat.remoteAgentHostsEnabled` must be on (it is by default). If you are not signed in to GitHub in VS Code, also set
+   `"chat.agentHost.allowSignedOutWhenUsable": true`.
+
+Reaching a host on another machine:
+
+- **SSH port forward** (simplest): `ssh -L 41234:127.0.0.1:41234 <host>`, start the listener there, and use the forwarded
+  `ws://127.0.0.1:41234?tkn=<token>` locally. The host keeps its loopback listener, so no token ever crosses the network unprotected
+  beyond the tunnel.
+- **VS Code's SSH remote agent host**: `chat.sshRemoteAgentHostCommand` (a development setting) replaces the command VS Code runs
+  on the remote. VS Code reads the first `ws://127.0.0.1:<port>?tkn=<token>` in the command's output, which is how the notice
+  starts. The command has to keep pig running without a terminal: `pig --mode rpc --ahp` prints the notice on standard output at
+  once and runs while its input stays open (checked with a plain shell, not yet with VS Code).
+- **A dev tunnel** is not bundled (the pi-ahp tunnel feature is not ported), and VS Code's own tunnel support looks for VS Code agent
+  hosts, not this one. A tunnel you start yourself can forward the port and give a `wss://` address that **Add Remote Agent Host...**
+  accepts, but VS Code sends no tunnel credentials on that connection, so the tunnel has to admit it anonymously and the token is
+  the only protection. Not tried.
+
+Debugging: set `"chat.agentHost.ahpJsonlLoggingEnabled": true` to have VS Code log every AHP message as JSON lines under the
+window's log directory (it is off by default in stable builds).
+
+What to expect, and the limits that apply to this port:
+
+- VS Code 1.140 offers protocol 0.9.0 first, then 0.7.0 down to 0.5.1; later builds offer 0.10.0 first and still 0.9.0. This host
+  speaks only 0.9.0 and negotiates it; a VS Code that stops offering 0.9.0 will report the host as incompatible. A wrong
+  or missing token is refused at the upgrade with HTTP 403, as VS Code's own agent host refuses one (pi-ahp answers 401; see
+  [proof/PORT.md](proof/PORT.md), deviation 15). A browser `Origin` that is not allowed also gets 403.
+- The host serves **the one running session** as one agent (`pi`). Other sessions are readable from their files; they are not
+  running agents. If the session is replaced (new, resume, fork, reload) clients are dropped (see Commands and flags).
+- No git changeset channels: VS Code's change views will have nothing to show (the changeset service of pi-ahp is not ported).
+- The remote filesystem, watches, terminals and session deletion are off until you opt in (see Safe by default).
+- No dev tunnel is bundled, and project trust cannot be gated from an extension (see [proof/PORT.md](proof/PORT.md)).
+
+## Other AHP clients
+
+Any client that speaks AHP 0.9.0 over WebSocket text frames can connect with `ws://127.0.0.1:<port>/?token=<token>` (or `?tkn=`).
+Two others are named for trying; **neither has been tried against this host**, and what they support has not been checked here:
+
+- **agent-host-protocol-ui**
+- **copilot-remote-host**
+
+Two things decide whether a client works: it must offer protocol 0.9.0 (this host does not down-convert from another version), and,
+if it runs in a browser, its `Origin` must be listed in `allowedOrigins` in the settings file, because the host refuses a browser
+`Origin` it does not know.
+
+## Install
+
+```sh
+pig install ./components/ahp
+```
+
+It builds from source on first use (Go toolchain required), or fuses into a Piglet Binary
+(`packages: {ahp: local:../../components/ahp}` in a Piglet). It needs no Node runtime.
+
+## Layout
+
+`extensions/ahp/internal`: `wire` (JSON-RPC, channel URIs, version negotiation), `host` (channel
+state, sequencing, replay, connections), `ws` (RFC 6455 server), `mapper` (Pi events to AHP
+actions), `pi` (chat driver, session registry, catalogue, hydration, history, models, completions),
+`svc` (resources, watches, terminals, PTY), `live` (the running PiG session behind the SDK),
+`compose` (wiring), `settings`. The Microsoft AHP Go types and reducers are vendored byte for byte
+under `third_party/`. Tests are twins of pi-ahp's 430 test cases (`internal/twin`); `twins_test.go`
+fails if one has neither a Go test nor a named skip.

package/extensions/ahp/access_options_test.go

@@ -0,0 +1,116 @@
+package ahp
+
+// Review (rev-pigpen-ahp): the capability wiring of the runtime was only exercised by the
+// real-pig scenarios, which are skipped unless PIGPEN_AHP_REAL=1, and those did not notice a
+// default root wider than the working directory. These unit tests pin it without a pig.
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+
+	ahptypes "github.com/microsoft/agent-host-protocol/clients/go/ahptypes"
+
+	"github.com/MichaelKinsy/pigpen/ahp/internal/compose"
+	"github.com/MichaelKinsy/pigpen/ahp/internal/pi"
+	"github.com/MichaelKinsy/pigpen/ahp/internal/settings"
+	"github.com/MichaelKinsy/pigpen/ahp/internal/wire"
+)
+
+func TestNoCapabilityUnlessTheSettingsGrantIt(t *testing.T) {
+	fs, terminals := accessOptions(settings.Access{}, "/work")
+	if fs != nil || terminals != nil {
+		t.Fatalf("an empty Access granted filesystem=%+v terminals=%+v", fs, terminals)
+	}
+}
+
+func TestFilesystemDefaultsToTheWorkingDirectoryOnly(t *testing.T) {
+	var a settings.Access
+	a.Filesystem.Enabled = true
+	fs, terminals := accessOptions(a, "/work")
+	if terminals != nil {
+		t.Fatal("enabling the filesystem must not enable terminals")
+	}
+	if fs == nil || fs.Unrestricted || len(fs.Roots) != 1 || fs.Roots[0] != "/work" {
+		t.Fatalf("filesystem without roots must be confined to the working directory, got %+v", fs)
+	}
+
+	a.Filesystem.Roots = []string{"/a", "/b"}
+	if fs, _ := accessOptions(a, "/work"); fs == nil || fs.Unrestricted || len(fs.Roots) != 2 || fs.Roots[0] != "/a" || fs.Roots[1] != "/b" {
+		t.Fatalf("configured roots must be used as given, got %+v", fs)
+	}
+
+	a.Filesystem.Roots, a.Filesystem.Unrestricted = nil, true
+	if fs, _ := accessOptions(a, "/work"); fs == nil || !fs.Unrestricted {
+		t.Fatalf("unrestricted must be passed on only when stated, got %+v", fs)
+	}
+}
+
+func TestTerminalsOnlyWhenEnabled(t *testing.T) {
+	var a settings.Access
+	a.Terminals.Enabled = true
+	fs, terminals := accessOptions(a, "/work")
+	if fs != nil || terminals == nil {
+		t.Fatalf("terminals enabled alone: filesystem=%+v terminals=%+v", fs, terminals)
+	}
+}
+
+// The default root, composed for real: a sibling of the working directory is refused.
+func TestDefaultRootRefusesASiblingOfTheWorkingDirectory(t *testing.T) {
+	root := t.TempDir()
+	work, sibling := filepath.Join(root, "work"), filepath.Join(root, "secret.txt")
+	if err := os.MkdirAll(work, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for path, body := range map[string]string{filepath.Join(work, "in.txt"): "inside", sibling: "outside"} {
+		if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	var a settings.Access
+	a.Filesystem.Enabled = true
+	fs, terminals := accessOptions(a, work)
+	if fs == nil {
+		t.Fatal("filesystem enabled but not composed")
+	}
+	built, err := compose.Build(compose.Options{
+		WorkingDirectory: work, Filesystem: fs, Terminals: terminals,
+		CreateBackend: func(*pi.LiveSession) (pi.Backend, error) { return nil, os.ErrInvalid },
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer built.Close()
+	read := func(path string) error {
+		_, err := built.Resources.Read(context.Background(), ahptypes.ResourceReadParams{Uri: wire.PathToFileURI(path)})
+		return err
+	}
+	if err := read(filepath.Join(work, "in.txt")); err != nil {
+		t.Fatalf("a file in the working directory must be readable: %v", err)
+	}
+	err = read(sibling)
+	var e *wire.Error
+	if !errors.As(err, &e) || e.Code != wire.CodePermissionDenied {
+		t.Fatalf("a sibling of the working directory must be refused with PermissionDenied, got %v", err)
+	}
+}
+
+func TestReplacementNotice(t *testing.T) {
+	// the listener is closed with the replaced session; say so unless --ahp brings it back
+	for _, reason := range []string{"new", "resume", "fork", "reload"} {
+		if n := replacementNotice(reason, true, false); n == "" {
+			t.Errorf("reason %q: a listener started with /ahp start closes silently", reason)
+		}
+		if n := replacementNotice(reason, true, true); n != "" {
+			t.Errorf("reason %q: --ahp restarts the listener, but got notice %q", reason, n)
+		}
+		if n := replacementNotice(reason, false, false); n != "" {
+			t.Errorf("reason %q: nothing was running, but got notice %q", reason, n)
+		}
+	}
+	if n := replacementNotice("quit", true, false); n != "" {
+		t.Errorf("quitting needs no notice, got %q", n)
+	}
+}

package/extensions/ahp/extension.go

@@ -0,0 +1,54 @@
+// Package ahp is a Go port of pi-ahp (Bang Lee / Qusic, MIT): a host for Microsoft's Agent
+// Host Protocol that serves the running PiG session to remote AHP clients over WebSocket.
+//
+// The extension opens no listener unless the user asks: with the --ahp flag, or with /ahp start.
+// Remote filesystem and terminal access are further opt-ins in the settings file.
+package ahp
+
+import (
+	"fmt"
+	"strings"
+
+	sdk "github.com/MichaelKinsy/PiG/extensions/sdk"
+)
+
+const (
+	flagStart    = "ahp"
+	flagSettings = "ahp-settings"
+)
+
+// Extension registers the extension. It starts no listener unless the user configured one.
+func Extension() *sdk.Extension {
+	e := sdk.New("ahp")
+	rt := newRuntime()
+
+	e.Flag(flagStart, sdk.FlagOptions{Type: sdk.FlagBoolean, Description: "Start the AHP listener for this session (settings file: see /ahp)"})
+	e.Flag(flagSettings, sdk.FlagOptions{Type: sdk.FlagString, Description: "AHP settings file (default: <pig home>/ahp/settings.json)"})
+
+	rt.live.Register(e, rt.onSessionStart, rt.onSessionShutdown)
+	rt.live.OnModelChanged(rt.onModelChanged)
+
+	e.Command("ahp", "AHP host: /ahp [status|start|stop]", func(ctx sdk.Context, args string) error {
+		switch strings.TrimSpace(args) {
+		case "", "status":
+			ctx.Notify(rt.status(), "info")
+		case "start":
+			addr, err := rt.start(ctx)
+			if err != nil {
+				ctx.Notify("AHP: "+err.Error(), "error")
+				return nil
+			}
+			ctx.Notify(addr, "info")
+		case "stop":
+			if rt.stop() {
+				ctx.Notify("AHP listener stopped", "info")
+			} else {
+				ctx.Notify("AHP listener is not running", "info")
+			}
+		default:
+			return fmt.Errorf("usage: /ahp [status|start|stop]")
+		}
+		return nil
+	})
+	return e
+}

package/extensions/ahp/go.mod

@@ -0,0 +1,12 @@
+module github.com/MichaelKinsy/pigpen/ahp
+
+go 1.26
+
+// PiG resolves this requirement to the version-matched staged SDK at build time.
+require github.com/MichaelKinsy/PiG/extensions/sdk v0.4.1
+
+// The Microsoft Agent Host Protocol Go types and reducers (MIT), vendored byte for byte.
+// See third_party/agent-host-protocol-go/NOTICE-PIGPEN.md.
+require github.com/microsoft/agent-host-protocol/clients/go v0.9.0
+
+replace github.com/microsoft/agent-host-protocol/clients/go => ./third_party/agent-host-protocol-go

package/extensions/ahp/go.sum

@@ -0,0 +1,2 @@
+github.com/MichaelKinsy/PiG/extensions/sdk v0.4.1/go.mod h1:4j0XhCW0EPOBWvqYE7XKjTvIAahI7K1VyyW3KpjTKj8=
+github.com/MichaelKinsy/PiG/extensions/sdk v0.4.1 h1:Ql9sTkc6dvAXaYQLq5nxqmSZgqu8S0L53ZTs8MkOuxw=

package/extensions/ahp/go.work

@@ -0,0 +1,8 @@
+go 1.26
+
+// Lists the vendored Microsoft AHP module so a fused Piglet Binary build (which does not honour
+// replace directives of the extension's go.mod) resolves it locally. See third_party/.../NOTICE-PIGPEN.md.
+use (
+	.
+	./third_party/agent-host-protocol-go
+)

package/extensions/ahp/internal/channels/chat.go

@@ -0,0 +1,110 @@
+package channels
+
+import (
+	"encoding/json"
+	"time"
+
+	"github.com/microsoft/agent-host-protocol/clients/go/ahptypes"
+
+	"github.com/MichaelKinsy/pigpen/ahp/internal/host"
+	"github.com/MichaelKinsy/pigpen/ahp/internal/wire"
+)
+
+// InitialChatState is a fresh, idle chat (port of initialChatState in src/channels/chat.ts).
+// Every session this host serves has exactly one chat, which is why the agent declares no
+// `multipleChats` capability: its absence tells a client not to call `createChat`.
+//
+// A selection seeds the draft's model before the agent exists. Starting one takes seconds, and a
+// client that subscribes in the meantime would otherwise find an empty model picker and be unable
+// to send. The backend refines it once it is up.
+func InitialChatState(uri, title string, selection *ahptypes.ModelSelection) *ahptypes.ChatState {
+	state := &ahptypes.ChatState{
+		Resource:   uri,
+		Title:      title,
+		Status:     ahptypes.SessionStatusIdle,
+		ModifiedAt: time.Now().UTC().Format("2006-01-02T15:04:05.000Z"),
+		// A session's default chat exists because the user made the session.
+		Origin: &ahptypes.ChatOrigin{Value: &ahptypes.ChatUserOrigin{Kind: ahptypes.ChatOriginKindUser}},
+		Turns:  []ahptypes.Turn{},
+	}
+	if selection != nil {
+		state.Draft = &ahptypes.Message{Text: "", Origin: ahptypes.MessageOrigin{Kind: ahptypes.MessageKindUser}, Model: selection}
+	}
+	return state
+}
+
+// ChatSummaryOf is the denormalised summary of a chat that its session carries.
+func ChatSummaryOf(state *ahptypes.ChatState) ahptypes.ChatSummary {
+	return ahptypes.ChatSummary{
+		Resource: state.Resource, Title: state.Title, Status: state.Status, ModifiedAt: state.ModifiedAt,
+		Activity: state.Activity, Origin: state.Origin, Interactivity: state.Interactivity,
+		WorkingDirectories: state.WorkingDirectories,
+	}
+}
+
+// InstallDefaultChat creates a session's default chat and registers it in the session catalogue.
+// The chat id is derived from the session id so the pairing is reconstructible without a lookup
+// table.
+func InstallDefaultChat(h *host.Host, sessionChannel, sessionID, title string, selection *ahptypes.ModelSelection) string {
+	uri := wire.ChatURI(sessionID)
+	h.Store().Create(uri, InitialChatState(uri, title, selection))
+	summary := ChatSummaryOf(h.Store().Chat(uri))
+	h.DispatchServerAction(sessionChannel, ahptypes.StateAction{Value: &ahptypes.SessionChatAddedAction{Type: ahptypes.ActionTypeSessionChatAdded, Summary: summary}})
+	h.DispatchServerAction(sessionChannel, ahptypes.StateAction{Value: &ahptypes.SessionDefaultChatChangedAction{Type: ahptypes.ActionTypeSessionDefaultChatChanged, DefaultChat: &uri}})
+	return uri
+}
+
+func jsonEqual(a, b any) bool {
+	ja, _ := json.Marshal(a)
+	jb, _ := json.Marshal(b)
+	return string(ja) == string(jb)
+}
+
+func equalSummary(a, b ahptypes.ChatSummary) bool {
+	return a.Resource == b.Resource && a.Title == b.Title && a.Status == b.Status && a.ModifiedAt == b.ModifiedAt &&
+		jsonEqual(a.Activity, b.Activity) && jsonEqual(a.Origin, b.Origin) && jsonEqual(a.Interactivity, b.Interactivity) &&
+		jsonEqual(a.WorkingDirectories, b.WorkingDirectories)
+}
+
+// SyncChatSummary mirrors a chat's denormalised summary fields into its owning session.
+//
+// Partial updates cannot express removal of an optional JSON field: a nil value disappears on
+// the wire and means "unchanged". The action's full-summary upsert form is used when one of those
+// fields is cleared. It reports whether anything was dispatched.
+func SyncChatSummary(h *host.Host, sessionChannel, chatChannel string) bool {
+	chat := h.Store().Chat(chatChannel)
+	session := h.Store().Session(sessionChannel)
+	if chat == nil || session == nil {
+		return false
+	}
+	var previous *ahptypes.ChatSummary
+	for i := range session.Chats {
+		if session.Chats[i].Resource == chatChannel {
+			previous = &session.Chats[i]
+			break
+		}
+	}
+	if previous == nil {
+		return false
+	}
+	current := ChatSummaryOf(chat)
+	if equalSummary(*previous, current) {
+		return false
+	}
+	clears := (previous.Activity != nil && current.Activity == nil) ||
+		(previous.Origin != nil && current.Origin == nil) ||
+		(previous.Interactivity != nil && current.Interactivity == nil) ||
+		(previous.WorkingDirectories != nil && current.WorkingDirectories == nil)
+	if clears {
+		h.DispatchServerAction(sessionChannel, ahptypes.StateAction{Value: &ahptypes.SessionChatAddedAction{Type: ahptypes.ActionTypeSessionChatAdded, Summary: current}})
+		return true
+	}
+	changes := ahptypes.PartialChatSummary{
+		Title: &current.Title, Status: &current.Status, Activity: current.Activity, ModifiedAt: &current.ModifiedAt,
+		Origin: current.Origin, WorkingDirectories: current.WorkingDirectories,
+	}
+	h.DispatchServerAction(sessionChannel, ahptypes.StateAction{Value: &ahptypes.SessionChatUpdatedAction{
+		Type: ahptypes.ActionTypeSessionChatUpdated, Chat: chatChannel, Changes: changes,
+	}})
+	return true
+}

package/extensions/ahp/internal/channels/root.go

@@ -0,0 +1,32 @@
+package channels
+
+import (
+	"github.com/microsoft/agent-host-protocol/clients/go/ahptypes"
+
+	"github.com/MichaelKinsy/pigpen/ahp/internal/host"
+	"github.com/MichaelKinsy/pigpen/ahp/internal/wire"
+)
+
+// Catalogue notifications are ephemeral and never replayed on reconnect; after reconnecting a
+// client re-fetches the catalogue with listSessions.
+
+// NotifySessionAdded announces a session on the root channel.
+func NotifySessionAdded(h *host.Host, summary ahptypes.SessionSummary) {
+	h.Notify(wire.RootChannel, "root/sessionAdded", map[string]any{"summary": summary})
+}
+
+// NotifySessionRemoved announces a removed session.
+func NotifySessionRemoved(h *host.Host, session string) {
+	h.Notify(wire.RootChannel, "root/sessionRemoved", map[string]any{"session": session})
+}
+
+// NotifySessionSummaryChanged announces changed catalogue fields.
+func NotifySessionSummaryChanged(h *host.Host, session string, changes ahptypes.PartialSessionSummary) {
+	h.Notify(wire.RootChannel, "root/sessionSummaryChanged", map[string]any{"session": session, "changes": changes})
+}
+
+// TerminalInfoOf is the root catalogue projection of a terminal; process handles never enter
+// protocol state.
+func TerminalInfoOf(resource string, state *ahptypes.TerminalState) ahptypes.TerminalInfo {
+	return ahptypes.TerminalInfo{Resource: resource, Title: state.Title, Claim: state.Claim, Lifecycle: state.Lifecycle}
+}

package/extensions/ahp/internal/channels/session.go

@@ -0,0 +1,128 @@
+// Package channels builds the protocol-shaped state of the session and chat channels. It
+// ports pi-ahp's src/channels (root.ts, session.ts, chat.ts) and knows nothing about Pi or PiG.
+package channels
+
+import (
+	"encoding/json"
+	"time"
+
+	"github.com/microsoft/agent-host-protocol/clients/go/ahptypes"
+
+	"github.com/MichaelKinsy/pigpen/ahp/internal/wire"
+)
+
+// InitialSessionState is a fresh session in lifecycle "creating".
+func InitialSessionState(provider, title, workingDirectory string) *ahptypes.SessionState {
+	return &ahptypes.SessionState{
+		Provider:           provider,
+		Title:              title,
+		Status:             ahptypes.SessionStatusIdle,
+		Lifecycle:          ahptypes.SessionLifecycleCreating,
+		WorkingDirectories: []ahptypes.URI{wire.PathToFileURI(workingDirectory)},
+		ActiveClients:      []ahptypes.SessionActiveClient{},
+		Chats:              []ahptypes.ChatSummary{},
+	}
+}
+
+// statusActivityMask: the low five bits encode activity; higher bits carry independent metadata
+// flags.
+const statusActivityMask = ahptypes.SessionStatus(1<<5 - 1)
+
+// SessionChatAggregate is what a session derives from its chat catalogue.
+type SessionChatAggregate struct {
+	Status     ahptypes.SessionStatus
+	Activity   *string
+	ModifiedAt string // "" when the session has no chats
+}
+
+// instant parses an ISO 8601 timestamp; an unparsable one sorts before every valid one.
+func instant(summary ahptypes.ChatSummary) (t time.Time, ok bool) {
+	for _, layout := range []string{time.RFC3339Nano, "2006-01-02T15:04:05.999999999Z0700", "2006-01-02T15:04:05Z0700"} {
+		if parsed, err := time.Parse(layout, summary.ModifiedAt); err == nil {
+			return parsed, true
+		}
+	}
+	return time.Time{}, false
+}
+
+func newer(a, b ahptypes.ChatSummary) bool { // a is strictly more recent than b
+	ta, oka := instant(a)
+	tb, okb := instant(b)
+	switch {
+	case !oka:
+		return false
+	case !okb:
+		return true
+	}
+	return ta.After(tb)
+}
+
+func mostRecent(chats []ahptypes.ChatSummary, matches func(ahptypes.ChatSummary) bool) (ahptypes.ChatSummary, bool) {
+	var latest ahptypes.ChatSummary
+	found := false
+	for _, chat := range chats {
+		if matches(chat) && (!found || newer(chat, latest)) {
+			latest, found = chat, true
+		}
+	}
+	return latest, found
+}
+
+// AggregateSessionChats projects the session-level summary fields AHP derives from its chat
+// catalogue. The current host exposes one chat, so this is a pass-through today; keeping the
+// complete 0.9 rule makes the projection deterministic. It never mutates the state.
+func AggregateSessionChats(state *ahptypes.SessionState) SessionChatAggregate {
+	if len(state.Chats) == 0 {
+		return SessionChatAggregate{Status: state.Status, Activity: state.Activity}
+	}
+	latest, ok := mostRecent(state.Chats, func(ahptypes.ChatSummary) bool { return true })
+	if !ok {
+		return SessionChatAggregate{Status: state.Status}
+	}
+	driver := latest
+	if state.DefaultChat != nil {
+		for _, chat := range state.Chats {
+			if chat.Resource == *state.DefaultChat {
+				driver = chat
+				break
+			}
+		}
+	}
+	if c, ok := mostRecent(state.Chats, func(c ahptypes.ChatSummary) bool {
+		return c.Status&ahptypes.SessionStatusInputNeeded == ahptypes.SessionStatusInputNeeded
+	}); ok {
+		driver = c
+	} else if c, ok := mostRecent(state.Chats, func(c ahptypes.ChatSummary) bool {
+		return c.Status&ahptypes.SessionStatusError == ahptypes.SessionStatusError
+	}); ok {
+		driver = c
+	}
+	metadata := state.Status &^ statusActivityMask
+	return SessionChatAggregate{
+		Status:     metadata | (driver.Status & statusActivityMask),
+		Activity:   driver.Activity,
+		ModifiedAt: latest.ModifiedAt,
+	}
+}
+
+// SessionSummaryOf is the root-catalogue projection of a session.
+func SessionSummaryOf(resource, createdAt string, state *ahptypes.SessionState, meta map[string]json.RawMessage) ahptypes.SessionSummary {
+	aggregate := AggregateSessionChats(state)
+	modifiedAt := aggregate.ModifiedAt
+	if modifiedAt == "" {
+		modifiedAt = createdAt
+	}
+	summary := ahptypes.SessionSummary{
+		Resource: resource, Provider: state.Provider, Title: state.Title, Status: aggregate.Status,
+		// Root summary activity is deliberately omitted for AHP 0.9: its partial update shape
+		// cannot distinguish "clear" from "unchanged" on the JSON wire.
+		CreatedAt: createdAt, ModifiedAt: modifiedAt,
+	}
+	if state.WorkingDirectories != nil {
+		summary.WorkingDirectories = state.WorkingDirectories
+	}
+	if meta != nil {
+		summary.Meta = meta
+	}
+	return summary
+}