Agent Mesh Repository AI Agent Guidelines

You are an expert software engineering assistant helping to develop, maintain, and test the Agent Mesh repository.

1. Architecture & Component Independence

• Decoupled Architecture: The agentmesh-control-plane, agentmesh-router and agentmesh-node components are strictly independent. They must not share internal state or tightly couple their logic.
• API Communication: All data communication between agentmesh-control-plane, agentmesh-router and agentmesh-node must happen exclusively via the common API defined in api/agentmesh.proto.
• One schema, two encodings: every request and response on any Agent Mesh-defined surface is a message in api/agentmesh.proto. The mesh protocol — anything a mesh component speaks (node, router, the SDKs under sdk/): enrollment, refresh, keys, leases, auth streams, policy sync, token exchange (/token/exchange), and outbound border JWT minting (/sts/token) — is binary protobuf (application/x-protobuf). The operator plane — what humans, the web console and admin CLIs call (/admin/*, /users/*, POST /policies) — is protojson of the same messages, with UseProtoNames and unknown fields rejected. Never define a wire shape on a Agent Mesh-defined surface as a Go struct with json tags, an anonymous struct or map[string]any, and never serialize an internal/storage (or any other internal) type onto either surface. The sole exceptions are external standard protocols for unmodified third-party clients and cloud federation: OAuth 2.1 / RFC 8693 / RFC 7009 / RFC 9728 (POST /oauth/token, POST /oauth/revoke, /oauth/authorize, /.well-known/*, /jwks), Envoy ext_authz / ext_proc, MCP JSON-RPC (/mcp), OpenAI /v1/*, and A2A /.well-known/agent-card.json. Clients in cmd/, internal/console and cross-language SDKs (sdk/js, sdk/python) import api/ or its generated bindings only; the in-module embedded Go SDK (sdk/meshnet) wraps internal/node, internal/identity, and api/ so embedded Go applications and agentmesh-node share one PEP implementation. The node's /debug/* endpoints are exempt: unversioned diagnostics for humans, printed as-is by agentmesh-node debug and parsed by no client, so they stay unexported Go structs.
• Instants are google.protobuf.Timestamp, named *_time (expire_time, sign_time, event_time), never int64 seconds or milliseconds. Timestamp has fixed units, an explicit unset, renders as RFC 3339 in protojson (an int64 renders as a quoted decimal string), and has a first-class conversion in Go, JavaScript, Python and Dart. A receiver treats an unset instant as invalid, never as the epoch. The one exception is a proof-of-possession value: it is the number that appears in the signed text (mesh:<endpoint>:<peer_id>:<n>), so it stays an int64 named challenge_unix_ms, the unit in the name. What a member persists between runs is also a message here (MemberCredential), so a state directory written by one implementation loads in another.
• Datalog text is the policy contract: the control plane renders the mesh policy as Datalog rules (PolicyConfigGetResponse.datalog_rules); every member, in any language, adds that text to its authorizer and none derives rules from roles and bindings itself. Datalog must stay in the form every Biscuit implementation parses: a predicate carries at least one term (presence-only facts are name(true), see api.MarkerFact).
• Secrets never travel as flag values: binaries read credentials from a file (--*-path) or the environment, never from a command-line argument that would sit in ps output and shell history. Banners and logs name the source of an operator-supplied secret instead of echoing it.
• Task-Scoped Authorization & Safe Biscuit Attenuation (tar_block): Agent Mesh acts as the Authority, Policy Decision Point (PDP), and Task-Scoped Credential Layer (site/content/docs/contributing/security-architecture.md). Never add Datalog rules or checks to non-authority Biscuit blocks (block_idx >= 1). Appended blocks must contain 0 rules, 0 checks, and exactly 1 tar_block("<base64url-proto>") fact encoding a serialized api.TaskAuthorizationRule. Verifiers enforce the intersection of Block 0 Datalog RBAC and every appended TaskAuthorizationRule in Go, TypeScript, and Python.
• Two-Token Model & Complementary Gateway/PEP Integration: Inside the mesh, credentials are Biscuits; at both borders, credentials are standard JWTs (site/content/docs/contributing/security-architecture.md). Inbound platform credentials (OIDC, K8s SA, SPIFFE JWT-SVID) exchange into delegated Biscuits (POST /token/exchange); outbound verified Biscuits mint short-lived ES256 JWTs at the control plane (POST /sts/token) that the egress node exchanges at cloud STS endpoints (CloudTokenExchanger). agentmesh-node integrates with existing gateways (agentgateway, Istio, Envoy) via Envoy ext_authz / ext_proc and RFC 8693 /oauth/token, while native SDKs (sdk/meshnet, sdk/js, sdk/python) attenuate and seal Biscuits in memory.
• Policy on Names: egress policy, secret injection and routing decisions are made on the destination name, never on an IP. Deny by default.
• Zero Trust: Enforce a Zero Trust architecture. Assume no implicit trust between nodes, control planes, routers, or external actors. All data passing through the API must be authenticated, authorized, and validated.
• Nothing interacts with the mesh unauthenticated: a router or a member serves a mesh protocol (the DHT, gossip, the relay, the data plane) only to a peer that completed the mesh handshake on that connection and whose credential has not lapsed; a stream from any other peer is reset and counted. The only protocols open to a peer that has not authenticated yet are the ones the handshake itself needs: the transport security handshake, identify, and /mesh/auth. A libp2p library that registers its own stream handlers (kad-dht, gossipsub) is built on a host wrapper that installs this check in front of every handler, and its routing table admits only authenticated peers. A connection that has not authenticated within the deadline is closed. This holds for reads as much as for writes: a directory lookup or a gossip subscription is mesh data.
• Zero config, safe defaults: the goal is zero trust with zero configuration. A component started with no flags must be secure; every default is the safe value (deny, verify, short-lived, loopback-only, bounded), and an operator opts into anything looser with an explicit flag whose help text names the risk. Before adding a flag, option or knob, ask whether a safe default removes the need for it.
• Auditable and traceable behavior: when a member is admitted, refused, disconnected, shed, skipped or retried, the process says so in a log line at the right level or in a counter, and the states a component is in (attached routers, authenticated peers, listed peer routers, leased addresses) are gauges. A silent continue, a swallowed error or a condition that short-circuits a decision without a trace is a defect even when the behavior is correct. When a failure in a test or on a testnet cannot be explained from the logs and metrics the binaries already emit, the fix includes the missing instrumentation, so that the next occurrence can be read from the data instead of reproduced.
• Simple UX: Maintain a very simple User Experience. Configuration, CLI usage, and error messages must be intuitive, minimal, and explicitly clear.

2. Dependency Management (Strict Constraint)

• You are forbidden from suggesting any code that requires a new entry in go.mod unless you explicitly ask for my permission first.
• If a task can be solved using the existing dependencies or the Go standard library, you must choose that path even if it requires more lines of code.

3. Testing Best Practices

Enforce strict modularity in testing. The repository uses a defined testing pyramid (Unit, Integration, and E2E via Bats). You must adhere to the following testing philosophy:

• Optimize for Test Speed: E2E tests are slow and strictly based on existing Critical User Journeys (CUJs).
• Push Coverage Down: If test coverage for a specific edge case or feature can be added at a lower level (Unit or Integration), it is strictly preferred over E2E for speed.
• No Redundancy: Do not replicate a test in the slower E2E path if it is already sufficiently covered in the Integration path.
• Test Domains:
  • Unit Tests: Focus on isolated, internal functions.
  • Integration Tests (tests/integration/): Verify module interactions and API compliance in Go and those are time bounded, no more than 10 seconds per execution.
  • E2E Tests (tests/e2e/*.bats): Use Bats (Bash Automated Testing System) exclusively for high-level, black-box testing of core CUJs.
• Idiomatic Go, no test frameworks: Go tests use the standard testing package and nothing else: t.Run for cases, table-driven tests, t.Fatalf/t.Errorf with a message that states what was got and what was wanted, t.Cleanup for teardown, t.TempDir for files, httptest and net.Listen("tcp", "127.0.0.1:0") for servers. Ginkgo, Gomega, Testify and any other assertion or matcher library are not used and must not be added, directly or through a dependency. Test code is production code: the people who write and read the implementation write and read its tests, so a test is plain Go that compiles under the same linter and reads top to bottom without a DSL to learn. A helper is justified by repetition across tests, not by making one test shorter; do not build fixture hierarchies, suite objects or matcher abstractions. A failing test must say in its own output what happened, and must not swallow an error to keep going.
• A flaky test is a bug report: a test that fails once in CI and passes on a rerun has found a race or an ordering the code did not account for, and that race exists in production too, where it has no rerun. Do not retry it, widen its timeout or add a time.Sleep. Reproduce it first: compile the test binary with the race detector and run it in parallel under load, go test -c -race -o /tmp/pkg.test ./internal/pkg && stress -p 8 -timeout 2m /tmp/pkg.test -test.run 'TestName' (golang.org/x/tools/cmd/stress), and starve it of CPU with taskset -c 0-1 when the CI runner is smaller than the workstation. Read the failure from the binaries' own output; when the logs and metrics in the failure do not explain it, that is the gap to close first, in the production code: the log line, counter or gauge for the state the test could not see. Then fix the code, make the test wait on the exported condition rather than on time, and run the stress loop again until it is clean for hundreds of runs. Tests in tests/integration/ reserve ports from one fixed base per process, so several processes of that suite collide on ports; run it with -p 1 under taskset and reserve -p N for package unit tests.

4. Code Quality & Modularity

• Ensure all new code is highly modular, prioritizing small, single-responsibility functions that are easy to unit test.
• Respect the existing repository structure (cmd/, api/, internal/, tests/).

5. Validation

• Ensure binaries build using make
• Ensure linter passes make lint
• Ensure test passes make test
• Ensure e2e test passes make e2e-test

6. Environments

• There are two public testnets available hub.sam-mesh.dev that is deployed from the latest released tag and bananas.sam-mesh.dev that is deployed from the main branch.
• Their configurations can be found under .github/k8s.
• Their deployments are managed under .github/workflows/deploy.yaml.