Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
sdk: name peers, not addresses; enroll resumes saved state
Antonio Ojeae90d0a514398
diff --git a/sdk/js/src/conformance.ts b/sdk/js/src/conformance.tsindex 12f47d67..f0881118 100644--- a/sdk/js/src/conformance.ts+++ b/sdk/js/src/conformance.ts@@ -45,7 +45,7 @@ async function main(): Promise<void> {const mesh = await AgentMesh.enroll({ controlPlaneUrl, allowInsecure, stateDir, bootstrapTokenPath, pollIntervalMs: 200 });const enrolled = mesh.credential;- const reloaded = await AgentMesh.load({ controlPlaneUrl, allowInsecure, stateDir });+ const reloaded = await AgentMesh.load({ allowInsecure, stateDir });const refreshed = await reloaded.refresh();process.stdout.write(diff --git a/sdk/js/src/controlplane.ts b/sdk/js/src/controlplane.tsindex 93066e33..a624b5f6 100644--- a/sdk/js/src/controlplane.ts+++ b/sdk/js/src/controlplane.ts@@ -81,7 +81,7 @@ export class InsecureControlPlaneURLError extends Error {}export interface ControlPlaneClientOptions {- /** Base URL, e.g. https://hub.sam-mesh.dev. */+ /** Base URL, e.g. https://mesh.example.com. */url: string;/** Accept plaintext http:// to a non-loopback host. Off by default. */allowInsecure?: boolean;diff --git a/sdk/js/src/discovery.ts b/sdk/js/src/discovery.tsindex e66372b5..2f1dde41 100644--- a/sdk/js/src/discovery.ts+++ b/sdk/js/src/discovery.ts@@ -24,6 +24,10 @@ export const DHT_PROTOCOL = "/sam/kad/1.0.0";export type ServiceType = "mcp" | "inference" | "a2a";+export function isServiceType(value: unknown): value is ServiceType {+ return value === "mcp" || value === "inference" || value === "a2a";+}+/** The DHT key of a service: by type and name, or by type alone when name is omitted. */export async function serviceCID(type: ServiceType, name?: string): Promise<CID> {const key = ["sam:service", type, ...(name !== undefined && name !== "" ? [name] : [])].join(":");diff --git a/sdk/js/src/index.ts b/sdk/js/src/index.tsindex 37140837..42db0ac6 100644--- a/sdk/js/src/index.ts+++ b/sdk/js/src/index.ts@@ -38,11 +38,11 @@ export {type MeshCredential,} from "./credential.ts";export { enrollChallenge, enrollStatusChallenge, refreshChallenge, registerChallenge } from "./challenges.ts";-export { MeshSession, type AdmittedRouter, type DiscoveredProvider, type JoinOptions, type ToolCallResult } from "./session.ts";+export { MeshSession, type AdmittedRouter, type DiscoveredProvider, type JoinOptions, type Peer, type ToolCallResult } from "./session.ts";export { BiscuitVerificationError, ROLE_ROUTER, requireRole, verifyPeerBiscuit, type VerifiedBiscuit } from "./biscuit.ts";export { AUTH_HANDLER_OPTIONS, AUTH_PROTOCOL, MCP_PROTOCOL, AuthRejectedError, authenticateWithPeer, authStreamHandler } from "./auth.ts";export { createMeshHost, type MeshHost, type MeshHostOptions } from "./host.ts";-export { DHT_PROTOCOL, parseServiceTarget, serviceCID, type ServiceType } from "./discovery.ts";+export { DHT_PROTOCOL, isServiceType, parseServiceTarget, serviceCID, type ServiceType } from "./discovery.ts";export { LabelsNotSatisfiedError, StreamTransport, openMCPSession, requireLabels, type MCPSession, type MCPSessionOptions } from "./mcp.ts";export { AuthorizationError, authorizeCaller, type AuthorizeRequest, type ProviderAuthorizerOptions } from "./authorizer.ts";export {diff --git a/sdk/js/src/mesh.test.ts b/sdk/js/src/mesh.test.tsindex 2675e7e8..52401208 100644--- a/sdk/js/src/mesh.test.ts+++ b/sdk/js/src/mesh.test.ts@@ -98,7 +98,7 @@ test("enroll persists identity and credential, load resumes them, refresh rotate}assert.equal((await stat(join(dir, "state"))).mode & 0o777, 0o700);- const resumed = await AgentMesh.load({ controlPlaneUrl: "ignored://", stateDir: join(dir, "state"), fetch: cp.fetch });+ const resumed = await AgentMesh.load({ stateDir: join(dir, "state"), fetch: cp.fetch });assert.equal(resumed.peerId, mesh.peerId);assert.deepEqual(resumed.credential.biscuit, text("biscuit-1"));assert.equal(resumed.controlPlane.url.toString(), "http://127.0.0.1:1/");@@ -108,9 +108,37 @@ test("enroll persists identity and credential, load resumes them, refresh rotateconst onDisk = JSON.parse(await readFile(join(dir, "state", "credential.json"), "utf8")) as { biscuit: string };assert.equal(Buffer.from(onDisk.biscuit, "base64").toString(), "biscuit-2");- // Re-enrolling from the same directory keeps the identity.- const again = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", stateDir: join(dir, "state"), bootstrapToken: "sbt_secret", fetch: cp.fetch });+ // Enrolling again from the same directory resumes the saved credential+ // without a token; another control plane or an expiring credential+ // enrolls afresh with the same identity.+ const issuedBefore = cp.issued;+ const again = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", stateDir: join(dir, "state"), fetch: cp.fetch });assert.equal(again.peerId, mesh.peerId);+ assert.deepEqual(again.credential.biscuit, text("biscuit-2"));+ assert.equal(cp.issued, issuedBefore);++ await assert.rejects(AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.2:1", stateDir: join(dir, "state"), fetch: cp.fetch }), /no credential to resume/);+ const elsewhere = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.2:1", stateDir: join(dir, "state"), bootstrapToken: "sbt_secret", fetch: cp.fetch });+ assert.equal(elsewhere.peerId, mesh.peerId);+ assert.equal(cp.issued, issuedBefore + 1);+ assert.equal(elsewhere.credential.controlPlaneUrl, "http://127.0.0.2:1/");++ const expiring = JSON.parse(await readFile(join(dir, "state", "credential.json"), "utf8")) as { expiration: number };+ expiring.expiration = Math.floor(Date.now() / 1000) + 60;+ await writeFile(join(dir, "state", "credential.json"), JSON.stringify(expiring));+ await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.2:1", stateDir: join(dir, "state"), bootstrapToken: "sbt_secret", fetch: cp.fetch });+ assert.equal(cp.issued, issuedBefore + 2);+ } finally {+ await rm(dir, { recursive: true, force: true });+ }+});++test("load needs both the identity and the credential", async () => {+ const dir = await mkdtemp(join(tmpdir(), "sam-sdk-"));+ try {+ await assert.rejects(AgentMesh.load({ stateDir: dir }), /no identity/);+ await writeFile(join(dir, "identity.key"), Identity.generate().toLibp2pPrivateKey());+ await assert.rejects(AgentMesh.load({ stateDir: dir }), /no credential/);} finally {await rm(dir, { recursive: true, force: true });}diff --git a/sdk/js/src/mesh.ts b/sdk/js/src/mesh.tsindex 225987ef..33c12f5f 100644--- a/sdk/js/src/mesh.ts+++ b/sdk/js/src/mesh.ts@@ -15,15 +15,17 @@import { mkdir, readFile, rename, writeFile } from "node:fs/promises";import { join } from "node:path";import { ControlPlaneClient, ROLE_NODE, type Enrollment } from "./controlplane.ts";-import { credentialFromJSON, credentialPredatesRotation, credentialToJSON, encodeAuthFrame, type MeshCredential } from "./credential.ts";+import { credentialFromJSON, credentialPredatesRotation, credentialTimeToLiveSeconds, credentialToJSON, encodeAuthFrame, type MeshCredential } from "./credential.ts";import { Identity } from "./identity.ts";import { joinMesh, type JoinOptions, type MeshSession } from "./session.ts";const IDENTITY_FILE = "identity.key";const CREDENTIAL_FILE = "credential.json";+/** A saved credential with less validity left than this is not worth resuming; enroll again instead. */+const REUSE_MIN_TTL_SECONDS = 5 * 60;export interface AgentMeshOptions {- /** Base URL of the control plane, e.g. https://hub.sam-mesh.dev. */+ /** Base URL of the control plane, e.g. https://mesh.example.com. */controlPlaneUrl: string;/** Accept plaintext http:// to a non-loopback control plane. Off by default. */allowInsecure?: boolean;@@ -31,7 +33,7 @@ export interface AgentMeshOptions {* Directory that keeps the identity key and the credential across* restarts. Without it the identity lives only in this process.*/- stateDir?: string;+ stateDir?: string | undefined;/** Use this identity instead of the persisted or a freshly generated one. */identity?: Identity;/** Role to enroll as. Defaults to ROLE_NODE. */@@ -44,11 +46,11 @@ export interface AgentMeshOptions {export interface EnrollOptions extends AgentMeshOptions {/** A bootstrap token value, when the caller already holds it in memory. */- bootstrapToken?: string;+ bootstrapToken?: string | undefined;/** Path of a file holding the bootstrap token. Preferred over a value. */- bootstrapTokenPath?: string;+ bootstrapTokenPath?: string | undefined;/** An OIDC ID token, for meshes that enroll identities interactively. */- jwt?: string;+ jwt?: 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. */@@ -97,15 +99,29 @@ export class AgentMesh {/*** Enrolls with the control plane and returns a member holding a credential.- * Exactly one of bootstrapToken, bootstrapTokenPath or jwt must be given.+ *+ * When stateDir already holds an unexpired credential from this control+ * 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.*/static async enroll(options: EnrollOptions): Promise<AgentMesh> {+ const saved = await loadIdentity(options.stateDir);+ const identity = options.identity ?? saved ?? Identity.generate();+ const controlPlane = newClient(options);+ if (options.stateDir !== undefined && saved !== undefined && saved.peerId === identity.peerId) {+ const credential = await loadCredential(options.stateDir);+ if (credential !== undefined && credential.controlPlaneUrl === controlPlane.url.toString() && credentialTimeToLiveSeconds(credential) > REUSE_MIN_TTL_SECONDS) {+ return new AgentMesh(identity, controlPlane, credential, options.stateDir);+ }+ }const given = [options.bootstrapToken, options.bootstrapTokenPath, options.jwt].filter((v) => v !== undefined).length;if (given !== 1) {- throw new Error("exactly one of bootstrapToken, bootstrapTokenPath or jwt is required");+ 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}`);}- const identity = options.identity ?? (await loadIdentity(options.stateDir)) ?? Identity.generate();- const controlPlane = newClient(options);const role = options.role ?? ROLE_NODE;let enrollment: Enrollment;@@ -150,13 +166,20 @@ export class AgentMesh {return mesh;}- /** Resumes a member from a state directory written by an earlier enroll(). */- static async load(options: AgentMeshOptions & { stateDir: string }): Promise<AgentMesh> {+ /**+ * Resumes a member from a state directory written by an earlier enroll(),+ * for a process that must never hold an enrollment token. The control+ * plane URL comes from the saved credential.+ */+ static async load(options: Omit<AgentMeshOptions, "controlPlaneUrl"> & { stateDir: string }): Promise<AgentMesh> {const identity = options.identity ?? (await loadIdentity(options.stateDir));if (!identity) {throw new Error(`no identity in ${options.stateDir}; enroll first`);}- const credential = credentialFromJSON(await readFile(join(options.stateDir, CREDENTIAL_FILE), "utf8"));+ const credential = await loadCredential(options.stateDir);+ if (credential === undefined) {+ throw new Error(`no credential in ${options.stateDir}; enroll first`);+ }return new AgentMesh(identity, newClient({ ...options, controlPlaneUrl: credential.controlPlaneUrl }), credential, options.stateDir);}@@ -301,6 +324,17 @@ async function loadIdentity(stateDir: string | undefined): Promise<Identity | un}}+async function loadCredential(stateDir: string): Promise<MeshCredential | undefined> {+ try {+ return credentialFromJSON(await readFile(join(stateDir, CREDENTIAL_FILE), "utf8"));+ } catch (err) {+ if ((err as NodeJS.ErrnoException).code === "ENOENT") {+ return undefined;+ }+ throw err;+ }+}+async function writeAtomic(path: string, data: Uint8Array | string, mode: number): Promise<void> {const tmp = `${path}.tmp`;await writeFile(tmp, data, { mode });diff --git a/sdk/js/src/session.ts b/sdk/js/src/session.tsindex f3f0ca61..4d9f468f 100644--- a/sdk/js/src/session.ts+++ b/sdk/js/src/session.ts@@ -15,10 +15,10 @@import type { Connection } from "@libp2p/interface";import { TopicValidatorResult } from "@libp2p/gossipsub";import { peerIdFromString } from "@libp2p/peer-id";-import { multiaddr, type Multiaddr } from "@multiformats/multiaddr";+import { isMultiaddr, multiaddr, type Multiaddr } from "@multiformats/multiaddr";import { AUTH_HANDLER_OPTIONS, AUTH_PROTOCOL, MCP_PROTOCOL, authenticateWithPeer, authStreamHandler } from "./auth.ts";import { ROLE_ROUTER, requireRole, type VerifiedBiscuit } from "./biscuit.ts";-import { serviceCID, type ServiceType } from "./discovery.ts";+import { isServiceType, parseServiceTarget, serviceCID, type ServiceType } from "./discovery.ts";import { createMeshHost, listenThroughRelay, type MeshHost, type MeshHostOptions } from "./host.ts";import { openMCPSession, type MCPSession, type MCPSessionOptions } from "./mcp.ts";import type { AgentMesh, ControlPlaneSync } from "./mesh.ts";@@ -77,6 +77,15 @@ export interface DiscoveredProvider {addrs: string[];}+/**+ * How a caller names the peer it wants to reach: a provider `discover`+ * returned, a peer id, or a multiaddr. For a provider or a peer id the SDK+ * dials the addresses the peer advertised and the relayed path through+ * every router that admitted this member, so the caller never assembles a+ * `/p2p-circuit` address. A multiaddr is dialed as given.+ */+export type Peer = DiscoveredProvider | string | Multiaddr;+/** A tool call's outcome, as MCP reports it. */export interface ToolCallResult {isError: boolean;@@ -164,32 +173,57 @@ export class MeshSession {}/**- * Connects to a peer by address; a `/p2p-circuit` address goes through- * the named relay. Returns the connection, reused if one is already open.- * A banned peer is refused here and by the connection gater.+ * Connects to a peer; see Peer for how it is named. Returns the+ * connection, reused if one is already open. A banned peer is refused+ * here and by the connection gater.*/- connect(addr: string | Multiaddr, signal?: AbortSignal): Promise<Connection> {- const ma = typeof addr === "string" ? multiaddr(addr) : addr;- const target = ma.getComponents().findLast((c) => c.name === "p2p")?.value;- if (target !== undefined && this.banned.has(target)) {- return Promise.reject(new Error(`peer ${target} is banned by the control plane`));+ connect(peer: Peer, signal?: AbortSignal): Promise<Connection> {+ const { peerId, addrs } = this.dialTargets(peer);+ if (peerId !== undefined && this.banned.has(peerId)) {+ return Promise.reject(new Error(`peer ${peerId} is banned by the control plane`));}- return this.node.dial(ma, signal !== undefined ? { signal } : {});+ return this.node.dial(addrs, signal !== undefined ? { signal } : {});+ }++ /** The addresses connect() dials for a peer, in the order libp2p tries them. */+ dialTargets(peer: Peer): { peerId: string | undefined; addrs: Multiaddr[] } {+ if (typeof peer === "string" && !peer.startsWith("/")) {+ return { peerId: peer, addrs: this.relayedAddresses(peer) };+ }+ if (typeof peer === "string" || isMultiaddr(peer)) {+ const ma = typeof peer === "string" ? multiaddr(peer) : peer;+ return { peerId: targetPeerOf(ma), addrs: [ma] };+ }+ const advertised = peer.addrs.map((text) => {+ const ma = multiaddr(text);+ return targetPeerOf(ma) === undefined ? ma.encapsulate(`/p2p/${peer.peerId}`) : ma;+ });+ return { peerId: peer.peerId, addrs: [...advertised, ...this.relayedAddresses(peer.peerId)] };+ }++ /** `<router>/p2p-circuit/p2p/<peer>` through every router that admitted this member. */+ relayedAddresses(peerId: string): Multiaddr[] {+ return this.routers.map((r) => r.addr.encapsulate(`/p2p-circuit/p2p/${peerId}`));}/** Connects to a peer and runs the mutual auth handshake, returning its verified credential. */- async authenticate(addr: string | Multiaddr, signal?: AbortSignal): Promise<VerifiedBiscuit> {- const conn = await this.connect(addr, signal);+ async authenticate(peer: Peer, signal?: AbortSignal): Promise<VerifiedBiscuit> {+ const conn = await this.connect(peer, signal);return authenticateWithPeer(conn, this.mesh.authFrame(), this.mesh.credential.controlPlaneKeys);}/**- * Looks the DHT up for peers offering a service, by type and name, or by- * type alone when name is omitted. Bounded by the timeout; the DHT walk- * itself is what sam-node's discover does.+ * Looks the DHT up for peers offering a service: `"mcp://calc"`, the+ * same string callTool and request take, or a type alone (`"mcp"`) for+ * every service of that type, or (type, name). Bounded by the timeout;+ * the DHT walk itself is what sam-node's discover does.*/- async discover(type: ServiceType, name?: string, options: { timeoutMs?: number; limit?: number } = {}): Promise<DiscoveredProvider[]> {- const cid = await serviceCID(type, name);+ async discover(service: string, name?: string, options: { timeoutMs?: number; limit?: number } = {}): Promise<DiscoveredProvider[]> {+ const target = service.includes("://") ? parseServiceTarget(service) : { type: service, name };+ if (!isServiceType(target.type)) {+ throw new Error(`service type must be mcp, inference or a2a, got ${JSON.stringify(target.type)}`);+ }+ const cid = await serviceCID(target.type, target.name);const signal = AbortSignal.timeout(options.timeoutMs ?? DISCOVERY_TIMEOUT_MS);const found = new Map<string, DiscoveredProvider>();try {@@ -220,17 +254,17 @@ export class MeshSession {}/**- * Opens an MCP session with the provider at addr for targetService- * ("mcp://<name>", or "" for the provider's own catalog tools).+ * Opens an MCP session with a provider for targetService ("mcp://<name>",+ * or "" for the provider's own catalog tools).*/- async openMCP(addr: string | Multiaddr, targetService: string, options: MCPSessionOptions = {}): Promise<MCPSession> {- const conn = await this.connect(addr, options.signal);+ async openMCP(peer: Peer, targetService: string, options: MCPSessionOptions = {}): Promise<MCPSession> {+ const conn = await this.connect(peer, options.signal);return openMCPSession(conn, this.mesh.authFrame(targetService, options.agent ?? ""), this.mesh.credential.controlPlaneKeys, options);}/** Lists the tools a provider serves for a service. */- async listTools(addr: string | Multiaddr, targetService: string, options: MCPSessionOptions = {}): Promise<{ name: string; description?: string }[]> {- const mcp = await this.openMCP(addr, targetService, options);+ async listTools(peer: Peer, targetService: string, options: MCPSessionOptions = {}): Promise<{ name: string; description?: string }[]> {+ const mcp = await this.openMCP(peer, targetService, options);try {const { tools } = await mcp.client.listTools();return tools.map((t) => (t.description !== undefined ? { name: t.name, description: t.description } : { name: t.name }));@@ -240,8 +274,8 @@ export class MeshSession {}/** Calls one tool on a provider's service. */- async callTool(addr: string | Multiaddr, targetService: string, tool: string, args: Record<string, unknown> = {}, options: MCPSessionOptions = {}): Promise<ToolCallResult> {- const mcp = await this.openMCP(addr, targetService, options);+ async callTool(peer: Peer, targetService: string, tool: string, args: Record<string, unknown> = {}, options: MCPSessionOptions = {}): Promise<ToolCallResult> {+ const mcp = await this.openMCP(peer, targetService, options);try {const result = await mcp.client.callTool({ name: tool, arguments: args });const content = Array.isArray(result.content) ? (result.content as Array<{ type: string; text?: string }>) : [];@@ -384,8 +418,8 @@ export class MeshSession {* Calls an inference or A2A service on a provider over /libp2p-http, the* way sam-node's egress proxy does for /sam/<peer>/<type>/<name>/<path>.*/- async request(addr: string | Multiaddr, targetService: string, path: string, options: HTTPRequestOptions = {}): Promise<HTTPResponse> {- const conn = await this.connect(addr, options.signal);+ async request(peer: Peer, targetService: string, path: string, options: HTTPRequestOptions = {}): Promise<HTTPResponse> {+ const conn = await this.connect(peer, options.signal);return httpRequestOverStream(conn, this.mesh.credential.biscuit, targetService, path, options);}@@ -508,7 +542,7 @@ export async function joinMesh(mesh: AgentMesh, options: JoinOptions = {}): Promconst failures: string[] = [];for (const addr of routerAddrs) {- const routerPeer = addr.getComponents().findLast((c) => c.name === "p2p")?.value;+ const routerPeer = targetPeerOf(addr);if (routerPeer === undefined) {failures.push(`${addr.toString()}: no /p2p/<peer id> component`);continue;@@ -538,3 +572,9 @@ export async function joinMesh(mesh: AgentMesh, options: JoinOptions = {}): Promreturn new MeshSession(mesh, node, admitted, authenticatedPeers, banned, options);}++/** The peer a multiaddr ends at: its trailing `/p2p/<id>`, or undefined for a relay address with no target yet. */+function targetPeerOf(ma: Multiaddr): string | undefined {+ const last = ma.getComponents().at(-1);+ return last?.name === "p2p" ? last.value : undefined;+}diff --git a/sdk/python/src/agent_mesh/__init__.py b/sdk/python/src/agent_mesh/__init__.pyindex 8837e426..518a2683 100644--- a/sdk/python/src/agent_mesh/__init__.py+++ b/sdk/python/src/agent_mesh/__init__.py@@ -32,7 +32,7 @@ from .controlplane import (from .credential import MeshCredential, decode_auth_response, encode_auth_framefrom .discovery import DHT_PROTOCOL, DiscoveredProvider, find_providers, parse_service_target, provide, service_keyfrom .identity import Identity, libp2p_public_key, peer_id_from_public_key, verify_ed25519-from .mcp_client import LabelsNotSatisfiedError, ToolCallResult, open_mcp_session, require_labels+from .mcp_client import LabelsNotSatisfiedError, ToolCallResult, ToolInfo, open_mcp_session, require_labelsfrom .mesh import AgentMesh, ControlPlaneSyncfrom .relay import dial_through_relay, reserve_relayfrom .serve import (@@ -48,7 +48,7 @@ from .serve import (http_request_over_stream,mcp_stream_handler,)-from .session import AdmittedRouter, MeshSession+from .session import AdmittedRouter, MeshSession, Peerfrom .sync import GOSSIP_EVENTS_TOPIC, BanSet, verify_mesh_event__version__ = "0.1.0"@@ -83,6 +83,7 @@ __all__ = ["MCPService","MeshCredential","MeshSession",+ "Peer","ProviderAuthorizerOptions","ProviderOptions","ROLE_NODE",@@ -90,6 +91,7 @@ __all__ = ["RefreshResult","ServiceRegistry","ToolCallResult",+ "ToolInfo","VerifiedBiscuit","auth_stream_handler","authenticate_with_peer",diff --git a/sdk/python/src/agent_mesh/conformance_join.py b/sdk/python/src/agent_mesh/conformance_join.pyindex 94c06e8a..046cce10 100644--- a/sdk/python/src/agent_mesh/conformance_join.py+++ b/sdk/python/src/agent_mesh/conformance_join.py@@ -96,7 +96,7 @@ async def _handle(session: MeshSession, command: dict) -> dict:if cmd == "tools":with trio.fail_after(15):tools = await session.list_tools(command["addr"], command.get("service", ""))- return {"cmd": cmd, "ok": True, "tools": tools}+ return {"cmd": cmd, "ok": True, "tools": [t.name for t in tools]}if cmd == "call":with trio.fail_after(15):result = await session.call_tool(command["addr"], command.get("service", ""), command["tool"], command.get("args") or {})@@ -169,9 +169,6 @@ async def _handle(session: MeshSession, command: dict) -> dict:async def main() -> None:# stdout carries the protocol lines only; every log goes to stderr.logging.basicConfig(stream=sys.stderr, level=logging.WARNING, force=True)- # py-libp2p's pubsub tries meshsub with every new peer and the host logs- # an error for each one that does not run pubsub; that is expected here.- logging.getLogger("libp2p.host.basic_host").setLevel(logging.CRITICAL)control_plane_url = _require_env("SAM_CONTROL_PLANE_URL")bootstrap_token_path = _require_env("SAM_BOOTSTRAP_TOKEN_PATH")state_dir = _require_env("SAM_SDK_STATE_DIR")diff --git a/sdk/python/src/agent_mesh/mcp_client.py b/sdk/python/src/agent_mesh/mcp_client.pyindex 5048aa08..b432a32e 100644--- a/sdk/python/src/agent_mesh/mcp_client.py+++ b/sdk/python/src/agent_mesh/mcp_client.py@@ -59,6 +59,14 @@ def require_labels(provider: VerifiedBiscuit, required: Optional[Mapping[str, straise LabelsNotSatisfiedError(provider.peer_id, missing)+@dataclass+class ToolInfo:+ """One entry of a provider's tool list."""++ name: str+ description: str | None = None++@dataclassclass ToolCallResult:"""A tool call's outcome, as MCP reports it."""diff --git a/sdk/python/src/agent_mesh/mesh.py b/sdk/python/src/agent_mesh/mesh.pyindex eddeb506..eb5f6c3e 100644--- a/sdk/python/src/agent_mesh/mesh.py+++ b/sdk/python/src/agent_mesh/mesh.py@@ -27,6 +27,8 @@ from .identity import Identity_IDENTITY_FILE = "identity.key"_CREDENTIAL_FILE = "credential.json"+# A saved credential with less validity left than this is not worth resuming; enroll again instead.+_REUSE_MIN_TTL_SECONDS = 5 * 60@dataclass(frozen=True)@@ -82,21 +84,33 @@ class AgentMesh:transport: Optional[Transport] = None,) -> "AgentMesh":"""Enrolls with the control plane and returns a member holding a credential.- Exactly one of bootstrap_token, bootstrap_token_path or jwt must be given.- A bootstrap token is better read from a file than passed as a value."""++ When state_dir already holds an unexpired credential from this control+ 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+ 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."""+ state = Path(state_dir).expanduser() if state_dir is not None else None+ saved = _load_identity(state)+ identity = identity or saved or Identity.generate()+ control_plane = ControlPlaneClient(control_plane_url, allow_insecure=allow_insecure, transport=transport)+ if state is not None and saved is not None and saved.peer_id == identity.peer_id:+ credential = _load_credential(state)+ if credential is not None and credential.control_plane_url == control_plane.url 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))if given != 1:- raise ValueError("exactly one of bootstrap_token, bootstrap_token_path or jwt is required")- state = Path(state_dir) if state_dir is not None else None- identity = identity or _load_identity(state) or Identity.generate()- control_plane = ControlPlaneClient(control_plane_url, allow_insecure=allow_insecure, transport=transport)+ 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}")enrollment: Enrollmentif jwt is not None:enrollment = control_plane.register(identity, jwt, role=role, labels=labels)else:if bootstrap_token_path is not None:- bootstrap_token = Path(bootstrap_token_path).read_text().strip()+ bootstrap_token = Path(bootstrap_token_path).expanduser().read_text().strip()assert bootstrap_token is not Noneenrollment = control_plane.enroll_bootstrap(identity, bootstrap_token, role=role, labels=labels, poll_interval=poll_interval, cancel=cancel@@ -136,12 +150,16 @@ class AgentMesh:allow_insecure: bool = False,transport: Optional[Transport] = None,) -> "AgentMesh":- """Resumes a member from a state directory written by an earlier enroll()."""- state = Path(state_dir)+ """Resumes a member from a state directory written by an earlier enroll(),+ for a process that must never hold an enrollment token. The control plane+ URL comes from the saved credential."""+ state = Path(state_dir).expanduser()identity = identity or _load_identity(state)if identity is None:raise FileNotFoundError(f"no identity in {state}; enroll first")- credential = MeshCredential.from_json((state / _CREDENTIAL_FILE).read_text())+ credential = _load_credential(state)+ if credential is None:+ raise FileNotFoundError(f"no credential in {state}; enroll first")control_plane = ControlPlaneClient(credential.control_plane_url, allow_insecure=allow_insecure, transport=transport)return cls(identity, control_plane, credential, state)@@ -245,6 +263,13 @@ def _load_identity(state: Optional[Path]) -> Optional[Identity]:return None+def _load_credential(state: Path) -> Optional[MeshCredential]:+ try:+ return MeshCredential.from_json((state / _CREDENTIAL_FILE).read_text())+ except FileNotFoundError:+ return None++def _write_atomic(path: Path, data: bytes) -> None:tmp = path.with_name(path.name + ".tmp")fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)diff --git a/sdk/python/src/agent_mesh/session.py b/sdk/python/src/agent_mesh/session.pyindex 82db4291..a3e00579 100644--- a/sdk/python/src/agent_mesh/session.py+++ b/sdk/python/src/agent_mesh/session.py@@ -20,14 +20,14 @@ import timefrom contextlib import asynccontextmanagerfrom dataclasses import dataclass, fieldfrom datetime import datetime-from typing import TYPE_CHECKING, Any, AsyncIterator, Mapping, Optional, Sequence+from typing import TYPE_CHECKING, Any, AsyncIterator, Mapping, Optional, Sequence, Unionimport multiaddrimport triofrom libp2p.abc import IHostfrom libp2p.custom_types import TProtocolfrom libp2p.peer.id import ID-from libp2p.peer.peerinfo import info_from_p2p_addr+from libp2p.peer.peerinfo import PeerInfo, info_from_p2p_addrfrom libp2p.pubsub.gossipsub import PROTOCOL_ID as GOSSIPSUB_V10from libp2p.pubsub.gossipsub import PROTOCOL_ID_V11 as GOSSIPSUB_V11from libp2p.pubsub.gossipsub import PROTOCOL_ID_V12 as GOSSIPSUB_V12@@ -41,9 +41,9 @@ from ._proto import sam_pb2 as pbfrom .auth import AUTH_PROTOCOL, MCP_PROTOCOL, auth_stream_handler, authenticate_with_peerfrom .authorizer import ProviderAuthorizerOptionsfrom .biscuit import ROLE_ROUTER, VerifiedBiscuit, require_role-from .discovery import DiscoveredProvider, ServiceType, find_providers, provide, service_key+from .discovery import DiscoveredProvider, ServiceType, find_providers, parse_service_target, provide, service_keyfrom .host import create_mesh_host-from .mcp_client import ToolCallResult, open_mcp_session, tool_call_result+from .mcp_client import ToolCallResult, ToolInfo, open_mcp_session, tool_call_resultfrom .relay import STOP_PROTOCOL, dial_through_relay, reserve_relay, split_circuit_address, stop_stream_handlerfrom .serve import (HTTP_PROTOCOL,@@ -74,6 +74,26 @@ DEFAULT_CONTROL_PLANE_SYNC = 15 * 60.0FIRST_CONTROL_PLANE_SYNC = 2.0DEFAULT_CONTROL_PLANE_SYNC_JITTER = 2.0+# How a caller names the peer it wants to reach: a provider `discover` returned,+# a peer id, or a multiaddr. For a provider or a peer id the SDK dials the+# addresses the peer advertised and then the relayed path through every router+# that admitted this member, so the caller never assembles a `/p2p-circuit`+# address. A multiaddr is dialed as given.+Peer = Union[DiscoveredProvider, str, multiaddr.Multiaddr]+++class _MeshsubNoise(logging.Filter):+ """py-libp2p's pubsub opens a meshsub stream to every new peer and the host+ logs an error for each one that does not answer. Peers that leave during+ that exchange and members without pubsub are ordinary on the mesh."""++ def filter(self, record: logging.LogRecord) -> bool:+ message = record.getMessage()+ return not ("Failed to open stream" in message and "/meshsub/" in message)+++_MESHSUB_NOISE = _MeshsubNoise()+@dataclass(frozen=True)class AdmittedRouter:@@ -130,10 +150,37 @@ class MeshSession:out.append(f"{text}/p2p-circuit/p2p/{self.peer_id}")return out- async def connect(self, addr: str | multiaddr.Multiaddr) -> ID:- """Connects to a peer by address, through a relay when the address says- `/p2p-circuit`, and returns its peer ID. A banned peer is refused."""- ma = multiaddr.Multiaddr(str(addr))+ async def connect(self, peer: Peer) -> ID:+ """Connects to a peer, see `Peer`, and returns its peer ID. A banned+ peer is refused."""+ if isinstance(peer, multiaddr.Multiaddr) or (isinstance(peer, str) and peer.startswith("/")):+ return await self._connect_addr(multiaddr.Multiaddr(str(peer)))+ if isinstance(peer, str):+ target, advertised = ID.from_base58(peer), []+ else:+ target, advertised = ID.from_base58(peer.peer_id), [multiaddr.Multiaddr(a) for a in peer.addrs]+ self._refuse_banned(target)+ if target in self.host.get_connected_peers():+ return target+ failures: list[str] = []+ suffix = f"/p2p/{target}"+ direct = [multiaddr.Multiaddr(str(a).removesuffix(suffix)) for a in advertised if "/p2p-circuit" not in str(a)]+ if direct:+ try:+ await self.host.connect(PeerInfo(target, direct))+ return target+ except Exception as err: # noqa: BLE001 - the relayed path is tried next+ failures.append(f"direct {[str(a) for a in direct]}: {err}")+ for r in self.routers:+ try:+ await self._connect_addr(multiaddr.Multiaddr(f"{r.addr}/p2p-circuit{suffix}"))+ return target+ except Exception as err: # noqa: BLE001 - the next router is tried+ failures.append(f"via router {r.peer_id}: {err}")+ raise ConnectionError(f"cannot reach {target}:\n " + "\n ".join(failures))++ async def _connect_addr(self, ma: multiaddr.Multiaddr) -> ID:+ """Dials one multiaddr, through a relay when it says `/p2p-circuit`."""if "/p2p-circuit" in str(ma):relay_addr, target = split_circuit_address(ma)self._refuse_banned(target)@@ -152,51 +199,56 @@ class MeshSession:if str(peer_id) in self.banned:raise PermissionError(f"peer {peer_id} is banned by the control plane")- async def authenticate(self, addr: str | multiaddr.Multiaddr) -> VerifiedBiscuit:+ async def authenticate(self, peer: Peer) -> VerifiedBiscuit:"""Connects to a peer and runs the mutual auth handshake, returning thepeer's verified credential."""- peer_id = await self.connect(addr)+ peer_id = await self.connect(peer)return await authenticate_with_peer(self.host, peer_id, self.mesh.auth_frame(), self.mesh.credential.control_plane_keys)- async def discover(self, service_type: ServiceType, name: str | None = None, limit: int = 20) -> list[DiscoveredProvider]:- """Looks the DHT up for peers offering a service, by type and name, or by- type alone. The routers we are connected to seed the walk."""+ async def discover(self, service: str, name: str | None = None, limit: int = 20) -> list[DiscoveredProvider]:+ """Looks the DHT up for peers offering a service: "mcp://calc", the same+ string call_tool and request take, or a type alone ("mcp") for every+ service of that type, or (type, name). The routers we are connected to+ seed the walk."""+ service_type, service_name = parse_service_target(service) if "://" in service else (service, name)+ if service_type not in ("mcp", "inference", "a2a"):+ raise ValueError(f"service type must be mcp, inference or a2a, got {service_type!r}")seeds = [ID.from_base58(r.peer_id) for r in self.routers]- return await find_providers(self.host, service_key(service_type, name), seeds, limit)+ return await find_providers(self.host, service_key(service_type, service_name), seeds, limit)def open_mcp(self,- addr: str | multiaddr.Multiaddr,+ peer: Peer,target_service: str,*,required_labels: Optional[Mapping[str, str]] = None,agent: str = "",): # type: ignore[no-untyped-def]- """Opens an MCP session with the provider at addr for target_service+ """Opens an MCP session with a provider for target_service("mcp://<name>", or "" for the provider's own catalog tools):- async with session.open_mcp(addr, "mcp://calc") as (mcp, provider): ...+ async with session.open_mcp(provider, "mcp://calc") as (mcp, verified): ..."""@asynccontextmanagerasync def opened() -> AsyncIterator[tuple[ClientSession, VerifiedBiscuit]]:- peer_id = await self.connect(addr)+ peer_id = await self.connect(peer)frame = self.mesh.auth_frame(target_service, agent)async with open_mcp_session(self.host, peer_id, frame, self.mesh.credential.control_plane_keys, required_labels=required_labels) as opened_session:yield opened_sessionreturn opened()- async def list_tools(self, addr: str | multiaddr.Multiaddr, target_service: str, **options: Any) -> list[str]:+ async def list_tools(self, peer: Peer, target_service: str, **options: Any) -> list[ToolInfo]:"""Lists the tools a provider serves for a service."""- async with self.open_mcp(addr, target_service, **options) as (mcp, _):- return [t.name for t in (await mcp.list_tools()).tools]+ async with self.open_mcp(peer, target_service, **options) as (mcp, _):+ return [ToolInfo(name=t.name, description=t.description) for t in (await mcp.list_tools()).tools]async def call_tool(- self, addr: str | multiaddr.Multiaddr, target_service: str, tool: str, args: Optional[Mapping[str, Any]] = None, **options: Any+ self, peer: Peer, target_service: str, tool: str, args: Optional[Mapping[str, Any]] = None, **options: Any) -> ToolCallResult:"""Calls one tool on a provider's service."""- async with self.open_mcp(addr, target_service, **options) as (mcp, _):+ async with self.open_mcp(peer, target_service, **options) as (mcp, _):result = await mcp.call_tool(tool, dict(args or {}))if not hasattr(result, "content"):raise RuntimeError(f"tool {tool} answered with {type(result).__name__}, not a result")@@ -295,7 +347,7 @@ class MeshSession:async def request(self,- addr: str | multiaddr.Multiaddr,+ peer: Peer,target_service: str,path: str,*,@@ -306,7 +358,7 @@ class MeshSession:) -> HTTPResponse:"""Calls an inference or A2A service on a provider over /libp2p-http,the way sam-node's egress proxy does for /sam/<peer>/<type>/<name>/<path>."""- peer_id = await self.connect(addr)+ peer_id = await self.connect(peer)return await http_request_over_stream(self.host, peer_id, self.mesh.credential.biscuit, target_service, path, method=method, headers=headers, body=body, agent=agent)@@ -431,6 +483,7 @@ async def join_mesh(# registers here. StrictSign, as every Go component pins it.gossipsub = GossipSub(protocols=[GOSSIPSUB_V12, GOSSIPSUB_V11, GOSSIPSUB_V10], degree=6, degree_low=4, degree_high=12)pubsub = Pubsub(host, gossipsub, strict_signing=True)+ logging.getLogger("libp2p.host.basic_host").addFilter(_MESHSUB_NOISE)try:async with host.run(listen_addrs=listen), background_trio_service(pubsub), background_trio_service(gossipsub):diff --git a/sdk/python/tests/test_mesh.py b/sdk/python/tests/test_mesh.pyindex 3894d825..de783b3b 100644--- a/sdk/python/tests/test_mesh.py+++ b/sdk/python/tests/test_mesh.py@@ -85,9 +85,36 @@ def test_enroll_persists_load_resumes_refresh_rotates(tmp_path):on_disk = json.loads((state / "credential.json").read_text())assert on_disk["biscuit"] == "YmlzY3VpdC0y" # base64("biscuit-2")- # Re-enrolling from the same directory keeps the identity.- again = AgentMesh.enroll("http://127.0.0.1:1", bootstrap_token="sbt_secret", state_dir=state, transport=cp.transport)+ # Enrolling again from the same directory resumes the saved credential+ # without a token; another control plane or an expiring credential+ # enrolls afresh with the same identity.+ issued_before = cp.issued+ again = AgentMesh.enroll("http://127.0.0.1:1", state_dir=state, transport=cp.transport)assert again.peer_id == mesh.peer_id+ assert again.credential.biscuit == b"biscuit-2"+ assert cp.issued == issued_before++ with pytest.raises(ValueError, match="no credential to resume"):+ AgentMesh.enroll("http://127.0.0.2:1", state_dir=state, transport=cp.transport)+ elsewhere = AgentMesh.enroll("http://127.0.0.2:1", bootstrap_token="sbt_secret", state_dir=state, transport=cp.transport)+ assert elsewhere.peer_id == mesh.peer_id+ assert cp.issued == issued_before + 1+ assert elsewhere.credential.control_plane_url == "http://127.0.0.2:1"++ expiring = json.loads((state / "credential.json").read_text())+ expiring["expiration"] = int(time.time()) + 60+ (state / "credential.json").write_text(json.dumps(expiring))+ AgentMesh.enroll("http://127.0.0.2:1", bootstrap_token="sbt_secret", state_dir=state, transport=cp.transport)+ assert cp.issued == issued_before + 2+++def test_state_dir_and_token_path_expand_home(tmp_path, monkeypatch):+ monkeypatch.setenv("HOME", str(tmp_path))+ (tmp_path / "bootstrap.token").write_text("sbt_secret\n")+ cp = FakeControlPlane()+ mesh = AgentMesh.enroll("http://127.0.0.1:1", bootstrap_token_path="~/bootstrap.token", state_dir="~/state", transport=cp.transport)+ assert (tmp_path / "state" / "credential.json").exists()+ assert AgentMesh.load("~/state", transport=cp.transport).peer_id == mesh.peer_iddef test_enroll_without_state_dir_keeps_enrollment_key_when_keys_fails():@@ -109,7 +136,10 @@ def test_enroll_refuses_ambiguous_credentials():def test_load_without_identity_says_enroll_first(tmp_path):- with pytest.raises(FileNotFoundError, match="enroll first"):+ with pytest.raises(FileNotFoundError, match="no identity"):+ AgentMesh.load(tmp_path)+ (tmp_path / "identity.key").write_bytes(Identity.generate().to_libp2p_private_key())+ with pytest.raises(FileNotFoundError, match="no credential"):AgentMesh.load(tmp_path)