@pi-in-go/pigpen-a2a 0.1.0

package/extensions/a2a/client_test.go

@@ -0,0 +1,402 @@
+package a2aext
+
+import (
+	"context"
+	"errors"
+	"iter"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/a2aproject/a2a-go/v2/a2a"
+	"github.com/a2aproject/a2a-go/v2/a2asrv"
+)
+
+// fakeRemote is an A2A 1.0 agent built directly on the upstream server SDK (not on this
+// package's Server), so the client is tested against an independent implementation.
+type fakeRemote struct {
+	srv         *httptest.Server
+	mu          sync.Mutex
+	headers     []http.Header
+	cancels     atomic.Int32
+	execute     func(ctx context.Context, ec *a2asrv.ExecutorContext, yield func(a2a.Event, error) bool)
+	cardPath    bool
+	interface_  []*a2a.AgentInterface
+	requireAuth string
+}
+
+// remoteUser makes every caller the same authenticated user: the upstream in-memory task store
+// (and so ListTasks) needs one.
+type remoteUser struct {
+	a2asrv.PassthroughCallInterceptor
+}
+
+func (remoteUser) Before(ctx context.Context, cc *a2asrv.CallContext, _ *a2asrv.Request) (context.Context, any, error) {
+	cc.User = a2asrv.NewAuthenticatedUser("fake-user", nil)
+	return ctx, nil, nil
+}
+
+type remoteExec struct{ r *fakeRemote }
+
+func (e remoteExec) Execute(ctx context.Context, ec *a2asrv.ExecutorContext) iter.Seq2[a2a.Event, error] {
+	return func(yield func(a2a.Event, error) bool) { e.r.execute(ctx, ec, yield) }
+}
+
+func (e remoteExec) Cancel(ctx context.Context, ec *a2asrv.ExecutorContext) iter.Seq2[a2a.Event, error] {
+	e.r.cancels.Add(1)
+	return func(yield func(a2a.Event, error) bool) {
+		yield(a2a.NewStatusUpdateEvent(ec, a2a.TaskStateCanceled, nil), nil)
+	}
+}
+
+func completeWith(text string) func(context.Context, *a2asrv.ExecutorContext, func(a2a.Event, error) bool) {
+	return func(ctx context.Context, ec *a2asrv.ExecutorContext, yield func(a2a.Event, error) bool) {
+		if ec.StoredTask == nil && !yield(a2a.NewSubmittedTask(ec, ec.Message), nil) {
+			return
+		}
+		if !yield(a2a.NewStatusUpdateEvent(ec, a2a.TaskStateWorking, nil), nil) {
+			return
+		}
+		if !yield(a2a.NewArtifactEvent(ec, a2a.NewTextPart(text)), nil) {
+			return
+		}
+		yield(a2a.NewStatusUpdateEvent(ec, a2a.TaskStateCompleted, nil), nil)
+	}
+}
+
+func newFakeRemote(t *testing.T) *fakeRemote {
+	t.Helper()
+	r := &fakeRemote{execute: completeWith("remote says hi")}
+	handler := a2asrv.NewHandler(remoteExec{r}, a2asrv.WithCallInterceptors(remoteUser{}))
+	mux := http.NewServeMux()
+	mux.Handle("/rpc", a2asrv.NewJSONRPCHandler(handler))
+	mux.HandleFunc(a2asrv.WellKnownAgentCardPath, func(w http.ResponseWriter, req *http.Request) {
+		card := &a2a.AgentCard{
+			Name: "fake-remote", Description: "a fake remote agent", Version: "9",
+			SupportedInterfaces: r.interface_, DefaultInputModes: []string{"text/plain"}, DefaultOutputModes: []string{"text/plain"},
+			Skills:       []a2a.AgentSkill{{ID: "chat", Name: "Chat", Description: "chats", Tags: []string{"chat"}}},
+			Capabilities: a2a.AgentCapabilities{Streaming: true},
+		}
+		a2asrv.NewStaticAgentCardHandler(card).ServeHTTP(w, req)
+	})
+	r.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		r.mu.Lock()
+		r.headers = append(r.headers, req.Header.Clone())
+		r.mu.Unlock()
+		if r.requireAuth != "" && req.URL.Path == "/rpc" && req.Header.Get("Authorization") != "Bearer "+r.requireAuth {
+			w.Header().Set("WWW-Authenticate", "Bearer")
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+		mux.ServeHTTP(w, req)
+	}))
+	r.interface_ = []*a2a.AgentInterface{a2a.NewAgentInterface(r.srv.URL+"/rpc", a2a.TransportProtocolJSONRPC)}
+	t.Cleanup(r.srv.Close)
+	return r
+}
+
+func (r *fakeRemote) lastRPCHeader() http.Header {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for i := len(r.headers) - 1; i >= 0; i-- {
+		if r.headers[i].Get("Content-Type") != "" && strings.Contains(r.headers[i].Get("Content-Type"), "json") && r.headers[i].Get("A2A-Version") != "" {
+			return r.headers[i]
+		}
+	}
+	return nil
+}
+
+func remotes(t *testing.T, r *fakeRemote, extra func(*RemoteAgent), env map[string]string) *Remotes {
+	t.Helper()
+	ra := RemoteAgent{URL: r.srv.URL}
+	if extra != nil {
+		extra(&ra)
+	}
+	return NewRemotes(map[string]RemoteAgent{"peer": ra}, envFrom(env))
+}
+
+func TestRemotesNamesAreSorted(t *testing.T) {
+	rs := NewRemotes(map[string]RemoteAgent{"b": {URL: "http://b"}, "a": {URL: "http://a"}}, envFrom(nil))
+	if got := strings.Join(rs.Names(), ","); got != "a,b" {
+		t.Fatalf("names %q", got)
+	}
+}
+
+func TestCardResolvesAndSummarises(t *testing.T) {
+	r := newFakeRemote(t)
+	card, err := remotes(t, r, nil, nil).Card(context.Background(), "peer")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if card.Name != "fake-remote" || len(card.Skills) != 1 {
+		t.Fatalf("%+v", card)
+	}
+}
+
+func TestSendReturnsCompletedTaskText(t *testing.T) {
+	r := newFakeRemote(t)
+	var progress []string
+	sum, err := remotes(t, r, nil, nil).Send(context.Background(), SendArgs{Agent: "peer", Message: "hello"}, func(s string) { progress = append(progress, s) })
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sum.State != "completed" || !sum.Terminal || sum.Text != "remote says hi" || sum.TaskID == "" || sum.ContextID == "" {
+		t.Fatalf("%+v", sum)
+	}
+	if strings.Join(progress, "") != "remote says hi" {
+		t.Fatalf("progress %q", progress)
+	}
+}
+
+func TestSendReusesContextAndSendsProtocolVersion(t *testing.T) {
+	r := newFakeRemote(t)
+	var seen atomic.Value
+	r.execute = func(ctx context.Context, ec *a2asrv.ExecutorContext, yield func(a2a.Event, error) bool) {
+		seen.Store(ec.ContextID)
+		completeWith("ok")(ctx, ec, yield)
+	}
+	rs := remotes(t, r, nil, nil)
+	if _, err := rs.Send(context.Background(), SendArgs{Agent: "peer", Message: "hello", ContextID: "ctx-77"}, nil); err != nil {
+		t.Fatal(err)
+	}
+	if seen.Load() != "ctx-77" {
+		t.Fatalf("remote saw context %v", seen.Load())
+	}
+	if v := r.lastRPCHeader().Get("A2A-Version"); v != "1.0" {
+		t.Fatalf("A2A-Version %q: the protocol version is pinned to 1.0", v)
+	}
+}
+
+func TestBearerAndCustomHeadersComeFromEnvironment(t *testing.T) {
+	r := newFakeRemote(t)
+	r.requireAuth = "remote-secret-value"
+	rs := remotes(t, r, func(ra *RemoteAgent) {
+		ra.BearerTokenEnv = "REMOTE_TOKEN"
+		ra.HeaderEnv = map[string]string{"X-Api-Key": "REMOTE_KEY"}
+	}, map[string]string{"REMOTE_TOKEN": "remote-secret-value", "REMOTE_KEY": "key-123"})
+	if _, err := rs.Send(context.Background(), SendArgs{Agent: "peer", Message: "hello"}, nil); err != nil {
+		t.Fatal(err)
+	}
+	if got := r.lastRPCHeader().Get("X-Api-Key"); got != "key-123" {
+		t.Fatalf("custom header %q", got)
+	}
+}
+
+func TestMissingTokenEnvironmentIsAnErrorBeforeAnyRequest(t *testing.T) {
+	r := newFakeRemote(t)
+	rs := remotes(t, r, func(ra *RemoteAgent) { ra.BearerTokenEnv = "REMOTE_TOKEN" }, nil)
+	_, err := rs.Send(context.Background(), SendArgs{Agent: "peer", Message: "hello"}, nil)
+	if err == nil || !strings.Contains(err.Error(), "REMOTE_TOKEN") {
+		t.Fatalf("want an error naming the variable: %v", err)
+	}
+	r.mu.Lock()
+	n := len(r.headers)
+	r.mu.Unlock()
+	if n != 0 {
+		t.Fatalf("%d requests were sent without credentials", n)
+	}
+}
+
+func TestRemoteAuthFailureDoesNotEchoTheToken(t *testing.T) {
+	r := newFakeRemote(t)
+	r.requireAuth = "the-right-one"
+	rs := remotes(t, r, func(ra *RemoteAgent) { ra.BearerTokenEnv = "REMOTE_TOKEN" }, map[string]string{"REMOTE_TOKEN": "wrong-secret-token"})
+	_, err := rs.Send(context.Background(), SendArgs{Agent: "peer", Message: "hello"}, nil)
+	if err == nil {
+		t.Fatal("want an error")
+	}
+	if strings.Contains(err.Error(), "wrong-secret-token") || strings.Contains(err.Error(), "the-right-one") {
+		t.Fatalf("token in error: %v", err)
+	}
+}
+
+func TestCardWithoutAProtocol10InterfaceIsRefused(t *testing.T) {
+	r := newFakeRemote(t)
+	old := a2a.NewAgentInterface(r.srv.URL+"/rpc", a2a.TransportProtocolJSONRPC)
+	old.ProtocolVersion = "0.3"
+	r.interface_ = []*a2a.AgentInterface{old}
+	_, err := remotes(t, r, nil, nil).Send(context.Background(), SendArgs{Agent: "peer", Message: "hello"}, nil)
+	if err == nil || !strings.Contains(err.Error(), "1.0") {
+		t.Fatalf("want an error naming the pinned version: %v", err)
+	}
+}
+
+func TestSkipCardUsesTheEndpointDirectly(t *testing.T) {
+	r := newFakeRemote(t)
+	r.interface_ = nil // the card is unusable, like kagent's in-cluster URL seen from outside
+	rs := remotes(t, r, func(ra *RemoteAgent) { ra.URL, ra.SkipCard = r.srv.URL+"/rpc", true }, nil)
+	sum, err := rs.Send(context.Background(), SendArgs{Agent: "peer", Message: "hello"}, nil)
+	if err != nil || sum.State != "completed" {
+		t.Fatalf("%+v %v", sum, err)
+	}
+}
+
+func TestUnknownAgentNamesTheKnownOnes(t *testing.T) {
+	r := newFakeRemote(t)
+	_, err := remotes(t, r, nil, nil).Send(context.Background(), SendArgs{Agent: "nope", Message: "hello"}, nil)
+	if err == nil || !strings.Contains(err.Error(), "peer") {
+		t.Fatalf("%v", err)
+	}
+}
+
+func TestFailedAndInputRequiredStates(t *testing.T) {
+	r := newFakeRemote(t)
+	r.execute = func(ctx context.Context, ec *a2asrv.ExecutorContext, yield func(a2a.Event, error) bool) {
+		yield(a2a.NewSubmittedTask(ec, ec.Message), nil)
+		msg := a2a.NewMessageForTask(a2a.MessageRoleAgent, ec, a2a.NewTextPart("which file?"))
+		yield(a2a.NewStatusUpdateEvent(ec, a2a.TaskStateInputRequired, msg), nil)
+	}
+	sum, err := remotes(t, r, nil, nil).Send(context.Background(), SendArgs{Agent: "peer", Message: "do it"}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sum.State != "input-required" || sum.Terminal || sum.Text != "which file?" {
+		t.Fatalf("%+v", sum)
+	}
+	r.execute = func(ctx context.Context, ec *a2asrv.ExecutorContext, yield func(a2a.Event, error) bool) {
+		yield(a2a.NewSubmittedTask(ec, ec.Message), nil)
+		yield(a2a.NewStatusUpdateEvent(ec, a2a.TaskStateFailed, a2a.NewMessageForTask(a2a.MessageRoleAgent, ec, a2a.NewTextPart("it broke"))), nil)
+	}
+	sum, err = remotes(t, r, nil, nil).Send(context.Background(), SendArgs{Agent: "peer", Message: "do it"}, nil)
+	if err != nil || sum.State != "failed" || !sum.Terminal || sum.Text != "it broke" {
+		t.Fatalf("%+v %v", sum, err)
+	}
+}
+
+func TestCancellingTheCallCancelsTheRemoteTask(t *testing.T) {
+	r := newFakeRemote(t)
+	r.execute = func(ctx context.Context, ec *a2asrv.ExecutorContext, yield func(a2a.Event, error) bool) {
+		if !yield(a2a.NewSubmittedTask(ec, ec.Message), nil) {
+			return
+		}
+		yield(a2a.NewStatusUpdateEvent(ec, a2a.TaskStateWorking, nil), nil)
+		yield(a2a.NewArtifactEvent(ec, a2a.NewTextPart("partial")), nil)
+		<-ctx.Done()
+	}
+	rs := remotes(t, r, nil, nil)
+	ctx, cancel := context.WithCancel(context.Background())
+	got := make(chan struct{})
+	var once sync.Once
+	errc := make(chan error, 1)
+	go func() {
+		_, err := rs.Send(ctx, SendArgs{Agent: "peer", Message: "long job"}, func(string) { once.Do(func() { close(got) }) })
+		errc <- err
+	}()
+	waitChan(t, got, "the first streamed chunk")
+	cancel()
+	select {
+	case err := <-errc:
+		if !errors.Is(err, context.Canceled) {
+			t.Fatalf("want context.Canceled, got %v", err)
+		}
+	case <-time.After(10 * time.Second):
+		t.Fatal("Send did not return")
+	}
+	waitFor(t, func() bool { return r.cancels.Load() == 1 }, "the remote CancelTask call")
+}
+
+func TestGetAndCancelTask(t *testing.T) {
+	r := newFakeRemote(t)
+	rs := remotes(t, r, nil, nil)
+	sum, err := rs.Send(context.Background(), SendArgs{Agent: "peer", Message: "hello"}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got, err := rs.GetTask(context.Background(), "peer", sum.TaskID)
+	if err != nil || got.State != "completed" || got.Text != "remote says hi" {
+		t.Fatalf("%+v %v", got, err)
+	}
+	r.execute = func(ctx context.Context, ec *a2asrv.ExecutorContext, yield func(a2a.Event, error) bool) {
+		yield(a2a.NewSubmittedTask(ec, ec.Message), nil)
+		yield(a2a.NewStatusUpdateEvent(ec, a2a.TaskStateWorking, nil), nil)
+		<-ctx.Done()
+	}
+	// A task that is still running can be cancelled by id.
+	idc := make(chan string, 1)
+	go func() {
+		_, _ = rs.Send(context.Background(), SendArgs{Agent: "peer", Message: "again"}, func(string) {})
+	}()
+	go func() {
+		for i := 0; i < 500; i++ {
+			list, err := rs.list(context.Background(), "peer")
+			if err == nil && len(list) > 0 {
+				for _, s := range list {
+					if s.State == "working" {
+						idc <- s.TaskID
+						return
+					}
+				}
+			}
+			time.Sleep(10 * time.Millisecond)
+		}
+	}()
+	var id string
+	select {
+	case id = <-idc:
+	case <-time.After(10 * time.Second):
+		t.Fatal("no working task")
+	}
+	c, err := rs.CancelTask(context.Background(), "peer", id)
+	if err != nil || c.State != "canceled" {
+		t.Fatalf("%+v %v", c, err)
+	}
+}
+
+func TestSendHonoursTheConfiguredTimeout(t *testing.T) {
+	r := newFakeRemote(t)
+	r.execute = func(ctx context.Context, ec *a2asrv.ExecutorContext, yield func(a2a.Event, error) bool) {
+		yield(a2a.NewSubmittedTask(ec, ec.Message), nil)
+		<-ctx.Done()
+	}
+	rs := remotes(t, r, func(ra *RemoteAgent) { ra.TimeoutSeconds = 1 }, nil)
+	start := time.Now()
+	_, err := rs.Send(context.Background(), SendArgs{Agent: "peer", Message: "hang"}, nil)
+	if err == nil || time.Since(start) > 8*time.Second {
+		t.Fatalf("err %v after %v", err, time.Since(start))
+	}
+}
+
+func TestCredentialsAreNotSentToAHostTheCardNamed(t *testing.T) {
+	evil := newFakeRemote(t) // stands in for an attacker's server named in an untrusted card
+	honest := newFakeRemote(t)
+	honest.interface_ = []*a2a.AgentInterface{a2a.NewAgentInterface(evil.srv.URL+"/rpc", a2a.TransportProtocolJSONRPC)}
+	rs := remotes(t, honest, func(ra *RemoteAgent) { ra.BearerTokenEnv = "REMOTE_TOKEN" }, map[string]string{"REMOTE_TOKEN": "remote-secret-value"})
+	_, err := rs.Send(context.Background(), SendArgs{Agent: "peer", Message: "hello"}, nil)
+	if err == nil || !strings.Contains(err.Error(), "skipCard") {
+		t.Fatalf("want an error that points at skipCard: %v", err)
+	}
+	evil.mu.Lock()
+	n := len(evil.headers)
+	evil.mu.Unlock()
+	if n != 0 {
+		t.Fatalf("%d requests reached the host the card named, with credentials configured", n)
+	}
+}
+
+func TestSendToATerminalTaskStillReportsItsState(t *testing.T) {
+	r := newFakeRemote(t)
+	rs := remotes(t, r, nil, nil)
+	first, err := rs.Send(context.Background(), SendArgs{Agent: "peer", Message: "one"}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// A2A refuses a message for a task that is already terminal; the tool must surface that, not hide it.
+	_, err = rs.Send(context.Background(), SendArgs{Agent: "peer", Message: "two", TaskID: first.TaskID, ContextID: first.ContextID}, nil)
+	if err == nil {
+		t.Fatal("want the remote's refusal")
+	}
+}
+
+func TestRemotesNamesAreSortedForManyNames(t *testing.T) { // names-unsorted: two names can pass by luck
+	cfg := map[string]RemoteAgent{}
+	for _, n := range []string{"f", "c", "a", "e", "b", "d", "h", "g"} {
+		cfg[n] = RemoteAgent{URL: "http://" + n}
+	}
+	if got := strings.Join(NewRemotes(cfg, envFrom(nil)).Names(), ""); got != "abcdefgh" {
+		t.Fatalf("names %q", got)
+	}
+}

package/extensions/a2a/config.go

@@ -0,0 +1,282 @@
+package a2aext
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net"
+	"net/url"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+// Config is the a2a extension's configuration. The listener is off unless Listen is set.
+//
+// Secrets are never stored here: tokens and remote credentials are named by the
+// environment variable that holds them.
+type Config struct {
+	// Listen is the address of the A2A server ("127.0.0.1:8787"). Empty means off.
+	Listen string `json:"listen"`
+	// ExternalURL is the base URL peers reach the listener at (behind a proxy). Default: derived from Listen.
+	ExternalURL string `json:"externalUrl"`
+	Name        string `json:"name"`
+	Description string `json:"description"`
+	// StateDir holds per-principal PiG session files. Default: <config home>/a2a.
+	StateDir string `json:"stateDir"`
+	// InsecureNoAuth serves without tokens; only allowed on a loopback address.
+	InsecureNoAuth     bool                   `json:"insecureNoAuth"`
+	Tokens             []TokenConfig          `json:"tokens"`
+	TLS                *TLSConfig             `json:"tls"`
+	Worker             WorkerConfig           `json:"worker"`
+	MaxConcurrentTasks int                    `json:"maxConcurrentTasks"`
+	TaskTimeoutSeconds int                    `json:"taskTimeoutSeconds"`
+	Remotes            map[string]RemoteAgent `json:"remotes"`
+}
+
+// TokenConfig names a bearer token by the environment variable that holds it.
+type TokenConfig struct {
+	// Name identifies the caller in logs and in task ownership.
+	Name string `json:"name"`
+	// TokenEnv is the environment variable holding the token (at least 16 characters).
+	TokenEnv string `json:"tokenEnv"`
+	// Tenant, when set, is the tenant boundary this token belongs to. Tokens of one tenant share tasks and contexts.
+	Tenant string `json:"tenant"`
+}
+
+// TLSConfig holds certificate file paths for the listener.
+type TLSConfig struct {
+	CertFile string `json:"certFile"`
+	KeyFile  string `json:"keyFile"`
+}
+
+// WorkerConfig says how a task turn runs PiG.
+type WorkerConfig struct {
+	// Command is the pig executable. Default: $PIG_A2A_PIG, then "pig" on PATH.
+	Command string `json:"command"`
+	// Args are extra arguments appended to the fixed ones.
+	Args []string `json:"args"`
+	// Cwd is the worker's working directory. Default: the session's directory.
+	Cwd string `json:"cwd"`
+	// Tools is the tool allowlist. Default: none (pig --no-tools). PiG's file tools take absolute paths, so any
+	// tool named here reaches every file the account can, not only Cwd.
+	Tools    []string `json:"tools"`
+	Provider string   `json:"provider"`
+	Model    string   `json:"model"`
+	// PassEnv names extra environment variables to hand to the worker (for example a provider API key).
+	PassEnv      []string `json:"passEnv"`
+	GraceSeconds int      `json:"graceSeconds"`
+}
+
+// RemoteAgent is an A2A agent this extension can call.
+type RemoteAgent struct {
+	URL string `json:"url"`
+	// BearerTokenEnv names the environment variable holding a bearer token.
+	BearerTokenEnv string `json:"bearerTokenEnv"`
+	// HeaderEnv maps a header name to the environment variable holding its value.
+	HeaderEnv map[string]string `json:"headerEnv"`
+	// SkipCard uses URL as the JSON-RPC endpoint without fetching the agent card (kagent's card URL is in-cluster).
+	SkipCard       bool `json:"skipCard"`
+	TimeoutSeconds int  `json:"timeoutSeconds"`
+}
+
+// LoadOptions are the inputs of LoadConfig.
+type LoadOptions struct {
+	ConfigHome string
+	Getenv     func(string) string
+	FlagListen string
+}
+
+const (
+	defaultMaxConcurrent = 4
+	defaultTaskTimeout   = 900
+	defaultRemoteTimeout = 300
+	defaultGraceSeconds  = 5
+	minTokenLength       = 16
+)
+
+var (
+	identRE  = regexp.MustCompile(`^[A-Za-z0-9._-]{1,64}$`)
+	envRE    = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
+	headerRE = regexp.MustCompile("^[!#$%&'*+.^_`|~0-9A-Za-z-]+$")
+)
+
+// Enabled reports whether the listener is configured.
+func (c Config) Enabled() bool { return c.Listen != "" }
+
+// LoadConfig reads the configuration file, then the environment and the flag
+// (flag over environment over file). It validates the result.
+//
+// Environment: PIG_A2A_CONFIG (file path), PIG_A2A_LISTEN, PIG_A2A_WORKER=1
+// (set on worker children, which never listen).
+func LoadConfig(o LoadOptions) (Config, error) {
+	getenv := o.Getenv
+	if getenv == nil {
+		getenv = os.Getenv
+	}
+	path, explicit := getenv("PIG_A2A_CONFIG"), true
+	if path == "" {
+		explicit = false
+		if o.ConfigHome != "" {
+			path = filepath.Join(o.ConfigHome, "a2a.json")
+		}
+	}
+	var cfg Config
+	if path != "" {
+		raw, err := os.ReadFile(path)
+		switch {
+		case err == nil:
+			dec := json.NewDecoder(bytes.NewReader(raw))
+			dec.DisallowUnknownFields()
+			if err := dec.Decode(&cfg); err != nil {
+				return Config{}, fmt.Errorf("a2a: %s: %w (secrets belong in environment variables named by tokenEnv, bearerTokenEnv or headerEnv)", path, err)
+			}
+		case errors.Is(err, os.ErrNotExist) && !explicit:
+		default:
+			return Config{}, fmt.Errorf("a2a: read %s: %w", path, err)
+		}
+	}
+	if v := getenv("PIG_A2A_LISTEN"); v != "" {
+		cfg.Listen = v
+	}
+	if o.FlagListen != "" {
+		cfg.Listen = o.FlagListen
+	}
+	if getenv("PIG_A2A_WORKER") == "1" {
+		// A worker child is a PiG the server started for one task; it must not start a second server.
+		cfg.Listen = ""
+	}
+	if cfg.StateDir == "" && o.ConfigHome != "" {
+		cfg.StateDir = filepath.Join(o.ConfigHome, "a2a")
+	}
+	cfg.applyDefaults()
+	if err := cfg.validate(getenv); err != nil {
+		return Config{}, err
+	}
+	return cfg, nil
+}
+
+func (c *Config) applyDefaults() {
+	if c.Name == "" {
+		c.Name = "PiG"
+	}
+	if c.Description == "" {
+		c.Description = "A PiG coding agent serving tasks over A2A."
+	}
+	if c.MaxConcurrentTasks <= 0 {
+		c.MaxConcurrentTasks = defaultMaxConcurrent
+	}
+	if c.TaskTimeoutSeconds <= 0 {
+		c.TaskTimeoutSeconds = defaultTaskTimeout
+	}
+	if c.Worker.GraceSeconds <= 0 {
+		c.Worker.GraceSeconds = defaultGraceSeconds
+	}
+	for name, r := range c.Remotes {
+		if r.TimeoutSeconds <= 0 {
+			r.TimeoutSeconds = defaultRemoteTimeout
+		}
+		c.Remotes[name] = r
+	}
+}
+
+// Validate checks the configuration without reading the environment for secrets.
+func (c Config) Validate() error { return c.validate(func(string) string { return "" }) }
+
+func isLoopbackHost(host string) bool {
+	if strings.EqualFold(host, "localhost") {
+		return true
+	}
+	ip := net.ParseIP(host)
+	return ip != nil && ip.IsLoopback()
+}
+
+func (c Config) validate(getenv func(string) string) error {
+	if c.Listen != "" {
+		host, port, err := net.SplitHostPort(c.Listen)
+		if err != nil {
+			return fmt.Errorf("a2a: listen %q is not host:port: %w", c.Listen, err)
+		}
+		if n, err := strconv.Atoi(port); err != nil || n < 0 || n > 65535 {
+			return fmt.Errorf("a2a: listen port %q is not a port number", port)
+		}
+		switch {
+		case c.InsecureNoAuth && len(c.Tokens) > 0:
+			return errors.New("a2a: insecureNoAuth and tokens are both set; remove one")
+		case c.InsecureNoAuth && !isLoopbackHost(host):
+			return fmt.Errorf("a2a: insecureNoAuth is only allowed on a loopback address, not %q", host)
+		case !c.InsecureNoAuth && len(c.Tokens) == 0:
+			return errors.New("a2a: a listener needs at least one entry in tokens (or insecureNoAuth on a loopback address)")
+		}
+		if err := c.validateTokens(getenv); err != nil {
+			return err
+		}
+		if c.TLS != nil && (c.TLS.CertFile == "" || c.TLS.KeyFile == "") {
+			return errors.New("a2a: tls needs both certFile and keyFile")
+		}
+		if c.ExternalURL != "" {
+			if err := checkHTTPURL(c.ExternalURL); err != nil {
+				return fmt.Errorf("a2a: externalUrl: %w", err)
+			}
+		}
+	}
+	for name, r := range c.Remotes {
+		if !identRE.MatchString(name) {
+			return fmt.Errorf("a2a: remote name %q must match %s", name, identRE)
+		}
+		if err := checkHTTPURL(r.URL); err != nil {
+			return fmt.Errorf("a2a: remote %q: %w", name, err)
+		}
+		if r.BearerTokenEnv != "" && !envRE.MatchString(r.BearerTokenEnv) {
+			return fmt.Errorf("a2a: remote %q: bearerTokenEnv %q is not an environment variable name", name, r.BearerTokenEnv)
+		}
+		for header, env := range r.HeaderEnv {
+			if !headerRE.MatchString(header) || !envRE.MatchString(env) {
+				return fmt.Errorf("a2a: remote %q: headerEnv entry %q: %q is not a valid header name or variable name", name, header, env)
+			}
+		}
+	}
+	return nil
+}
+
+func (c Config) validateTokens(getenv func(string) string) error {
+	names, envs, values := map[string]bool{}, map[string]bool{}, map[string]bool{}
+	for i, t := range c.Tokens {
+		if !identRE.MatchString(t.Name) {
+			return fmt.Errorf("a2a: tokens[%d].name %q must match %s", i, t.Name, identRE)
+		}
+		if t.Tenant != "" && !identRE.MatchString(t.Tenant) {
+			return fmt.Errorf("a2a: tokens[%d].tenant %q must match %s", i, t.Tenant, identRE)
+		}
+		if !envRE.MatchString(t.TokenEnv) {
+			return fmt.Errorf("a2a: tokens[%d].tokenEnv %q is not an environment variable name", i, t.TokenEnv)
+		}
+		if names[t.Name] || envs[t.TokenEnv] {
+			return fmt.Errorf("a2a: tokens[%d]: name %q or variable %s is used twice", i, t.Name, t.TokenEnv)
+		}
+		names[t.Name], envs[t.TokenEnv] = true, true
+		v := getenv(t.TokenEnv)
+		if v == "" {
+			return fmt.Errorf("a2a: token %q: environment variable %s is not set", t.Name, t.TokenEnv)
+		}
+		if len(v) < minTokenLength {
+			return fmt.Errorf("a2a: token %q (%s) is shorter than %d characters", t.Name, t.TokenEnv, minTokenLength)
+		}
+		if values[v] {
+			return fmt.Errorf("a2a: token %q has the same value as another token", t.Name)
+		}
+		values[v] = true
+	}
+	return nil
+}
+
+func checkHTTPURL(raw string) error {
+	u, err := url.Parse(raw)
+	if err != nil || u.Host == "" || (u.Scheme != "http" && u.Scheme != "https") {
+		return fmt.Errorf("%q must be an http or https URL", raw)
+	}
+	return nil
+}