Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
sdk/js: reach peers through a router the control plane names by /dnsaddr
Antonio Ojeaa1d5da8c9833
diff --git a/.github/k8s/sam-sdk-canary-template.yaml b/.github/k8s/sam-sdk-canary-template.yamlindex 46e0567e..de68e2e6 100644--- a/.github/k8s/sam-sdk-canary-template.yaml+++ b/.github/k8s/sam-sdk-canary-template.yaml@@ -233,21 +233,27 @@ data:#!/bin/sh# Sends the agent beside this container a message with the A2A SDK's# client every INTERVAL seconds, by the peer ID it printed to- # /var/run/sam/agent.log, and keeps- # /var/run/sam/reachable present while the last call succeeded; the- # readiness probe reads it. One JSON line per call, for a log-based- # metric. The first call enrolls with the projected token; the later ones- # resume from SAM_STATE_DIR.+ # $SAM_CANARY_DIR/agent.log, and keeps $SAM_CANARY_DIR/reachable present+ # while the last call succeeded; the readiness probe reads it. One JSON+ # line per call, for a log-based metric. The first call enrolls with the+ # projected token; the later ones resume from SAM_STATE_DIR.+ # tests/integration runs this script against the example programs.set -uINTERVAL=${INTERVAL:-300}- LOG=/var/run/sam/agent.log- REACHABLE=/var/run/sam/reachable+ LOG=${SAM_CANARY_DIR:-/var/run/sam}/agent.log+ REACHABLE=${SAM_CANARY_DIR:-/var/run/sam}/reachableverdict() {printf '{"canary":"%s","ok":%s,"agent_peer":"%s","call_s":%d,"error":"%s"}\n' \"$CANARY" "$1" "${AGENT_PEER:-}" "$2" "$(printf '%s' "$3" | tr -d '"\n' | cut -c1-300)"}+ # The line naming the error: Node prints it before the stack trace and+ # Python after, so the end of the output is not the place to look.+ reason() {+ printf '%s\n' "$1" | grep -m1 -E '^[A-Za-z_.]*(Error|Exception)\b' || printf '%s' "$1" | tail -c 200+ }+while :; doAGENT_PEER=$(grep -o 'accepting a2a://agent as [^ ]*' "$LOG" 2>/dev/null | tail -1 | cut -d' ' -f4)if [ -z "$AGENT_PEER" ]; then@@ -262,7 +268,7 @@ data:sleep "$INTERVAL"elserm -f "$REACHABLE"- verdict false $(( $(date +%s) - start )) "$(printf '%s' "$out" | tail -c 200)"+ verdict false $(( $(date +%s) - start )) "$(reason "$out")"# A failed call is retried soon; the readiness probe already shows it.sleep 30fidiff --git a/sdk/js/src/host.ts b/sdk/js/src/host.tsindex 70f4946f..852df2e3 100644--- a/sdk/js/src/host.ts+++ b/sdk/js/src/host.ts@@ -28,7 +28,7 @@ import { ping } from "@libp2p/ping";import { tcp } from "@libp2p/tcp";import { tls } from "@libp2p/tls";import type { Multiaddr } from "@multiformats/multiaddr";-import { createLibp2p } from "libp2p";+import { createLibp2p, type Libp2pOptions } from "libp2p";import { DHT_PROTOCOL } from "./discovery.ts";import type { Identity } from "./identity.ts";@@ -44,6 +44,8 @@ export interface MeshHostOptions {* it current from /info and the gossip events.*/banned?: { has(peerId: string): boolean };+ /** The resolver for `/dnsaddr` and `/dns*` addresses; the system's by default. */+ dns?: Libp2pOptions["dns"];}/** The services a mesh host runs; `services.pubsub` carries the control plane's events. */@@ -55,6 +57,7 @@ export async function createMeshHost(identity: Identity, options: MeshHostOptionreturn createLibp2p({privateKey: privateKeyFromProtobuf(identity.toLibp2pPrivateKey()),addresses: { listen: options.listenAddrs ?? [] },+ ...(options.dns !== undefined ? { dns: options.dns } : {}),transports: [tcp(), circuitRelayTransport()],connectionEncrypters: [tls()],streamMuxers: [yamux()],diff --git a/sdk/js/src/session.test.ts b/sdk/js/src/session.test.tsindex 17bf632d..e8ab8f3f 100644--- a/sdk/js/src/session.test.ts+++ b/sdk/js/src/session.test.ts@@ -156,6 +156,39 @@ test("join authenticates with the router, reserves a relay slot and answers peer}});+test("a router handed out as /dnsaddr still relays to peers", async () => {+ // The testnets advertise their routers as /dnsaddr/<host>/p2p/<id>, one+ // TXT lookup away from the addresses. A stub resolver answers with the+ // real router's addresses, as the records would.+ const dnsaddr = `/dnsaddr/router.test/p2p/${router.peerId.toString()}`;+ const dns = {+ query: async (domain: string) => {+ assert.equal(domain, "_dnsaddr.router.test");+ return { Answer: router.getMultiaddrs().map((ma) => ({ name: domain, type: 16, TTL: 60, data: `dnsaddr=${ma.toString()}` })) };+ },+ } as unknown as NonNullable<Parameters<typeof createLibp2p>[0]>["dns"];++ const agent = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: fakeControlPlane([routerAddr]) });+ const agentSession = await agent.join({ refreshLeadMs: 0 });+ const caller = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: fakeControlPlane([dnsaddr]) });+ const callerSession = await caller.join({ refreshLeadMs: 0, dns });+ try {+ // The router is known by the address the connection was made on: the+ // relay address for a peer is dialable as it stands.+ const routerAddrs = callerSession.routers.map((r) => r.addr.toString());+ assert.deepEqual(routerAddrs, [routerAddr]);+ assert.ok(callerSession.relayAddresses.some((ma) => ma.toString().startsWith(routerAddr)), `reserved on ${callerSession.relayAddresses.map(String).join(",")}`);+ const targets = callerSession.dialTargets(agent.peerId).addrs.map(String);+ assert.deepEqual(targets, [`${routerAddr}/p2p-circuit/p2p/${agent.peerId}`]);++ const verified = await callerSession.authenticate(agent.peerId);+ assert.equal(verified.peerId, agent.peerId);+ } finally {+ await callerSession.close();+ await agentSession.close();+ }+});+test("join fails closed when the router is not a router", async () => {// A relay whose credential lacks the router role must not admit us to the mesh.const impostor = await createLibp2p({diff --git a/sdk/js/src/session.ts b/sdk/js/src/session.tsindex 3286356c..49db9b9a 100644--- a/sdk/js/src/session.ts+++ b/sdk/js/src/session.ts@@ -68,6 +68,14 @@ export interface JoinOptions extends MeshHostOptions {export interface AdmittedRouter {peerId: string;+ /**+ * The address the connection to the router was made on, resolved: a+ * `/ip4` or `/ip6` address ending in `/p2p/<router>`. Relay addresses+ * are built on it. The control plane may hand a router out as+ * `/dnsaddr/<host>/p2p/<router>`; js-libp2p resolves such an address to+ * the TXT records themselves and drops what follows it, so a+ * `/dnsaddr/.../p2p-circuit/p2p/<peer>` address reaches nobody.+ */addr: Multiaddr;credential: VerifiedBiscuit;}@@ -557,7 +565,7 @@ export async function joinMesh(mesh: AgentMesh, options: JoinOptions = {}): Prom// Enforced under the key that verified the token; a relay that is// not a router must not become our way onto the mesh.requireRole(credential, ROLE_ROUTER);- admitted.push({ peerId: routerPeer, addr, credential });+ admitted.push({ peerId: routerPeer, addr: connectedAddress(conn, routerPeer), credential });} catch (err) {failures.push(`${addr.toString()}: ${err instanceof Error ? err.message : String(err)}`);}@@ -583,6 +591,11 @@ function targetPeerOf(ma: Multiaddr): string | undefined {return last?.name === "p2p" && last.value !== undefined ? canonicalPeerId(last.value) : undefined;}+/** The remote address of a connection, ending in `/p2p/<peerId>`. */+function connectedAddress(conn: Connection, peerId: string): Multiaddr {+ return targetPeerOf(conn.remoteAddr) === undefined ? conn.remoteAddr.encapsulate(`/p2p/${peerId}`) : conn.remoteAddr;+}+/** Canonicalizes a list from the control plane, dropping entries that are not peer IDs. */function canonicalPeerIds(ids: string[]): string[] {const out: string[] = [];diff --git a/tests/integration/sdk_canary_test.go b/tests/integration/sdk_canary_test.gonew file mode 100644index 00000000..27999993--- /dev/null+++ b/tests/integration/sdk_canary_test.go@@ -0,0 +1,249 @@+// Copyright 2026 Google LLC+//+// 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 integration_test++import (+ "bufio"+ "context"+ "encoding/json"+ "os"+ "os/exec"+ "path/filepath"+ "strings"+ "syscall"+ "testing"+ "time"++ "github.com/google/sam/api"+)++const sdkCanaryTemplate = ".github/k8s/sam-sdk-canary-template.yaml"++// canaryVerdict is one line the canary script prints per call.+type canaryVerdict struct {+ Canary string `json:"canary"`+ OK bool `json:"ok"`+ AgentPeer string `json:"agent_peer"`+ CallS int `json:"call_s"`+ Error string `json:"error"`+}++// TestSDKCanaryScript runs the testnet's SDK canary script, taken from+// .github/k8s/sam-sdk-canary-template.yaml, the way its pod runs it: an+// agent example in one language writes its output to the directory the pod+// shares, and the script calls it with the other language's A2A example,+// both enrolled with the same projected token, the caller resuming its+// identity from SAM_STATE_DIR on the second call. The script reports each+// call as one JSON line and keeps the readiness file while the last call+// succeeded; a failed call is reported by the line that names the error.+func TestSDKCanaryScript(t *testing.T) {+ script := canaryScript(t)++ t.Run("a failed call is reported by the line naming the error", func(t *testing.T) {+ for _, tc := range []struct{ name, output, want string }{+ {"node", nodeCrash, "NoValidAddressesError: The dial request has no valid addresses for peer: 12D3KooWfake"},+ {"python", pythonTraceback, "ConnectionError: cannot reach 12D3KooWfake:"},+ } {+ dir := t.TempDir()+ if err := os.WriteFile(filepath.Join(dir, "agent.log"), []byte("accepting a2a://agent as 12D3KooWfake\n"), 0o644); err != nil {+ t.Fatal(err)+ }+ call := filepath.Join(dir, "call.sh")+ if err := os.WriteFile(call, []byte("#!/bin/sh\ncat <<'EOF' >&2\n"+tc.output+"EOF\nexit 1\n"), 0o755); err != nil {+ t.Fatal(err)+ }+ verdicts := runCanaryScript(t, script, dir, tc.name+"-fails", call, nil)+ v := <-verdicts+ if v.OK || v.Error != tc.want || v.AgentPeer != "12D3KooWfake" {+ t.Fatalf("%s failure reported as %+v, want error %q", tc.name, v, tc.want)+ }+ if _, err := os.Stat(filepath.Join(dir, "reachable")); err == nil {+ t.Fatalf("%s: the readiness file is present after a failed call", tc.name)+ }+ }+ })++ root := repoRoot(t)+ var launchers []sdkExampleLauncher+ for _, l := range sdkExampleLaunchers {+ _, skip := l.cmd(context.Background(), root, "a2a-agent")+ if skip == "" {+ skip = a2aSDKMissing(root, l.name)+ }+ if skip != "" {+ t.Logf("%s SDK skipped: %s", l.name, skip)+ continue+ }+ launchers = append(launchers, l)+ }+ if len(launchers) == 0 {+ t.Skip("no SDK toolchain with the A2A SDK available; see sdk/README.md")+ }+ mesh := startSDKMesh(t)+ for i, agent := range launchers {+ caller := launchers[(i+1)%len(launchers)]+ t.Run(caller.name+"-calls-"+agent.name+"-agent", func(t *testing.T) {+ t.Parallel()+ dir := t.TempDir()+ jwtPath := filepath.Join(dir, "sam-token")+ jwt := mesh.mintToken(map[string]interface{}{"sub": "mock-user", "roles": []string{api.RoleNode}})+ if err := os.WriteFile(jwtPath, []byte(jwt+"\n"), 0o600); err != nil {+ t.Fatal(err)+ }+ env := []string{+ "SAM_CONTROL_PLANE_URL=" + mesh.baseURL,+ "SAM_INSECURE_CONTROL_PLANE=true",+ "SAM_JWT_PATH=" + jwtPath,+ "PYTHONUNBUFFERED=1",+ }++ // The agent's output is the log the caller reads the peer ID from.+ logFile, err := os.Create(filepath.Join(dir, "agent.log"))+ if err != nil {+ t.Fatal(err)+ }+ agentCmd, _ := agent.cmd(context.Background(), mesh.root, "a2a-agent")+ agentCmd.Env = append(os.Environ(), append(env, "SAM_STATE_DIR="+filepath.Join(dir, "agent"))...)+ agentCmd.Dir = mesh.root+ agentCmd.Stdout, agentCmd.Stderr = logFile, logFile+ if err := agentCmd.Start(); err != nil {+ t.Fatal(err)+ }+ t.Cleanup(func() {+ _ = agentCmd.Process.Kill()+ _ = agentCmd.Wait()+ _ = logFile.Close()+ if t.Failed() {+ log, _ := os.ReadFile(filepath.Join(dir, "agent.log"))+ t.Logf("%s agent log:\n%s", agent.name, log)+ }+ })++ callCmd, _ := caller.cmd(context.Background(), mesh.root, "a2a-call")+ verdicts := runCanaryScript(t, script, dir, caller.name+"-calls-"+agent.name+"-agent", strings.Join(callCmd.Args, " "),+ append(env, "SAM_STATE_DIR="+filepath.Join(dir, "caller"), "INTERVAL=1"))+ for i := 0; i < 2; i++ {+ v := <-verdicts+ if !v.OK || v.Error != "" || v.AgentPeer == "" {+ t.Fatalf("call %d: %+v", i+1, v)+ }+ }+ if _, err := os.Stat(filepath.Join(dir, "reachable")); err != nil {+ t.Fatalf("the readiness file is missing after two successful calls: %v", err)+ }+ })+ }+}++// canaryScript returns the path of canary.sh as the template's ConfigMap carries it.+func canaryScript(t *testing.T) string {+ t.Helper()+ data, err := os.ReadFile(filepath.Join(repoRoot(t), sdkCanaryTemplate))+ if err != nil {+ t.Fatal(err)+ }+ var script []string+ inScript := false+ for _, line := range strings.Split(string(data), "\n") {+ switch {+ case strings.TrimSpace(line) == "canary.sh: |":+ inScript = true+ case inScript && (line == "" || strings.HasPrefix(line, " ")):+ script = append(script, strings.TrimPrefix(line, " "))+ case inScript:+ inScript = false+ }+ }+ if len(script) == 0 {+ t.Fatalf("no canary.sh in %s", sdkCanaryTemplate)+ }+ path := filepath.Join(t.TempDir(), "canary.sh")+ if err := os.WriteFile(path, []byte(strings.Join(script, "\n")), 0o755); err != nil {+ t.Fatal(err)+ }+ return path+}++// runCanaryScript starts the canary script as the pod does, `sh canary.sh`+// with CANARY and CALL in the environment, and streams its verdict lines.+// The script loops forever; it is killed with its children at cleanup.+func runCanaryScript(t *testing.T, script, dir, canary, call string, env []string) <-chan canaryVerdict {+ t.Helper()+ cmd := exec.Command("sh", script)+ cmd.Dir = dir+ cmd.Env = append(os.Environ(), append(env, "SAM_CANARY_DIR="+dir, "CANARY="+canary, "CALL="+call)...)+ cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}+ stdout, err := cmd.StdoutPipe()+ if err != nil {+ t.Fatal(err)+ }+ if err := cmd.Start(); err != nil {+ t.Fatal(err)+ }+ t.Cleanup(func() {+ _ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)+ _ = cmd.Wait()+ })+ verdicts := make(chan canaryVerdict)+ go func() {+ defer close(verdicts)+ scanner := bufio.NewScanner(stdout)+ for scanner.Scan() {+ var v canaryVerdict+ if err := json.Unmarshal(scanner.Bytes(), &v); err != nil {+ t.Errorf("canary line %q is not JSON: %v", scanner.Text(), err)+ return+ }+ verdicts <- v+ }+ }()+ out := make(chan canaryVerdict)+ go func() {+ defer close(out)+ for {+ select {+ case v, ok := <-verdicts:+ if !ok {+ return+ }+ out <- v+ case <-time.After(60 * time.Second):+ t.Errorf("%s: no verdict within 60s", canary)+ return+ }+ }+ }()+ return out+}++const nodeCrash = `file:///app/node_modules/libp2p/dist/src/connection-manager/dial-queue.js:398+ throw new NoValidAddressesError(` + "`" + `The dial request has no valid addresses for peer: ${peerId}` + "`" + `);+ ^++NoValidAddressesError: The dial request has no valid addresses for peer: 12D3KooWfake+ at DialQueue.calculateMultiaddrs (file:///app/node_modules/libp2p/dist/src/connection-manager/dial-queue.js:398:19)+ at async Job.run (file:///app/node_modules/@libp2p/utils/dist/src/queue/job.js:62:28)++Node.js v22.23.3+`++const pythonTraceback = `Traceback (most recent call last):+ File "/app/examples/a2a_call.py", line 61, in <module>+ trio.run(main)+ File "/app/src/agent_mesh/session.py", line 233, in connect+ raise ConnectionError(f"cannot reach {target}:\n " + "\n ".join(failures))+ConnectionError: cannot reach 12D3KooWfake:+ via router 12D3KooWrouter: NO_RESERVATION+`