Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
agents: auditable behavior, safe defaults, idiomatic Go tests
Antonio Ojeabfa83b4554c4
diff --git a/.gemini/styleguide.md b/.gemini/styleguide.mdindex e0ef7633..ddda31a1 100644--- a/.gemini/styleguide.md+++ b/.gemini/styleguide.md@@ -170,6 +170,17 @@ per execution. Coverage belongs at the lowest layer that can express it.7. **Tests must not weaken production checks.** Flag test-only flags, `iftesting` branches, or exported hooks whose only purpose is to skip averification step.+8. **Tests are plain Go on the standard `testing` package.** Flag any+ import of `github.com/stretchr/testify`, `github.com/onsi/ginkgo`,+ `github.com/onsi/gomega` or another assertion or matcher library, in+ test code or in `go.mod`; the fix is `if got != want { t.Fatalf("...: got+ %v, want %v", got, want) }`. Flag suite objects, fixture hierarchies,+ `Describe`/`It` style nesting, and helpers whose only effect is to make+ one test shorter: a helper is justified by repetition across tests.+ Flag a test that logs an error and continues, or that ignores a returned+ error (`_ = f()`) on the path under test: the error must fail the test.+ Flag assertion messages that do not state both the observed and the+ expected value.## 4. Dependencies@@ -216,11 +227,58 @@ regardless of how carefully the rest of the system handles them.`agentmesh-control-plane --admin-token-path` and `agentmesh-node--bootstrap-token-path` are the reference shape.-## 6. Review output+## 6. Behavior must be auditable from logs and metrics++### Why++Agent Mesh runs as a fleet of routers and thousands of members on networks+nobody can attach a debugger to. When a member does not attach, a router+pair does not federate, or a call fails, the operator has the binaries'+logs and `/metrics` and nothing else. A decision the code takes without a+trace (a `continue` on a condition, an early `return nil`, a branch that+skips a handshake because a connection already exists) is correct until it+is not, and then the failure cannot be explained without a reproduction. A+bug whose diagnosis needed a temporary print statement is a bug in the+instrumentation as much as in the logic.++### Rules++1. **Every decision about a peer leaves a trace.** Admission, refusal,+ closing a connection, sending a peer away, skipping a candidate, giving+ up a retry: each has a log line at the level its frequency allows+ (`Info` for state changes, `Debug` for per-request steps, `Warn` for+ something an operator should act on) or a counter with a `reason` or+ `result` label. Flag a `continue`, `return` or `break` on an error or a+ condition that has neither.+2. **State is a gauge.** A set the component maintains (attached routers,+ authenticated peers, peer routers listed and authenticated, leased+ addresses, banned peers, pending retries) is exported as a gauge from the+ live data structure, never from a counter that is incremented and+ decremented by hand. Flag a new `sync.Map`, map or slice that models a+ peer or member set without a corresponding metric.+3. **Errors are not swallowed.** `_ = f()` and `if err != nil { return }` on+ anything other than a close or a best-effort write need a log line or a+ counter. Flag the bare form.+4. **Log lines carry the identifier.** A line about a peer names the peer+ ID; a line about a lease names the addresses; a line about a router+ names the router. Flag lines that say what happened without saying to+ whom.+5. **A flaky-test fix adds instrumentation.** A PR that makes a test+ deterministic by waiting on a condition must expose that condition in+ the binary (a gauge, a `/debug` view, a log line) and wait on it there,+ not on a `time.Sleep`. Flag a fix whose only change is in the test.+6. **Safe defaults, zero configuration.** A new flag or option needs a+ default that is secure without the operator reading the docs: deny, verify,+ short-lived, loopback-only, bounded. Flag a default that opens something+ (`AllowInsecure*` true, an unbounded limit, a disabled check) and a flag+ whose help text does not name the risk of loosening it. Ask whether the+ flag is needed at all when the safe default covers every deployment.++## 7. Review output- Group findings by the section numbers above so the author can see whichrule applies.-- For rule 1, rule 2 and rule 5 findings, always propose the corrected code, not- just the diagnosis.+- For rule 1, rule 2, rule 5 and rule 6 findings, always propose the+ corrected code, not just the diagnosis.- Do not raise generic Go style nits (naming, comment punctuation, importordering) that `gofmt` and `golangci-lint` already enforce via `make lint`.diff --git a/AGENTS.md b/AGENTS.mdindex 4e3f241d..a3bab059 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -13,6 +13,8 @@ You are an expert software engineering assistant helping to develop, maintain, a* **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/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.+* **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)@@ -28,6 +30,7 @@ Enforce strict modularity in testing. The repository uses a defined testing pyra* **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.## 4. Code Quality & Modularity* Ensure all new code is highly modular, prioritizing small, single-responsibility functions that are easy to unit test.