@pi-in-go/pigpen-a2a 0.1.0

package/extensions/a2a/worker_test.go

@@ -0,0 +1,257 @@
+package a2aext
+
+import (
+	"context"
+	"path/filepath"
+	"regexp"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+)
+
+var alice = Principal{Name: "alice", Tenant: "team-a"}
+
+func newTestWorker(t *testing.T) (*ProcessWorker, string, string) {
+	t.Helper()
+	cfg, logPath, getenv := fakeWorkerConfig(t)
+	state := t.TempDir()
+	w, err := NewProcessWorker(cfg, state, getenv)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return w, logPath, state
+}
+
+func TestSessionIDIsStableScopedAndSafe(t *testing.T) {
+	hex := regexp.MustCompile(`^[0-9a-f]{32,64}$`)
+	a := SessionID(alice, "ctx-1")
+	if !hex.MatchString(a) {
+		t.Fatalf("session id %q must be lowercase hex", a)
+	}
+	if a != SessionID(alice, "ctx-1") {
+		t.Fatal("the same context must map to the same session")
+	}
+	if a == SessionID(alice, "ctx-2") {
+		t.Fatal("different contexts must not share a session")
+	}
+	if a == SessionID(Principal{Name: "mallory", Tenant: "team-b"}, "ctx-1") {
+		t.Fatal("the same context id under another tenant must not share a session")
+	}
+	if id := SessionID(alice, "../../etc/passwd"); !hex.MatchString(id) {
+		t.Fatalf("a hostile context id must not reach the file name: %q", id)
+	}
+}
+
+func TestWorkerPassesFlagsSessionAndCwd(t *testing.T) {
+	w, logPath, state := newTestWorker(t)
+	res, err := w.Run(context.Background(), Turn{Principal: alice, ContextID: "c1", TaskID: "t1", Prompt: "hello there"}, func(Update) {})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Text != "echo: hello there" || res.Failure != "" {
+		t.Fatalf("result %+v", res)
+	}
+	l := readFakeLog(t, logPath)
+	for _, want := range []string{"--mode", "rpc", "--no-extensions", "--no-skills", "--no-context-files", "--no-prompt-templates", "--offline"} {
+		if !contains(l.Args, want) {
+			t.Errorf("argv lacks %s: %v", want, l.Args)
+		}
+	}
+	if contains(l.Args, "--no-session") {
+		t.Error("contexts continue across tasks, so the session must be kept")
+	}
+	if got := argValue(l.Args, "--tools"); got != "read,grep,find,ls" {
+		t.Errorf("--tools = %q", got)
+	}
+	if got := argValue(l.Args, "--session-id"); got != SessionID(alice, "c1") {
+		t.Errorf("--session-id = %q", got)
+	}
+	dir := argValue(l.Args, "--session-dir")
+	if !strings.HasPrefix(dir, state) || dir == state {
+		t.Errorf("--session-dir %q must be a per-principal directory under %q", dir, state)
+	}
+	if other := w.sessionDir(Principal{Name: "bob"}); other == dir {
+		t.Error("principals must not share a session directory")
+	}
+	if l.Prompt != "hello there" {
+		t.Errorf("prompt = %q", l.Prompt)
+	}
+	// The child reports the directory the OS resolved (macOS's TMPDIR is a symlink: /var -> /private/var).
+	if got, want := realPath(t, l.Cwd), realPath(t, w.cfg.Cwd); got != want {
+		t.Errorf("cwd = %q (%q), want %q (%q)", l.Cwd, got, w.cfg.Cwd, want)
+	}
+}
+
+// realPath is p with symlinks resolved, so two spellings of one directory compare equal.
+func realPath(t *testing.T, p string) string {
+	t.Helper()
+	r, err := filepath.EvalSymlinks(p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return r
+}
+
+func TestWorkerModelAndExtraArgs(t *testing.T) {
+	cfg, logPath, getenv := fakeWorkerConfig(t)
+	cfg.Provider, cfg.Model, cfg.Args = "p", "m", []string{"--thinking", "off"}
+	w, err := NewProcessWorker(cfg, t.TempDir(), getenv)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := w.Run(context.Background(), Turn{Principal: alice, ContextID: "c", Prompt: "x y"}, func(Update) {}); err != nil {
+		t.Fatal(err)
+	}
+	l := readFakeLog(t, logPath)
+	if argValue(l.Args, "--provider") != "p" || argValue(l.Args, "--model") != "m" || argValue(l.Args, "--thinking") != "off" {
+		t.Fatalf("argv %v", l.Args)
+	}
+}
+
+func TestWorkerEnvironmentIsAllowlisted(t *testing.T) {
+	w, logPath, _ := newTestWorker(t)
+	if _, err := w.Run(context.Background(), Turn{Principal: alice, ContextID: "c", Prompt: "ab"}, func(Update) {}); err != nil {
+		t.Fatal(err)
+	}
+	env := readFakeLog(t, logPath).Env
+	if env["PIG_A2A_WORKER"] != "1" {
+		t.Error("the child must be marked as a worker so it never opens a listener")
+	}
+	if env["OPENAI_API_KEY"] != "sk-passthrough" || env["PIG_HOME"] != "/pig/home" || env["PIG_CODING_AGENT_DIR"] != "/pig/agent" {
+		t.Errorf("configured passthrough and PiG's config directories must reach the child: %v", env)
+	}
+	for _, leak := range []string{"TOKEN_A", "SOMETHING_SECRET"} {
+		if _, ok := env[leak]; ok {
+			t.Errorf("%s leaked into the worker environment", leak)
+		}
+	}
+}
+
+func TestWorkerStreamsUpdatesAndFinalText(t *testing.T) {
+	w, _, _ := newTestWorker(t)
+	var text strings.Builder
+	var tools []string
+	res, err := w.Run(context.Background(), Turn{Principal: alice, ContextID: "c", Prompt: "TOOL please"}, func(u Update) {
+		text.WriteString(u.Text)
+		if u.Tool != "" {
+			tools = append(tools, u.Tool)
+		}
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Text != "done" || text.String() != "done" || strings.Join(tools, ",") != "read" {
+		t.Fatalf("res %+v streamed %q tools %v", res, text.String(), tools)
+	}
+}
+
+func TestWorkerStreamedTextEqualsFinalTextWithoutDuplication(t *testing.T) {
+	w, _, _ := newTestWorker(t)
+	var text strings.Builder
+	res, err := w.Run(context.Background(), Turn{Principal: alice, ContextID: "c", Prompt: "abcdef"}, func(u Update) { text.WriteString(u.Text) })
+	if err != nil {
+		t.Fatal(err)
+	}
+	if text.String() != res.Text {
+		t.Fatalf("streamed %q, final %q", text.String(), res.Text)
+	}
+}
+
+func TestWorkerModelFailureIsAFailureWithoutProviderDetail(t *testing.T) {
+	w, _, _ := newTestWorker(t)
+	res, err := w.Run(context.Background(), Turn{Principal: alice, ContextID: "c", Prompt: "FAIL now"}, func(Update) {})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Failure == "" {
+		t.Fatal("a model error must fail the task")
+	}
+	if strings.Contains(res.Failure, "sk-123") {
+		t.Fatalf("provider error text can carry secrets; it must not reach the A2A peer: %q", res.Failure)
+	}
+}
+
+func TestWorkerCancelAbortsThenReaps(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("process liveness probe is POSIX")
+	}
+	w, logPath, _ := newTestWorker(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() {
+		_, err := w.Run(ctx, Turn{Principal: alice, ContextID: "c", Prompt: "SLOW task"}, func(Update) {})
+		done <- err
+	}()
+	l := waitFakeLog(t, logPath, func(l fakeLog) bool { return l.Started })
+	cancel()
+	select {
+	case err := <-done:
+		if err == nil {
+			t.Fatal("cancellation must surface as an error")
+		}
+	case <-time.After(10 * time.Second):
+		t.Fatal("Run did not return after cancellation")
+	}
+	if l2 := readFakeLog(t, logPath); !l2.Aborted {
+		t.Error("the worker must send the RPC abort before killing anything")
+	}
+	if processAlive(l.PID) {
+		t.Error("the child process must be reaped")
+	}
+}
+
+func TestWorkerKillsAChildThatIgnoresAbort(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("process liveness probe is POSIX")
+	}
+	w, logPath, _ := newTestWorker(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() {
+		_, err := w.Run(ctx, Turn{Principal: alice, ContextID: "c", Prompt: "IGNORE_ABORT"}, func(Update) {})
+		done <- err
+	}()
+	l := waitFakeLog(t, logPath, func(l fakeLog) bool { return l.Started })
+	cancel()
+	select {
+	case <-done:
+	case <-time.After(15 * time.Second):
+		t.Fatal("a child that ignores abort must be killed after the grace period")
+	}
+	deadline := time.Now().Add(5 * time.Second)
+	for processAlive(l.PID) && time.Now().Before(deadline) {
+		time.Sleep(20 * time.Millisecond)
+	}
+	if processAlive(l.PID) {
+		t.Fatal("child survived")
+	}
+}
+
+func TestWorkerCommandThatCannotStartIsReported(t *testing.T) {
+	cfg, _, getenv := fakeWorkerConfig(t)
+	cfg.Command = "/nonexistent/pig"
+	w, err := NewProcessWorker(cfg, t.TempDir(), getenv)
+	if err != nil {
+		return // refusing at construction is fine too
+	}
+	if _, err := w.Run(context.Background(), Turn{Principal: alice, ContextID: "c", Prompt: "x"}, func(Update) {}); err == nil {
+		t.Fatal("want an error")
+	}
+}
+
+func TestWorkerRefusesEmptyPrompt(t *testing.T) {
+	w, _, _ := newTestWorker(t)
+	if _, err := w.Run(context.Background(), Turn{Principal: alice, ContextID: "c", Prompt: "  "}, func(Update) {}); err == nil {
+		t.Fatal("an empty prompt is not a task")
+	}
+}
+
+func contains(list []string, s string) bool {
+	for _, x := range list {
+		if x == s {
+			return true
+		}
+	}
+	return false
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@pi-in-go/pigpen-a2a",
+  "version": "0.1.0",
+  "description": "A2A (Agent2Agent) for PiG: serve PiG tasks to A2A agents and call remote A2A agents, on the upstream Go SDK a2a-go. The listener is off unless configured.",
+  "keywords": [
+    "pig-package",
+    "a2a",
+    "agent2agent",
+    "protocol",
+    "kagent",
+    "extension",
+    "pigpen"
+  ],
+  "license": "MIT",
+  "author": "Michael Kinsy",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MichaelKinsy/pigpen.git",
+    "directory": "components/a2a"
+  },
+  "homepage": "https://github.com/MichaelKinsy/pigpen/tree/main/components/a2a#readme",
+  "bugs": {
+    "url": "https://github.com/MichaelKinsy/pigpen/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "extensions",
+    "port",
+    "README.md",
+    "LICENSE",
+    "CREDITS.md",
+    "provenance.json"
+  ],
+  "pi": {
+    "extensions": [
+      "extensions/a2a"
+    ]
+  }
+}

package/port/PORT.md

@@ -0,0 +1,126 @@
+# a2a: port record
+
+**Kind of port (Skill, "What kind of port is this?"): 3, new code with no original.** a2a is an *original adapter* on the upstream
+Go SDK [a2a-go](https://github.com/a2aproject/a2a-go) v2.6.0 (commit `ebf17c56ef7e63c72883a45454a538bbc0df66b8`, Apache-2.0). There
+is no TypeScript or Pi original to twin, so there is **no Pi oracle and no equivalence claim**. The golden traces in `golden/` are
+**self-recorded** regression baselines (lane `pig-go-self`): the port was recorded from itself and reviewed by hand, and `pigeq check`
+labels them that way. What replaces the oracle for protocol facts is a2a-go's own contract plus an independent A2A peer (below).
+
+## Identities
+
+| Item | Value |
+|---|---|
+| Package | `components/a2a` (module `github.com/MichaelKinsy/pigpen/a2a`, Go extension `a2a`), Piglet `piglets/a2a` |
+| Upstream SDK | `github.com/a2aproject/a2a-go/v2` **v2.6.0**, A2A protocol **1.0** (JSON-RPC binding), Apache-2.0, `port/a2a-go-LICENSE` |
+| Host | PiG 0.3.0 (commit `63c6ba456`), upstream Pi 0.87.1, go1.27.1 |
+| Interop peer | kagent upstream `main` at `e4516302` (its Go ADK server package `go/adk/pkg/a2a/server`, which pins a2a-go v2.6.0) |
+| Gap check | `pig docs list` / `pig docs show built-in-extensions` in 0.3.0: PiG ships no A2A. The older port map lists A2A remote sessions as "not ported (spec 482)". `pigeq gaps --go`: PASS (`port-gaps`), public SDK only, no process-global calls |
+
+## Gap check against the SDK surface
+
+Everything the extension uses is fully provided by the 0.3.0 Go SDK: `sdk.New`, `RegisterTool`, `RegisterCommand`, `RegisterFlag`,
+`OnEvent("session_start"|"session_shutdown")`, `Context.Notify`, `sdk.NewToolError`. No `PARTIAL` or `MISSING` (`pigeq gaps --go`).
+Fused-extension rule found in `pig docs show extensions`: a fused extension shares PiG's process, so a2a discards the HTTP server's and
+a2a-go's logs (`ErrorLog` and slog to `io.Discard`, `RecentLogs` ring instead) rather than writing to PiG's terminal.
+
+## Contract
+
+Every behaviour is a row; each has a test and, where a mutation applies, a named mutant that the tests kill (`mutations.json`).
+
+| # | Contract | Tests | Mutants |
+|---|---|---|---|
+| C01 | Listener is off unless configured; installing opens no port | `TestListenerIsOffUnlessConfigured`, `TestNoConfigurationOpensNoListener`, scenario `listener-off` | `listener-on-by-default` |
+| C02 | Config: `a2a.json` in the agent dir, `PIG_A2A_CONFIG`, env `PIG_A2A_LISTEN`, flag `--a2a-listen` (flag > env > file); strict JSON | `TestConfigFileEnablesListener`, `TestPrecedenceFlagOverEnvOverFile`, `TestConfigPathFromEnv`, `TestConfigIsReadFromTheAgentDirectory`, `TestFlagOverridesTheConfigurationFile` | precedence, agent-dir, flag mutants |
+| C03 | Secrets are named by env var, never inline; never echoed | `TestInlineSecretsAreRejected`, `TestTokenEnvMustBeSetAndIsNotEchoed`, `TestRemoteAuthFailureDoesNotEchoTheToken` | inline-secret, echo mutants |
+| C04 | A listener needs authentication; `insecureNoAuth` only on loopback; not together with tokens; tokens ≥16 chars, unique names and values | `TestListenerNeedsAuthentication`, `TestInsecureNoAuthOnlyOnLoopback`, `TestTokenConfigValidation`, `TestTwoVariablesWithOneValueAreRejected`, `TestInsecureNoAuthWithTokensIsAmbiguous`, scenario `flag-without-auth-refused` | auth/loopback/duplicate mutants |
+| C05 | Bearer tokens compared by digest, constant time; token in a query string ignored; 401 + `WWW-Authenticate: Bearer`; agent card public | `TestAuthenticateBearer`, `TestAuthenticateRejects`, `TestTokenInQueryStringIsIgnored`, `TestWrapRejectsWith401AndChallenge`, `TestWrapPassesPrincipalAndPublicPaths`, `TestUnauthenticatedRequestIsRejectedBeforeTheWorker` | compare, query, 401 mutants |
+| C06 | Protocol pinned to A2A 1.0: `A2A-Version: 1.0` required (an absent header, which the specification reads as 0.3, is refused), other versions refused, repeated `1.0, 1.0` accepted (kagent's client), `1.0, 0.3` refused | `TestProtocolVersionIsPinned`, `TestMixedVersionHeaderIsRefused`, `TestAgentCardIsPublicAndPinnedToProtocol10` | version mutants |
+| C07 | Agent card: name, Bearer scheme, streaming true, push false, one 1.0 JSON-RPC interface, external URL | `TestAgentCardIsPublicAndPinnedToProtocol10`, `TestAgentCardAdvertisesExternalURL` | card mutants |
+| C08 | Task identity: one message is one task on one worker turn; result is a completed task with the reply as artifact | `TestSendMessageRunsATurnAndReturnsACompletedTask`, `TestE2E_TaskRunsRealPiGWithAToolCall` | `worker-keeps-extensions`, `worker-not-marked`, `tool-updates-dropped` |
+| C09 | Context identity: a `contextId` is a PiG session; the same id continues it, across tasks | `TestSameContextIDContinuesTheSameWorkerContext`, `TestE2E_ContextContinuesAcrossTasksAndTenantsAreIsolated`, `TestSessionIDIsStableScopedAndSafe` | session-id mutants |
+| C10 | Tenant isolation: contexts, tasks and sessions are scoped to the caller's principal; another caller cannot read, attach to or subscribe to a task | `TestTenantsDoNotShareContextsOrTasks`, `TestBobCannotAttachToAliceTaskWithAMessage`, `TestSubscribeToALiveTaskDeliversTheRest`, `TestPrincipalKeysIsolate`, `TestExecutorRefusesAForgedUser` | `principal-not-checked`, key mutants |
+| C11 | A request's tenant must match the token's | `TestRequestTenantMustMatchTheTokensTenant` | `tenant-not-enforced` |
+| C12 | Cancellation aborts the worker (RPC abort, grace, SIGTERM, SIGKILL of the process group), ends `canceled`, reaps the child | `TestCancelTaskAbortsTheWorkerAndEndsCanceled`, `TestWorkerCancelAbortsThenReaps`, `TestWorkerKillsAChildThatIgnoresAbort`, `TestWorkerAsksForTermBeforeKill`, `TestWorkerEscalatesToKillWhenTermIsIgnored`, `TestE2E_CancelAbortsRealPiG` | `no-terminate`, `no-kill-after-grace`, `abort-not-sent`, `cancel-does-not-stop-worker` |
+| C13 | Streaming: artifact chunks arrive before completion; streamed text equals the final text | `TestStreamingDeliversArtifactChunksBeforeCompletion`, `TestWorkerStreamsUpdatesAndFinalText…` | stream mutants |
+| C14 | Failures end `failed` without provider detail sent to the peer | `TestWorkerFailureBecomesAFailedTask`, `TestWorkerErrorDetailIsNotSentToThePeer`, `TestModelFailureMessageIsExactlyGeneric`, `TestWorkerModelFailureIsAFailureWithoutProviderDetail` | `model-error-text-copied` |
+| C15 | Limits: concurrent tasks, one task at a time per context, task timeout, prompt 256 KiB, body 1 MiB | `TestConcurrencyLimitQueuesTasks`, `TestTasksInOneContextRunOneAtATime`, `TestTaskTimeoutFailsTheTask`, `TestOversizedPromptIsRefusedBelowTheBodyLimit`, `TestBodyLimitAppliesEvenWithASmallPrompt`, `TestOversizedRequestBodyIsRefused` | limit mutants |
+| C16 | Only text parts; empty message refused; attachments refused, not dropped | `TestNonTextPartsAreRejected`, `TestEmptyMessageIsRejected`, `TestTextPlusFilePartIsRefusedNotTrimmed` | `file-parts-dropped` |
+| C17 | Worker has no tools by default (`--no-tools`; PiG's file tools take absolute paths, so even `read` reaches every file the account can), configured tools are the allowlist, no extensions, no context files, own session dir, allowlisted env; the worker never opens a listener | `TestWorkerDefaultsHaveNoTools`, `TestReview_WorkerHasNoToolsUnlessConfigured`, `TestE2E_DefaultWorkerCannotReadFilesOutsideItsWorkspace`, `TestWorkerPassesFlagsSessionAndCwd`, `TestWorkerEnvironmentIsAllowlisted`, `TestWorkerProcessDoesNotOpenAListener`, `TestWorkerChildNeverListens` | tool/env mutants |
+| C18 | A turn that needs interactive input or a rejected prompt fails, never hangs | `TestWorkerFailsATurnThatNeedsInteractiveInput`, `TestWorkerReportsARejectedPromptWithoutTheReason` | `ui-request-hangs`, `rejected-prompt-ignored` |
+| C27 | A cancel that arrives before the worker starts (queued behind the concurrency limit, or behind another task of the same context) ends the task `canceled`, never starts a worker, and leaves the task ahead untouched | `TestCancelBeforeTheWorkerStartsBehindTheConcurrencyLimit`, `TestCancelBeforeTheWorkerStartsBehindTheSameContext` | `queued-cancel-ignored-at-slot`, `queued-cancel-ignored-at-context-lock` |
+| C28 | An `insecureNoAuth` listener answers only a loopback `Host` (DNS rebinding); a token listener serves any `Host` (proxies) | `TestReview_InsecureLoopbackListenerRefusesAForeignHostHeader`, `TestReview_TokenListenerServesAnyHostHeader` | `insecure-host-unchecked` |
+| C29 | The per-context lock is per principal (two tenants with one `contextId` do not queue behind each other); a process a turn left behind is killed | `TestReview_SameContextIDInTwoTenantsRunsConcurrently`, `TestReview_WorkerKillsWhatATurnLeftBehind` | `context-lock-shared-across-tenants`, `left-behind-child-survives` |
+| C19 | Shutdown cancels running tasks, waits, and closes the listener; a second start and a busy port are errors; TLS load failure is an error | `TestShutdownCancelsRunningTasksAndStopsListening`, `TestStartFailsOnAnAddressInUse`, `TestSecondStartIsAnError`, `TestShutdownClosesThePortEvenRightAfterStart`, `TestTLSListener`, `TestUnreadableTLSKeyPairFailsStart` | lifecycle mutants |
+| C20 | Client: named remotes, card resolution, direct endpoint (`skipCard`), pinned 1.0 JSON-RPC interface only, `A2A-Version: 1.0` sent | `TestCardResolvesAndSummarises`, `TestSkipCardUsesTheEndpointDirectly`, `TestCardWithoutAProtocol10InterfaceIsRefused`, `TestSendReusesContextAndSendsProtocolVersion` | client mutants |
+| C21 | Client credentials go only to the configured origin, scheme and host (transport check and card pinning, two independent defences; https is never downgraded to http); redirects are not followed | `TestReview_CredentialsAreNotDowngradedToPlainHTTP`, `TestCredentialsAreNotSentToAHostTheCardNamed`, `TestCredentialTransportRefusesAnotherHost`, `TestRemoteRedirectsAreNotFollowed`, `TestInterop_KagentCardHostIsNotTrustedWithCredentials` | `transport-host-not-checked`, `transport-scheme-not-checked`, `card-scheme-downgrade-accepted`, `redirects-followed-with-credentials` |
+| C22 | Client: cancelling the call (or its timeout) cancels the remote task; states failed/input-required reported; terminal task reported | `TestCancellingTheCallCancelsTheRemoteTask`, `TestSendHonoursTheConfiguredTimeout`, `TestFailedAndInputRequiredStates`, `TestSummaryOfAnInputRequiredTaskIsNotTerminal`, `TestSendToATerminalTaskStillReportsItsState`, `TestGetAndCancelTask` | client-cancel mutants |
+| C23 | Tools `a2a_agents`, `a2a_send`, `a2a_task`, command `/a2a`; argument errors name the argument; no remotes says how to configure | `TestRegistersToolsCommandAndLifecycleHandlers`, `TestToolsRejectBadArguments`, `TestToolsWithoutRemotesSayWhy`, `TestSendToolPassesTheContextIDThrough`, `TestStatusListsRemotes`, scenarios `tools-visible-to-model`, `send-missing-message`, `send-without-remotes`, `task-unknown-action` | tool mutants |
+| C24 | Lifecycle: new/resume/fork keep the listener, other reasons stop it; reload re-reads the configuration; invalid config is reported, not fatal | `TestSessionSwitchKeepsTheListenerReloadRestartsIt`, `TestReloadAppliesChangedConfiguration`, `TestToolAfterShutdownUsesTheRewrittenConfiguration`, `TestInvalidConfigurationIsReportedNotFatal`, `TestListenFailureIsReportedToTheUser` | lifecycle mutants |
+| C26 | The Piglet Binary hosts the listener itself: configured, it serves the card publicly, refuses unauthenticated calls, runs a real worker (the same Binary) on a local model, isolates tenants; unconfigured or flag-only it stays off | `TestBinary_*` (3, `PIG_A2A_BINARY`) | (external) |
+| C25 | Interop with kagent's A2A server package (as a remote for PiG) and a kagent-shaped client (a2a-go v2, repeated version header) against PiG's server | `TestInterop_*` (4), `scripts/interop-kagent.mjs` | (external) |
+
+## Named gaps (skipped tests, `gaps_test.go`)
+
+Each is a `t.Skip` with a reason; none is silent. 13 gaps: `TestGap_GRPCTransportBinding`, `TestGap_RESTTransportBinding`, `TestGap_PushNotifications`,
+`TestGap_ProtocolV03Compatibility`, `TestGap_ExtendedAgentCard`, `TestGap_PersistentTaskStore`, `TestGap_InputRequiredFromPiG`,
+`TestGap_FileAndDataParts`, `TestGap_OAuth2AndMutualTLSAuthentication`, `TestGap_SignedAgentCards`, `TestGap_SubscribeToTaskAfterRestart`,
+`TestGap_ClientStreamingProgressToTheModel`, `TestGap_ClientResubscribeTool`. Conditional skips (not gaps), each with a named reason: three kagent tests unless `KAGENT_A2A_ECHO` is set (`scripts/interop-kagent.mjs`), four e2e tests unless `PIG_A2A_E2E_BIN` is set, four Binary tests unless `PIG_A2A_BINARY` is set.
+
+## Deviations from the Skill (recorded, not hidden)
+
+- **Red-green.** RED commit `16ddb5c` (74 tests fail on a signature stub; `red.txt`), then GREEN. Two RED tests were fixed in GREEN because the *test double* was wrong, not
+  the expectation: the fake remote lacked an authenticated user for a2a-go's task store, and one cancel test raced the stream's first event (it now waits for it). Tests were added
+  after the first mutation run (survivors below); they only add assertions.
+- **No twins.** There is no upstream suite; a2a-go's conformance behaviour is exercised through its own client against the server, and the fake remote (an independent
+  `a2asrv` server) against the client.
+- **Golden traces** are self-recorded (`pig-go-self`), six scenarios, hand reviewed.
+
+## Host findings (for the porter and PiG)
+
+- The fake-host template's `Command` sent the wrong request shape (fixed in the porter branch); a tool's own argument check runs, since the host does not validate schemas in the fake.
+- A stale `go.mod` passes workspace tests but fails PiG's packed build (missing `go.sum` entries): always `go mod tidy` with the full source, then build a Binary.
+- kagent's ADK server hard-codes its readiness port `:8081`; kagent's client repeats the `A2A-Version` header (`1.0, 1.0`); a2a-go's in-memory task store lists tasks only for an authenticated user.
+- **a2a-go v2.6.0 defect (reported here, not fixed upstream):** `SubscribeToTask` on a *live* task attaches to the task's event queue without an ownership check
+  (`a2asrv/handler.go`, `execManager.Resubscribe` before `taskStore.Get`), so any authenticated caller who knows a task id can read another tenant's live stream. `GetTask`,
+  `CancelTask` and `ListTasks` are masked. The port owns the task store and checks ownership in its call interceptor (`guard`); `TestSubscribeToALiveTaskDeliversTheRest`
+  and mutant `subscribe-ownership-unchecked` pin it. Found only by writing the roadmap's "stream resubscription" item with a second principal.
+- a2a-go's client ends the event stream with an error on cancel, so a "cancel after clean end" branch would be dead code (removed).
+- `go.work` written by `pigeq` uses `go 1.26`, which is below `go 1.26.0`; needed a local fix.
+- PiG 0.3.0's `read`, `grep`, `find` and `ls` resolve absolute paths and `~` outside the working directory
+  (`internal/codingagent/tools/path_utils.go` `resolveToCwd`), so a tool allowlist is not a file-access boundary. The worker
+  therefore defaults to `--no-tools`; a PiG option that confines file tools to the working directory would let a served
+  worker have read tools safely.
+
+## What PiG 0.4.0 (Pi 0.99.1) will change
+
+Not built or run against 0.4.0. Expected: the SDK module path and `sdk.New` surface are the public API this port already uses, so a rebuild is the test; the worker's RPC
+protocol (`--mode rpc` JSONL: `prompt`, `abort`, `message_update`, `agent_end`, `extension_ui_request`) and flags (`--session-dir`, `--session-id`, `--tools`, `--no-*`) are read by
+`worker.go` and are the surface to re-check. The kagent interop does not depend on a PiG version (it speaks A2A only).
+
+## Proof results
+
+Host: PiG 0.3.0+0.87.1 built from `63c6ba456`; Piglet Binary `piglets/a2a` built with `pig piglet build --format binary` from the staged tree
+(58.9 MB, fused, a2a-go linked; the Binary is not committed). Lane build: sha256 `17eff7afd824d1b5…`; review rebuild after the fixes: sha256 `8e0f00bd44bbdab7…`.
+
+| Layer | Result |
+|---|---|
+| Unit tests, `go test -race -count=3` | 122 pass, 24 skip (13 named gaps, 11 conditional), 0 fail (review re-run; the lane's run was 116 pass, 22 skip); also `GOMAXPROCS=4 taskset -c 0-3 -race -count=24`: pass (a first 24-run found a real race: `Server.Shutdown` could return before the Serve goroutine had closed the port; fixed, pinned by `TestShutdownClosesThePortEvenRightAfterStart`); `-count=8` under 6 CPU burners: pass |
+| Real PiG worker end to end (`PIG_A2A_E2E_BIN`) | 4 pass with `pig` 0.3.0 and with the Binary: tool call (tools named), context continuity, tenant isolation, cancel reaps the child, and a worker configured only by `a2a.json` cannot read a file outside its workspace (this last test failed on the lane's code: the default `read` tool returned the file to the peer) |
+| The Binary hosts the listener (`PIG_A2A_BINARY`) | 4 pass: configured (card public, 401, task on a real worker that is the same Binary, the tools named in `a2a.json` and no others, tenant isolation), off without configuration, flag without tokens refused, and its default worker cannot read outside its workspace (fails against the lane's Binary, passes against the review's) |
+| kagent interop (`KAGENT_A2A_ECHO`, `scripts/interop-kagent.mjs`, kagent upstream `e4516302`) | 4 pass: kagent's own A2A server package as a remote for PiG (send, stream, cancel; credentials not sent to the card's host), a kagent-shaped client (a2a-go v2, repeated version header) against PiG's server. **No live kagent cluster**: `docker` and `kubectl` exist here, `kind` does not |
+| Host scenarios, `pigeq check` (self-recorded, `pig-go-self`) | 6 pass + `port-gaps` + `exec-coverage` |
+| Mutation (`mutation-run.txt`) | **109 mutants, 109 killed, 0 survived** (review re-run with an exact find/replace runner; the review replaced `default-tools-not-read-only` with `worker-gets-pig-default-tools` and added six: `insecure-host-unchecked`, `transport-scheme-not-checked`, `card-scheme-downgrade-accepted`, `context-lock-shared-across-tenants` and `left-behind-child-survives`, the last two surviving the lane's tests). Lane's run, `pigeq mutate --unit-only --jobs 4`: 104/104. First run: 65 killed of 102; after adding tests (`survivors_test.go` and additions) and fixing 6 mutants that did not compile: 96/100; the last 5 (plus one new mutant for the SubscribeToTask defect) killed. One mutant judged equivalent and dropped (`cancel-does-not-wait`: a2a-go's cancel already waits for the executor). Two dropped as dead code (`cancel-after-stream-end-missed`) or equivalent (`shutdown-leaves-workers`) |
+| `go vet` | linux, windows, darwin |
+| Repository | `npm run generate`/`check`, `npm test` (62), `npm run validate`, `npm run test:go-ports -- -race -count=3`: run against the porter-driver's scripts (this branch keeps the shared scripts at base, so merge the porter-driver branch first), all pass. `pig install components/a2a/extensions/a2a --validate-only`: packable |
+
+### Mutants (109)
+
+`listener-starts-without-config`, `worker-child-may-listen`, `flag-not-highest-precedence`, `env-not-over-file`, `unknown-keys-and-inline-secrets-accepted`, `listener-without-tokens-allowed`, `insecure-no-auth-off-loopback`, `insecure-and-tokens-both`, `short-tokens-allowed`, `duplicate-token-values-allowed`, `duplicate-token-names-allowed`, `tenant-not-validated`, `missing-token-env-allowed`, `listen-not-host-port`, `worker-gets-pig-default-tools`, `remote-url-scheme-unchecked`, `remote-name-unchecked`, `basic-scheme-accepted`, `extra-fields-accepted`, `token-comparison-inverted`, `insecure-flag-ignored`, `tenant-key-uses-token-name`, `key-namespaces-collide`, `everything-public`, `no-bearer-challenge`, `empty-authenticator-allowed`, `file-parts-dropped`, `empty-prompt-accepted`, `prompt-size-unbounded`, `timeout-never-fires`, `worker-error-detail-leaks`, `context-not-serialised`, `concurrency-limit-ignored`, `cancel-does-not-stop-worker`, `failure-reason-dropped`, `principal-not-checked`, `version-not-enforced`, `absent-version-accepted`, `minor-versions-accepted`, `mixed-version-values-accepted`, `tenant-not-enforced`, `user-not-attached`, `body-size-unbounded`, `card-requires-auth`, `card-drops-streaming`, `card-claims-push`, `card-ignores-external-url`, `card-without-security-requirement`, `plain-http-on-tls`, `second-start-allowed`, `worker-keeps-extensions`, `worker-not-marked`, `worker-inherits-secrets`, `passenv-ignored`, `session-id-ignores-principal`, `session-id-ignores-context`, `session-dir-shared`, `worker-cwd-not-set`, `tools-allowlist-dropped`, `session-not-kept`, `abort-not-sent`, `no-kill-after-grace`, `no-terminate`, `model-error-text-copied`, `model-error-not-a-failure`, `streamed-and-final-text-duplicated`, `empty-prompt-sent`, `tool-updates-dropped`, `ui-request-hangs`, `rejected-prompt-ignored`, `any-protocol-version-accepted`, `credentials-follow-the-card`, `transport-host-not-checked`, `redirects-followed-with-credentials`, `bearer-not-sent`, `missing-bearer-env-tolerated`, `custom-headers-dropped`, `remote-not-cancelled-on-abort`, `timeout-ignored`, `unknown-agent-unnamed`, `names-unsorted`, `empty-message-sent`, `input-required-called-terminal`, `failure-text-hidden`, `auth-error-shows-token-context`, `switch-drops-listener`, `shutdown-keeps-listener`, `config-error-silent`, `start-failure-silent`, `flag-not-read`, `agent-dir-ignored`, `stop-does-not-reload-config`, `status-hides-remotes`, `tool-required-not-enforced`, `tool-empty-message-allowed`, `tool-errors-not-errors`, `unfinished-task-not-flagged`, `task-action-unchecked`, `send-drops-context`, `tls-load-failure-ignored`, `subscribe-ownership-unchecked`, `queued-cancel-ignored-at-slot`, `queued-cancel-ignored-at-context-lock`, `shutdown-does-not-close-the-port`, `insecure-host-unchecked`, `transport-scheme-not-checked`, `card-scheme-downgrade-accepted`, `context-lock-shared-across-tenants`, `left-behind-child-survives`
+
+
+## Re-verified on PiG 0.4.1 (porter-verify)
+
+The golden traces were recorded again from the port itself (`--self`, a regression baseline), with PiG 0.4.1 content (`5f948f86a`, `pig --version`
+`0.3.1+1.0.1`) and normalizer v3, because Pi 1.0.x changed the trace format: a `prompt` response now carries
+`data.disposition` (Pi 0.99.0, #9098). An event-by-event diff against the previous traces shows no other
+difference, and `pigeq check` passes on the Go port. Details: `docs/plan/progress/porter-verify.md`.

package/port/a2a-go-LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/port/golden/flag-without-auth-refused.jsonl

@@ -0,0 +1,5 @@
+{"kind":"header","scenario":"flag-without-auth-refused","lane":"pig-go-self","host":"pig 0.3.1+1.0.1","extension":"sha256:766f7013020ffc915c35c324d2997a21f7274842e4e3a5c598801682e171d7fd","normalizer":"v3"}
+{"step":"00-startup","ch":"ui","data":{"message":"a2a: a listener needs at least one entry in tokens (or insecureNoAuth on a loopback address)","method":"notify","notifyType":"error"}}
+{"step":"01-status","ch":"ui","data":{"message":"a2a: listener off (a2a: a listener needs at least one entry in tokens (or insecureNoAuth on a loopback address))","method":"notify","notifyType":"info"}}
+{"step":"01-status","ch":"response","data":{"command":"prompt","data":{"disposition":"handled"},"success":true}}
+{"step":"99-shutdown","ch":"exit","data":{"code":0}}

package/port/golden/listener-off.jsonl

@@ -0,0 +1,4 @@
+{"kind":"header","scenario":"listener-off","lane":"pig-go-self","host":"pig 0.3.1+1.0.1","extension":"sha256:766f7013020ffc915c35c324d2997a21f7274842e4e3a5c598801682e171d7fd","normalizer":"v3"}
+{"step":"01-status","ch":"ui","data":{"message":"a2a: listener off (set listen in a2a.json, PIG_A2A_LISTEN or --a2a-listen to serve tasks)","method":"notify","notifyType":"info"}}
+{"step":"01-status","ch":"response","data":{"command":"prompt","data":{"disposition":"handled"},"success":true}}
+{"step":"99-shutdown","ch":"exit","data":{"code":0}}