HTTP API: peers

Workeři tohoto repozitáře, pojmenovaní podle vlastního initialize, a co každý oznámil, že dělá — sesbíráno z nástěnky každého checkoutu, protože server obsluhuje jeden checkout a repozitář, na kterém se pracuje přes propojené worktrees, má jednu nástěnku na worktree. V paměti; zaniká s procesy.

Vykresleno z docs/generated/openapi.json, který spustitelný soubor generuje ze svého registru schopností a CI jej odmítne, je-li zastaralý. Surový dokument je na /openapi.json; běžící server servíruje stejný dokument na vlastní /openapi.json a Swagger UI na /swagger.

peers

GET /api/v1/peers peers.list

Výpis peerů

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
vyžaduje se měření výkonu
cache vypnuta
Nástroj MCP majordomus_peers

Parametry dotazu

název	typ	povinné	popis	příklady
checkouty	Checkouty	ne	Které checkouty nástěnka pokrývá. Chybí-li, platí `repository`; `this` je checkout, který volání zasáhlo, a nic jiného, a to se ptá sourozeneckého serveru, aby se sběr nikdy nemohl ptát zpět.	výchozí: "this"

Vyzkoušejte

Port je ten, který server zalogoval; 8741 je ten, o který žádá jako první. Hodnoty jsou první příklad operace.

curl -s "http://127.0.0.1:8741/api/v1/peers?checkouts=this"

Testováno v apps/majordomus-cli/tests/http_serve.rs, který přehrává routu s těmito hodnotami proti serveru na skutečném socketu.

Odpovědi

status	tělo	význam
200	PeerList	Výpis peerů: výsledek.
400	ErrorBody	`invalid_input`: Vstup neodpovídá schématu: parametr špatného typu, neznámý parametr nebo hodnota, kterou schopnost odmítne.
404	ErrorBody	`not_found`: Vstup pojmenovává něco, co repozitář nemá.
500	ErrorBody	`internal`: Schopnost selhala z vlastního důvodu; zpráva ho pojmenovává.
výchozí	ErrorBody	Jakékoli jiné selhání, které transport hlásí: 405 `method_not_allowed` pro jinou metodu na této cestě, 400 `invalid_input` pro tělo, které není objektem JSON.

POST /api/v1/peers/announce peers.announce

Oznámit, na čem tento peer pracuje

Řekne ostatním peerům tohoto sdíleného serveru, co volající relace dělá a kterých cest se chce dotknout. Peer může držet několik claimů najednou: pojmenujte jeden přes 'claim' a stojí vedle ostatních, ohlaste se pod tímto jménem znovu a aktualizuje se, vynechte ho a je to jediný nepojmenovaný claim peera. Pojmenujte své claimy, když jedna relace dělá několik věcí najednou — subagenti sdílejí relaci svého rodiče, takže nepojmenované ohlášení od každého z nich by nahradilo předchozí, místo aby se přidalo. Mění jen paměť tohoto procesu; do repozitáře se nikdy nezapisuje. Vyžaduje relaci MCP: přes prosté HTTP volající neexistuje.

command
behaviorally_verified
vyžaduje se měření výkonu
cache vypnuta
MCP nástroj majordomus_announce

Tělo požadavku — AnnounceInput, JSON

příklad default

{"intent":"benchmark: announcing","scope":["apps/majordomus-cli"]}

Vyzkoušejte

Port je ten, který server zalogoval; 8741 je ten, o který žádá jako první. Hodnoty jsou první příklad operace.

curl -s -X POST "http://127.0.0.1:8741/api/v1/peers/announce" -H "content-type: application/json" -d '{"intent":"benchmark: announcing","scope":["apps/majordomus-cli"]}'

Testováno v apps/majordomus-cli/tests/http_serve.rs, který přehrává routu s těmito hodnotami proti serveru na skutečném socketu.

Odpovědi

status	tělo	význam
200	Oznámeno	Oznámit, na čem tento peer pracuje: výsledek.
400	ErrorBody	`invalid_input`: Vstup neodpovídá schématu: parametr špatného typu, neznámý parametr nebo hodnota, kterou schopnost odmítne.
404	ErrorBody	`not_found`: Vstup pojmenovává něco, co repozitář nemá.
422	ErrorBody	`refused`: Příkaz byl srozumitelný a byl odmítnut z důvodu, který uvádí zpráva.
500	ErrorBody	`internal`: Schopnost selhala z vlastního důvodu; zpráva ho pojmenovává.
výchozí	ErrorBody	Jakékoli jiné selhání, které transport hlásí: 405 `method_not_allowed` pro jinou metodu na této cestě, 400 `invalid_input` pro tělo, které není objektem JSON.

Schémata

Komponenty, které používají jen operace tohoto tagu. Každý řádek je pole daného typu, jeho doc komentář je popis; typ vlastněný jinou stránkou na ni odkazuje.

