monitor.stream

A page of signals after a cursor, oldest first, or without one the newest of the last `since` seconds: each with its time, source, kind, severity, machine, session, actor, pull request, branch, issue, paths, a one-line summary and whether it is for the reader. Re-projections and undecided steps are counted as `suppressed`; a source that cannot be read is listed with its reason, never answered as empty. The page's `cursor` is the next page's `after`, and nothing on this page comes back. Reads only.

query
experimental
module monitor
#monitor
#mesh
#coordination
#observability

Exposure

Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.

surface	as
MCP	tool majordomus_monitor
HTTP	GET /api/v1/monitor operationId monitor.stream
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 · MonitorInput

The input of monitor: where the reader stands, how much it wants, from which sources, and who it is.

property	type	required	description
after	string \| null	no	The `cursor` of the previous page; without it, the page is the newest signals of the last `since` seconds.
for	string \| null	no	Comma-separated names of the reader — a worker (`1b`), a role, a login — so that what is addressed to it is marked `for_you`. An MCP caller is also its own board session.
limit	integer \| null	no	At most this many signals (default 50, at most 500).
since	integer \| null	no	How far back a first page reaches, in seconds (default 3600).
sources	string \| null	no	A comma-separated subset of `mesh`, `executor` and `github` (default: all three).

JSON Schema

