Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
sdk: package READMEs carry what a user needs, nothing about the repository
Antonio Ojea3959981b0cb5
diff --git a/sdk/README.md b/sdk/README.mdindex 9bac8bf6..a03e7924 100644--- a/sdk/README.md+++ b/sdk/README.md@@ -457,3 +457,36 @@ Interoperability facts that the tests pin: `sdk/testdata/identity_vectors.json`holds key encodings, peer IDs and challenge signatures produced withgo-libp2p, `sdk/testdata/biscuit_vectors.json` holds tokens minted by thecontrol plane's code, and every SDK reproduces or agrees with them.++The package READMEs (`sdk/js/README.md`, `sdk/python/README.md`) are the+registry pages on npm and PyPI: they hold what a user of the package needs+and nothing about this repository's internals. Everything below is for+contributors.++### Layout++Both SDKs mirror the same Go code, one module per concern; the Go file each+one follows is named so a change on one side can be carried to the others.++| JavaScript (`sdk/js/src/`) | Python (`sdk/python/src/agent_mesh/`) | Mirrors |+| --- | --- | --- |+| `identity.ts` | `identity.py` | ed25519 key pair, libp2p key encodings, peer ID |+| `controlplane.ts` | `controlplane.py` | `/info`, `/keys`, `/enroll`, `/enroll/status`, `/register`, `/refresh`, `/policies`, `/nodes/catalog`, with the challenges of `api/network.go` |+| `credential.ts` | `credential.py` | what a member holds, `AuthFrame` encoding, `issuedUnderKeys` |+| `mesh.ts` | `mesh.py` | `AgentMesh`: enroll, load, refresh, `syncControlPlane` as `SyncControlPlane` in `internal/node/controlplane_sync.go`; state directory (`identity.key`, `credential.json`) |+| `biscuit.ts` | `biscuit.py` | verification of a peer's credential, as `internal/identity.verifyBiscuit` |+| `host.ts` | `host.py` | the libp2p host as `internal/node/node.go` configures it, plus gossipsub and the connection gater |+| `auth.ts` | `auth.py` | `/sam/auth/1.0.0` on both sides, as `HandleAuthHandshake` |+| — | `relay.py` | circuit relay v2 client (py-libp2p's cannot talk to go-libp2p) |+| `session.ts` | `session.py` | `MeshSession`: join, relay reservation, refresh loop, control plane sync loop, gossip events, `serve()` |+| `discovery.ts` | `discovery.py` | service keys and DHT lookups as `internal/node/service.go`; Python also provides, py-libp2p's client cannot |+| `mcp.ts` | `mcp_client.py` | MCP over `/sam/mcp/1.0.0`, the client side of `internal/node/gate.go` |+| `authorizer.ts` | `authorizer.py` | the provider authorizer, as `internal/node.(*SamNode).Authorize`, over the generated baseline and `datalog_rules` |+| `serve.ts` | `serve.py` | `/sam/mcp/1.0.0` server, `/libp2p-http` server and client, service registry, as `WithBiscuitAuth` and `StartIngressServer` |+| `sync.ts` | `sync.py` | ban set and mesh event verification, as `reconcileBannedPeers` and `verifyEvent` |+| `conformance.ts`, `conformance-join.ts` | `conformance.py`, `conformance_join.py` | the runners the integration tests drive |+| `gen/` | `_proto/`, `_gen/` | generated by `hack/gen-sdk-proto.sh` from `api/sam.proto`, `sdk/python/proto/circuit.proto` and `api/datalog.go` |++Unit tests sit beside the code (`*.test.ts`, `tests/test_*.py`) and build a+fake control plane and router in the process; the real ones are exercised+only by `tests/integration`.diff --git a/sdk/js/README.md b/sdk/js/README.mdindex 94aadbc9..af3fde8a 100644--- a/sdk/js/README.md+++ b/sdk/js/README.md@@ -1,25 +1,21 @@# @sam-mesh/sdkNative JavaScript SDK for joining a SAM agent mesh from inside the agent-process. It replaces the `sam-node` sidecar for agents written for Node.js.+process. It replaces the `sam-node` sidecar for agents written for Node.js:+the agent enrolls with the control plane, joins the mesh through a router,+finds services and calls them, publishes services of its own, and follows+the control plane's keys, bans and policy while it runs.-Status: **milestone 3** (identity, enrollment, credential refresh, joining-the mesh over libp2p with mutual authentication, discovering services and-calling their tools). Serving tools is the next milestone; see-[../README.md](../README.md) for the plan.+Guide: [sam-mesh.dev/docs/guides/native-sdks](https://sam-mesh.dev/docs/guides/native-sdks/).+Source: [github.com/google/sam/tree/main/sdk/js](https://github.com/google/sam/tree/main/sdk/js).## Install```bash-npm install @sam-mesh/sdk # from npm, released with the repository-cd sdk/js && npm ci && npm run build # from a checkout+npm install @sam-mesh/sdk```-Requires Node.js 22.18 or later. Runtime dependencies are-`@bufbuild/protobuf`, `@biscuit-auth/biscuit-wasm`, `@modelcontextprotocol/sdk`,-`zod` and the js-libp2p packages (`libp2p`, `@libp2p/tcp`, `@libp2p/tls`,-`@chainsafe/libp2p-yamux`, `@libp2p/circuit-relay-v2`, `@libp2p/identify`,-`@libp2p/kad-dht`, `@libp2p/ping`, `@libp2p/gossipsub`, `@libp2p/peer-id`).+Requires Node.js 22.18 or later.## Use@@ -81,40 +77,7 @@ command line.A plaintext `http://` control plane is accepted only on loopback. Pass`allowInsecure: true` for a network you trust.-## Layout--- `src/identity.ts`: ed25519 key pair, libp2p key encodings, peer ID.-- `src/controlplane.ts`: `/info`, `/keys`, `/enroll`, `/enroll/status`,- `/register`, `/refresh`, with the proof-of-possession challenges from- `api/network.go`.-- `src/credential.ts`: what a member holds, `AuthFrame` encoding.-- `src/mesh.ts`: `AgentMesh`, persistence under a state directory- (`identity.key` in the libp2p private key encoding, `credential.json`).-- `src/biscuit.ts`: verification of a peer's credential with biscuit-wasm,- as `internal/identity.verifyBiscuit` does.-- `src/host.ts`, `src/auth.ts`, `src/session.ts`: the libp2p host, the- `/sam/auth/1.0.0` handshake on both sides, `MeshSession` with the relay- reservation and the refresh loop.-- `src/discovery.ts`, `src/mcp.ts`: service keys for the mesh DHT, and MCP- over `/sam/mcp/1.0.0` (a `Transport` for the official MCP client).-- `src/authorizer.ts`: the provider authorizer, as- `internal/node.(*SamNode).Authorize`, over the generated baseline Datalog- and the mesh policy rules from `GET /policies`.-- `src/serve.ts`: the `/sam/mcp/1.0.0` server, the `/libp2p-http` server- and client, and the service registry behind `session.serve()`.-- `src/sync.ts`: the ban set and the control plane's gossip events;- `session.sync()` pulls keys, bans and router addresses as- `internal/node/controlplane_sync.go` does.-- `src/gen/`: generated from `api/sam.proto` and `api/datalog.go` by- `hack/gen-sdk-proto.sh`.--## Test+## License-```bash-npm test # unit tests, fake control plane and router-go test ./tests/integration -run TestNativeSDKs # real control plane, router and sam-node-```--The integration tests run `dist/conformance.js` and-`dist/conformance-join.js`, so build first. They skip when `dist/` or-`node_modules/` is missing.+Apache-2.0. Issues and contributions at+[github.com/google/sam](https://github.com/google/sam).diff --git a/sdk/python/README.md b/sdk/python/README.mdindex 16134b40..f440334b 100644--- a/sdk/python/README.md+++ b/sdk/python/README.md@@ -1,25 +1,24 @@# sam-mesh (Python)Native Python SDK for joining a SAM agent mesh from inside the agent-process. It replaces the `sam-node` sidecar for agents written in Python.-Import it as `agent_mesh`.+process. It replaces the `sam-node` sidecar for agents written in Python:+the agent enrolls with the control plane, joins the mesh through a router,+finds services and calls them, publishes services of its own, and follows+the control plane's keys, bans and policy while it runs. Import it as+`agent_mesh`.-Status: **milestone 3** (identity, enrollment, credential refresh, joining-the mesh over libp2p with mutual authentication, discovering services and-calling their tools). Serving tools is the next milestone; see-[../README.md](../README.md) for the plan.+Guide: [sam-mesh.dev/docs/guides/native-sdks](https://sam-mesh.dev/docs/guides/native-sdks/).+Source: [github.com/google/sam/tree/main/sdk/python](https://github.com/google/sam/tree/main/sdk/python).## Install```bash-pip install sam-mesh # from PyPI, released with the repository-pip install -e 'sdk/python[test]' # from a checkout+pip install sam-mesh```-Runtime dependencies are `cryptography`, `protobuf`, `biscuit-python`,-`libp2p` (py-libp2p 0.7, trio-based), `multiaddr`, `mcp` (2.x), `h11` and-`httpx`. Python 3.11 or later. py-libp2p's `fastecdsa` builds from source-against GMP (`libgmp-dev` on Debian).+Python 3.11 or later. The SDK runs on trio (py-libp2p is trio-based); under+asyncio, use it through `anyio` with the trio backend. One dependency,+`fastecdsa`, builds from source against GMP (`libgmp-dev` on Debian).## Use@@ -93,43 +92,7 @@ command line.A plaintext `http://` control plane is accepted only on loopback. Pass`allow_insecure=True` for a network you trust.-## Layout--- `agent_mesh.identity`: ed25519 key pair, libp2p key encodings, peer ID.-- `agent_mesh.controlplane`: `/info`, `/keys`, `/enroll`, `/enroll/status`,- `/register`, `/refresh`, with the proof-of-possession challenges from- `api/network.go`.-- `agent_mesh.credential`: what a member holds, `AuthFrame` encoding.-- `agent_mesh.mesh`: `AgentMesh`, persistence under a state directory- (`identity.key` in the libp2p private key encoding, `credential.json`).-- `agent_mesh.biscuit`: verification of a peer's credential with- biscuit-python, as `internal/identity.verifyBiscuit` does.-- `agent_mesh.host`, `agent_mesh.auth`, `agent_mesh.relay`,- `agent_mesh.session`: the libp2p host, the `/sam/auth/1.0.0` handshake on- both sides, the circuit relay v2 client (reservation, dial, accept) and- `MeshSession` with the refresh loop.-- `agent_mesh.discovery`, `agent_mesh.mcp_client`: the bounded- GET_PROVIDERS walk and ADD_PROVIDER on the mesh DHT, and MCP over- `/sam/mcp/1.0.0` for `mcp.ClientSession`.-- `agent_mesh.authorizer`: the provider authorizer, as- `internal/node.(*SamNode).Authorize`, over the generated baseline Datalog- and the mesh policy rules from `GET /policies`.-- `agent_mesh.serve`: the `/sam/mcp/1.0.0` server, the `/libp2p-http`- server and client (`h11` on the stream), and the service registry behind- `session.serve()`.-- `agent_mesh.sync`: the ban set and the control plane's gossip events;- `session.sync()` pulls keys, bans and router addresses as- `internal/node/controlplane_sync.go` does.-- `agent_mesh._proto`, `agent_mesh._gen`: generated from `api/sam.proto`,- `sdk/python/proto/circuit.proto` and `api/datalog.go` by- `hack/gen-sdk-proto.sh`.--## Test+## License-```bash-pytest sdk/python/tests # unit tests, fake control plane and router-go test ./tests/integration -run TestNativeSDKs # real control plane, router and sam-node-```--The integration tests skip unless `agent_mesh` imports in-`sdk/python/.venv/bin/python` or `python3`.+Apache-2.0. Issues and contributions at+[github.com/google/sam](https://github.com/google/sam).