HTTP API: blackboard

Who works on what in this repository, as one projection of the records that already know it: every checkout's board, the mesh journal's sessions, claims, reviews and handovers on every linked machine, and the monitor's newest signals, joined once so that no surface joins them again (ADR 0176). A board peer and a mesh session are one worker only when an explicit identifier joins them; a source that could not be read makes the answer incomplete and says why.

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.

blackboard

GET /api/v1/blackboard blackboard.snapshot

Who works on what, now

Every worker of this repository — attached to a checkout's board or in an active mesh session on any linked machine — with the client it is, what it announced, its checkout, branch, machine and claims (advisory or exclusive); the claims that meet (potential, or confirmed when both are exclusive or the mesh marked one conflicted); the open reviews and untaken handovers; typed relations between workers, verified only when an explicit identifier joins them; the newest signals with the monitor's cursor a follower resumes from; each source with how it was read, and whether the answer is complete. Reads only.

query
experimentální
vyžaduje se měření výkonu
cache vypnuta
MCP tool majordomus_blackboard
$ blackboard

Parametry dotazu

název	typ	povinné	popis	příklady
checkouty	Checkouty	ne	Which checkouts' boards it covers: `repository` (every one, the default) or `this`.	addressed: "this"this-checkout: "this"
pro	string	ne	Comma-separated names of the reader — a worker (`1b`), a role, a login — so that the signals addressed to it are marked `for_you`. An MCP caller is also its own board session.	addressed: "1b"
signály	integer (uint64)	ne	How many of the newest signals of the last hour it carries (default 30, at most 200); 0 reads no signals at all, for a follower that reads them by its own cursor.	addressed: 10
zdroje	string	ne	A comma-separated subset of the monitor's sources, `mesh`, `executor` and `github` (default: `mesh,executor`).	addressed: "mesh"this-checkout: "mesh,executor"

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/blackboard?checkouts=this&for=1b&signals=10&sources=mesh"

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	Blackboard	Who works on what, now: the result.
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.

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.

Blackboard

object

The answer of blackboard.snapshot: who works on what in this repository, on every board and every linked machine, with what meets and what waits, read once from the records that know it.

vlastnost	typ	povinné	popis
v	string	ano	When it was read (RFC 3339).
checkout	string	ano	The identity of the checkout whose server answered.
head	string \| null	ne	That checkout's HEAD, when it has one.
dokončeno	boolean	ano	Whether every board was read and the mesh, when the repository declares one, could be asked. `false` names its reason in `sources`, so that "nobody is here" is never what "I could not ask" reads as. The monitor's sources are reported in `sources` with their state and do not decide it: an empty executor trail or an absent `gh` is no board that could not be read.
zdroje	array of BlackboardSource → BlackboardSource	ano	Each source and how it was read.
nástěnky	pole BoardView → BoardView	ano	Each checkout's board the summary lists: reached or not, with a server or a worker.
pokryto	integer (uint)	ano	How many checkouts the answer covers, listed in `boards` or counted in `omitted`.
omitted	mapa celých čísel (uint)	ne	The covered checkouts `boards` does not list, counted by standing (`absent`, `stale`): no server, nobody attached, no board.
přítomno	integer (uint)	ano	How many workers are here now: attached to a board or in an active mesh session.
workers	array of BlackboardWorker → BlackboardWorker	ano	Every worker, this checkout's board first, then the other boards, then the mesh.
konflikty	array of BlackboardConflict → BlackboardConflict	ano	The claims that meet, at most a hundred, confirmed first.
conflicts_total	integer (uint)	ano	How many conflicts there are in all.
recenze	array of BlackboardReview → BlackboardReview	ano	The review requests nobody has answered, at most fifty.
předávky	array of BlackboardHandover → BlackboardHandover	ano	The handovers nobody has taken, at most fifty.
vztahy	array of BlackboardRelation → BlackboardRelation	ano	The typed relations between workers.
signály	pole MonitorSignal → MonitorSignal	ano	The newest signals of the last hour, oldest first.
for_you	integer (uint)	ano	Kolik z nich je pro čtenáře.
cursor	string	ano	The monitor's cursor after these signals: where a follower resumes.

Used by blackboard.snapshot

BlackboardCertainty

"potential" | "confirmed"

How sure a conflict is.

potentialTwo claims meet and at least one of them is advisory: two workers about to touch the same paths, told and not stopped.
confirmedTwo exclusive claims meet, or the mesh marked one conflicted: what an exclusive claim exists to prevent has happened.

Used by BlackboardConflict

BlackboardClaim

object

One claim a worker holds.

vlastnost	typ	povinné	popis
název	string \| null	ne	The claim's name, when its worker holds several.
intent	string \| null	ne	What it is for, in the worker's words.
scope	array of string	ano	The repository paths it names.
režim	ClaimMode → ClaimMode	ano	`advisory` (an announcement: overlaps are reported) or `exclusive` (a second exclusive claim meeting it is refused while it lives). A board announcement is advisory.
issue	string \| null	ne	The issue it is for, when the claim names one.
record	string \| null	ne	The mesh claim's key, when it is a journal record; a board announcement has none.
v konfliktu	boolean	ne	Whether the mesh found it conflicting with another live claim.

Used by BlackboardWorker

BlackboardClaimRef

object

One side of a conflict: a worker and which of its claims.

vlastnost	typ	povinné	popis
worker	string	ano	The worker's key.
claim	string \| null	ne	The claim's name, when it has one.
record	string \| null	ne	The mesh claim's key, when it is a journal record.

