Skip to content

Agent Mesh

sdk: package READMEs carry what a user needs, nothing about the repository

Antonio Ojea3959981b0cb5
diff --git a/sdk/README.md b/sdk/README.md
index 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 with
go-libp2p, `sdk/testdata/biscuit_vectors.json` holds tokens minted by the
control 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.md
index 94aadbc9..af3fde8a 100644
--- a/sdk/js/README.md
+++ b/sdk/js/README.md
@@ -1,25 +1,21 @@
# @sam-mesh/sdk
Native 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.md
index 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).