monitor.stream

{
  "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"
}

{
  "$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"
}