Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
testnets: the SDK examples run as canaries beside the sam-node ones
Antonio Ojea35ca6d4600f6
diff --git a/.dockerignore b/.dockerignoreindex ca4acce1..05a6cf7b 100644--- a/.dockerignore+++ b/.dockerignore@@ -33,6 +33,7 @@ __pycache__/*.outcoverage.*mobile/sam-node-app/build/+sdk/js/build/site/public/site/resources/rootfs.ext4diff --git a/.github/k8s/sam-probe-cronjob-template.yaml b/.github/k8s/sam-probe-cronjob-template.yamlindex b3053864..2b3943de 100644--- a/.github/k8s/sam-probe-cronjob-template.yaml+++ b/.github/k8s/sam-probe-cronjob-template.yaml@@ -1,9 +1,10 @@# The cold path, on a schedule: a node with no identity enrolls with the# control plane, authenticates to a router, finds a service on the mesh and-# speaks MCP to it through the mesh, then exits. The long-lived canaries only-# do this when a pod restarts, so between rollouts nobody re-checks that a new-# user could still join. Each run enrolls a fresh identity; the control-# plane's --node-retention sweep reclaims the rows.+# speaks MCP to it through the mesh, then reaches the services the SDK+# canaries serve, and exits. The long-lived canaries only do this when a pod+# restarts, so between rollouts nobody re-checks that a new user could still+# join. Each run enrolls a fresh identity; the control plane's+# --node-retention sweep reclaims the rows.apiVersion: batch/v1kind: CronJobmetadata:@@ -19,8 +20,9 @@ spec:# One attempt: a retry would hide exactly the flakiness this exists to# measure. A failed Job is the signal.backoffLimit: 0- # 180s to be ready plus 120s to reach a provider, with headroom.- activeDeadlineSeconds: 360+ # 180s to be ready, 120s to reach a provider, 120s for the SDK+ # canaries, with headroom.+ activeDeadlineSeconds: 480template:metadata:labels:@@ -78,6 +80,10 @@ spec:# The everything canary's MCP server (sam-node-everything-template.yaml):# a real server, so the node advertises it and initialize succeeds.value: everything+ - name: SDK_SERVICES+ # What the SDK canaries publish (sam-sdk-canary-template.yaml),+ # each with a `greet` tool and an A2A endpoint.+ value: "greeter-js greeter-py"resources:requests:cpu: 10m@@ -157,8 +163,57 @@ spec:doneREACH_S=$(( $(date +%s) - REACH_START ))- printf '{"probe":"sam-cold-path","ok":true,"ready_s":%d,"router_latency_ms":%s,"connected_peers":%s,"reach_s":%d,"providers_tried":%d,"call_s":%s,"provider":"%s","elapsed_s":%d}\n' \- "$READY_S" "${ROUTER_MS:-null}" "${PEERS:-null}" "$REACH_S" "$TRIED" "$CALL_S" "$PEER" "$(( $(date +%s) - START ))"+ # 4. A service an SDK member serves (sam-sdk-canary-template.yaml)+ # is reachable from a node the way an agent behind a node+ # reaches it: its MCP tool through the node's own MCP API+ # (call_remote_tool opens /sam/mcp/1.0.0 to the provider), and+ # its A2A endpoint through the egress proxy. The node's MCP+ # endpoint is stateful, so one session is opened first.+ MCP=http://localhost/mcp+ SESSION=""+ mcp_post() {+ curl -s --unix-socket "$SOCK" -o "$2" -D /tmp/mcp.hdr -X POST "$MCP" \+ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \+ ${SESSION:+-H "Mcp-Session-Id: $SESSION"} -d "$1"+ }+ mcp_post '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"sam-probe","version":"0"}}}' /tmp/mcp-init.out \+ || fail sdk "initialize on the node's MCP API failed"+ SESSION=$(grep -i '^mcp-session-id:' /tmp/mcp.hdr | tr -d '\r' | cut -d' ' -f2)+ [ -n "$SESSION" ] || fail sdk "the node's MCP API returned no session"+ mcp_post '{"jsonrpc":"2.0","method":"notifications/initialized"}' /dev/null++ SDK_START=$(date +%s)+ SDK_PROVIDERS=""+ for svc in ${SDK_SERVICES}; do+ SDK_PEER=""+ LAST_ERR=""+ while [ -z "$SDK_PEER" ]; do+ if curl -sf --unix-socket "$SOCK" -o /tmp/sdk-providers.json \+ "http://localhost/sam/service/discover?type=mcp&name=${svc}&timeout=20s"; then+ for p in $(grep -oE '"peer_id":"[^"]+"' /tmp/sdk-providers.json | cut -d'"' -f4); do+ mcp_post '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"call_remote_tool","arguments":{"peer_id":"'"$p"'","tool_name":"mcp://'"$svc"'/greet","arguments":{"name":"sam-probe"}}}}' /tmp/sdk-call.out+ if grep -q 'hello sam-probe' /tmp/sdk-call.out; then+ CODE=$(curl -s --unix-socket "$SOCK" -o /tmp/sdk-card.out -w '%{http_code}' "http://localhost/sam/${p}/a2a/${svc}/card")+ if [ "$CODE" = "200" ] && grep -q '"caller"' /tmp/sdk-card.out; then+ SDK_PEER=$p+ break+ fi+ LAST_ERR="${p}: a2a card HTTP ${CODE} $(head -c 120 /tmp/sdk-card.out | tr -d '"\n')"+ else+ LAST_ERR="${p}: $(head -c 160 /tmp/sdk-call.out | tr -d '"\n')"+ fi+ done+ fi+ [ -n "$SDK_PEER" ] && break+ [ $(( $(date +%s) - SDK_START )) -ge 120 ] && fail sdk "no provider of ${svc} answered greet and its card in 120s (last: ${LAST_ERR:-none discovered})"+ sleep 5+ done+ SDK_PROVIDERS="${SDK_PROVIDERS}${SDK_PROVIDERS:+,}\"${svc}\":\"${SDK_PEER}\""+ done+ SDK_S=$(( $(date +%s) - SDK_START ))++ printf '{"probe":"sam-cold-path","ok":true,"ready_s":%d,"router_latency_ms":%s,"connected_peers":%s,"reach_s":%d,"providers_tried":%d,"call_s":%s,"provider":"%s","sdk_s":%d,"sdk_providers":{%s},"elapsed_s":%d}\n' \+ "$READY_S" "${ROUTER_MS:-null}" "${PEERS:-null}" "$REACH_S" "$TRIED" "$CALL_S" "$PEER" "$SDK_S" "$SDK_PROVIDERS" "$(( $(date +%s) - START ))"volumes:- name: config-volumeconfigMap:diff --git a/.github/k8s/sam-sdk-canary-template.yaml b/.github/k8s/sam-sdk-canary-template.yamlnew file mode 100644index 00000000..16fb75d7--- /dev/null+++ b/.github/k8s/sam-sdk-canary-template.yaml@@ -0,0 +1,124 @@+# Two members with no sam-node beside them: the JavaScript and Python SDK+# example servers (sdk/js/examples/serve.ts, sdk/python/examples/serve.py),+# unchanged, each publishing mcp://greeter-<lang> and a2a://greeter-<lang>.+# They enroll with the pod's projected service account token, the way every+# other canary does, and keep their identity in an emptyDir, so a restart+# resumes and a new pod enrolls afresh. What the mesh sees from them is what a+# user of the packages gets.+apiVersion: apps/v1+kind: Deployment+metadata:+ name: js-canary-${ENV_NAME}+ namespace: sam-canary-${ENV_NAME}+spec:+ replicas: 1+ selector:+ matchLabels:+ app: js-canary-${ENV_NAME}+ template:+ metadata:+ labels:+ app: js-canary-${ENV_NAME}+ sam-canary: "true"+ spec:+ serviceAccountName: sam-node-sa+ containers:+ - name: sdk+ image: ghcr.io/google/sam-sdk-js:${IMAGE_TAG}+ args: ["build/examples/serve.js", "greeter-js"]+ env:+ - name: SAM_CONTROL_PLANE_URL+ value: "http://sam-control-plane-${ENV_NAME}.${NAMESPACE}.svc.cluster.local:8080"+ - name: SAM_INSECURE_CONTROL_PLANE+ value: "true"+ - name: SAM_JWT_PATH+ value: /var/run/secrets/tokens/sam-token+ - name: SAM_STATE_DIR+ value: /var/run/sam/state+ securityContext:+ allowPrivilegeEscalation: false+ capabilities:+ drop: ["ALL"]+ resources:+ requests:+ cpu: 50m+ memory: 128Mi+ limits:+ cpu: 500m+ memory: 512Mi+ volumeMounts:+ - name: sam-token+ mountPath: /var/run/secrets/tokens+ readOnly: true+ - name: sam-state+ mountPath: /var/run/sam+ volumes:+ - name: sam-state+ emptyDir: {}+ - name: sam-token+ projected:+ sources:+ - serviceAccountToken:+ path: sam-token+ expirationSeconds: 3600+ audience: "sam-control-plane-audience"+---+apiVersion: apps/v1+kind: Deployment+metadata:+ name: python-canary-${ENV_NAME}+ namespace: sam-canary-${ENV_NAME}+spec:+ replicas: 1+ selector:+ matchLabels:+ app: python-canary-${ENV_NAME}+ template:+ metadata:+ labels:+ app: python-canary-${ENV_NAME}+ sam-canary: "true"+ spec:+ serviceAccountName: sam-node-sa+ containers:+ - name: sdk+ image: ghcr.io/google/sam-sdk-python:${IMAGE_TAG}+ args: ["examples/serve.py", "greeter-py"]+ env:+ - name: SAM_CONTROL_PLANE_URL+ value: "http://sam-control-plane-${ENV_NAME}.${NAMESPACE}.svc.cluster.local:8080"+ - name: SAM_INSECURE_CONTROL_PLANE+ value: "true"+ - name: SAM_JWT_PATH+ value: /var/run/secrets/tokens/sam-token+ - name: SAM_STATE_DIR+ value: /var/run/sam/state+ - name: PYTHONUNBUFFERED+ value: "1"+ securityContext:+ allowPrivilegeEscalation: false+ capabilities:+ drop: ["ALL"]+ resources:+ requests:+ cpu: 50m+ memory: 128Mi+ limits:+ cpu: 500m+ memory: 512Mi+ volumeMounts:+ - name: sam-token+ mountPath: /var/run/secrets/tokens+ readOnly: true+ - name: sam-state+ mountPath: /var/run/sam+ volumes:+ - name: sam-state+ emptyDir: {}+ - name: sam-token+ projected:+ sources:+ - serviceAccountToken:+ path: sam-token+ expirationSeconds: 3600+ audience: "sam-control-plane-audience"diff --git a/.github/k8s/sam-sdk-probe-cronjob-template.yaml b/.github/k8s/sam-sdk-probe-cronjob-template.yamlnew file mode 100644index 00000000..a02239b9--- /dev/null+++ b/.github/k8s/sam-sdk-probe-cronjob-template.yaml@@ -0,0 +1,183 @@+# The cold path through the SDKs, on a schedule: a fresh identity enrolls with+# the control plane through each SDK, joins through a router, and calls out+# across every implementation boundary a user can cross: an MCP service a+# sam-node serves (the everything canary), and an MCP tool and an A2A endpoint+# the other language's SDK serves (the sdk canaries). The programs are the+# examples the READMEs embed, unchanged; the shell around them only retries+# discovery, which a member that joined seconds ago can miss, and prints one+# verdict line. Each run enrolls a fresh identity per language; the control+# plane's --node-retention sweep reclaims the rows.+apiVersion: batch/v1+kind: CronJob+metadata:+ name: sam-sdk-probe-${ENV_NAME}+ namespace: sam-canary-${ENV_NAME}+spec:+ schedule: "7,22,37,52 * * * *"+ concurrencyPolicy: Forbid+ successfulJobsHistoryLimit: 3+ failedJobsHistoryLimit: 5+ jobTemplate:+ spec:+ # One attempt: a retry would hide exactly the flakiness this exists to+ # measure. A failed Job is the signal; both containers must succeed.+ backoffLimit: 0+ # Three calls with up to 120s of discovery each, plus enrollment.+ activeDeadlineSeconds: 480+ template:+ metadata:+ labels:+ app: sam-sdk-probe-${ENV_NAME}+ spec:+ # Bound to the sam-canary role by deploy.yaml's policy seed, which+ # is what lets the probe call the canaries' services.+ serviceAccountName: sam-node-sa+ restartPolicy: Never+ containers:+ - name: js+ image: ghcr.io/google/sam-sdk-js:${IMAGE_TAG}+ env:+ - name: SAM_CONTROL_PLANE_URL+ value: "http://sam-control-plane-${ENV_NAME}.${NAMESPACE}.svc.cluster.local:8080"+ - name: SAM_INSECURE_CONTROL_PLANE+ value: "true"+ - name: SAM_JWT_PATH+ value: /var/run/secrets/tokens/sam-token+ - name: SAM_STATE_DIR+ value: /var/run/sam/js+ - name: PROBE+ value: sam-sdk-js+ - name: CALL+ value: "node build/examples/call.js"+ - name: PEER_SERVICE+ # The other SDK's canary (sam-sdk-canary-template.yaml).+ value: greeter-py+ securityContext:+ allowPrivilegeEscalation: false+ capabilities:+ drop: ["ALL"]+ resources:+ requests:+ cpu: 50m+ memory: 128Mi+ limits:+ cpu: 500m+ memory: 512Mi+ volumeMounts:+ - name: sam-token+ mountPath: /var/run/secrets/tokens+ readOnly: true+ - name: sam-state+ mountPath: /var/run/sam+ - name: probe-script+ mountPath: /etc/sam-probe+ readOnly: true+ command: ["/bin/sh", "/etc/sam-probe/probe.sh"]+ - name: python+ image: ghcr.io/google/sam-sdk-python:${IMAGE_TAG}+ env:+ - name: SAM_CONTROL_PLANE_URL+ value: "http://sam-control-plane-${ENV_NAME}.${NAMESPACE}.svc.cluster.local:8080"+ - name: SAM_INSECURE_CONTROL_PLANE+ value: "true"+ - name: SAM_JWT_PATH+ value: /var/run/secrets/tokens/sam-token+ - name: SAM_STATE_DIR+ value: /var/run/sam/python+ - name: PYTHONUNBUFFERED+ value: "1"+ - name: PROBE+ value: sam-sdk-python+ - name: CALL+ value: "python examples/call.py"+ - name: PEER_SERVICE+ value: greeter-js+ securityContext:+ allowPrivilegeEscalation: false+ capabilities:+ drop: ["ALL"]+ resources:+ requests:+ cpu: 50m+ memory: 128Mi+ limits:+ cpu: 500m+ memory: 512Mi+ volumeMounts:+ - name: sam-token+ mountPath: /var/run/secrets/tokens+ readOnly: true+ - name: sam-state+ mountPath: /var/run/sam+ - name: probe-script+ mountPath: /etc/sam-probe+ readOnly: true+ command: ["/bin/sh", "/etc/sam-probe/probe.sh"]+ volumes:+ - name: sam-state+ emptyDir: {}+ - name: probe-script+ configMap:+ name: sam-sdk-probe-script-${ENV_NAME}+ - name: sam-token+ projected:+ sources:+ - serviceAccountToken:+ path: sam-token+ expirationSeconds: 3600+ audience: "sam-control-plane-audience"+---+apiVersion: v1+kind: ConfigMap+metadata:+ name: sam-sdk-probe-script-${ENV_NAME}+ namespace: sam-canary-${ENV_NAME}+data:+ probe.sh: |+ #!/bin/sh+ # Runs the SDK's call example against three services and prints one JSON+ # verdict line. PROBE names the run, CALL is the example's command line,+ # PEER_SERVICE is the other SDK's canary. Discovery is retried: a member+ # that joined seconds ago has a thin routing table, and a provider record+ # can name a pod a rollout just replaced. The first call enrolls with the+ # projected token; the later ones resume from SAM_STATE_DIR.+ set -u+ START=$(date +%s)++ fail() {+ printf '{"probe":"%s","ok":false,"stage":"%s","error":"%s","elapsed_s":%d}\n' \+ "$PROBE" "$1" "$(printf '%s' "$2" | tr -d '"\n' | cut -c1-300)" "$(( $(date +%s) - START ))"+ exit 1+ }++ # call <stage> <expected substring> <example arguments...>; sets PROVIDER.+ call() {+ stage=$1; want=$2; shift 2+ stage_start=$(date +%s)+ attempts=0+ while :; do+ attempts=$((attempts + 1))+ out=$($CALL "$@" 2>&1); rc=$?+ if [ $rc -eq 0 ] && printf '%s' "$out" | grep -q "$want"; then+ PROVIDER=$(printf '%s' "$out" | grep -o 'is served by [^ ]*' | tail -1 | cut -d' ' -f4)+ return 0+ fi+ [ $(( $(date +%s) - stage_start )) -ge 120 ] && fail "$stage" "no answer with '$want' in 120s ($attempts attempts; last: $(printf '%s' "$out" | tail -c 200))"+ sleep 5+ done+ }++ # 1. Enroll, join and call an MCP service a sam-node serves.+ call node-mcp 'Echo: sam-sdk-probe' mcp://everything echo '{"message": "sam-sdk-probe"}'+ NODE_PEER=$PROVIDER+ NODE_S=$(( $(date +%s) - START ))++ # 2. The other SDK's MCP tool, then its A2A endpoint over /libp2p-http.+ SDK_START=$(date +%s)+ call sdk-mcp 'hello sam-sdk-probe' "mcp://${PEER_SERVICE}" greet '{"name": "sam-sdk-probe"}'+ SDK_PEER=$PROVIDER+ call sdk-a2a '"caller"' "a2a://${PEER_SERVICE}" /card+ SDK_S=$(( $(date +%s) - SDK_START ))++ printf '{"probe":"%s","ok":true,"node_s":%d,"node_provider":"%s","sdk_s":%d,"sdk_provider":"%s","elapsed_s":%d}\n' \+ "$PROBE" "$NODE_S" "$NODE_PEER" "$SDK_S" "$SDK_PEER" "$(( $(date +%s) - START ))"diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yamlindex b6b40def..84425cc3 100644--- a/.github/workflows/deploy.yaml+++ b/.github/workflows/deploy.yaml@@ -208,6 +208,54 @@ jobs:tags: ${{ steps.meta-sam-one.outputs.tags }}labels: ${{ steps.meta-sam-one.outputs.labels }}+ # The SDK images carry the example programs the docs embed, as the+ # testnet canaries and probes run them. Built from the commit, not from+ # npm or PyPI, so bananas exercises the SDK at the same commit as the+ # Go components it talks to.+ - name: Extract metadata for sam-sdk-js+ id: meta-sdk-js+ uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0+ with:+ images: ${{ env.REGISTRY }}/google/sam-sdk-js+ tags: |+ type=ref,event=branch+ type=ref,event=tag+ type=raw,value=${{ github.sha }}+ type=raw,value=latest,enable={{is_default_branch}}+ type=raw,value=stable,enable=${{ startsWith(github.ref, 'refs/tags/v') }}++ - name: Build and push sam-sdk-js image+ uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0+ with:+ context: .+ file: Dockerfile.sam-sdk-js+ platforms: ${{ github.ref_type == 'tag' && 'linux/amd64,linux/arm64' || 'linux/amd64' }}+ push: true+ tags: ${{ steps.meta-sdk-js.outputs.tags }}+ labels: ${{ steps.meta-sdk-js.outputs.labels }}++ - name: Extract metadata for sam-sdk-python+ id: meta-sdk-python+ uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0+ with:+ images: ${{ env.REGISTRY }}/google/sam-sdk-python+ tags: |+ type=ref,event=branch+ type=ref,event=tag+ type=raw,value=${{ github.sha }}+ type=raw,value=latest,enable={{is_default_branch}}+ type=raw,value=stable,enable=${{ startsWith(github.ref, 'refs/tags/v') }}++ - name: Build and push sam-sdk-python image+ uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0+ with:+ context: .+ file: Dockerfile.sam-sdk-python+ platforms: ${{ github.ref_type == 'tag' && 'linux/amd64,linux/arm64' || 'linux/amd64' }}+ push: true+ tags: ${{ steps.meta-sdk-python.outputs.tags }}+ labels: ${{ steps.meta-sdk-python.outputs.labels }}+deploy:name: Deploy to GKEruns-on: ubuntu-latest@@ -758,6 +806,35 @@ jobs:exit 1}+ # Two members with no sam-node: the SDK example servers, each+ # publishing an MCP tool and an A2A endpoint. What the probes below+ # reach from a node and from the other SDK.+ - name: Deploy SDK Canaries+ env:+ VAR_ENV_NAME: ${{ vars.ENV_NAME }}+ VAR_IMAGE_TAG: ${{ env.IMAGE_TAG }}+ run: |+ export ENV_NAME="${VAR_ENV_NAME}"+ export CANARY_NAMESPACE="sam-canary-${ENV_NAME}"+ export NAMESPACE="sam-${ENV_NAME}"+ export IMAGE_TAG="${VAR_IMAGE_TAG}"++ envsubst '${ENV_NAME} ${NAMESPACE} ${IMAGE_TAG}' < .github/k8s/sam-sdk-canary-template.yaml | kubectl apply -f -+ for lang in js python; do+ kubectl rollout status deployment/${lang}-canary-${ENV_NAME} -n ${CANARY_NAMESPACE} --timeout=180s || {+ echo "${lang} SDK canary deployment failed!"+ kubectl describe deployment/${lang}-canary-${ENV_NAME} -n ${CANARY_NAMESPACE} || true+ kubectl get pods -n ${CANARY_NAMESPACE} -l app=${lang}-canary-${ENV_NAME} -o wide || true+ kubectl describe pods -n ${CANARY_NAMESPACE} -l app=${lang}-canary-${ENV_NAME} || true+ kubectl logs -n ${CANARY_NAMESPACE} -l app=${lang}-canary-${ENV_NAME} --tail=-1 || true++ echo "Rolling back ${lang} SDK canary deployment..."+ kubectl rollout undo deployment/${lang}-canary-${ENV_NAME} -n ${CANARY_NAMESPACE}+ kubectl rollout status deployment/${lang}-canary-${ENV_NAME} -n ${CANARY_NAMESPACE} || true+ exit 1+ }+ done+- name: Deploy OpenRouter Node to Testnetenv:OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}@@ -857,3 +934,47 @@ jobs:;;esac+ # The same cold path through each SDK: a fresh identity enrolls with+ # the JavaScript and the Python SDK, reaches the everything canary's+ # MCP server (a sam-node) and the other SDK's canary, MCP and A2A. With+ # the node probe above, every pair of implementations is crossed in+ # both directions on every rollout and every 15 minutes after.+ - name: Deploy and run the SDK cold-path probe+ env:+ VAR_ENV_NAME: ${{ vars.ENV_NAME }}+ VAR_IMAGE_TAG: ${{ env.IMAGE_TAG }}+ run: |+ export ENV_NAME="${VAR_ENV_NAME}"+ export CANARY_NAMESPACE="sam-canary-${ENV_NAME}"+ export NAMESPACE="sam-${ENV_NAME}"+ export IMAGE_TAG="${VAR_IMAGE_TAG}"+ JOB="sam-sdk-probe-rollout-${ENV_NAME}"++ envsubst '${ENV_NAME} ${NAMESPACE} ${IMAGE_TAG}' < .github/k8s/sam-sdk-probe-cronjob-template.yaml | kubectl apply -f -++ kubectl delete job "${JOB}" -n "${CANARY_NAMESPACE}" --ignore-not-found+ kubectl create job --from="cronjob/sam-sdk-probe-${ENV_NAME}" "${JOB}" -n "${CANARY_NAMESPACE}"++ for _ in $(seq 1 96); do+ status=$(kubectl get job "${JOB}" -n "${CANARY_NAMESPACE}" -o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\n"}{end}')+ case "${status}" in+ *Complete=True*) break ;;+ *Failed=True*) break ;;+ esac+ sleep 5+ done++ for lang in js python; do+ echo "==== ${lang} SDK probe output ===="+ kubectl logs "job/${JOB}" -n "${CANARY_NAMESPACE}" -c "${lang}" --tail=-1 || true+ done++ case "${status:-}" in+ *Complete=True*) echo "SDK cold-path probe passed." ;;+ *)+ echo "SDK cold-path probe did not pass: an SDK could not enroll, reach a router, or call a service a node or the other SDK serves."+ kubectl describe job "${JOB}" -n "${CANARY_NAMESPACE}" || true+ exit 1+ ;;+ esac+diff --git a/.github/workflows/sdk.yml b/.github/workflows/sdk.ymlindex 21044d87..1e83b8bf 100644--- a/.github/workflows/sdk.yml+++ b/.github/workflows/sdk.yml@@ -30,6 +30,7 @@ on:- 'hack/verify-sdk-generated.sh'- 'site/content/docs/guides/native-sdks.md'- 'tests/integration/sdk_*_test.go'+ - 'Dockerfile.sam-sdk-*'- '.github/workflows/sdk.yml'pull_request:branches: [main]@@ -41,6 +42,7 @@ on:- 'hack/verify-sdk-generated.sh'- 'site/content/docs/guides/native-sdks.md'- 'tests/integration/sdk_*_test.go'+ - 'Dockerfile.sam-sdk-*'- '.github/workflows/sdk.yml'permissions:@@ -88,3 +90,13 @@ jobs:- name: Both SDKs and the documented examples on a mesh with a real control plane, router and sam-noderun: go test ./tests/integration -run TestNativeSDK -count=1 -v++ # The images the testnets run the examples from (deploy.yaml builds and+ # pushes them on main); built here so a broken Dockerfile fails the+ # pull request, not the deploy.+ - name: SDK canary images build+ run: |+ docker build -f Dockerfile.sam-sdk-js -t sam-sdk-js:ci .+ docker build -f Dockerfile.sam-sdk-python -t sam-sdk-python:ci .+ docker run --rm sam-sdk-js:ci build/examples/call.js 2>&1 | grep -q 'exactly one of'+ docker run --rm sam-sdk-python:ci examples/call.py 2>&1 | grep -q 'exactly one of'diff --git a/Dockerfile.sam-sdk-js b/Dockerfile.sam-sdk-jsnew file mode 100644index 00000000..c9b6fd0a--- /dev/null+++ b/Dockerfile.sam-sdk-js@@ -0,0 +1,26 @@+# The JavaScript SDK with its example programs, as the testnet canaries run+# them: `node build/examples/serve.js <name>` publishes services on the mesh,+# `node build/examples/call.js <service> <tool|path> [args]` calls one. The+# examples import "@sam-mesh/sdk" by name and resolve it through the package's+# own exports, so the image keeps the package layout: package.json, dist/,+# build/examples/ and the production node_modules/.++# Stage 1: Build+FROM node:22-bookworm-slim@sha256:43ac6c60b8f89723f746e8a92ce91abd5017e627ce1ddfe4238355d3a30b772c AS builder+WORKDIR /src+COPY sdk/js/package.json sdk/js/package-lock.json sdk/js/.npmrc ./+RUN npm ci --no-fund --no-audit+COPY sdk/js/ ./+RUN npm run build && npm run examples && npm prune --omit=dev --no-fund --no-audit++# Stage 2: Final+FROM node:22-bookworm-slim@sha256:43ac6c60b8f89723f746e8a92ce91abd5017e627ce1ddfe4238355d3a30b772c+WORKDIR /app+COPY --from=builder --chown=node:node /src/package.json ./+COPY --from=builder --chown=node:node /src/dist ./dist+COPY --from=builder --chown=node:node /src/build/examples ./build/examples+COPY --from=builder --chown=node:node /src/node_modules ./node_modules+USER node+ENV HOME=/home/node+ENTRYPOINT ["node"]+CMD ["build/examples/serve.js"]diff --git a/Dockerfile.sam-sdk-python b/Dockerfile.sam-sdk-pythonnew file mode 100644index 00000000..d7ba4094--- /dev/null+++ b/Dockerfile.sam-sdk-python@@ -0,0 +1,23 @@+# The Python SDK with its example programs, as the testnet canaries run them:+# `python examples/serve.py <name>` publishes services on the mesh,+# `python examples/call.py <service> <tool|path> [args]` calls one. fastecdsa,+# a py-libp2p dependency, builds from source against GMP, so the build stage+# carries a compiler and the final image only libgmp10.++# Stage 1: Build+FROM python:3.12-slim-bookworm@sha256:392307d22300de8b5986851a12d9176dfc0fc073e65bf6523ebd7dcbeb23564e AS builder+RUN apt-get update && apt-get install -y --no-install-recommends gcc libgmp-dev python3-dev && rm -rf /var/lib/apt/lists/*+COPY sdk/python /src+RUN python -m venv /opt/venv && /opt/venv/bin/pip install --no-cache-dir /src++# Stage 2: Final+FROM python:3.12-slim-bookworm@sha256:392307d22300de8b5986851a12d9176dfc0fc073e65bf6523ebd7dcbeb23564e+RUN apt-get update && apt-get install -y --no-install-recommends libgmp10 && rm -rf /var/lib/apt/lists/* \+ && groupadd --gid 65532 nonroot && useradd --uid 65532 --gid nonroot --create-home nonroot+WORKDIR /app+COPY --from=builder --chown=nonroot:nonroot /opt/venv /opt/venv+COPY --chown=nonroot:nonroot sdk/python/examples ./examples+USER nonroot:nonroot+ENV PATH=/opt/venv/bin:$PATH+ENTRYPOINT ["python"]+CMD ["examples/serve.py"]diff --git a/sdk/README.md b/sdk/README.mdindex b3d1cf7f..98791462 100644--- a/sdk/README.md+++ b/sdk/README.md@@ -436,6 +436,22 @@ holds against the control plane's records.that verifies only under the new one, and still authenticating with the`sam-node`.+### On the testnets++Both testnets run the example programs, unchanged, as canaries beside the+`sam-node` ones (`.github/k8s/sam-sdk-canary-template.yaml`): the JavaScript+and the Python `serve` publish `mcp://greeter-js` / `a2a://greeter-js` and+`…-py`, enrolled with the pod's projected service account token through+`SAM_JWT_PATH`. Two CronJobs cross every implementation boundary every 15+minutes and once per rollout: the `sam-node` cold-path probe now also calls+both greeters (node → SDK, MCP through `call_remote_tool` and A2A through+the egress proxy), and the SDK cold-path probe+(`sam-sdk-probe-cronjob-template.yaml`) runs each SDK's `call` against the+everything canary (SDK → node) and the other SDK's greeter (SDK → SDK). The+images (`Dockerfile.sam-sdk-js`, `Dockerfile.sam-sdk-python`) are built per+commit by `deploy.yaml`, so `bananas` runs the SDKs at the same commit as+the Go components they talk to.+### Later- The connector interface for platforms (issue #480): `Attach`, `Detach`,diff --git a/sdk/js/README.md b/sdk/js/README.mdindex 4a526932..135390d5 100644--- a/sdk/js/README.md+++ b/sdk/js/README.md@@ -38,10 +38,11 @@ Find a service and call it:// node call.js a2a://greeter /card// node call.js inference://ollama /v1/models//-// SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file-// holding the token the mesh operator gave you; the first run spends it and-// keeps the identity and credential in SAM_STATE_DIR, later runs resume from-// there without it.+// SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file+// SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or+// SAM_JWT_PATH (a workload identity token your platform issues, such as a+// Kubernetes projected service account token), and keeps the identity and+// credential in SAM_STATE_DIR; later runs resume from there without it.import { homedir } from "node:os";import { AgentMesh } from "@sam-mesh/sdk";@@ -50,7 +51,10 @@ const [service = "mcp://greeter", toolOrPath = "greet", args = '{"name": "world"const mesh = await AgentMesh.enroll({controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",bootstrapTokenPath: process.env.SAM_BOOTSTRAP_TOKEN_PATH,+ jwtPath: process.env.SAM_JWT_PATH,stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/caller`,+ // A plaintext http:// control plane is otherwise accepted only on loopback.+ allowInsecure: process.env.SAM_INSECURE_CONTROL_PLANE === "true",});const session = await mesh.join();console.log(`on the mesh as ${session.peerId}`);@@ -85,31 +89,38 @@ Publish services of your own:// members may call; the SDK turns the others away before anything reaches// this code or Ollama.//-// node serve.js+// node serve.js # publishes mcp://greeter and a2a://greeter+// node serve.js greeter-2 # the same under another name//-// SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file-// holding the token the mesh operator gave you; the first run spends it and-// keeps the identity and credential in SAM_STATE_DIR, later runs resume from-// there without it.+// SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file+// SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or+// SAM_JWT_PATH (a workload identity token your platform issues, such as a+// Kubernetes projected service account token), and keeps the identity and+// credential in SAM_STATE_DIR; later runs resume from there without it.import { homedir } from "node:os";import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";import { AgentMesh } from "@sam-mesh/sdk";import { z } from "zod";+const [name = "greeter"] = process.argv.slice(2);+const mesh = await AgentMesh.enroll({controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",bootstrapTokenPath: process.env.SAM_BOOTSTRAP_TOKEN_PATH,- stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/greeter`,+ jwtPath: process.env.SAM_JWT_PATH,+ stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/${name}`,+ // A plaintext http:// control plane is otherwise accepted only on loopback.+ allowInsecure: process.env.SAM_INSECURE_CONTROL_PLANE === "true",});const session = await mesh.join();await session.serve({type: "mcp",- name: "greeter",+ name,createServer: () => {- const server = new McpServer({ name: "greeter", version: "1.0.0" });- server.registerTool("greet", { description: "Greets someone by name", inputSchema: { name: z.string() } }, async ({ name }) => ({- content: [{ type: "text", text: `hello ${name}` }],+ const server = new McpServer({ name, version: "1.0.0" });+ server.registerTool("greet", { description: "Greets someone by name", inputSchema: { name: z.string() } }, async ({ name: who }) => ({+ content: [{ type: "text", text: `hello ${who}` }],}));return server;},@@ -117,8 +128,8 @@ await session.serve({await session.serve({type: "a2a",- name: "greeter",- target: (request, caller) => Response.json({ name: "greeter", path: new URL(request.url).pathname, caller: caller.peerId }),+ name,+ target: (request, caller) => Response.json({ name, path: new URL(request.url).pathname, caller: caller.peerId }),});if (process.env.OLLAMA_URL !== undefined) {diff --git a/sdk/js/examples/call.ts b/sdk/js/examples/call.tsindex ddccacb6..124003c4 100644--- a/sdk/js/examples/call.ts+++ b/sdk/js/examples/call.ts@@ -5,10 +5,11 @@// node call.js a2a://greeter /card// node call.js inference://ollama /v1/models//-// SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file-// holding the token the mesh operator gave you; the first run spends it and-// keeps the identity and credential in SAM_STATE_DIR, later runs resume from-// there without it.+// SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file+// SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or+// SAM_JWT_PATH (a workload identity token your platform issues, such as a+// Kubernetes projected service account token), and keeps the identity and+// credential in SAM_STATE_DIR; later runs resume from there without it.import { homedir } from "node:os";import { AgentMesh } from "@sam-mesh/sdk";@@ -17,7 +18,10 @@ const [service = "mcp://greeter", toolOrPath = "greet", args = '{"name": "world"const mesh = await AgentMesh.enroll({controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",bootstrapTokenPath: process.env.SAM_BOOTSTRAP_TOKEN_PATH,+ jwtPath: process.env.SAM_JWT_PATH,stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/caller`,+ // A plaintext http:// control plane is otherwise accepted only on loopback.+ allowInsecure: process.env.SAM_INSECURE_CONTROL_PLANE === "true",});const session = await mesh.join();console.log(`on the mesh as ${session.peerId}`);diff --git a/sdk/js/examples/serve.ts b/sdk/js/examples/serve.tsindex a3c3fca0..18a75a69 100644--- a/sdk/js/examples/serve.ts+++ b/sdk/js/examples/serve.ts@@ -4,31 +4,38 @@// members may call; the SDK turns the others away before anything reaches// this code or Ollama.//-// node serve.js+// node serve.js # publishes mcp://greeter and a2a://greeter+// node serve.js greeter-2 # the same under another name//-// SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file-// holding the token the mesh operator gave you; the first run spends it and-// keeps the identity and credential in SAM_STATE_DIR, later runs resume from-// there without it.+// SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file+// SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or+// SAM_JWT_PATH (a workload identity token your platform issues, such as a+// Kubernetes projected service account token), and keeps the identity and+// credential in SAM_STATE_DIR; later runs resume from there without it.import { homedir } from "node:os";import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";import { AgentMesh } from "@sam-mesh/sdk";import { z } from "zod";+const [name = "greeter"] = process.argv.slice(2);+const mesh = await AgentMesh.enroll({controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",bootstrapTokenPath: process.env.SAM_BOOTSTRAP_TOKEN_PATH,- stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/greeter`,+ jwtPath: process.env.SAM_JWT_PATH,+ stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/${name}`,+ // A plaintext http:// control plane is otherwise accepted only on loopback.+ allowInsecure: process.env.SAM_INSECURE_CONTROL_PLANE === "true",});const session = await mesh.join();await session.serve({type: "mcp",- name: "greeter",+ name,createServer: () => {- const server = new McpServer({ name: "greeter", version: "1.0.0" });- server.registerTool("greet", { description: "Greets someone by name", inputSchema: { name: z.string() } }, async ({ name }) => ({- content: [{ type: "text", text: `hello ${name}` }],+ const server = new McpServer({ name, version: "1.0.0" });+ server.registerTool("greet", { description: "Greets someone by name", inputSchema: { name: z.string() } }, async ({ name: who }) => ({+ content: [{ type: "text", text: `hello ${who}` }],}));return server;},@@ -36,8 +43,8 @@ await session.serve({await session.serve({type: "a2a",- name: "greeter",- target: (request, caller) => Response.json({ name: "greeter", path: new URL(request.url).pathname, caller: caller.peerId }),+ name,+ target: (request, caller) => Response.json({ name, path: new URL(request.url).pathname, caller: caller.peerId }),});if (process.env.OLLAMA_URL !== undefined) {diff --git a/sdk/js/src/mesh.test.ts b/sdk/js/src/mesh.test.tsindex 500234bd..53206dd6 100644--- a/sdk/js/src/mesh.test.ts+++ b/sdk/js/src/mesh.test.ts@@ -24,6 +24,8 @@ import {AuthFrameSchema,AuthResponseSchema,BootstrapEnrollResponseSchema,+ EnrollRequestSchema,+ EnrollResponseSchema,EnrollmentStatus,KeysResponseSchema,TokenRefreshResponseSchema,@@ -66,6 +68,22 @@ function fakeControlPlane(keysOk = true): { fetch: typeof fetch; issued: numbercase "POST /refresh":state.issued++;return proto(toBinary(TokenRefreshResponseSchema, create(TokenRefreshResponseSchema, { biscuitToken: text(`biscuit-${state.issued}`), expireTime: timestampFromMs(Date.now() + 7200_000) })));+ case "POST /register": {+ // The biscuit names the JWT that was presented, so a test can see which.+ const jwt = fromBinary(EnrollRequestSchema, new Uint8Array(await req.arrayBuffer())).jwt;+ state.issued++;+ return proto(+ toBinary(+ EnrollResponseSchema,+ create(EnrollResponseSchema, {+ biscuitToken: text(`biscuit-for-${jwt}`),+ controlPlanePublicKey: cpKey.publicKeyRaw,+ routerAddresses: ["/dns4/router.example/tcp/4001/p2p/12D3KooWP8iKhDf3iCMo2H3butNVfdTUtYwYWYQ75jTGnynXPFMp"],+ expireTime: timestampFromMs(Date.now() + 3600_000),+ }),+ ),+ );+ }case "GET /keys":return keysOk ? proto(toBinary(KeysResponseSchema, signedKeys())) : new Response("boom", { status: 500 });default:@@ -161,9 +179,24 @@ test("enroll refuses ambiguous credentials", async () => {const cp = fakeControlPlane();await assert.rejects(AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", fetch: cp.fetch }), /exactly one of/);await assert.rejects(AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "a", jwt: "b", fetch: cp.fetch }), /exactly one of/);+ await assert.rejects(AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", jwt: "a", jwtPath: "/nonexistent", fetch: cp.fetch }), /exactly one of/);assert.equal(cp.issued, 0);});+test("enroll reads a workload identity token from jwtPath", async () => {+ const dir = await mkdtemp(join(tmpdir(), "sam-sdk-"));+ try {+ const cp = fakeControlPlane();+ const jwtPath = join(dir, "token");+ await writeFile(jwtPath, "eyJ.projected.token\n");+ const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", jwtPath, fetch: cp.fetch });+ assert.deepEqual(mesh.credential.biscuit, text("biscuit-for-eyJ.projected.token"));+ await assert.rejects(AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", jwtPath: join(dir, "missing"), fetch: cp.fetch }), /ENOENT/);+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});+test("authFrame is the AuthFrame protobuf with this member's biscuit", async () => {const cp = fakeControlPlane();const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt_secret", fetch: cp.fetch });diff --git a/sdk/js/src/mesh.ts b/sdk/js/src/mesh.tsindex 85cbafab..d5192207 100644--- a/sdk/js/src/mesh.ts+++ b/sdk/js/src/mesh.ts@@ -51,6 +51,12 @@ export interface EnrollOptions extends AgentMeshOptions {bootstrapTokenPath?: string | undefined;/** An OIDC ID token, for meshes that enroll identities interactively. */jwt?: string | undefined;+ /**+ * Path of a file holding an OIDC ID token or a platform's workload identity+ * token, such as a Kubernetes projected service account token. Preferred+ * over a value; the file is read at enrollment.+ */+ jwtPath?: string | undefined;/** Bounds the wait for an operator to approve a pending enrollment. */signal?: AbortSignal;/** Overrides the control plane's suggested poll interval while pending. */@@ -104,8 +110,8 @@ export class AgentMesh {* plane for the saved identity, that member is returned and no token is* needed, so a program can call enroll on every start and read the token* from its environment only on the first. Otherwise exactly one of- * bootstrapToken, bootstrapTokenPath or jwt must be given. Delete the- * state directory to enroll afresh, for instance with other labels.+ * bootstrapToken, bootstrapTokenPath, jwt or jwtPath must be given. Delete+ * the state directory to enroll afresh, for instance with other labels.*/static async enroll(options: EnrollOptions): Promise<AgentMesh> {const saved = await loadIdentity(options.stateDir);@@ -117,16 +123,17 @@ export class AgentMesh {return new AgentMesh(identity, controlPlane, credential, options.stateDir);}}- const given = [options.bootstrapToken, options.bootstrapTokenPath, options.jwt].filter((v) => v !== undefined).length;+ const given = [options.bootstrapToken, options.bootstrapTokenPath, options.jwt, options.jwtPath].filter((v) => v !== undefined).length;if (given !== 1) {const where = options.stateDir !== undefined ? ` (no credential to resume in ${options.stateDir})` : "";- throw new Error(`exactly one of bootstrapToken, bootstrapTokenPath or jwt is required${where}`);+ throw new Error(`exactly one of bootstrapToken, bootstrapTokenPath, jwt or jwtPath is required${where}`);}const role = options.role ?? ROLE_NODE;let enrollment: Enrollment;- if (options.jwt !== undefined) {- enrollment = await controlPlane.register({ identity, jwt: options.jwt, role, ...labelsOf(options) });+ if (options.jwt !== undefined || options.jwtPath !== undefined) {+ const jwt = options.jwtPath !== undefined ? (await readFile(options.jwtPath, "utf8")).trim() : (options.jwt as string);+ enrollment = await controlPlane.register({ identity, jwt, role, ...labelsOf(options) });} else {const bootstrapToken = options.bootstrapTokenPath !== undefined ? (await readFile(options.bootstrapTokenPath, "utf8")).trim() : (options.bootstrapToken as string);enrollment = await controlPlane.enrollBootstrap({diff --git a/sdk/python/README.md b/sdk/python/README.mdindex 7a6288c8..b5f800f9 100644--- a/sdk/python/README.md+++ b/sdk/python/README.md@@ -41,10 +41,11 @@ path of an inference or A2A service.python call.py a2a://greeter /cardpython call.py inference://ollama /v1/models-SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file-holding the token the mesh operator gave you; the first run spends it and-keeps the identity and credential in SAM_STATE_DIR, later runs resume from-there without it.+SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file+SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH+(a workload identity token your platform issues, such as a Kubernetes+projected service account token), and keeps the identity and credential in+SAM_STATE_DIR; later runs resume from there without it."""import json@@ -62,7 +63,10 @@ args = json.loads(argv[2]) if len(argv) > 2 else {"name": "world"}mesh = AgentMesh.enroll(os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),bootstrap_token_path=os.environ.get("SAM_BOOTSTRAP_TOKEN_PATH"),+ jwt_path=os.environ.get("SAM_JWT_PATH"),state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/caller"),+ # A plaintext http:// control plane is otherwise accepted only on loopback.+ allow_insecure=os.environ.get("SAM_INSECURE_CONTROL_PLANE") == "true",)@@ -100,30 +104,38 @@ beside this program as an inference service. The mesh policy decides whichmembers may call; the SDK turns the others away before anything reaches thiscode or Ollama.- python serve.py+ python serve.py # publishes mcp://greeter and a2a://greeter+ python serve.py greeter-2 # the same under another name-SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file-holding the token the mesh operator gave you; the first run spends it and-keeps the identity and credential in SAM_STATE_DIR, later runs resume from-there without it.+SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file+SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH+(a workload identity token your platform issues, such as a Kubernetes+projected service account token), and keeps the identity and credential in+SAM_STATE_DIR; later runs resume from there without it."""import jsonimport os+import sysimport triofrom agent_mesh import AgentMesh, HTTPRequest, HTTPResponse, HTTPService, MCPService, VerifiedBiscuitfrom mcp.server.mcpserver import MCPServer+service_name = sys.argv[1] if len(sys.argv) > 1 else "greeter"+mesh = AgentMesh.enroll(os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),bootstrap_token_path=os.environ.get("SAM_BOOTSTRAP_TOKEN_PATH"),- state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/greeter"),+ jwt_path=os.environ.get("SAM_JWT_PATH"),+ state_dir=os.environ.get("SAM_STATE_DIR", f"~/.config/sam-mesh/{service_name}"),+ # A plaintext http:// control plane is otherwise accepted only on loopback.+ allow_insecure=os.environ.get("SAM_INSECURE_CONTROL_PLANE") == "true",)def create_server() -> MCPServer:- server = MCPServer("greeter")+ server = MCPServer(service_name)@server.tool(description="Greets someone by name")def greet(name: str) -> str:@@ -133,14 +145,14 @@ def create_server() -> MCPServer:async def card(request: HTTPRequest, caller: VerifiedBiscuit) -> HTTPResponse:- body = json.dumps({"name": "greeter", "path": request.path, "caller": caller.peer_id})+ body = json.dumps({"name": service_name, "path": request.path, "caller": caller.peer_id})return HTTPResponse(status=200, headers={"content-type": "application/json"}, body=body.encode())async def main() -> None:async with mesh.join() as session:- await session.serve(MCPService(name="greeter", create_server=create_server))- await session.serve(HTTPService(type="a2a", name="greeter", target=card))+ await session.serve(MCPService(name=service_name, create_server=create_server))+ await session.serve(HTTPService(type="a2a", name=service_name, target=card))if "OLLAMA_URL" in os.environ:await session.serve(HTTPService(type="inference", name="ollama", target=os.environ["OLLAMA_URL"]))diff --git a/sdk/python/examples/call.py b/sdk/python/examples/call.pyindex 721838dc..f37c1985 100644--- a/sdk/python/examples/call.py+++ b/sdk/python/examples/call.py@@ -5,10 +5,11 @@ path of an inference or A2A service.python call.py a2a://greeter /cardpython call.py inference://ollama /v1/models-SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file-holding the token the mesh operator gave you; the first run spends it and-keeps the identity and credential in SAM_STATE_DIR, later runs resume from-there without it.+SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file+SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH+(a workload identity token your platform issues, such as a Kubernetes+projected service account token), and keeps the identity and credential in+SAM_STATE_DIR; later runs resume from there without it."""import json@@ -26,7 +27,10 @@ args = json.loads(argv[2]) if len(argv) > 2 else {"name": "world"}mesh = AgentMesh.enroll(os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),bootstrap_token_path=os.environ.get("SAM_BOOTSTRAP_TOKEN_PATH"),+ jwt_path=os.environ.get("SAM_JWT_PATH"),state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/caller"),+ # A plaintext http:// control plane is otherwise accepted only on loopback.+ allow_insecure=os.environ.get("SAM_INSECURE_CONTROL_PLANE") == "true",)diff --git a/sdk/python/examples/serve.py b/sdk/python/examples/serve.pyindex 7f5e2935..6821732a 100644--- a/sdk/python/examples/serve.py+++ b/sdk/python/examples/serve.py@@ -4,30 +4,38 @@ beside this program as an inference service. The mesh policy decides whichmembers may call; the SDK turns the others away before anything reaches thiscode or Ollama.- python serve.py--SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file-holding the token the mesh operator gave you; the first run spends it and-keeps the identity and credential in SAM_STATE_DIR, later runs resume from-there without it.+ python serve.py # publishes mcp://greeter and a2a://greeter+ python serve.py greeter-2 # the same under another name++SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file+SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH+(a workload identity token your platform issues, such as a Kubernetes+projected service account token), and keeps the identity and credential in+SAM_STATE_DIR; later runs resume from there without it."""import jsonimport os+import sysimport triofrom agent_mesh import AgentMesh, HTTPRequest, HTTPResponse, HTTPService, MCPService, VerifiedBiscuitfrom mcp.server.mcpserver import MCPServer+service_name = sys.argv[1] if len(sys.argv) > 1 else "greeter"+mesh = AgentMesh.enroll(os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),bootstrap_token_path=os.environ.get("SAM_BOOTSTRAP_TOKEN_PATH"),- state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/greeter"),+ jwt_path=os.environ.get("SAM_JWT_PATH"),+ state_dir=os.environ.get("SAM_STATE_DIR", f"~/.config/sam-mesh/{service_name}"),+ # A plaintext http:// control plane is otherwise accepted only on loopback.+ allow_insecure=os.environ.get("SAM_INSECURE_CONTROL_PLANE") == "true",)def create_server() -> MCPServer:- server = MCPServer("greeter")+ server = MCPServer(service_name)@server.tool(description="Greets someone by name")def greet(name: str) -> str:@@ -37,14 +45,14 @@ def create_server() -> MCPServer:async def card(request: HTTPRequest, caller: VerifiedBiscuit) -> HTTPResponse:- body = json.dumps({"name": "greeter", "path": request.path, "caller": caller.peer_id})+ body = json.dumps({"name": service_name, "path": request.path, "caller": caller.peer_id})return HTTPResponse(status=200, headers={"content-type": "application/json"}, body=body.encode())async def main() -> None:async with mesh.join() as session:- await session.serve(MCPService(name="greeter", create_server=create_server))- await session.serve(HTTPService(type="a2a", name="greeter", target=card))+ await session.serve(MCPService(name=service_name, create_server=create_server))+ await session.serve(HTTPService(type="a2a", name=service_name, target=card))if "OLLAMA_URL" in os.environ:await session.serve(HTTPService(type="inference", name="ollama", target=os.environ["OLLAMA_URL"]))diff --git a/sdk/python/src/agent_mesh/mesh.py b/sdk/python/src/agent_mesh/mesh.pyindex 748c006e..ce1b642b 100644--- a/sdk/python/src/agent_mesh/mesh.py+++ b/sdk/python/src/agent_mesh/mesh.py@@ -74,6 +74,7 @@ class AgentMesh:bootstrap_token: Optional[str] = None,bootstrap_token_path: Optional[str | os.PathLike[str]] = None,jwt: Optional[str] = None,+ jwt_path: Optional[str | os.PathLike[str]] = None,state_dir: Optional[str | os.PathLike[str]] = None,identity: Optional[Identity] = None,role: str = ROLE_NODE,@@ -89,9 +90,11 @@ class AgentMesh:plane for the saved identity, that member is returned and no token isneeded, so a program can call enroll on every start and read the tokenfrom its environment only on the first. Otherwise exactly one of- bootstrap_token, bootstrap_token_path or jwt must be given; a token is- better read from a file than passed as a value. Delete the state- directory to enroll afresh, for instance with other labels."""+ bootstrap_token, bootstrap_token_path, jwt or jwt_path must be given; a+ token is better read from a file than passed as a value, and jwt_path+ also takes a platform's workload identity token, such as a Kubernetes+ projected service account token. Delete the state directory to enroll+ afresh, for instance with other labels."""state = Path(state_dir).expanduser() if state_dir is not None else Nonesaved = _load_identity(state)identity = identity or saved or Identity.generate()@@ -100,13 +103,16 @@ class AgentMesh:credential = _load_credential(state)if credential is not None and credential.control_plane_url.rstrip("/") == control_plane.url.rstrip("/") and credential.time_to_live_seconds() > _REUSE_MIN_TTL_SECONDS:return cls(identity, control_plane, credential, state)- given = sum(v is not None for v in (bootstrap_token, bootstrap_token_path, jwt))+ given = sum(v is not None for v in (bootstrap_token, bootstrap_token_path, jwt, jwt_path))if given != 1:where = f" (no credential to resume in {state})" if state is not None else ""- raise ValueError(f"exactly one of bootstrap_token, bootstrap_token_path or jwt is required{where}")+ raise ValueError(f"exactly one of bootstrap_token, bootstrap_token_path, jwt or jwt_path is required{where}")enrollment: Enrollment- if jwt is not None:+ if jwt is not None or jwt_path is not None:+ if jwt_path is not None:+ jwt = Path(jwt_path).expanduser().read_text().strip()+ assert jwt is not Noneenrollment = control_plane.register(identity, jwt, role=role, labels=labels)else:if bootstrap_token_path is not None:diff --git a/sdk/python/tests/test_mesh.py b/sdk/python/tests/test_mesh.pyindex ead4917d..0af392d1 100644--- a/sdk/python/tests/test_mesh.py+++ b/sdk/python/tests/test_mesh.py@@ -55,6 +55,16 @@ class FakeControlPlane:def transport(self, method, url, headers, body):path = urllib.parse.urlsplit(url).path+ if (method, path) == ("POST", "/register"):+ # The biscuit names the JWT that was presented, so a test can see which.+ jwt = pb.EnrollRequest.FromString(body).jwt+ self.issued += 1+ return 200, pb.EnrollResponse(+ biscuit_token=f"biscuit-for-{jwt}".encode(),+ control_plane_public_key=CP_KEY.public_key_raw,+ router_addresses=["/dns4/router.example/tcp/4001/p2p/12D3KooWP8iKhDf3iCMo2H3butNVfdTUtYwYWYQ75jTGnynXPFMp"],+ expire_time=_ts_s(int(time.time()) + 3600),+ ).SerializeToString()if (method, path) == ("POST", "/enroll"):self.issued += 1return 200, pb.BootstrapEnrollResponse(@@ -149,9 +159,21 @@ def test_enroll_refuses_ambiguous_credentials():AgentMesh.enroll("http://127.0.0.1:1", transport=cp.transport)with pytest.raises(ValueError, match="exactly one of"):AgentMesh.enroll("http://127.0.0.1:1", bootstrap_token="a", jwt="b", transport=cp.transport)+ with pytest.raises(ValueError, match="exactly one of"):+ AgentMesh.enroll("http://127.0.0.1:1", jwt="a", jwt_path="/nonexistent", transport=cp.transport)assert cp.issued == 0+def test_enroll_reads_a_workload_identity_token_from_jwt_path(tmp_path):+ cp = FakeControlPlane()+ token = tmp_path / "token"+ token.write_text("eyJ.projected.token\n")+ mesh = AgentMesh.enroll("http://127.0.0.1:1", jwt_path=token, transport=cp.transport)+ assert mesh.credential.biscuit == b"biscuit-for-eyJ.projected.token"+ with pytest.raises(FileNotFoundError):+ AgentMesh.enroll("http://127.0.0.1:1", jwt_path=tmp_path / "missing", transport=cp.transport)++def test_load_without_identity_says_enroll_first(tmp_path):with pytest.raises(FileNotFoundError, match="no identity"):AgentMesh.load(tmp_path)diff --git a/site/content/docs/guides/native-sdks.md b/site/content/docs/guides/native-sdks.mdindex 3be874cc..85e81e52 100644--- a/site/content/docs/guides/native-sdks.md+++ b/site/content/docs/guides/native-sdks.md@@ -76,7 +76,18 @@ export SAM_BOOTSTRAP_TOKEN_PATH=~/sam-one/join-tokenA plain `http://` URL is accepted only for a control plane on the samemachine. Anything else needs `https://`, because the control plane is thetrust root of every member and the SDK refuses to fetch it over plaintext-from a remote address.+from a remote address. Inside a network you already trust, such as a+Kubernetes cluster where the control plane is a cluster-local service, set+`SAM_INSECURE_CONTROL_PLANE=true` (`allowInsecure` in code), the same choice+as `sam-node --insecure-control-plane`.++On a platform that issues workload identity tokens, a program needs no+bootstrap token. A mesh whose control plane trusts the platform's issuer+enrolls the program from that token instead; on Kubernetes that is a+projected service account token, as [Headless enrollment](../headless-enrollment/)+shows for `sam-node`. Set `SAM_JWT_PATH` to the token file rather than+`SAM_BOOTSTRAP_TOKEN_PATH`. That is how the public testnets run these same+programs as canaries beside the `sam-node` ones.## 2. Install the SDK@@ -111,31 +122,38 @@ JavaScript, `serve.js`:// members may call; the SDK turns the others away before anything reaches// this code or Ollama.//-// node serve.js+// node serve.js # publishes mcp://greeter and a2a://greeter+// node serve.js greeter-2 # the same under another name//-// SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file-// holding the token the mesh operator gave you; the first run spends it and-// keeps the identity and credential in SAM_STATE_DIR, later runs resume from-// there without it.+// SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file+// SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or+// SAM_JWT_PATH (a workload identity token your platform issues, such as a+// Kubernetes projected service account token), and keeps the identity and+// credential in SAM_STATE_DIR; later runs resume from there without it.import { homedir } from "node:os";import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";import { AgentMesh } from "@sam-mesh/sdk";import { z } from "zod";+const [name = "greeter"] = process.argv.slice(2);+const mesh = await AgentMesh.enroll({controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",bootstrapTokenPath: process.env.SAM_BOOTSTRAP_TOKEN_PATH,- stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/greeter`,+ jwtPath: process.env.SAM_JWT_PATH,+ stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/${name}`,+ // A plaintext http:// control plane is otherwise accepted only on loopback.+ allowInsecure: process.env.SAM_INSECURE_CONTROL_PLANE === "true",});const session = await mesh.join();await session.serve({type: "mcp",- name: "greeter",+ name,createServer: () => {- const server = new McpServer({ name: "greeter", version: "1.0.0" });- server.registerTool("greet", { description: "Greets someone by name", inputSchema: { name: z.string() } }, async ({ name }) => ({- content: [{ type: "text", text: `hello ${name}` }],+ const server = new McpServer({ name, version: "1.0.0" });+ server.registerTool("greet", { description: "Greets someone by name", inputSchema: { name: z.string() } }, async ({ name: who }) => ({+ content: [{ type: "text", text: `hello ${who}` }],}));return server;},@@ -143,8 +161,8 @@ await session.serve({await session.serve({type: "a2a",- name: "greeter",- target: (request, caller) => Response.json({ name: "greeter", path: new URL(request.url).pathname, caller: caller.peerId }),+ name,+ target: (request, caller) => Response.json({ name, path: new URL(request.url).pathname, caller: caller.peerId }),});if (process.env.OLLAMA_URL !== undefined) {@@ -169,30 +187,38 @@ beside this program as an inference service. The mesh policy decides whichmembers may call; the SDK turns the others away before anything reaches thiscode or Ollama.- python serve.py+ python serve.py # publishes mcp://greeter and a2a://greeter+ python serve.py greeter-2 # the same under another name-SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file-holding the token the mesh operator gave you; the first run spends it and-keeps the identity and credential in SAM_STATE_DIR, later runs resume from-there without it.+SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file+SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH+(a workload identity token your platform issues, such as a Kubernetes+projected service account token), and keeps the identity and credential in+SAM_STATE_DIR; later runs resume from there without it."""import jsonimport os+import sysimport triofrom agent_mesh import AgentMesh, HTTPRequest, HTTPResponse, HTTPService, MCPService, VerifiedBiscuitfrom mcp.server.mcpserver import MCPServer+service_name = sys.argv[1] if len(sys.argv) > 1 else "greeter"+mesh = AgentMesh.enroll(os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),bootstrap_token_path=os.environ.get("SAM_BOOTSTRAP_TOKEN_PATH"),- state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/greeter"),+ jwt_path=os.environ.get("SAM_JWT_PATH"),+ state_dir=os.environ.get("SAM_STATE_DIR", f"~/.config/sam-mesh/{service_name}"),+ # A plaintext http:// control plane is otherwise accepted only on loopback.+ allow_insecure=os.environ.get("SAM_INSECURE_CONTROL_PLANE") == "true",)def create_server() -> MCPServer:- server = MCPServer("greeter")+ server = MCPServer(service_name)@server.tool(description="Greets someone by name")def greet(name: str) -> str:@@ -202,14 +228,14 @@ def create_server() -> MCPServer:async def card(request: HTTPRequest, caller: VerifiedBiscuit) -> HTTPResponse:- body = json.dumps({"name": "greeter", "path": request.path, "caller": caller.peer_id})+ body = json.dumps({"name": service_name, "path": request.path, "caller": caller.peer_id})return HTTPResponse(status=200, headers={"content-type": "application/json"}, body=body.encode())async def main() -> None:async with mesh.join() as session:- await session.serve(MCPService(name="greeter", create_server=create_server))- await session.serve(HTTPService(type="a2a", name="greeter", target=card))+ await session.serve(MCPService(name=service_name, create_server=create_server))+ await session.serve(HTTPService(type="a2a", name=service_name, target=card))if "OLLAMA_URL" in os.environ:await session.serve(HTTPService(type="inference", name="ollama", target=os.environ["OLLAMA_URL"]))@@ -257,10 +283,11 @@ JavaScript, `call.js`:// node call.js a2a://greeter /card// node call.js inference://ollama /v1/models//-// SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file-// holding the token the mesh operator gave you; the first run spends it and-// keeps the identity and credential in SAM_STATE_DIR, later runs resume from-// there without it.+// SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file+// SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or+// SAM_JWT_PATH (a workload identity token your platform issues, such as a+// Kubernetes projected service account token), and keeps the identity and+// credential in SAM_STATE_DIR; later runs resume from there without it.import { homedir } from "node:os";import { AgentMesh } from "@sam-mesh/sdk";@@ -269,7 +296,10 @@ const [service = "mcp://greeter", toolOrPath = "greet", args = '{"name": "world"const mesh = await AgentMesh.enroll({controlPlaneUrl: process.env.SAM_CONTROL_PLANE_URL ?? "https://mesh.example.com",bootstrapTokenPath: process.env.SAM_BOOTSTRAP_TOKEN_PATH,+ jwtPath: process.env.SAM_JWT_PATH,stateDir: process.env.SAM_STATE_DIR ?? `${homedir()}/.config/sam-mesh/caller`,+ // A plaintext http:// control plane is otherwise accepted only on loopback.+ allowInsecure: process.env.SAM_INSECURE_CONTROL_PLANE === "true",});const session = await mesh.join();console.log(`on the mesh as ${session.peerId}`);@@ -305,10 +335,11 @@ path of an inference or A2A service.python call.py a2a://greeter /cardpython call.py inference://ollama /v1/models-SAM_CONTROL_PLANE_URL names the mesh. SAM_BOOTSTRAP_TOKEN_PATH is the file-holding the token the mesh operator gave you; the first run spends it and-keeps the identity and credential in SAM_STATE_DIR, later runs resume from-there without it.+SAM_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file+SAM_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or SAM_JWT_PATH+(a workload identity token your platform issues, such as a Kubernetes+projected service account token), and keeps the identity and credential in+SAM_STATE_DIR; later runs resume from there without it."""import json@@ -326,7 +357,10 @@ args = json.loads(argv[2]) if len(argv) > 2 else {"name": "world"}mesh = AgentMesh.enroll(os.environ.get("SAM_CONTROL_PLANE_URL", "https://mesh.example.com"),bootstrap_token_path=os.environ.get("SAM_BOOTSTRAP_TOKEN_PATH"),+ jwt_path=os.environ.get("SAM_JWT_PATH"),state_dir=os.environ.get("SAM_STATE_DIR", "~/.config/sam-mesh/caller"),+ # A plaintext http:// control plane is otherwise accepted only on loopback.+ allow_insecure=os.environ.get("SAM_INSECURE_CONTROL_PLANE") == "true",)diff --git a/tests/integration/sdk_examples_test.go b/tests/integration/sdk_examples_test.goindex 202df849..d0b869e5 100644--- a/tests/integration/sdk_examples_test.go+++ b/tests/integration/sdk_examples_test.go@@ -30,6 +30,8 @@ import ("sync""testing""time"++ "github.com/google/sam/api")// sdkExampleLauncher starts one of the example programs the SDK READMEs and@@ -75,22 +77,26 @@ var sdkExampleLaunchers = []sdkExampleLauncher{// sdkExampleServer is a running serve example.type sdkExampleServer struct {- name string- peerID string+ name string+ // service is what it publishes, greeter-<lang>, as the testnet canaries do.+ service string+ peerID string}var servingLine = regexp.MustCompile(`^serving (.*) as (\S+)$`)// TestNativeSDKExamples runs the programs the SDK READMEs and the Native-// SDKs guide embed, unchanged, against a real mesh. Each SDK's serve-// example publishes mcp://greeter, a2a://greeter and inference://ollama,-// the last forwarding to a stand-in for Ollama this test runs. Each SDK's-// call example then reaches the sam-node's mcp://calc and a greeter, which-// is whichever serve example the DHT lists first when both toolchains are-// present, naming providers only by what discover returned; the SDK finds-// the path through the router by itself. The first run spends a bootstrap-// token, the later runs resume from the state directory without one.-// Cross-language calls with a fixed pairing are TestNativeSDKsMesh's job.+// SDKs guide embed, unchanged, against a real mesh, configured as the+// testnet canaries are (.github/k8s/sam-sdk-canary-template.yaml). Each+// SDK's serve example enrolls with an OIDC token through SAM_JWT_PATH, the+// way a Kubernetes workload does, and publishes mcp://greeter-<lang>,+// a2a://greeter-<lang> and inference://ollama, the last forwarding to a+// stand-in for Ollama this test runs. Each SDK's call example enrolls with+// a bootstrap token, reaches the sam-node's mcp://calc and the other+// language's greeter (its own when the other toolchain is missing), naming+// providers only by what discover returned; the SDK finds the path through+// the router by itself. The first run spends the token, the later runs+// resume from the state directory without one.func TestNativeSDKExamples(t *testing.T) {mesh := startSDKMesh(t)@@ -107,7 +113,7 @@ func TestNativeSDKExamples(t *testing.T) {var launchers []sdkExampleLaunchervar cmds []*exec.Cmdfor _, l := range sdkExampleLaunchers {- cmd, skip := l.cmd(context.Background(), mesh.root, "serve")+ cmd, skip := l.cmd(context.Background(), mesh.root, "serve", "greeter-"+l.name)if skip != "" {t.Logf("%s SDK skipped: %s", l.name, skip)continue@@ -122,13 +128,14 @@ func TestNativeSDKExamples(t *testing.T) {errs := make([]error, len(launchers))var wg sync.WaitGroupfor i := range launchers {- tokenPath := filepath.Join(t.TempDir(), "join-token")- if err := os.WriteFile(tokenPath, []byte(mintBootstrapToken(t, mesh.baseURL, mesh.adminToken)+"\n"), 0o600); err != nil {+ jwtPath := filepath.Join(t.TempDir(), "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)}cmds[i].Env = append(os.Environ(),"SAM_CONTROL_PLANE_URL="+mesh.baseURL,- "SAM_BOOTSTRAP_TOKEN_PATH="+tokenPath,+ "SAM_JWT_PATH="+jwtPath,"SAM_STATE_DIR="+filepath.Join(t.TempDir(), "state"),"OLLAMA_URL="+ollama.URL,)@@ -136,7 +143,7 @@ func TestNativeSDKExamples(t *testing.T) {wg.Add(1)go func(i int) {defer wg.Done()- servers[i], errs[i] = startExampleServer(t, launchers[i].name, cmds[i])+ servers[i], errs[i] = startExampleServer(t, launchers[i].name, "greeter-"+launchers[i].name, cmds[i])}(i)}wg.Wait()@@ -149,19 +156,26 @@ func TestNativeSDKExamples(t *testing.T) {waitForPeerOnRouter(t, mesh.cpPort, mesh.adminToken, s.peerID, 5*time.Second)}- servedBy := func(t *testing.T, out, service string) {- t.Helper()- got := expectLine(t, out, service+" is served by ")+ // The greeter a caller of one language targets: the other language's,+ // as the testnet probes do, or its own when it is the only one present.+ peerServer := func(name string) *sdkExampleServer {for _, s := range servers {- if s.peerID == got {- return+ if s.name != name {+ return s}}- t.Fatalf("%s is served by %s, which is none of the serve examples", service, got)+ return servers[0]+ }+ servedBy := func(t *testing.T, out string, want *sdkExampleServer, serviceType string) {+ t.Helper()+ if got := expectLine(t, out, serviceType+"://"+want.service+" is served by "); got != want.peerID {+ t.Fatalf("%s://%s is served by %s, want the %s serve example %s", serviceType, want.service, got, want.name, want.peerID)+ }}for _, l := range launchers {l := l+ target := peerServer(l.name)t.Run(l.name+"-calls", func(t *testing.T) {t.Parallel()stateDir := filepath.Join(t.TempDir(), "state")@@ -187,11 +201,11 @@ func TestNativeSDKExamples(t *testing.T) {if err := os.Remove(tokenPath); err != nil {t.Fatal(err)}- out = runExample(t, mesh, l, withoutToken, "a2a://greeter", "/card")+ out = runExample(t, mesh, l, withoutToken, "a2a://"+target.service, "/card")if got := expectLine(t, out, "on the mesh as "); got != caller {t.Fatalf("second run joined as %s, want the identity of the first run %s", got, caller)}- servedBy(t, out, "a2a://greeter")+ servedBy(t, out, target, "a2a")card := expectLine(t, out, "200 ")if !strings.Contains(card, `"path": "/card"`) && !strings.Contains(card, `"path":"/card"`) {t.Fatalf("a2a card %q does not echo the path", card)@@ -200,7 +214,9 @@ func TestNativeSDKExamples(t *testing.T) {t.Fatalf("a2a card %q does not name the verified caller %s", card, caller)}out = runExample(t, mesh, l, withoutToken, "inference://ollama", "/v1/models")- servedBy(t, out, "inference://ollama")+ if got := expectLine(t, out, "inference://ollama is served by "); got != servers[0].peerID && (len(servers) < 2 || got != servers[1].peerID) {+ t.Fatalf("inference://ollama is served by %s, which is none of the serve examples", got)+ }models := expectLine(t, out, "200 ")if !strings.Contains(models, `"gemma3"`) || !strings.Contains(models, caller) {t.Fatalf("models %q: want gemma3 owned by the caller %s", models, caller)@@ -214,7 +230,7 @@ func TestNativeSDKExamples(t *testing.T) {if other.name == l.name {continue}- out := runExample(t, mesh, other, withoutToken, "mcp://greeter", "greet", `{"name": "sam"}`)+ out := runExample(t, mesh, other, withoutToken, "mcp://"+target.service, "greet", `{"name": "sam"}`)if got := expectLine(t, out, "on the mesh as "); got != caller {t.Fatalf("%s resumed %s's state directory as %s, want %s", other.name, l.name, got, caller)}@@ -227,10 +243,16 @@ func TestNativeSDKExamples(t *testing.T) {importedAPI := importedNode.waitForAPI(t)waitForPeerOnRouter(t, mesh.cpPort, mesh.adminToken, caller, 10*time.Second)answer, err := callMCPAllowError(t, importedAPI, "imported-token", "call_remote_tool", map[string]any{- "peer_id": servers[0].peerID, "tool_name": "mcp://greeter/greet", "arguments": map[string]any{"name": "node"},+ "peer_id": target.peerID, "tool_name": "mcp://" + target.service + "/greet", "arguments": map[string]any{"name": "node"},})if err != nil || !strings.Contains(answer, "hello node") {- t.Fatalf("sam-node running %s's identity could not call greeter: %v\n%s", l.name, err, answer)+ t.Fatalf("sam-node running %s's identity could not call %s: %v\n%s", l.name, target.service, err, answer)+ }+ // The node's A2A egress path reaches the SDK's handler too, as the+ // testnet's node probe expects.+ status, body := egressGet(t, importedAPI, "imported-token", "/sam/"+target.peerID+"/a2a/"+target.service+"/card")+ if status != 200 || !strings.Contains(body, `"caller"`) || !strings.Contains(body, caller) {+ t.Fatalf("a2a card through the node: %d %s", status, body)}})}@@ -264,7 +286,7 @@ func importStateIntoNode(t *testing.T, mesh *sdkMesh, stateDir string) *backgrou// startExampleServer starts a configured serve example and waits for its// "serving ... as <peer>" line. Safe to call from several goroutines at// once, so it reports failures instead of ending the test.-func startExampleServer(t *testing.T, name string, cmd *exec.Cmd) (*sdkExampleServer, error) {+func startExampleServer(t *testing.T, name, service string, cmd *exec.Cmd) (*sdkExampleServer, error) {stderr := &bytes.Buffer{}cmd.Stderr = stderrstdout, err := cmd.StdoutPipe()@@ -306,12 +328,12 @@ func startExampleServer(t *testing.T, name string, cmd *exec.Cmd) (*sdkExampleSereturn nil, fmt.Errorf("%s serve example exited before serving\nstderr:\n%s", name, stderr.String())}m := servingLine.FindStringSubmatch(line)- for _, want := range []string{"mcp://greeter", "a2a://greeter", "inference://ollama"} {+ for _, want := range []string{"mcp://" + service, "a2a://" + service, "inference://ollama"} {if !strings.Contains(m[1], want) {return nil, fmt.Errorf("%s serve example serves %q, want %s among them", name, m[1], want)}}- return &sdkExampleServer{name: name, peerID: m[2]}, nil+ return &sdkExampleServer{name: name, service: service, peerID: m[2]}, nilcase <-time.After(30 * time.Second):return nil, fmt.Errorf("%s serve example did not report serving within 30s\nstderr:\n%s", name, stderr.String())}diff --git a/tests/integration/sdk_mesh_test.go b/tests/integration/sdk_mesh_test.goindex 60fed942..fec4eb0a 100644--- a/tests/integration/sdk_mesh_test.go+++ b/tests/integration/sdk_mesh_test.go@@ -67,6 +67,9 @@ type sdkMesh struct {routerPeer stringsamNode *backgroundNodenodeAPI string+ // mintToken mints an OIDC token the control plane accepts, as a platform's+ // workload identity token would be.+ mintToken func(map[string]interface{}) string}const sdkMeshAdminToken = "test-admin-token"@@ -172,6 +175,7 @@ bindings:routerPeer: extractPeerID(routerAddr),samNode: samNode,nodeAPI: samNode.waitForAPI(t),+ mintToken: mintToken,}}