Skip to content

Agent Mesh

sdk: name peers, not addresses; enroll resumes saved state

Antonio Ojeae90d0a514398
diff --git a/sdk/js/src/conformance.ts b/sdk/js/src/conformance.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 rotate
const 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.ts
index 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.ts
index 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 = {}): Prom
const 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 = {}): Prom
return 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__.py
index 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_frame
from .discovery import DHT_PROTOCOL, DiscoveredProvider, find_providers, parse_service_target, provide, service_key
from .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_labels
from .mesh import AgentMesh, ControlPlaneSync
from .relay import dial_through_relay, reserve_relay
from .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, Peer
from .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.py
index 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.py
index 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, st
raise LabelsNotSatisfiedError(provider.peer_id, missing)
+@dataclass
+class ToolInfo:
+ """One entry of a provider's tool list."""
+
+ name: str
+ description: str | None = None
+
+
@dataclass
class 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.py
index 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: Enrollment
if 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 None
enrollment = 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.py
index 82db4291..a3e00579 100644
--- a/sdk/python/src/agent_mesh/session.py
+++ b/sdk/python/src/agent_mesh/session.py
@@ -20,14 +20,14 @@ import time
from contextlib import asynccontextmanager
from dataclasses import dataclass, field
from datetime import datetime
-from typing import TYPE_CHECKING, Any, AsyncIterator, Mapping, Optional, Sequence
+from typing import TYPE_CHECKING, Any, AsyncIterator, Mapping, Optional, Sequence, Union
import multiaddr
import trio
from libp2p.abc import IHost
from libp2p.custom_types import TProtocol
from libp2p.peer.id import ID
-from libp2p.peer.peerinfo import info_from_p2p_addr
+from libp2p.peer.peerinfo import PeerInfo, info_from_p2p_addr
from libp2p.pubsub.gossipsub import PROTOCOL_ID as GOSSIPSUB_V10
from libp2p.pubsub.gossipsub import PROTOCOL_ID_V11 as GOSSIPSUB_V11
from libp2p.pubsub.gossipsub import PROTOCOL_ID_V12 as GOSSIPSUB_V12
@@ -41,9 +41,9 @@ from ._proto import sam_pb2 as pb
from .auth import AUTH_PROTOCOL, MCP_PROTOCOL, auth_stream_handler, authenticate_with_peer
from .authorizer import ProviderAuthorizerOptions
from .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_key
from .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_result
from .relay import STOP_PROTOCOL, dial_through_relay, reserve_relay, split_circuit_address, stop_stream_handler
from .serve import (
HTTP_PROTOCOL,
@@ -74,6 +74,26 @@ DEFAULT_CONTROL_PLANE_SYNC = 15 * 60.0
FIRST_CONTROL_PLANE_SYNC = 2.0
DEFAULT_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 the
peer'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): ...
"""
@asynccontextmanager
async 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_session
return 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.py
index 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_id
def 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)