peers.list
Každý worker tohoto repozitáře: id, vlastní název a verze klienta z jeho initialize, transport, kdy se připojil, kdy byl naposledy viděn, co oznámil a ke kterému checkoutu je připojen. Server obsluhuje jeden checkout, takže nástěnka repozitáře, na kterém se pracuje přes propojené worktree, se sbírá: nástěnka tohoto checkoutu z paměti, nástěnka každého jiného checkoutu ze serveru, který jmenuje jeho lease, dotázaného jen na jeho vlastní nástěnku. 'boards' říká, které checkouty byly pokryty, a 'complete', zda bylo možné přečíst každý z nich, takže krátká nástěnka se nikdy nesplete s prázdným repozitářem. 'checkouts: this' přečte jednu nástěnku a nic dalšího nevyjmenovává, netestuje ani se na nic neptá. V paměti na každém serveru; mizí s procesy.
Každý worker tohoto repozitáře: id, vlastní název a verze klienta z jeho initialize, transport, kdy se připojil, kdy byl naposledy viděn, co oznámil a ke kterému checkoutu je připojen. Server obsluhuje jeden checkout, takže nástěnka repozitáře, na kterém se pracuje přes propojené worktree, se sbírá: nástěnka tohoto checkoutu z paměti, nástěnka každého jiného checkoutu ze serveru, který jmenuje jeho lease, dotázaného jen na jeho vlastní nástěnku. 'boards' říká, které checkouty byly pokryty, a 'complete', zda bylo možné přečíst každý z nich, takže krátká nástěnka se nikdy nesplete s prázdným repozitářem. 'checkouts: this' přečte jednu nástěnku a nic dalšího nevyjmenovává, netestuje ani se na nic neptá. V paměti na každém serveru; mizí s procesy.
- query
- behaviorally_verified
- moduly peers
- #peers
- #coordination
Zpřístupnění
Kde je tato jedna definice dosažitelná. Absence je explicitní: povrch, který není uveden, ji nenese.
| povrch | jako |
|---|---|
| MCP | nástroj majordomus_peers |
| HTTP | GET /api/v1/peers operationId peers.list |
| příkazová řádka | — |
Schémata
Kanonický vstup a výstup z typů Rustu; schéma nástroje MCP a parametry a odpovědi OpenAPI se odvozují z nich.
vstup · PeerListInput
Na co se ptát
peers.list: jak široká je nástěnka.
Totéž jedno pole, totéž slovo a tatáž výchozí hodnota jako super::server::ServerStatusInput, protože je to táž otázka kladená téže množině checkoutů a volající by se ji neměl učit dvakrát.
Důkazem je níže the_default_board_is_the_repositorys, ne zde příklad v dokumentaci: tento modul je pub(crate), takže doc test — který se kompiluje jako externí crate — nemůže typ vůbec pojmenovat.
| vlastnost | typ | povinné | popis |
|---|---|---|---|
| checkouty | reference | ne | Které checkouty nástěnka pokrývá. Chybějící znamená repository; this je checkout, ke kterému volání dospělo, a nic jiného, a tím se ptá sourozenecký server, aby se sběr nikdy nemohl zeptat zpět. výchozí "repository" |
JSON Schema
{
"$defs": {
"Checkouts": {
"description": "Which checkouts a reading of the server status covers.\n\nThe two answers cost differently and that is the whole reason the choice exists: the\nrepository's checkouts are read from git's registry of them and each one costs a lease\nread and a probe, while this checkout alone costs one of each and enumerates nothing.\nThe word each variant serialises to is the word the query parameter, the tool input and\nthe command-line flag all take.\n\n```\nuse majordomus_cli::capability::builtin::server::Checkouts;\nassert_eq!(serde_json::to_value(Checkouts::This).unwrap(), \"this\");\nassert_eq!(serde_json::to_value(Checkouts::Repository).unwrap(), \"repository\");\nassert_eq!(Checkouts::default(), Checkouts::Repository, \"the wide answer is what a caller who says nothing has always got\");\n```",
"oneOf": [
{
"const": "repository",
"description": "Every checkout git registers for the repository, the primary first — a lease read\nand a probe each. The default, because it is the answer this capability gave before\nthere was anything to ask.",
"type": "string"
},
{
"const": "this",
"description": "This checkout alone. No other checkout is enumerated, no other lease is read and no\nother server is probed; `servers` holds the one entry, and it is this one.",
"type": "string"
}
]
}
},
"description": "What to ask of `peers.list`: how wide the board is.\n\nThe same one field, the same word and the same default as\n`super::server::ServerStatusInput`, because it is the same question asked of the same\nset of checkouts, and a caller should not have to learn it twice.\n\nThe evidence for that is `the_default_board_is_the_repositorys` below rather than a doc\nexample here: this module is `pub(crate)`, so a doc test — which compiles as an external\ncrate — cannot name the type at all.",
"properties": {
"checkouts": {
"$ref": "#/$defs/Checkouts",
"default": "repository",
"description": "Which checkouts the board covers. Absent means `repository`; `this` is the checkout the call reached and nothing else, and it is what a sibling server is asked so that a gather can never ask back."
}
},
"title": "PeerListInput",
"type": "object"
}výstup · PeerList
Odpověď
peers.list: každý pracovník tohoto repozitáře, z nástěnky každého checkoutu.| vlastnost | typ | povinné | popis |
|---|---|---|---|
| nástěnky | array | ano | Jedna položka na každý checkout, který odpověď pokrývá, ať už byl zasažen, nebo ne. |
| volající | jedno ze 2 | ne | Vlastní id peera volajícího, když volání přišlo přes relaci MCP. Pozice na nástěnce tohoto checkoutu, ne trvalá identita: po opětovném připojení se přidělí znovu a Peer::checkout je ta polovina identity workera, která není. |
| dokončeno | boolean | ano | Zda byla přečtena každá nástěnka, kterou odpověď pokrývá. false, když se server některého checkoutu nepodařilo zeptat, a BoardView::reason říká který a proč — aby se nikdy nehlásilo „nikdo jiný tu není“, když pravda zní „nemohl jsem se zeptat“. |
| počet | integer | ano | Kolik peerů je připojeno napříč všemi načtenými nástěnkami, včetně volajícího. |
| překryvy | array | ne | Každá dvojice peerů, jejichž nárokované rozsahy se potkávají, každá dvojice jednou — nyní i napříč checkouty, nejen v rámci jednoho. Prázdný výpis je běžný případ a čtenář, který zde vidí záznam, se dívá na dva pracovníky, kteří se chystají dělat tutéž práci. |
| peers | array | ano | Peeři, nejdřív nástěnka tohoto checkoutu a pak sourozenci v pořadí, v jakém je git registruje, každý v pořadí připojení své vlastní nástěnky. Každý nese checkout, ke kterému patří, protože p1 je první relace každé nástěnky. Peer, který něco oznámil a pak odešel, je tu stále, s attached: false. |
JSON Schema
{
"$defs": {
"Announcement": {
"description": "One claim a peer has made: what it is working on, and where.\n\nA peer may hold several. The `name` is what tells them apart and what makes announcing\nagain an update rather than a second claim: announce under the same name and the claim\nis replaced, announce under a new one and the peer now holds both. A peer that never\nnames anything holds exactly one claim, the unnamed one, which is what a single session\nannouncing about itself has always had.",
"properties": {
"at": {
"description": "When it was announced, RFC 3339, UTC.",
"type": "string"
},
"intent": {
"description": "One line: the task or intent, in the peer's words.",
"type": "string"
},
"name": {
"description": "What this claim is called, when the peer named it. Absent for a peer's unnamed claim.",
"type": [
"string",
"null"
]
},
"scope": {
"description": "Repository-relative paths the peer expects to touch; informational, never enforced here.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"intent",
"scope",
"at"
],
"type": "object"
},
"BoardView": {
"description": "One checkout's board, as the gather found it.\n\nPresent for every checkout the answer covers, whether or not its board could be read,\nbecause a listing that silently drops the checkouts it could not reach is the shape of\nanswer that made this capability wrong in the first place: a reader would see a short\nboard and conclude nobody else is working here.",
"properties": {
"attached": {
"description": "How many of this board's peers are attached.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"branch": {
"description": "The branch checked out there, when it could be read.",
"type": [
"string",
"null"
]
},
"id": {
"description": "The checkout's identity digest, the same value `server.status` reports as\n`checkout_id`. One per checkout, never a path, and stable across a restart.",
"type": "string"
},
"reason": {
"description": "Why this board is not in the answer. `None` when it is.",
"type": [
"string",
"null"
]
},
"standing": {
"$ref": "#/$defs/ServerStanding",
"description": "Where its server stands, by the same reading `server.status` reports."
},
"this_checkout": {
"description": "Whether this is the checkout of the server answering the call.",
"type": "boolean"
},
"url": {
"description": "The address its lease names, when it has one.",
"type": [
"string",
"null"
]
},
"worktree": {
"description": "Where the checkout is. The one thing on this board that a human can act on\ndirectly, and the one thing that survives a reconnect.",
"type": "string"
}
},
"required": [
"id",
"worktree",
"this_checkout",
"standing",
"attached"
],
"type": "object"
},
"ClientInfo": {
"description": "What a client said about itself in `initialize`.",
"properties": {
"name": {
"description": "`clientInfo.name`: `claude-code`, `codex`, `gemini-cli`, whatever the client sends.",
"type": "string"
},
"title": {
"description": "`clientInfo.title`, when the client sends one.",
"type": [
"string",
"null"
]
},
"version": {
"description": "`clientInfo.version`.",
"type": "string"
}
},
"required": [
"name",
"version"
],
"type": "object"
},
"Overlap": {
"description": "Two peers that claimed the same ground.\n\nReported when the second of them announces, so that a collision is known at the moment\nit is created rather than discovered afterwards in the history of a branch.",
"properties": {
"attached": {
"description": "Whether that peer is still attached. An overlap with a departed peer is a weaker\nsignal than one with a live session, and the reader is told which it is.",
"type": "boolean"
},
"checkout": {
"anyOf": [
{
"$ref": "#/$defs/PeerCheckout"
},
{
"type": "null"
}
],
"description": "Which checkout the other peer is attached to, when the reader knew.\n\nThe overlap that matters most is the one nobody could see before: two workers in\ntwo worktrees of one repository, each reading a board that held only itself, both\nclaiming `apps/majordomus-cli/src`. Naming the checkout is what turns \"p1 is on\nyour ground\" into something a reader can act on when `p1` is not on this board."
},
"intent": {
"description": "What it said it was doing.",
"type": "string"
},
"paths": {
"description": "The claims that meet: one line per pair, `yours` and `theirs`.",
"items": {
"$ref": "#/$defs/OverlapPath"
},
"type": "array"
},
"peer": {
"$ref": "#/$defs/PeerId",
"description": "The other peer."
}
},
"required": [
"peer",
"attached",
"intent",
"paths"
],
"type": "object"
},
"OverlapPath": {
"description": "One pair of claims that contain one another.",
"properties": {
"theirs": {
"description": "The path the other peer claimed.",
"type": "string"
},
"yours": {
"description": "The path the announcing peer claimed.",
"type": "string"
}
},
"required": [
"yours",
"theirs"
],
"type": "object"
},
"Peer": {
"description": "One peer as the board lists it.",
"properties": {
"announcement": {
"anyOf": [
{
"$ref": "#/$defs/Announcement"
},
{
"type": "null"
}
],
"description": "The most recently made of `Peer::claims`, for a reader that wants one line rather\nthan all of them. Derived from `claims` and never a second account of it: a peer\nholding one claim reports the same thing in both, which is what every peer that does\nnot name its claims reports."
},
"attached": {
"description": "Whether the session is still attached. A peer that announced something and then\nwent away is kept and listed with `attached: false`: what it said it was working on\noutlives the connection that said it, because the work does.",
"type": "boolean"
},
"checkout": {
"anyOf": [
{
"$ref": "#/$defs/PeerCheckout"
},
{
"type": "null"
}
],
"description": "Which checkout of the repository this peer is attached to; see `PeerCheckout`.\n\nThe board itself never sets it — a board does not know where it is — and it is\nstamped by the reader that gathered this peer, which is the one thing that knows\nwhich checkout's server it asked."
},
"claims": {
"description": "Every claim this peer holds, in name order, the unnamed one first. Empty for a peer\nthat has announced nothing.\n\nOne connection may be doing several things at once — a session that fans work out to\nsubagents shares its MCP session with all of them — and before this field the board\ncould hold only the last thing said, so each announcement silently erased the one\nbefore it and the other peers stopped seeing the rest of the scope.",
"items": {
"$ref": "#/$defs/Announcement"
},
"type": "array"
},
"client": {
"$ref": "#/$defs/ClientInfo",
"description": "The client behind it."
},
"connected_at": {
"description": "When it attached, RFC 3339, UTC.",
"type": "string"
},
"id": {
"$ref": "#/$defs/PeerId",
"description": "`p1`, `p2`, ..."
},
"last_seen_seconds_ago": {
"description": "Seconds since its last message.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"transport": {
"$ref": "#/$defs/Transport",
"description": "How it is attached."
}
},
"required": [
"id",
"client",
"transport",
"connected_at",
"last_seen_seconds_ago",
"attached"
],
"type": "object"
},
"PeerCheckout": {
"description": "Which checkout of the repository a peer is attached to.\n\nA board is one process's memory and a server serves one checkout, so a peer read from\na sibling checkout's server and a peer of this one are otherwise indistinguishable —\nand worse than indistinguishable, because the ids collide: `p1` is the first session\nof *every* board, so a repository-wide listing without this field would hold several\npeers called `p1` and no way to tell them apart. This is the qualification. The\nworktree path is the durable half of a worker's identity: the peer id is a position on\none board and is handed out again after a reconnect (`p3` this morning, `p1` after the\nbridge re-attached), while the checkout a worker is working in outlives its connection.\n\nAbsent on a peer a server reports about its own board without being asked which\ncheckout that is — `peers.announce` answers about the announcing session and the\nanswer is this server's by construction. The repository-wide listing stamps every\npeer it gathers, its own included, so that no entry of that answer is unqualified.\n\n```\nuse majordomus_cli::peers::PeerCheckout;\nlet c = PeerCheckout {\n id: \"b8293f11\".into(),\n worktree: \"/repo-wt/feature/x\".into(),\n branch: Some(\"feature/x\".into()),\n this_checkout: false,\n};\nlet v = serde_json::to_value(&c).unwrap();\nassert_eq!(v[\"branch\"], \"feature/x\");\nassert_eq!(v[\"this_checkout\"], false);\n```",
"properties": {
"branch": {
"description": "The branch checked out there, when it could be read.",
"type": [
"string",
"null"
]
},
"id": {
"description": "The checkout's identity digest, the same value `server.status` reports as\n`checkout_id`. One per checkout, never a path, and stable across a restart.",
"type": "string"
},
"this_checkout": {
"description": "Whether this is the checkout of the server answering the call.",
"type": "boolean"
},
"worktree": {
"description": "Where the checkout is. The one thing on this board that a human can act on\ndirectly, and the one thing that survives a reconnect.",
"type": "string"
}
},
"required": [
"id",
"worktree",
"this_checkout"
],
"type": "object"
},
"PeerId": {
"description": "A peer's identity for the life of the server: `p1`, `p2`, ... in attachment order.\n`p1` is the session that started the server.",
"type": "string"
},
"ServerStanding": {
"description": "Where a checkout's server stands, decided from its lease, whether the server the lease\nnames answers for that checkout, and whether what answers is this executable's code.\n\n```\nuse majordomus_cli::capability::builtin::server::ServerStanding;\nlet all = [ServerStanding::Absent, ServerStanding::Starting, ServerStanding::Ready,\n ServerStanding::Outdated, ServerStanding::Stale];\nlet words: Vec<&str> = all.iter().map(|s| s.as_str()).collect();\nassert_eq!(words, [\"absent\", \"starting\", \"ready\", \"outdated\", \"stale\"]);\nassert_eq!(serde_json::from_str::<ServerStanding>(\"\\\"stale\\\"\").unwrap(), ServerStanding::Stale);\n```",
"oneOf": [
{
"const": "absent",
"description": "No lease: nothing serves this checkout.",
"type": "string"
},
{
"const": "starting",
"description": "A lease without an address, young enough that its owner is still binding.",
"type": "string"
},
{
"const": "ready",
"description": "The server the lease names answers for this checkout, from the code on disk, at\nthis executable's version.",
"type": "string"
},
{
"const": "outdated",
"description": "The server answers, but from older code than this executable, or from a file that\nhas been replaced since it started: everything it says is yesterday's.",
"type": "string"
},
{
"const": "stale",
"description": "The lease names a server that does not answer, or is not a lease at all.",
"type": "string"
}
]
},
"Transport": {
"description": "How a peer reached the server.",
"oneOf": [
{
"const": "stdio",
"description": "The owner's own client, on the process's stdin and stdout.",
"type": "string"
},
{
"const": "http",
"description": "MCP over HTTP at `/mcp`: a `majordomus mcp` bridge, or a client speaking it directly.",
"type": "string"
}
]
}
},
"description": "The answer of `peers.list`: every worker of this repository, from every checkout's board.",
"properties": {
"boards": {
"description": "One entry per checkout the answer covers, reached or not.",
"items": {
"$ref": "#/$defs/BoardView"
},
"type": "array"
},
"caller": {
"anyOf": [
{
"$ref": "#/$defs/PeerId"
},
{
"type": "null"
}
],
"description": "The caller's own peer id, when the call came through an MCP session. A position on\nthis checkout's board, not a durable identity: it is handed out again after a\nreconnect, and `Peer::checkout` is the half of a worker's identity that is not."
},
"complete": {
"description": "Whether every board the answer covers was read. `false` when a checkout's server\ncould not be asked, and `BoardView::reason` says which and why — so that \"nobody\nelse is here\" is never reported when the truth is \"I could not ask\".",
"type": "boolean"
},
"count": {
"description": "How many peers are attached across every board that was read, the caller included.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"overlaps": {
"description": "Every pair of peers whose claimed scope meets, each pair once — now across\ncheckouts as well as within one. Empty is the ordinary case, and a reader who sees\nan entry here is looking at two workers about to do the same work.",
"items": {
"$ref": "#/$defs/Overlap"
},
"type": "array"
},
"peers": {
"description": "The peers, this checkout's board first and then the siblings in the order git\nregisters them, each in its own board's attachment order. Every one carries the\ncheckout it belongs to, because `p1` is the first session of every board. A peer\nthat announced something and then went away is still here, with `attached: false`.",
"items": {
"$ref": "#/$defs/Peer"
},
"type": "array"
}
},
"required": [
"count",
"peers",
"boards",
"complete"
],
"title": "PeerList",
"type": "object"
}Politiky
- benchmark
- povinné — cíl na každém transportu, který expozice deklaruje; případy jsou ty ze vstupního typu
- cache
- vypnuto — každé volání spustí handler
Cíle benchmarku
Odvozeno z registru pro tento repozitář: jeden požadavek na transport a případy, které poskytuje typ vstupu. Celá matice je na stránce měření výkonu.
Okamžiky, na které to odpovídá
- měl dvě relace zapisující do jednoho checkoutu, aniž o sobě jedna věděla Dva workeři v jednom pracovním stromu se vidí jen jako nevysvětlené změny souborů a každý z nich druhého považuje za šum.
- nedokázal říct, proč byl pro tuto práci použit jeden poskytovatel a pro jinou druhý Výběr poskytovatele a modelu se dělá implicitně, pro každou relaci zvlášť, a nikde se nezaznamenává, takže ho nelze zrevidovat ani zopakovat.