Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
sdk/js: the mesh's replication factor from /info is the DHT client's k
Antonio Ojea4f28721e4658
diff --git a/sdk/js/src/discovery.ts b/sdk/js/src/discovery.tsindex 0ddee318..9a3669d0 100644--- a/sdk/js/src/discovery.ts+++ b/sdk/js/src/discovery.ts@@ -22,6 +22,14 @@ import { sha256 } from "multiformats/hashes/sha2";/** The DHT protocol, go-libp2p-kad-dht with dht.ProtocolPrefix("/mesh"). */export const DHT_PROTOCOL = "/mesh/kad/1.0.0";+/**+ * How many routers hold each record and answer each lookup when the control+ * plane publishes no directory parameters on /info: api.DefaultDHTReplication.+ * A member reads the mesh's value from /info (AgentMesh.dhtReplication) and+ * runs its DHT client on it (createMeshHost), as agentmesh-node does.+ */+export const DEFAULT_DHT_REPLICATION = 3;+export type ServiceType = "mcp" | "inference" | "a2a" | "egress";export function isServiceType(value: unknown): value is ServiceType {diff --git a/sdk/js/src/host.ts b/sdk/js/src/host.tsindex 3d691eaf..388874e2 100644--- a/sdk/js/src/host.ts+++ b/sdk/js/src/host.ts@@ -28,7 +28,7 @@ import { kadDHT, passthroughMapper } from "@libp2p/kad-dht";import { ping } from "@libp2p/ping";import type { Multiaddr } from "@multiformats/multiaddr";import { createLibp2p, type Libp2pOptions } from "libp2p";-import { DHT_PROTOCOL } from "./discovery.ts";+import { DEFAULT_DHT_REPLICATION, DHT_PROTOCOL } from "./discovery.ts";import type { Identity } from "./identity.ts";import { connectionEncrypters, transports } from "./platform/transports.ts";@@ -47,6 +47,14 @@ export interface MeshHostOptions {banned?: { has(peerId: string): boolean };/** The resolver for `/dnsaddr` and `/dns*` addresses; the system's by default. */dns?: Libp2pOptions["dns"];+ /**+ * The mesh's replication factor, from /info (AgentMesh.dhtReplication):+ * kademlia's k on this member. A record lives on that many routers, the+ * closest to its key, and a lookup asks those, that many at a time. The+ * same figure on every member of a mesh, which is why it comes from the+ * control plane; DEFAULT_DHT_REPLICATION when it published none.+ */+ dhtReplication?: number;}/** The services a mesh host runs; `services.pubsub` carries the control plane's events. */@@ -55,6 +63,7 @@ export type MeshHost = Libp2p<{ pubsub: GossipSub }>;export async function createMeshHost(identity: Identity, options: MeshHostOptions = {}): Promise<MeshHost> {const banned = options.banned ?? { has: () => false };const denyBanned = (peerId: PeerId) => banned.has(peerId.toString());+ const replication = options.dhtReplication !== undefined && options.dhtReplication >= 1 ? Math.floor(options.dhtReplication) : DEFAULT_DHT_REPLICATION;return createLibp2p({privateKey: privateKeyFromProtobuf(identity.toLibp2pPrivateKey()),addresses: { listen: options.listenAddrs ?? [] },@@ -89,7 +98,7 @@ export async function createMeshHost(identity: Identity, options: MeshHostOption// A client of the mesh DHT: it looks providers up and does not hold// records. Peers keep their private addresses; a mesh member often// is one, and the router relays to it.- dht: kadDHT({ protocol: DHT_PROTOCOL, clientMode: true, peerInfoMapper: passthroughMapper, initialQuerySelfInterval: 20 }),+ dht: kadDHT({ protocol: DHT_PROTOCOL, clientMode: true, peerInfoMapper: passthroughMapper, initialQuerySelfInterval: 20, kBucketSize: replication, alpha: replication }),// The control plane's events reach members through the routers.// StrictSign, as every Go component pins it: the pubsub envelope is// signed by the author, and the event inside by the control plane.diff --git a/sdk/js/src/mesh.ts b/sdk/js/src/mesh.tsindex 9f34ac6f..f1b9bc0e 100644--- a/sdk/js/src/mesh.ts+++ b/sdk/js/src/mesh.ts@@ -15,6 +15,7 @@import type { MessageInitShape } from "@bufbuild/protobuf";import { toHex } from "./bytes.ts";import { ControlPlaneClient, KeysNotTrustedError, ROLE_NODE, type Enrollment } from "./controlplane.ts";+import { DEFAULT_DHT_REPLICATION } from "./discovery.ts";import {attenuateCredential,credentialFromJSON,@@ -144,6 +145,7 @@ export class AgentMesh {readonly controlPlane: ControlPlaneClient;#credential: MeshCredential;#routers: RouterInfo[] = [];+ #dhtReplication = DEFAULT_DHT_REPLICATION;readonly #state: StateStore | undefined;readonly #jwtSource: (() => Promise<string>) | undefined;// Refreshes run one after another, as agentmesh-node's refreshMu: the control@@ -178,6 +180,16 @@ export class AgentMesh {return this.#routers;}+ /**+ * How many routers hold each record and answer each lookup on this mesh,+ * as /info last published it (ControlPlaneInfoResponse.directory);+ * DEFAULT_DHT_REPLICATION until the control plane has answered or when it+ * publishes none.+ */+ get dhtReplication(): number {+ return this.#dhtReplication;+ }+/** Returns a new MeshCredential with a tar_block appended offline in memory. */attenuate(rule: MessageInitShape<typeof TaskAuthorizationRuleSchema>): Promise<MeshCredential> {return attenuateCredential(this.#credential, rule);@@ -407,6 +419,9 @@ export class AgentMesh {const info = await this.controlPlane.info();routers = info.routers;this.#routers = info.routers;+ if (info.directory !== undefined && info.directory.replication >= 1) {+ this.#dhtReplication = info.directory.replication;+ }const discovered =info.routerAddresses.length > 0? info.routerAddressesdiff --git a/sdk/js/src/session.ts b/sdk/js/src/session.tsindex 579c403f..91bb2b4b 100644--- a/sdk/js/src/session.ts+++ b/sdk/js/src/session.ts@@ -1360,7 +1360,7 @@ export async function joinMesh(mesh: AgentMesh, options: JoinOptions = {}): Prom}const banned = new BanSet();- const node = await createMeshHost(mesh.identity, { ...options, banned });+ const node = await createMeshHost(mesh.identity, { ...options, banned, dhtReplication: mesh.dhtReplication });const authenticatedPeers = new Map<string, Date>();let session: MeshSession | undefined;try {diff --git a/sdk/js/src/sync.test.ts b/sdk/js/src/sync.test.tsindex 049e7bc2..63817e06 100644--- a/sdk/js/src/sync.test.ts+++ b/sdk/js/src/sync.test.ts@@ -35,6 +35,7 @@ import { AUTH_PROTOCOL, authenticateWithPeer, authStreamHandler } from "./auth.timport { ROLE_ROUTER, loadBiscuit, verifyPeerBiscuit } from "./biscuit.ts";import { ROLE_NODE } from "./controlplane.ts";import { credentialPredatesRotation } from "./credential.ts";+import { DEFAULT_DHT_REPLICATION } from "./discovery.ts";import {AuthFrameSchema,BootstrapEnrollRequestSchema,@@ -80,6 +81,8 @@ class SigningKey {class FakeControlPlane {keys: SigningKey[];banned: string[] = [];+ /** The replication /info publishes; undefined is a control plane that predates the field. */+ replication: number | undefined;refreshes = 0;constructor(initial: SigningKey) {this.keys = [initial];@@ -115,7 +118,16 @@ class FakeControlPlane {return proto(toBinary(KeysResponseSchema, create(KeysResponseSchema, { ...unsigned, signatures: this.keys.map((k) => k.identity.sign(payload)) })));}if (req.method === "GET" && path === "/info") {- return proto(toBinary(ControlPlaneInfoResponseSchema, create(ControlPlaneInfoResponseSchema, { routerAddresses: [routerAddr], bannedPeerIds: this.banned })));+ return proto(+ toBinary(+ ControlPlaneInfoResponseSchema,+ create(ControlPlaneInfoResponseSchema, {+ routerAddresses: [routerAddr],+ bannedPeerIds: this.banned,+ ...(this.replication !== undefined ? { directory: { replication: this.replication } } : {}),+ }),+ ),+ );}if (req.method === "POST" && path === "/refresh") {this.refreshes++;@@ -212,6 +224,25 @@ test("a mesh event verifies only under a trusted key and only when fresh", () =>assert.equal(verifyMeshEvent(bannedNobody, [key.pub], now), undefined, "not a peer id");});+test("a pull takes the mesh's replication from /info, and the default when it publishes none", async () => {+ const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: cp.fetch });+ assert.equal(mesh.dhtReplication, DEFAULT_DHT_REPLICATION, "before any pull");+ cp.replication = 5;+ try {+ await mesh.syncControlPlane();+ assert.equal(mesh.dhtReplication, 5);+ // A control plane that stops publishing it, or publishes nothing usable, leaves the last value.+ cp.replication = 0;+ await mesh.syncControlPlane();+ assert.equal(mesh.dhtReplication, 5);+ cp.replication = undefined;+ await mesh.syncControlPlane();+ assert.equal(mesh.dhtReplication, 5);+ } finally {+ cp.replication = undefined;+ }+});+test("a pull learns a key rotation and refreshes the credential under the new key", async () => {const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: cp.fetch });const session = await mesh.join({ refreshLeadMs: 0, controlPlaneSyncIntervalMs: 0 });