Used by BlackboardConflict

BlackboardConflict

object

Two claims of two different workers whose scopes meet.

vlastnost	typ	povinné	popis
jistota	BlackboardCertainty → BlackboardCertainty	ano	Potential or confirmed.
první	BlackboardClaimRef → BlackboardClaimRef	ano	The claim that came first in the answer's order.
druhý	BlackboardClaimRef → BlackboardClaimRef	ano	The claim that meets it.
cesty	pole OverlapPath → OverlapPath	ano	The paths that meet, `yours` the first's and `theirs` the second's.

Used by Blackboard

BlackboardEvidence

"verified" | "candidate"

What a relation rests on.

verifiedAn explicit identifier or a journal record joins the two ends.
candidateThe ends could be joined and nothing proves it: more than one record fits.

Used by BlackboardRelation

BlackboardHandover

object

A handover published to the mesh that nobody has taken. Its body is not repeated here: mesh.state holds it. The journal names no recipient for a handover — whoever takes it is its addressee — so none is inferred here.

vlastnost	typ	povinné	popis
id	string	ano	The handover's id.
runtime	string	ano	The runtime that published it.
název	string \| null	ne	Its name, when it has one.
větev	string \| null	ne	Větev, kterou pokračuje.
issue	string \| null	ne	Úkol, který pokračuje.
úloha	string \| null	ne	The task it continues.
created_at	string \| null	ne	When it was written.

Used by Blackboard

BlackboardOrigin

"board" | "mesh"

Where a worker of the blackboard was found.

boardOn a checkout's board: an MCP client attached to that checkout's server.
meshIn the mesh journal only: a session no board of this repository holds — another machine's, a task's, or a client's own.

Used by BlackboardWorker

BlackboardPresence

"attached" | "departed" | "active"

Whether a worker is here now.

attachedAttached to its board now.
departedGone from its board, kept because it still holds an announcement.
activeAn open mesh session whose runtime still beats.

Used by BlackboardWorker

BlackboardRelation

object

A typed relation between two workers, or a worker and the addressee a record names.

vlastnost	typ	povinné	popis
druh	BlackboardRelationKind → BlackboardRelationKind	ano	Co to je.
evidence	BlackboardEvidence → BlackboardEvidence	ano	What it rests on.
z	string	ano	A worker's key.
do	string	ano	A worker's key, or the addressee as the record names it when no worker is it.
record	string	ano	The record it rests on: a session or a review key.

Used by Blackboard

BlackboardRelationKind

"same_worker" | "review"

What a relation between two workers is.

same_workerA board peer and a mesh session that may be one worker.
reviewOne worker asked another for a review.

Used by BlackboardRelation

BlackboardReview

object

A review request nobody has answered.

vlastnost	typ	povinné	popis
klíč	string	ano	The review's key in the journal.
z	string	ano	The requesting worker's key, or its session key when no worker holds it.
předmět	string	ano	What it asks about.
reviewer	string \| null	ne	Whom it asks, as the request names it; absent means anyone.
issue	string \| null	ne	The issue it names.

Used by Blackboard

BlackboardSource

object

One source of the blackboard and how it was read.

vlastnost	typ	povinné	popis
zdroj	string	ano	`board`, `mesh`, or a monitor source as `monitor.<name>`.
state	BlackboardSourceState → BlackboardSourceState	ano	How it was read.
důvod	string \| null	ne	Why it is not `ok`.

Used by Blackboard

BlackboardSourceState

"ok" | "partial" | "absent" | "skipped"

How one source of the blackboard was read.

okRead whole.
partialRead, and some of what it covers could not be asked.
absentNot read; the reason says why.
skippedNot asked for.

Used by BlackboardSource

BlackboardWorker

object

One worker of the repository: a board peer, a mesh session, or one of each that an explicit identifier joins.

vlastnost	typ	povinné	popis
klíč	string	ano	Stable for as long as the worker is here: `board:<checkout>/<peer>` or `mesh:<stream>/<session>`. Never a bare peer id.
původ	BlackboardOrigin → BlackboardOrigin	ano	Where it was found.
přítomnost	BlackboardPresence → BlackboardPresence	ano	Whether it is here now.
klient	string	ano	The client's own name, from its MCP initialize or its mesh session.
název	string \| null	ne	The client's display title or the worker it says it is, when it gave one.
verze	string \| null	ne	The client's version, from its initialize.
intent	string \| null	ne	What it said it is doing; absent means it announced nothing.
checkout	string \| null	ne	The checkout's identity.
worktree	string \| null	ne	The checkout's path on its machine.
větev	string \| null	ne	The branch it works on.
board_peer	string \| null	ne	Its position on its board (`p3`): meaningful on that board only.
session	string \| null	ne	Its mesh session's key, when it has one.
machine	string \| null	ne	The machine's display name.
runtime	string \| null	ne	The runtime (`<node>-<runtime>`) its mesh session belongs to.
úloha	string \| null	ne	The task its mesh session names.
issue	string \| null	ne	The issue its mesh session names.
connected_at	string \| null	ne	When it attached to its board.
last_seen_seconds_ago	integer \| null	ne	Seconds since its board last heard from it.
last_beat_ms	integer \| null	ne	Milliseconds since its runtime last beat. A beat is liveness, not work done.
tvrzení	array of BlackboardClaim → BlackboardClaim	ne	Its claims, board announcements and live mesh claims alike.

Used by Blackboard