{
  "additionalProperties": false,
  "description": "The input of `monitor`: where the reader stands, how much it wants, from which sources,\nand who it is.",
  "properties": {
    "after": {
      "description": "The `cursor` of the previous page; without it, the page is the newest signals of the\nlast `since` seconds.",
      "type": [
        "string",
        "null"
      ]
    },
    "for": {
      "description": "Comma-separated names of the reader — a worker (`1b`), a role, a login — so that what\nis addressed to it is marked `for_you`. An MCP caller is also its own board session.",
      "type": [
        "string",
        "null"
      ]
    },
    "limit": {
      "description": "At most this many signals (default 50, at most 500).",
      "format": "uint64",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "since": {
      "description": "How far back a first page reaches, in seconds (default 3600).",
      "format": "uint64",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "sources": {
      "description": "A comma-separated subset of `mesh`, `executor` and `github` (default: all three).",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "MonitorInput",
  "type": "object"
}

output · MonitorPage

A page of the stream.

property	type	required	description
cursor	string	yes	The cursor of the next page: ask with `after` set to it and nothing on this page comes back.
for_you	integer	yes	How many of them are for the reader.
more	boolean	yes	Whether more signals wait after this page than its limit let through.
signals	array	yes	The signals, oldest first.
sources	array	yes	Every source, read or not, with its reason.
suppressed	integer	yes	How many records were read and folded away as noise.

JSON Schema

{
  "$defs": {
    "MonitorSeverity": {
      "description": "How much a signal asks of its reader.",
      "oneOf": [
        {
          "const": "info",
          "description": "Something happened; nothing is asked.",
          "type": "string"
        },
        {
          "const": "attention",
          "description": "Something failed or waits for someone: worth a look.",
          "type": "string"
        },
        {
          "const": "action",
          "description": "Something waits for the reader: a review asked of them, a handover for them.",
          "type": "string"
        }
      ]
    },
    "MonitorSignal": {
      "description": "One thing that happened, as one line a person or an agent can act on.",
      "properties": {
        "actor": {
          "description": "Who did it: a session's worker or client, the executor's actor, a GitHub login.",
          "type": [
            "string",
            "null"
          ]
        },
        "at": {
          "description": "When it happened, in Unix seconds, on the clock of whoever recorded it.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        },
        "branch": {
          "description": "The branch it is about.",
          "type": [
            "string",
            "null"
          ]
        },
        "for_you": {
          "default": false,
          "description": "Whether it names the reader: a review asked of them, an answer to their request, a\nhandover or a text that names them.",
          "type": "boolean"
        },
        "issue": {
          "description": "The issue it is about.",
          "type": [
            "string",
            "null"
          ]
        },
        "kind": {
          "description": "What happened, e.g. `session_joined`, `review_requested`, `merged`, `run_failed`.",
          "type": "string"
        },
        "link": {
          "description": "Where to read more, when there is a page for it.",
          "type": [
            "string",
            "null"
          ]
        },
        "machine": {
          "description": "The machine it happened on, by its display name when the mesh knows it.",
          "type": [
            "string",
            "null"
          ]
        },
        "paths": {
          "description": "The repository paths it is about.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "pr": {
          "description": "The pull request it is about.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "session": {
          "description": "The session that did it.",
          "type": [
            "string",
            "null"
          ]
        },
        "severity": {
          "$ref": "#/$defs/MonitorSeverity",
          "description": "How much it asks of the reader."
        },
        "source": {
          "$ref": "#/$defs/MonitorSource",
          "description": "Which record it comes from."
        },
        "summary": {
          "description": "What happened, in one line of at most 200 characters.",
          "type": "string"
        }
      },
      "required": [
        "at",
        "source",
        "kind",
        "severity",
        "summary"
      ],
      "type": "object"
    },
    "MonitorSource": {
      "description": "Where a signal comes from.",
      "oneOf": [
        {
          "const": "mesh",
          "description": "The mesh journal: sessions on every linked machine (this checkout's board among\nthem), their claims, handovers and reviews.",
          "type": "string"
        },
        {
          "const": "executor",
          "description": "The executor's trail: the pull-request lane's merges, refreshes, repairs, closures\nand failures.",
          "type": "string"
        },
        {
          "const": "github",
          "description": "GitHub: pull requests opened, merged and closed, and finished workflow runs.",
          "type": "string"
        }
      ]
    },
    "MonitorSourceHealth": {
      "description": "Whether a source could be read, and what it contributed to the page.",
      "oneOf": [
        {
          "const": "ok",
          "description": "Read.",
          "type": "string"
        },
        {
          "const": "absent",
          "description": "Not there to read: the mesh is not running, there is no trail, `gh` is missing.",
          "type": "string"
        },
        {
          "const": "error",
          "description": "There, but reading it failed.",
          "type": "string"
        },
        {
          "const": "skipped",
          "description": "Not asked for in `sources`.",
          "type": "string"
        }
      ]
    },
    "MonitorSourceState": {
      "description": "One source's standing on a page.",
      "properties": {
        "reason": {
          "description": "Why it was not, when it was not.",
          "type": [
            "string",
            "null"
          ]
        },
        "signals": {
          "description": "How many of its signals are on this page.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "source": {
          "$ref": "#/$defs/MonitorSource",
          "description": "The source."
        },
        "state": {
          "$ref": "#/$defs/MonitorSourceHealth",
          "description": "Whether it was read."
        },
        "suppressed": {
          "description": "How many of its records were read and folded away as noise.",
          "format": "uint64",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "source",
        "state",
        "signals",
        "suppressed"
      ],
      "type": "object"
    }
  },
  "description": "A page of the stream.",
  "properties": {
    "cursor": {
      "description": "The cursor of the next page: ask with `after` set to it and nothing on this page\ncomes back.",
      "type": "string"
    },
    "for_you": {
      "description": "How many of them are for the reader.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "more": {
      "description": "Whether more signals wait after this page than its limit let through.",
      "type": "boolean"
    },
    "signals": {
      "description": "The signals, oldest first.",
      "items": {
        "$ref": "#/$defs/MonitorSignal"
      },
      "type": "array"
    },
    "sources": {
      "description": "Every source, read or not, with its reason.",
      "items": {
        "$ref": "#/$defs/MonitorSourceState"
      },
      "type": "array"
    },
    "suppressed": {
      "description": "How many records were read and folded away as noise.",
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "signals",
    "for_you",
    "suppressed",
    "sources",
    "cursor",
    "more"
  ],
  "title": "MonitorPage",
  "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.

transport	state	cases	targets
direct	covered	2	local-first-page local-resumed
mcp	covered	2	local-first-page local-resumed
http	covered	2	local-first-page local-resumed