peers.announce
Tell the other peers of this shared server what the calling session is doing and which paths it expects to touch. Changes this process's memory only; the repository is never written. Needs an MCP session: over plain HTTP there is no caller.
Tell the other peers of this shared server what the calling session is doing and which paths it expects to touch. Changes this process's memory only; the repository is never written. Needs an MCP session: over plain HTTP there is no caller.
- command
- behaviorally_verified
- module peers
- #peers
- #coordination
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | tool majordomus_announce |
| HTTP | POST /api/v1/peers/announce operationId peers.announce |
| command line | — |
Schemas
The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.
input · AnnounceInput
The input of `peers.announce`: what the calling peer is working on.
| property | type | required | description |
|---|---|---|---|
| intent | string | yes | One line, in the peer's words: the task, the question, the intent. |
| scope | array | no | Repository-relative paths the peer expects to touch. Informational: other peers read it to avoid a collision; nothing here enforces it. default [] |
JSON Schema
{
"additionalProperties": false,
"description": "The input of `peers.announce`: what the calling peer is working on.",
"properties": {
"intent": {
"description": "One line, in the peer's words: the task, the question, the intent.",
"type": "string"
},
"scope": {
"default": [],
"description": "Repository-relative paths the peer expects to touch. Informational: other peers\nread it to avoid a collision; nothing here enforces it.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"intent"
],
"title": "AnnounceInput",
"type": "object"
}output · Announced
What `announce` answers: the peer as recorded, and who else is on that ground.
| property | type | required | description |
|---|---|---|---|
| announcement | one of 2 | no | Its announcement, when it made one. |
| attached | boolean | yes | Whether the session is still attached. A peer that announced something and then went away is kept and listed with `attached: false`: what it said it was working on outlives the connection that said it, because the work does. |
| client | reference | yes | The client behind it. |
| connected_at | string | yes | When it attached, RFC 3339, UTC. |
| id | reference | yes | `p1`, `p2`, ... |
| last_seen_seconds_ago | integer | yes | Seconds since its last message. |
| overlaps | array | no | Every other peer whose claimed scope meets this one. Empty is the ordinary case. |
| transport | reference | yes | How it is attached. |
JSON Schema
{
"$defs": {
"Announcement": {
"description": "What a peer said it is working on.",
"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"
},
"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"
},
"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"
},
"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"
},
"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"
},
"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": "What `announce` answers: the peer as recorded, and who else is on that ground.",
"properties": {
"announcement": {
"anyOf": [
{
"$ref": "#/$defs/Announcement"
},
{
"type": "null"
}
],
"description": "Its announcement, when it made one."
},
"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"
},
"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"
},
"overlaps": {
"description": "Every other peer whose claimed scope meets this one. Empty is the ordinary case.",
"items": {
"$ref": "#/$defs/Overlap"
},
"type": "array"
},
"transport": {
"$ref": "#/$defs/Transport",
"description": "How it is attached."
}
},
"required": [
"id",
"client",
"transport",
"connected_at",
"last_seen_seconds_ago",
"attached"
],
"title": "Announced",
"type": "object"
}Policies
- benchmark
- required — a target on every transport the exposure declares; the cases are the input type's
- cache
- disabled — every call runs the handler
Benchmark targets
Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.