AnnounceInput

object

Vstup peers.announce: na čem pracuje volající peer.

vlastnost	typ	povinné	popis
intent	string	ano	Jeden řádek slovy peera: úloha, otázka, záměr.
scope	array of string	ne	Cesty relativní k repozitáři, kterých se peer dotkne. Informativní: ostatní peers je čtou, aby se vyhnuli kolizi; nic zde nic nevynucuje.
claim	string \| null	ne	Který z claimů tohoto peera to je, když peer drží více než jeden. Jedna relace MCP není vždy jedna práce — klient, který rozdává práci subagentům, s nimi všemi sdílí svou relaci — a bez názvu každé ohlášení nahradí předchozí, takže nástěnka nakonec popisuje toho pracovníka, který promluvil naposledy, a zbytek rozsahu se potichu přestane claimovat. Pojmenujte claim a stojí vedle ostatních; ohlaste se pod tímto názvem znovu a aktualizuje se. Vynechte ho a jde o jediný nepojmenovaný claim peera, což je to, co chce jedna relace ohlašující sama o sobě.

vlastnost

typ

povinné

popis

intent

string

ano

Jeden řádek slovy peera: úloha, otázka, záměr.

scope

array of string

Cesty relativní k repozitáři, kterých se peer dotkne. Informativní: ostatní peers je čtou, aby se vyhnuli kolizi; nic zde nic nevynucuje.

claim

string | null

Který z claimů tohoto peera to je, když peer drží více než jeden.

Jedna relace MCP není vždy jedna práce — klient, který rozdává práci subagentům, s nimi všemi sdílí svou relaci — a bez názvu každé ohlášení nahradí předchozí, takže nástěnka nakonec popisuje toho pracovníka, který promluvil naposledy, a zbytek rozsahu se potichu přestane claimovat. Pojmenujte claim a stojí vedle ostatních; ohlaste se pod tímto názvem znovu a aktualizuje se. Vynechte ho a jde o jediný nepojmenovaný claim peera, což je to, co chce jedna relace ohlašující sama o sobě.

Používá peers.announce

Oznámeno

object

Na co announce odpovídá: peer tak, jak je zaznamenán, a kdo další je na stejném místě.

vlastnost	typ	povinné	popis
id	PeerId → PeerId	ano	`p1`, `p2`, ...
klient	ClientInfo → ClientInfo	ano	Klient za ním.
transport	Transport → Transport	ano	Jak je připojena.
connected_at	string	ano	Kdy se připojil, RFC 3339, UTC.
last_seen_seconds_ago	integer (uint64)	ano	Sekundy od její poslední zprávy.
připojeno	boolean	ano	Zda je relace stále připojena. Peer, který něco oznámil a pak odešel, se uchová a vypíše s `attached: false`: to, na čem řekl, že pracuje, přežije spojení, které to řeklo, protože práce přežije také.
tvrzení	pole Announcement → Announcement	ne	Každý claim, který tento peer drží, v pořadí podle jména, nepojmenovaný první. Prázdné u peera, který nic neoznámil. Jedno spojení může dělat několik věcí najednou — relace, která rozdělí práci mezi subagenty, s nimi všemi sdílí svou relaci MCP — a před tímto polem mohla nástěnka držet jen poslední řečené, takže každé oznámení tiše smazalo to předchozí a ostatní peery přestaly vidět zbytek rozsahu.
oznámení	Announcement \| null → Announcement	ne	Nejnověji vytvořený z `Peer::claims`, pro čtenáře, který chce jeden řádek místo všech. Odvozeno z `claims` a nikdy ne druhý účet téhož: peer držící jeden nárok hlásí totéž v obou, což hlásí každý peer, který své nároky nejmenuje.
checkout	PeerCheckout \| null → PeerCheckout	ne	Ke kterému checkoutu repozitáře je tento peer připojen; viz `PeerCheckout`. Nástěnka ho sama nikdy nenastavuje — nástěnka neví, kde je — a razítkuje ho čtečka, která tohoto peera shromáždila, protože jediná ví, na server kterého checkoutu se ptala.
překryvy	pole Overlap → Overlap	ne	Každý další peer, jehož nárokovaný rozsah se s tímto střetává. Prázdné je běžný případ.
vydáno	array of string	ne	Cesty, které měl nárok, jejž tento nahradil, a tento je nemá. Oznámení pod jménem, které peer už použil, nahradí onen nárok, což je smysl aktualizace. Když je náhrada užší, peer právě přestal nárokovat půdu, kterou o chvíli dřív držel, a ostatní peeři přestanou být před ní varováni. Občas je to záměr, jindy chyba, kterou by nikdo nikdy neviděl, a proto se to říká tady, ve chvíli, kdy k tomu dojde, místo aby se to objevilo až v pozdější kolizi. Prázdné je běžný případ.

