@pi-in-go/pigpen-a2a 0.1.0

package/CREDITS.md

@@ -0,0 +1,26 @@
+# Credits
+
+The `a2a` Package is original work by Michael Kinsy (MIT, see [LICENSE](LICENSE)). It is an adapter
+between PiG and the Agent2Agent (A2A) protocol and contains no copied source. It **depends on** and
+links the upstream Go SDK:
+
+- **a2a-go**, the A2A Go SDK, `github.com/a2aproject/a2a-go/v2` **v2.6.0**
+  (commit `ebf17c56ef7e63c72883a45454a538bbc0df66b8`, tag `v2.6.0`), © The A2A Authors, Linux Foundation,
+  licensed under the **Apache License 2.0** ([port/a2a-go-LICENSE](port/a2a-go-LICENSE), unmodified).
+  <https://github.com/a2aproject/a2a-go>. The SDK implements the A2A protocol version 1.0
+  (<https://a2a-protocol.org>). It is used unmodified: `a2asrv` (server), `a2aclient` and
+  `a2aclient/agentcard` (client). Its transitive requirements (`github.com/google/uuid`,
+  `golang.org/x/mod`, `golang.org/x/sync`) are recorded in `extensions/a2a/go.mod` and `go.sum`.
+  A Piglet Binary that fuses this extension redistributes a2a-go, so the Apache-2.0 text must travel with it.
+
+## Interoperability test target
+
+The interop test drives **kagent**'s A2A server package (`go/adk/pkg/a2a/server`, Apache-2.0,
+<https://github.com/kagent-dev/kagent>) from a kagent checkout you provide. `scripts/interop-kagent.mjs`
+copies that package into a temporary directory at test time and changes one line (its readiness port);
+nothing of kagent is committed here. `port/interop/kagent/main.go` is original glue code (an echo
+executor around kagent's server).
+
+## What is not here
+
+No Kubernetes orchestration is ported. kagent is an A2A peer, not a dependency.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Kinsy
+
+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,97 @@
+# a2a: PiG speaks A2A
+
+Serve PiG tasks to [A2A](https://a2a-protocol.org) (Agent2Agent) agents, and call remote A2A agents from PiG.
+Built on the upstream Go SDK [a2a-go](https://github.com/a2aproject/a2a-go) v2.6.0 (Apache-2.0, see
+[CREDITS.md](CREDITS.md)), pinned to **A2A protocol 1.0**, JSON-RPC binding. It interoperates with
+[kagent](https://github.com/kagent-dev/kagent), which speaks the same protocol through the same SDK; Kubernetes
+orchestration is not ported.
+
+**The listener is off unless you configure it.** Installing the Package opens no port. It registers three tools and one
+command; the tools do nothing until a remote is configured.
+
+```sh
+pig install ./components/a2a          # builds from source on first use (Go toolchain), or fuses into a Piglet Binary
+```
+
+Original work (MIT) on a dependency (Apache-2.0). Go only, public PiG SDK, no Node. Not a published release.
+
+## Serve PiG tasks
+
+Create `$PIG_CODING_AGENT_DIR/a2a.json` (default `~/.pig/agent/a2a.json`; `PIG_A2A_CONFIG` names another file):
+
+```json
+{
+  "listen": "127.0.0.1:8787",
+  "name": "my-pig",
+  "tokens": [
+    {"name": "ci",   "tokenEnv": "A2A_TOKEN_CI",   "tenant": "team-a"},
+    {"name": "alice", "tokenEnv": "A2A_TOKEN_ALICE"}
+  ],
+  "worker": {"cwd": "/srv/project", "provider": "anthropic", "model": "claude-sonnet-4-5", "passEnv": ["ANTHROPIC_API_KEY"]},
+  "maxConcurrentTasks": 4,
+  "taskTimeoutSeconds": 900
+}
+```
+
+`PIG_A2A_LISTEN=host:port` and `pig --a2a-listen host:port` override `listen` (flag over environment over file).
+Tokens are **only** named by environment variable; the file never holds a secret, and an inline `token` key is refused.
+
+What the server does:
+
+| | |
+|---|---|
+| Endpoint | JSON-RPC 2.0 at `/`, agent card at `/.well-known/agent-card.json` (public; declares the Bearer scheme). Streaming (`SendStreamingMessage`) works; push notifications, gRPC and REST do not. |
+| Protocol | `A2A-Version: 1.0` is required on every call. Any other value, and a missing header (which the specification reads as 0.3), is answered `VERSION_NOT_SUPPORTED` before anything runs. |
+| Tasks | Each A2A task is one turn of a PiG worker: a fresh `pig --mode rpc` process. Text goes in; assistant text streams out as artifact chunks; the task ends `completed`, `failed` or `canceled`. |
+| Context | A `contextId` **is** a PiG session: a later task with the same `contextId` continues the conversation (the session file persists on disk). Tasks of one context run one at a time. |
+| Cancellation | `CancelTask` sends the worker the RPC `abort`, waits for it, then kills the process group after `graceSeconds`. Closing the listener, a reload or quitting PiG cancels every running task. `taskTimeoutSeconds` fails a task that runs too long. |
+| Authentication | Static bearer tokens (`Authorization: Bearer ...`, header only, compared in constant time on SHA-256 digests). No token, no work: a listener needs at least one, or `insecureNoAuth` on a loopback address. An `insecureNoAuth` listener answers only requests whose `Host` is a loopback name or address (`403` otherwise), so a web page that rebinds its own name to `127.0.0.1` cannot drive it. `tls.certFile`/`keyFile` serve HTTPS. |
+| Tenants | Every token is a principal; tokens sharing a `tenant` share tasks and contexts, everything else is its own boundary. Task lists, `GetTask`, `CancelTask`, `SubscribeToTask` and follow-up messages are scoped to it, the session file is derived from `(principal, contextId)` so two tenants that pick the same `contextId` never share a conversation, and a request that names another tenant than its credential's is refused. This boundary is in the protocol only: every worker runs as the same operating-system user, so once you give workers file tools (below) a tenant can read the other tenants' session files. |
+| Safety | The worker runs with **no tools** unless `worker.tools` names some (`pig --no-tools`), no extensions, skills or context files, an empty private working directory unless you set `worker.cwd`, and only an allowlisted environment (provider keys must be named in `passEnv`; the A2A tokens never reach it). It cannot start another listener. Requests are capped at 1 MiB, prompts at 256 KiB. Provider error text is never sent to the peer. |
+
+Give the worker tools only with intent. PiG's file tools are **not confined** to `worker.cwd`: they take absolute paths and `~`.
+`"worker": {"tools": ["read", "grep", "find", "ls"]}` lets every token holder read any file the operating-system user running PiG
+can read, including PiG's own credentials (`auth.json`), SSH keys and other tenants' session files; adding `edit`, `write` or
+`bash` lets them change or run anything that user can. Run a listener with tools as a dedicated user (or in a container) that
+holds only the workspace and the provider key, one per trust boundary.
+
+`worker.command` (or `PIG_A2A_PIG`) names the pig executable; the default is `pig` on `PATH`. In a Piglet Binary set it to the
+Binary itself. A running server is shown by `/a2a`.
+
+## Call remote agents
+
+```json
+{
+  "remotes": {
+    "kagent": {"url": "http://localhost:8083/api/a2a/kagent/helm-agent", "bearerTokenEnv": "KAGENT_TOKEN", "skipCard": true},
+    "review": {"url": "https://agents.example.com/review", "bearerTokenEnv": "REVIEW_TOKEN"}
+  }
+}
+```
+
+| Tool | Use |
+|---|---|
+| `a2a_agents` | List the configured remotes with their cards (name, description, skills). |
+| `a2a_send` `{agent, message, contextId?, taskId?}` | Send a task and wait; returns `state`, `taskId`, `contextId` and the reply. Streams progress. Cancelling the tool call cancels the remote task. |
+| `a2a_task` `{agent, action: get|cancel|list, taskId?}` | Inspect or cancel remote tasks. |
+
+`/a2a` shows the listener and the remotes. Credentials: `bearerTokenEnv`, or `headerEnv` (`{"X-Api-Key": "MY_KEY_VAR"}`), both
+environment variable names; a missing variable is an error before any request. Credentials go **only** to the configured origin
+(scheme and host; an `https` remote's token is never sent over `http`): a card that names another origin is refused unless `skipCard` is set (kagent's card carries an in-cluster URL, so use `skipCard` and the
+routable URL). Redirects are not followed. Only A2A 1.0 JSON-RPC interfaces are used; a card that offers only 0.3 is refused.
+Data you send to a remote leaves the machine.
+
+## Layout
+
+```text
+extensions/a2a/         the Go extension (package a2aext): config, auth, worker, executor, server, client, extension; tests
+port/PORT.md            contract table, gaps, host findings, proof results (this is an original adapter: there is no Pi oracle)
+port/scenarios,golden   host-level scenarios recorded from the port itself under PiG (self-recorded regression, not equivalence)
+port/mutations.json     109 deliberate defects; every one is caught (port/mutation-run.txt)
+port/interop/kagent/    kagent-compatible endpoint used by scripts/interop-kagent.mjs
+port/red.txt            the RED run of the tests on a stub
+```
+
+Tests: `PIG_BIN=pig npm run test:go-ports` (unit and fake-host, `-race`); real PiG end to end:
+`PIG_A2A_E2E_BIN=pig go test -run E2E` in `extensions/a2a` (temporary HOME, PIG_HOME and PIG_CODING_AGENT_DIR, a local fake
+model server); the Piglet Binary hosting the listener: `PIG_A2A_BINARY=<binary built from piglets/a2a> go test -run Binary`; kagent: `KAGENT_GO_DIR=<kagent>/go PIG_BIN=pig node scripts/interop-kagent.mjs`.

package/extensions/a2a/auth.go

@@ -0,0 +1,120 @@
+package a2aext
+
+import (
+	"context"
+	"crypto/sha256"
+	"crypto/subtle"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"strings"
+)
+
+// Principal is an authenticated caller.
+type Principal struct {
+	Name   string
+	Tenant string
+}
+
+// Key is the isolation key for tasks and sessions: every token of one tenant shares
+// it, a token without a tenant is its own boundary, and the two namespaces cannot collide.
+func (p Principal) Key() string {
+	if p.Tenant != "" {
+		return "tenant:" + p.Tenant
+	}
+	return "token:" + p.Name
+}
+
+type tokenEntry struct {
+	digest    [sha256.Size]byte
+	principal Principal
+}
+
+// Authenticator maps bearer tokens to principals.
+type Authenticator struct {
+	entries  []tokenEntry
+	insecure bool
+}
+
+// NewAuthenticator builds an Authenticator. Tokens are read from the environment variables
+// the configuration names; only their SHA-256 digests are kept.
+func NewAuthenticator(tokens []TokenConfig, getenv func(string) string, insecureNoAuth bool) (*Authenticator, error) {
+	if insecureNoAuth {
+		return &Authenticator{insecure: true}, nil
+	}
+	if len(tokens) == 0 {
+		return nil, errors.New("a2a: no tokens configured; refusing to build an authenticator that accepts everyone or no one")
+	}
+	a := &Authenticator{}
+	for _, t := range tokens {
+		v := getenv(t.TokenEnv)
+		if v == "" {
+			return nil, fmt.Errorf("a2a: token %q: environment variable %s is not set", t.Name, t.TokenEnv)
+		}
+		a.entries = append(a.entries, tokenEntry{digest: sha256.Sum256([]byte(v)), principal: Principal{Name: t.Name, Tenant: t.Tenant}})
+	}
+	return a, nil
+}
+
+// Authenticate returns the caller's principal from the Authorization header. Tokens in
+// URLs are never read: they end up in logs and proxies.
+func (a *Authenticator) Authenticate(r *http.Request) (Principal, bool) {
+	if a.insecure {
+		return Principal{Name: "anonymous"}, true
+	}
+	fields := strings.Fields(r.Header.Get("Authorization"))
+	if len(fields) != 2 || !strings.EqualFold(fields[0], "bearer") {
+		return Principal{}, false
+	}
+	digest := sha256.Sum256([]byte(fields[1]))
+	var found Principal
+	ok := false
+	for _, e := range a.entries { // no early exit: the time does not depend on which token matched
+		if subtle.ConstantTimeCompare(digest[:], e.digest[:]) == 1 {
+			found, ok = e.principal, true
+		}
+	}
+	return found, ok
+}
+
+// loopbackHostHeader reports whether a Host header names a loopback address (localhost, 127.0.0.0/8, ::1).
+func loopbackHostHeader(hostport string) bool {
+	host, _, err := net.SplitHostPort(hostport)
+	if err != nil {
+		host = strings.TrimSuffix(strings.TrimPrefix(hostport, "["), "]")
+	}
+	return isLoopbackHost(host)
+}
+
+type principalCtxKey struct{}
+
+// PrincipalFrom returns the principal Wrap attached to ctx.
+func PrincipalFrom(ctx context.Context) (Principal, bool) {
+	p, ok := ctx.Value(principalCtxKey{}).(Principal)
+	return p, ok
+}
+
+// Wrap rejects unauthenticated requests with 401 and a Bearer challenge, except those
+// isPublic accepts (the agent card), and passes the principal down in the request context.
+func (a *Authenticator) Wrap(next http.Handler, isPublic func(*http.Request) bool) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if a.insecure && !loopbackHostHeader(r.Host) {
+			// Without a credential, the Host header is what tells a local client from a web page that rebound
+			// its own name to 127.0.0.1 (DNS rebinding); such a page would be same-origin with the listener.
+			http.Error(w, "forbidden host", http.StatusForbidden)
+			return
+		}
+		if isPublic != nil && isPublic(r) {
+			next.ServeHTTP(w, r)
+			return
+		}
+		p, ok := a.Authenticate(r)
+		if !ok {
+			w.Header().Set("WWW-Authenticate", "Bearer")
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+		next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), principalCtxKey{}, p)))
+	})
+}

