Skip to content

Agent Mesh

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.yaml
index 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 -u
INTERVAL=${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}/reachable
verdict() {
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 :; do
AGENT_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"
else
rm -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 30
fi
diff --git a/sdk/js/src/host.ts b/sdk/js/src/host.ts
index 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: MeshHostOption
return 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.ts
index 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.ts
index 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.go
new file mode 100644
index 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
+`