Používá peers.announce

Oznámení

object

Jeden claim, který peer učinil: na čem pracuje a kde.

Peer jich může držet několik. name je to, co je rozlišuje a co dělá z opětovného oznámení aktualizaci místo druhého nároku: oznamte pod stejným názvem a nárok se nahradí, oznamte pod novým a peer nyní drží oba. Peer, který nikdy nic nepojmenuje, drží právě jeden nárok, nepojmenovaný, což je to, co měla vždy jediná relace oznamující sama o sobě.

vlastnost	typ	povinné	popis
název	string \| null	ne	Jak se tento nárok jmenuje, pokud ho peer pojmenoval. Chybí u nepojmenovaného nároku peera.
intent	string	ano	Jeden řádek: úloha nebo záměr, slovy peera.
scope	array of string	ano	Cesty relativní k repozitáři, kterých se peer chystá dotknout; informativní, zde se nikdy nevynucují.
v	string	ano	Kdy bylo oznámeno, RFC 3339, UTC.

Používá Announced Peer

BoardView

object

Nástěnka jednoho checkoutu, jak ji sběr našel.

Přítomno pro každý checkout, který odpověď pokrývá, ať už šlo jeho nástěnku přečíst, nebo ne, protože výpis, který mlčky vynechá checkouty, jež nedokázal oslovit, je přesně ten tvar odpovědi, kvůli kterému byla tato schopnost od začátku špatná: čtenář by viděl krátkou nástěnku a usoudil, že tu nikdo jiný nepracuje.

vlastnost	typ	povinné	popis
id	string	ano	Otisk identity checkoutu, stejná hodnota, kterou `server.status` hlásí jako `checkout_id`. Jedna na checkout, nikdy cesta, a stabilní napříč restartem.
worktree	string	ano	Kde checkout je. Jediná věc na této nástěnce, na kterou může člověk reagovat přímo, a jediná, která přežije opětovné připojení.
větev	string \| null	ne	Větev tam checkoutovaná, když šlo číst.
this_checkout	boolean	ano	Zda je to checkout serveru, který odpovídá na volání.
postavení	ServerStanding → ServerStanding	ano	Kde stojí jeho server, podle téhož odečtu, který hlásí `server.status`.
url	string \| null	ne	Adresa, kterou jmenuje jeho lease, pokud ji má.
připojeno	integer (uint)	ano	Kolik peerů této nástěnky je připojeno.
důvod	string \| null	ne	Proč tato nástěnka není v odpovědi. `None`, když je.

Používá PeerList

ClientInfo

object

Co klient o sobě řekl v initialize.

vlastnost	typ	povinné	popis
název	string	ano	`clientInfo.name`: `claude-code`, `codex`, `gemini-cli`, cokoli klient pošle.
verze	string	ano	`clientInfo.version`.
název	string \| null	ne	`clientInfo.title`, když ho klient pošle.

Používá Announced Peer

Překryv

object

Dva peeři, kteří si nárokovali stejný terén.

Hlásí se, když ohlásí druhý z nich, takže se kolize ví v okamžiku vzniku, a ne zpětně objevená v historii větve.

vlastnost	typ	povinné	popis
peer	PeerId → PeerId	ano	Druhý peer.
připojeno	boolean	ano	Zda je ten peer stále připojen. Překryv s odešlým peerem je slabší signál než s živou relací a čtenáři se říká, který to je.
intent	string	ano	Co řekl, že dělá.
cesty	pole OverlapPath → OverlapPath	ano	Tvrzení, která se střetávají: jeden řádek na dvojici, `yours` a `theirs`.
checkout	PeerCheckout \| null → PeerCheckout	ne	K jakému checkoutu je druhý peer připojen, pokud to čtenář věděl. Nejdůležitější překryv je ten, který dříve nikdo nemohl vidět: dva workeři ve dvou worktrees jednoho repozitáře, z nichž každý četl nástěnku, na které byl jen on sám, oba si nárokovali `apps/majordomus-cli/src`. Pojmenování checkoutu mění „p1 je na vašem pozemku“ v něco, podle čeho může čtenář jednat, když `p1` není na této nástěnce.

Používá Announced PeerList

OverlapPath

object

Jeden pár tvrzení, která se navzájem obsahují.

vlastnost	typ	povinné	popis
vaše	string	ano	Cesta, kterou oznamující peer zabral.
jejich	string	ano	Cesta, kterou si nárokoval druhý peer.

Používá Overlap

Peer

object

Jeden peer tak, jak ho vypisuje nástěnka.