package/extensions/a2a/auth_test.go

@@ -0,0 +1,133 @@
+package a2aext
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+const (
+	tokenA = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+	tokenB = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+)
+
+func testAuth(t *testing.T) *Authenticator {
+	t.Helper()
+	a, err := NewAuthenticator([]TokenConfig{
+		{Name: "alice", TokenEnv: "TOKEN_A", Tenant: "team-a"},
+		{Name: "bob", TokenEnv: "TOKEN_B"},
+	}, envFrom(map[string]string{"TOKEN_A": tokenA, "TOKEN_B": tokenB}), false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return a
+}
+
+func request(header string) *http.Request {
+	r := httptest.NewRequest(http.MethodPost, "http://x/", nil)
+	if header != "" {
+		r.Header.Set("Authorization", header)
+	}
+	return r
+}
+
+func TestAuthenticateBearer(t *testing.T) {
+	a := testAuth(t)
+	p, ok := a.Authenticate(request("Bearer " + tokenA))
+	if !ok || p.Name != "alice" || p.Tenant != "team-a" {
+		t.Fatalf("got %+v %v", p, ok)
+	}
+	p, ok = a.Authenticate(request("bearer " + tokenB))
+	if !ok || p.Name != "bob" {
+		t.Fatalf("scheme is case-insensitive: %+v %v", p, ok)
+	}
+}
+
+func TestAuthenticateRejects(t *testing.T) {
+	a := testAuth(t)
+	for name, h := range map[string]string{
+		"empty": "", "wrong": "Bearer " + tokenA + "x", "prefix": "Bearer " + tokenA[:10],
+		"basic": "Basic " + tokenA, "no scheme": tokenA, "bare bearer": "Bearer ", "two": "Bearer " + tokenA + " " + tokenB,
+	} {
+		if _, ok := a.Authenticate(request(h)); ok {
+			t.Errorf("%s: must not authenticate", name)
+		}
+	}
+}
+
+func TestTokenInQueryStringIsIgnored(t *testing.T) {
+	a := testAuth(t)
+	r := httptest.NewRequest(http.MethodPost, "http://x/?access_token="+tokenA, nil)
+	if _, ok := a.Authenticate(r); ok {
+		t.Fatal("tokens in URLs leak into logs; only the Authorization header counts")
+	}
+}
+
+func TestWrapRejectsWith401AndChallenge(t *testing.T) {
+	called := false
+	h := testAuth(t).Wrap(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { called = true }), func(*http.Request) bool { return false })
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, request(""))
+	if rec.Code != http.StatusUnauthorized || called {
+		t.Fatalf("code %d called %v", rec.Code, called)
+	}
+	if got := rec.Header().Get("WWW-Authenticate"); got != "Bearer" {
+		t.Fatalf("WWW-Authenticate = %q", got)
+	}
+}
+
+func TestWrapPassesPrincipalAndPublicPaths(t *testing.T) {
+	var got Principal
+	h := testAuth(t).Wrap(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		got, _ = PrincipalFrom(r.Context())
+	}), func(r *http.Request) bool { return r.URL.Path == "/public" })
+	h.ServeHTTP(httptest.NewRecorder(), request("Bearer "+tokenA))
+	if got.Name != "alice" {
+		t.Fatalf("principal %+v", got)
+	}
+	got = Principal{}
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "http://x/public", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("public path code %d", rec.Code)
+	}
+}
+
+func TestPrincipalKeysIsolate(t *testing.T) {
+	seen := map[string]Principal{}
+	for _, p := range []Principal{
+		{Name: "alice", Tenant: "team-a"}, {Name: "bob", Tenant: "team-a"}, {Name: "alice"}, {Name: "bob"}, {Name: "team-a"},
+	} {
+		k := p.Key()
+		if k == "" {
+			t.Fatalf("%+v has no key", p)
+		}
+		if other, dup := seen[k]; dup && !(other.Tenant != "" && p.Tenant == other.Tenant) {
+			t.Fatalf("%+v and %+v share key %q", p, other, k)
+		}
+		seen[k] = p
+	}
+	if (Principal{Name: "alice", Tenant: "t"}).Key() != (Principal{Name: "bob", Tenant: "t"}).Key() {
+		t.Fatal("two tokens of one tenant share tasks and contexts")
+	}
+	if (Principal{Name: "team-a"}).Key() == (Principal{Name: "x", Tenant: "team-a"}).Key() {
+		t.Fatal("a token named like a tenant must not collide with the tenant")
+	}
+}
+
+func TestInsecureNoAuthGivesOneAnonymousPrincipal(t *testing.T) {
+	a, err := NewAuthenticator(nil, envFrom(nil), true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	p, ok := a.Authenticate(request(""))
+	if !ok || p.Name != "anonymous" {
+		t.Fatalf("%+v %v", p, ok)
+	}
+}
+
+func TestNoTokensNoInsecureFlagIsAnError(t *testing.T) {
+	if _, err := NewAuthenticator(nil, envFrom(nil), false); err == nil {
+		t.Fatal("an authenticator with no tokens would reject everyone or accept everyone; refuse to build it")
+	}
+}

package/extensions/a2a/bench_test.go

@@ -0,0 +1,70 @@
+package a2aext
+
+import (
+	"bytes"
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// A2A request handling without the network: the server's http.Handler driven directly, a worker that answers at
+// once. This is what the listener adds per request (authentication, version check, JSON-RPC, task bookkeeping).
+// The listener is off unless configured; nothing here runs at startup.
+//
+//	go test -run xxx -bench . -benchmem
+func benchServer(b *testing.B) *Server {
+	b.Helper()
+	s, err := NewServer(serverConfig(), &scriptedWorker{}, serverEnv)
+	if err != nil {
+		b.Fatal(err)
+	}
+	b.Cleanup(func() { _ = s.Shutdown(context.Background()) })
+	return s
+}
+
+func BenchmarkSendMessage(b *testing.B) {
+	s := benchServer(b)
+	h := s.Handler()
+	body := []byte(`{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{"messageId":"m1","role":"ROLE_USER","parts":[{"text":"hello there"}]}}}`)
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		r := httptest.NewRequest(http.MethodPost, "http://x/", bytes.NewReader(body))
+		r.Header.Set("Content-Type", "application/json")
+		r.Header.Set("Authorization", "Bearer "+tokenA)
+		r.Header.Set("A2A-Version", "1.0")
+		w := httptest.NewRecorder()
+		h.ServeHTTP(w, r)
+		if w.Code != http.StatusOK {
+			b.Fatalf("status %d: %s", w.Code, w.Body.String())
+		}
+	}
+}
+
+func BenchmarkAuthenticate(b *testing.B) {
+	a, err := NewAuthenticator(serverConfig().Tokens, serverEnv, false)
+	if err != nil {
+		b.Fatal(err)
+	}
+	r := httptest.NewRequest(http.MethodPost, "http://x/", nil)
+	r.Header.Set("Authorization", "Bearer "+tokenB)
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		if _, ok := a.Authenticate(r); !ok {
+			b.Fatal("rejected")
+		}
+	}
+}
+
+func BenchmarkAgentCard(b *testing.B) {
+	h := benchServer(b).Handler()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		w := httptest.NewRecorder()
+		h.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "http://x/.well-known/agent-card.json", nil))
+		if w.Code != http.StatusOK {
+			b.Fatalf("status %d", w.Code)
+		}
+	}
+}