Repository navigation
docs: fix the CLI flag references and add the console and mcp-client pages - #787
Merged
Merged
Conversation
The agentmesh-node usage block omitted debug, and no section named its subcommands or its --socket-path flag. The node has debug mesh-info, network-info, token-info, logs, connectivity, peer-addrs and connect-peer, each a call of one /debug/* route over the Unix socket (cmd/agentmesh-node/debug.go:36-85).
The usage block and the Use string wrote the URL in square brackets, as optional, and the --control-plane row said join takes the flag as a positional argument. join exits with "No control plane specified" without the argument (cmd/agentmesh-node/main.go:680-682). join enrolls with the argument and overwrites the flag's value (cmd/agentmesh-node/main.go:712-713). The root command still checks the flag's transport before join runs (cmd/agentmesh-node/main.go:292-299).
The usage block wrote local-addr in square brackets, as optional. forward takes exactly two arguments and its own usage string writes <local-addr> (cmd/agentmesh-node/forward.go:43-45).
The global flags table said --audience is the OIDC audience to request. The flag reaches only the GCP metadata token source that run --cloud-provider selects (cmd/agentmesh-node/main.go:378, internal/node/tokensource.go:229-232). The interactive login requests the audience that /info advertises (cmd/agentmesh-node/main.go:280).
The global flags table said --oidc-issuer overrides the identity provider that the control plane advertises. The interactive login reads the issuer from /info and never from the flag (cmd/agentmesh-node/main.go:262-266). In run, a non-empty flag selects the client-credentials token source against that issuer (cmd/agentmesh-node/main.go:371-378, internal/node/tokensource.go:225-226).
The join table said a node that keeps the bootstrap token file recovers on its own after a 401. join does not store the path. Only run passes it to the node, and the recovery reads it from there (cmd/agentmesh-node/main.go:466, internal/node/controlplane_sync.go:398-402). The sentence moves to the run table.
The --daemonize row said it refuses to run on a node that has never enrolled. It refuses only when the command also passes none of --bootstrap-token-path, --bootstrap-token, --jwt-path and --jwt (cmd/agentmesh-node/daemonize.go:65).
The agentmesh-node page had no section for forward. The command takes --socket-path, --api-addr and --api-token-path, and reads AGENTMESH_API_ADDR, AGENTMESH_TASK_TOKEN and AGENTMESH_API_TOKEN (cmd/agentmesh-node/forward.go:64, 90-92, 135).
The skill table listed --project and --dir for skill install only. Both flags are registered on skill list as well (cmd/agentmesh-node/skill.go:85-88).
The --dht-replication help of agentmesh-control-plane said every member holds a session with each of the closest routers, and that each replica is a session more per key on every member. The help of agentmesh-one said the replicas hold each service and answer each lookup. The control plane reference counted the router a member announced to among the replicas. A member asks only the routers it holds. The router it announced to keeps the record and places a copy on this many routers closest to the key, besides itself (internal/router/directory.go:379-419).
The /info row said the directory parameters are what a node runs its DHT on. Only a router builds a DHT (internal/router/router.go:543). A node reads the reprovide interval from the parameters (internal/node/node.go:854) and nothing else.
The control plane flags table left out --sts-issuer-url and its environment variable (cmd/agentmesh-control-plane/main.go:219, 100). The value is the issuer of the discovery documents and the iss claim of the JWTs that /sts/token mints. Without it, the control plane takes the scheme and host of each request (internal/controlplane/sts.go:337-352).
The agentmesh-one page said a zero tunable keeps the component's default. --router-shutdown-lease-ttl and --router-auth-deadline have non-zero defaults and pass a zero through (cmd/agentmesh-one/main.go:245-246). The router then sends no last lease (internal/router/router.go:1214) or keeps every connection (internal/router/goaway.go:171).
The agentmesh-one flags table listed --db-dsn only. The binary also takes --db-dsn-path and the AGENTMESH_DB_DSN variable, and either one overrides --db-dsn (cmd/agentmesh-one/main.go:208, 85).
The router page said the refresh runs at the pass that finds less than a fifth of the credential's lifetime left. The threshold is the constant BiscuitTokenTTL/5, 4.8 hours, whatever lifetime the control plane minted (internal/router/router.go:1138-1146).
agentmesh-console ships in every release (.goreleaser.yaml, install.sh) and had no reference page. The page lists its seven flags from --help (cmd/agentmesh-console/main.go:35-43) and the routes it serves (internal/console/server.go:208-253).
mcp-client ships in every release (.goreleaser.yaml, install.sh) and had no reference page. The page lists its nine flags from --help and the AGENTMESH_API_TOKEN variable (cmd/mcp-client/main.go:38-47, 56-62). agentmesh-bench gets no page: .goreleaser.yaml deliberately leaves it out of releases as a measurement instrument built from the repo.
The --signing-key-path help of agentmesh-control-plane and agentmesh-one, the startup log of operator-managed keys and the agentmesh-one reference page said to keep the previous key for the grace period. A credential lives 24 hours by default (api/network.go:69), and the grace period is 1 hour (cmd/agentmesh-control-plane/main.go:207). The operator keeps the previous key until every credential it signed has expired (internal/controlplane/signingkeys.go:45-48). The control plane reference page already says so.
The join section said join refuses a different control plane until agentmesh-node reset has run. join never reads the stored control plane URL, so it enrolls with any URL it is given (cmd/agentmesh-node/main.go:669-795). Only run compares the two. With --join on a terminal, run asks for a confirmation and clears the stored identity before it switches (cmd/agentmesh-node/main.go:392-414). Without --join, run exits on a mismatch (cmd/agentmesh-node/main.go:498-503).
The exit section said a ban ends the node through a refused refresh, and that a node that loses its routers keeps running. A 403 on refresh is not fatal, and the node keeps its current credential (internal/node/node.go:1603-1611). The connection monitor exits after 3 failed checks in a row (internal/node/node.go:781, 977-981), one --monitor-interval apart, 1 minute by default (cmd/agentmesh-node/main.go:863). A router drops a banned node and refuses its handshake (internal/router/router.go:1046-1057, 1666). The renewal loop exits once the credential has expired and neither a refresh nor a new enrollment succeeds (internal/node/node.go:1496-1504).
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request updates command-line flag descriptions, logs, and reference documentation across several components, including the control plane, node, and router, to clarify behavior around key rotation, DHT replication, and exit conditions. It also introduces reference documentation for agentmesh-console and mcp-client. In the code changes, the join command usage in agentmesh-node was updated to indicate that the control plane URL is a required argument; feedback suggests updating the command's argument validation to cobra.ExactArgs(1) to enforce this requirement properly.
|
|
||
| joinCmd := &cobra.Command{ | ||
| Use: "join [control_plane_url]", | ||
| Use: "join <control-plane-url>", |
Contributor
There was a problem hiding this comment.
Since the command usage is updated to <control-plane-url> to indicate that the control plane URL is a required positional argument, the command's Args validation should also be updated to cobra.ExactArgs(1) instead of cobra.MaximumNArgs(1). This allows Cobra to automatically validate the argument presence and print the usage instructions on failure, rather than manually checking and calling logger.Fatal inside the Run function.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The CLI reference pages are where an operator looks up a flag. Sixteen statements there disagree with the binaries, two binaries that ship have no page, and two
--helpstrings say something the code does not do.What changed
agentmesh-node: the usage block listsdebugand its subcommands.joinrequires the URL, andforwardrequires the local address. The pages describe--audience,--oidc-issuer,--bootstrap-token-path,--daemonize, theforwardflags andskill listas the code uses them. They also say whenjoinandrun --joinswitch control planes and when a node exits.agentmesh-control-plane: the--dht-replicationhelp and row describe record placement, and members hold no session with the replica routers./infogives a node its reprovide interval, and the node runs no DHT. The page documents--sts-issuer-url.agentmesh-one: zero turns off the router's last lease and auth deadline. The page documents--db-dsn-pathandAGENTMESH_DB_DSN.agentmesh-router: the router refreshes its credential at a fixed 4.8 hours left.agentmesh-consoleandmcp-client, from their--helpoutput.agentmesh-benchis not released, so it gets no page.--signing-key-pathhelp, the startup log and theagentmesh-onepage say to keep a replaced key until every credential it signed has expired.Scope
cmd/andinternal/controlplane. No behavior change.Verification
--help. An independent review confirmed the new text, and its corrections are in.make lintreports 0 issues, andgo test ./internal/controlplanepasses. The site builds with Hugo 0.147.5 and adds no broken link.