vlastnost	typ	povinné	popis
id	PeerId → PeerId	ano	`p1`, `p2`, ...
klient	ClientInfo → ClientInfo	ano	Klient za ním.
transport	Transport → Transport	ano	Jak je připojena.
connected_at	string	ano	Kdy se připojil, RFC 3339, UTC.
last_seen_seconds_ago	integer (uint64)	ano	Sekundy od její poslední zprávy.
připojeno	boolean	ano	Zda je relace stále připojena. Peer, který něco oznámil a pak odešel, se uchová a vypíše s `attached: false`: to, na čem řekl, že pracuje, přežije spojení, které to řeklo, protože práce přežije také.
tvrzení	pole Announcement → Announcement	ne	Každý claim, který tento peer drží, v pořadí podle jména, nepojmenovaný první. Prázdné u peera, který nic neoznámil. Jedno spojení může dělat několik věcí najednou — relace, která rozdělí práci mezi subagenty, s nimi všemi sdílí svou relaci MCP — a před tímto polem mohla nástěnka držet jen poslední řečené, takže každé oznámení tiše smazalo to předchozí a ostatní peery přestaly vidět zbytek rozsahu.
oznámení	Announcement \| null → Announcement	ne	Nejnověji vytvořený z `Peer::claims`, pro čtenáře, který chce jeden řádek místo všech. Odvozeno z `claims` a nikdy ne druhý účet téhož: peer držící jeden nárok hlásí totéž v obou, což hlásí každý peer, který své nároky nejmenuje.
checkout	PeerCheckout \| null → PeerCheckout	ne	Ke kterému checkoutu repozitáře je tento peer připojen; viz `PeerCheckout`. Nástěnka ho sama nikdy nenastavuje — nástěnka neví, kde je — a razítkuje ho čtečka, která tohoto peera shromáždila, protože jediná ví, na server kterého checkoutu se ptala.

Používá PeerList

PeerCheckout

object

K jakému checkoutu repozitáře je peer připojen.

Nástěnka je paměť jednoho procesu a server obsluhuje jeden checkout, takže peer přečtený ze serveru sousedního checkoutu a peer tohoto jsou jinak nerozlišitelní — a hůř než nerozlišitelní, protože se id srážejí: p1 je první relace každé nástěnky, takže výpis napříč repozitářem bez tohoto pole by obsahoval několik peerů jménem p1 a žádný způsob, jak je odlišit. To je upřesnění. Cesta k worktree je trvalá polovina identity pracovníka: id peera je pozice na jedné nástěnce a po opětovném připojení se přiděluje znovu (p3 dnes ráno, p1 po opětovném připojení mostu), zatímco checkout, ve kterém pracovník pracuje, jeho spojení přežije.

Chybí u peera, o němž server hlásí z vlastní nástěnky, aniž by se ho ptali, který checkout to je — peers.announce odpovídá za oznamující relaci a odpověď je z konstrukce tohoto serveru. Repozitářový výpis označí každého peera, jehož shromáždí, včetně vlastních, takže žádná položka té odpovědi není nekvalifikovaná.

use majordomus_cli::peers::PeerCheckout;
let c = PeerCheckout {
    id: "b8293f11".into(),
    worktree: "/repo-wt/feature/x".into(),
    branch: Some("feature/x".into()),
    this_checkout: false,
};
let v = serde_json::to_value(&c).unwrap();
assert_eq!(v["branch"], "feature/x");
assert_eq!(v["this_checkout"], false);

vlastnost	typ	povinné	popis
id	string	ano	Otisk identity checkoutu, stejná hodnota, kterou `server.status` hlásí jako `checkout_id`. Jedna na checkout, nikdy cesta, a stabilní napříč restartem.
worktree	string	ano	Kde checkout je. Jediná věc na této nástěnce, na kterou může člověk reagovat přímo, a jediná, která přežije opětovné připojení.
větev	string \| null	ne	Větev tam checkoutovaná, když šlo číst.
this_checkout	boolean	ano	Zda je to checkout serveru, který odpovídá na volání.

Používá Announced Overlap Peer

PeerList

object

Odpověď peers.list: každý pracovník tohoto repozitáře, z nástěnky každého checkoutu.

vlastnost	typ	povinné	popis
počet	integer (uint)	ano	Kolik peerů je připojeno napříč všemi načtenými nástěnkami, včetně volajícího.
volající	PeerId \| null → PeerId	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í.
peers	pole Peer → Peer	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`.
překryvy	pole Overlap → Overlap	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.
nástěnky	pole BoardView → BoardView	ano	Jedna položka na každý checkout, který odpověď pokrývá, ať už byl zasažen, nebo ne.
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“.

Používá peers.list

Přenos

"stdio" | "http"

Jak se peer k serveru dostal.

stdioVlastní klient vlastníka, na stdin a stdout procesu.
httpMCP přes HTTP na /mcp: most majordomus mcp nebo klient, který ho mluví přímo.

Používá Announced Peer