executions.report

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "The execution's id, as the reporting process minted it."
    },
    "capability": {
      "type": "string",
      "description": "The capability it runs, by its canonical id."
    },
    "title": {
      "type": "string",
      "description": "That capability's title."
    },
    "input": {
      "description": "The input it was given, as the reporting process stored it: already redacted there,\nand redacted again here by this registry's schema when this registry knows it.",
      "default": null
    },
    "cancellable": {
      "type": "boolean",
      "description": "Whether the capability stops when asked. When it does, a cancel asked of this server\nreaches the reporter in the answer to its next report.",
      "default": false
    },
    "pid": {
      "type": "integer",
      "format": "uint32",
      "minimum": 0,
      "description": "The process that runs it."
    },
    "events": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ExecutionEvent"
      },
      "description": "Its events after the last sequence this server answered `through`, in its own\nsequence, oldest first; at most 500. Empty is a heartbeat.",
      "default": []
    }
  },
  "required": [
    "id",
    "capability",
    "title",
    "pid"
  ],
  "description": "The input of `executions.report`: what a process that runs an execution says about it to\nthe server serving the same checkout.",
  "title": "ReportInput",
  "$defs": {
    "ExecutionEvent": {
      "type": "object",
      "properties": {
        "schema_version": {
          "type": "string",
          "description": "The protocol version, `PROTOCOL_VERSION`."
        },
        "event_id": {
          "type": "string",
          "description": "The identity of this event: the execution's id and the sequence, so a client that\ndeduplicates needs no composite key of its own."
        },
        "execution_id": {
          "$ref": "#/$defs/ExecutionId",
          "description": "The execution it is about."
        },
        "sequence": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Its position in that execution's stream, from 1, without gaps."
        },
        "timestamp": {
          "type": "string",
          "description": "When the event was produced, RFC 3339 in UTC."
        }
      },
      "required": [
        "schema_version",
        "event_id",
        "execution_id",
        "sequence",
        "timestamp"
      ],
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.created"
            },
            "data": {
              "type": "object",
              "properties": {
                "capability": {
                  "description": "The capability's canonical id.",
                  "type": "string"
                },
                "title": {
                  "description": "Its title.",
                  "type": "string"
                },
                "input": {
                  "description": "The input, with sensitive values already replaced."
                }
              },
              "required": [
                "capability",
                "title",
                "input"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "The execution was accepted and exists. Carries what it will run and with what,\nredacted, so a client that joins at the first event needs nothing else to render a\nheading."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.queued"
            },
            "data": {
              "type": "object",
              "properties": {
                "ahead": {
                  "description": "How many executions are ahead of it.",
                  "type": "integer",
                  "format": "uint",
                  "minimum": 0
                }
              },
              "required": [
                "ahead"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "It is waiting for a worker."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.started"
            }
          },
          "required": [
            "type"
          ],
          "description": "A worker picked it up and is about to enter the handler."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.progress"
            },
            "data": {
              "$ref": "#/$defs/ProgressView"
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "How far along it is."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.step.started"
            },
            "data": {
              "type": "object",
              "properties": {
                "name": {
                  "description": "The step's stable name.",
                  "type": "string"
                },
                "title": {
                  "description": "One line for a reader.",
                  "type": "string"
                }
              },
              "required": [
                "name",
                "title"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "A named phase was entered."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.step.completed"
            },
            "data": {
              "type": "object",
              "properties": {
                "name": {
                  "description": "The step's stable name.",
                  "type": "string"
                },
                "ok": {
                  "description": "Whether what it was asked to do happened.",
                  "type": "boolean"
                },
                "detail": {
                  "description": "What it said, when it said anything.",
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "name",
                "ok"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "A named phase finished."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.log"
            },
            "data": {
              "type": "object",
              "properties": {
                "stream": {
                  "description": "Which stream it came from.",
                  "$ref": "#/$defs/LogStream"
                },
                "message": {
                  "description": "The text, with control characters and terminal escapes already removed.",
                  "type": "string"
                }
              },
              "required": [
                "stream",
                "message"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "A line of output."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.diagnostic"
            },
            "data": {
              "$ref": "#/$defs/ExecutionDiagnostic"
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "A structured finding, distinct from the outcome."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.cancelling"
            },
            "data": {
              "type": "object",
              "properties": {
                "by": {
                  "description": "Who asked, in one word.",
                  "type": "string"
                }
              },
              "required": [
                "by"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "Cancellation was asked for; the handler has not stopped yet."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.cancelled"
            }
          },
          "required": [
            "type"
          ],
          "description": "It stopped because it was asked to."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.completed"
            },
            "data": {
              "type": "object",
              "properties": {
                "output": {
                  "description": "What the handler returned."
                }
              },
              "required": [
                "output"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "It finished, and the handler returned an output.\n\nThe output is on this event and not on one of its own, because a client must never\nbe able to read \"succeeded\" and find no result: the state and the value it produced\nare one fact and travel together."
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "execution.failed"
            },
            "data": {
              "type": "object",
              "properties": {
                "error": {
                  "description": "Why.",
                  "$ref": "#/$defs/ExecutionError"
                }
              },
              "required": [
                "error"
              ]
            }
          },
          "required": [
            "type",
            "data"
          ],
          "description": "It finished, and it did not."
        }
      ],
      "description": "One event about one execution.\n\n`sequence` is dense and starts at 1 within an execution: a client that has seen\nsequence `n` knows it has missed something when the next event it reads is not `n + 1`,\nand asks for the gap by cursor rather than reloading the world."
    },
    "ExecutionId": {
      "type": "string",
      "description": "The identity of one execution: `x-<UTC timestamp>-<8 hex>`.\n\nThe shape is the layer's own — a task is `t-20260905034523-a9f1` — so that an id read\nin a log, a URL or a browser tab is recognisable as this repository's without a\ndependency on a UUID crate. The timestamp orders ids by creation for a reader; the\nsuffix, not the timestamp, is what makes two ids created in the same second differ."
    },
    "ProgressView": {
      "type": "object",
      "properties": {
        "current": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Units done."
        },
        "total": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint64",
          "minimum": 0,
          "description": "Units in total, when the handler knows how many."
        },
        "message": {
          "type": [
            "string",
            "null"
          ],
          "description": "What is being done, for a reader."
        }
      },
      "required": [
        "current"
      ],
      "description": "How far along an execution is."
    },
    "LogStream": {
      "oneOf": [
        {
          "type": "string",
          "const": "stdout",
          "description": "The standard output of a child process the handler ran."
        },
        {
          "type": "string",
          "const": "stderr",
          "description": "Its standard error."
        },
        {
          "type": "string",
          "const": "handler",
          "description": "The handler itself, saying something it wants a reader to see."
        }
      ],
      "description": "Which stream a log line came from."
    },
    "ExecutionDiagnostic": {
      "type": "object",
      "properties": {
        "severity": {
          "$ref": "#/$defs/Severity",
          "description": "How bad."
        },
        "code": {
          "type": "string",
          "description": "A stable machine-readable code."
        },
        "summary": {
          "type": "string",
          "description": "One line, for a person."
        },
        "detail": {
          "type": [
            "string",
            "null"
          ],
          "description": "The rest, when there is more."
        },
        "suggestion": {
          "type": [
            "string",
            "null"
          ],
          "description": "What to do about it, when there is something."
        }
      },
      "required": [
        "severity",
        "code",
        "summary"
      ],
      "description": "A structured finding an execution reported on its way, distinct from its outcome."
    },
    "Severity": {
      "oneOf": [
        {
          "type": "string",
          "const": "info",
          "description": "Worth knowing; changes nothing."
        },
        {
          "type": "string",
          "const": "warning",
          "description": "Something to look at; the object is still served."
        },
        {
          "type": "string",
          "const": "error",
          "description": "The file is excluded and the index is degraded."
        }
      ],
      "description": "How bad a diagnostic is. `Error` excludes the file it concerns from the index and puts\nthe index into the degraded state; `Warning` and `Info` do neither."
    },
    "ExecutionError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "`invalid_input`, `not_found`, `refused`, `forbidden`, `internal`, `cancelled`, `unavailable`."
        },
        "message": {
          "type": "string",
          "description": "What went wrong, for a person."
        },
        "suggestion": {
          "type": [
            "string",
            "null"
          ],
          "description": "What to do about it, when there is something."
        },
        "correlation_id": {
          "type": "string",
          "description": "The execution this failure belongs to, so a log line and a UI agree."
        }
      },
      "required": [
        "code",
        "message",
        "correlation_id"
      ],
      "description": "Why an execution ended badly, in the repository's diagnostic vocabulary rather than in\nRust's: a code a program branches on, a sentence a person reads, and where to look.\n\nA panic message and a backtrace are never in here. The engine catches a panicking\nhandler and reports `internal` with the execution's correlation id; the panic itself is\non the process's own error stream, where the operator running the server can read it."
    }
  }
}

{
  "type": "object",
  "properties": {
    "applied": {
      "type": "integer",
      "format": "uint",
      "minimum": 0,
      "description": "How many of the reported events were applied."
    },
    "through": {
      "type": "integer",
      "format": "uint64",
      "minimum": 0,
      "description": "The reporter's sequence this server holds everything up to: the next report sends\nthe events after it, so a lost or repeated report costs nothing."
    },
    "cancel_requested": {
      "type": "boolean",
      "description": "Whether somebody asked this server to stop the execution. The reporter runs it, so\nthe reporter cancels it."
    },
    "execution": {
      "$ref": "#/$defs/ExecutionView",
      "description": "The execution as this server now holds it."
    }
  },
  "required": [
    "applied",
    "through",
    "cancel_requested",
    "execution"
  ],
  "description": "The answer of `executions.report`.",
  "title": "ReportAnswer",
  "$defs": {
    "ExecutionView": {
      "type": "object",
      "properties": {
        "id": {
          "$ref": "#/$defs/ExecutionId",
          "description": "The identity."
        },
        "capability": {
          "type": "string",
          "description": "The capability that ran, by its canonical id."
        },
        "title": {
          "type": "string",
          "description": "That capability's title, so a list needs no second lookup."
        },
        "state": {
          "$ref": "#/$defs/ExecutionState",
          "description": "Where it is."
        },
        "created_at": {
          "type": "string",
          "description": "When it was accepted, RFC 3339 in UTC."
        },
        "started_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "When the handler was entered."
        },
        "finished_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "When it reached a final state."
        },
        "duration_ms": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint64",
          "minimum": 0,
          "description": "How long it ran, in milliseconds, once it has finished."
        },
        "input": {
          "description": "The input it was given, with every value the input schema marks sensitive replaced."
        },
        "output": {
          "description": "What the handler returned, for a succeeded execution and never before."
        },
        "error": {
          "anyOf": [
            {
              "$ref": "#/$defs/ExecutionError"
            },
            {
              "type": "null"
            }
          ],
          "description": "Why it failed, for a failed execution and never before."
        },
        "progress": {
          "anyOf": [
            {
              "$ref": "#/$defs/ProgressView"
            },
            {
              "type": "null"
            }
          ],
          "description": "The last progress the handler reported."
        },
        "steps": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/StepView"
          },
          "description": "The steps it entered, in order."
        },
        "diagnostics": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ExecutionDiagnostic"
          },
          "description": "The findings it reported."
        },
        "last_sequence": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "The sequence number of the last event: the cursor a client subscribes from."
        },
        "event_count": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "How many events it has produced, including the ones no longer retained."
        },
        "events_truncated": {
          "type": "boolean",
          "description": "Whether the retained event history has lost its oldest entries to the bound."
        },
        "cancellable": {
          "type": "boolean",
          "description": "Whether asking to cancel this execution will do anything: the capability's policy."
        },
        "actor": {
          "$ref": "#/$defs/Actor",
          "description": "Who asked for it."
        },
        "repository": {
          "$ref": "#/$defs/RepositoryRef",
          "description": "Which repository it ran against."
        },
        "correlation_id": {
          "type": "string",
          "description": "The id used in this process's logs and tracing spans for this execution; the\nexecution id itself, carried under the name a reader of a log expects."
        },
        "links": {
          "$ref": "#/$defs/ExecutionLinks",
          "description": "Where to read more."
        }
      },
      "required": [
        "id",
        "capability",
        "title",
        "state",
        "created_at",
        "input",
        "last_sequence",
        "event_count",
        "events_truncated",
        "cancellable",
        "actor",
        "repository",
        "correlation_id",
        "links"
      ],
      "description": "One execution with the links to everything else about it."
    },
    "ExecutionId": {
      "type": "string",
      "description": "The identity of one execution: `x-<UTC timestamp>-<8 hex>`.\n\nThe shape is the layer's own — a task is `t-20260905034523-a9f1` — so that an id read\nin a log, a URL or a browser tab is recognisable as this repository's without a\ndependency on a UUID crate. The timestamp orders ids by creation for a reader; the\nsuffix, not the timestamp, is what makes two ids created in the same second differ."
    },
    "ExecutionState": {
      "oneOf": [
        {
          "type": "string",
          "const": "queued",
          "description": "Accepted, and no worker has picked it up."
        },
        {
          "type": "string",
          "const": "running",
          "description": "The handler is running."
        },
        {
          "type": "string",
          "const": "cancelling",
          "description": "Cancellation was asked for and the handler has not stopped yet."
        },
        {
          "type": "string",
          "const": "succeeded",
          "description": "The handler returned an output."
        },
        {
          "type": "string",
          "const": "failed",
          "description": "The handler returned an error, or the worker could not run it."
        },
        {
          "type": "string",
          "const": "cancelled",
          "description": "It stopped because it was asked to."
        }
      ],
      "description": "Where an execution is in its life.\n\nThe transitions are the whole contract, and `ExecutionState::may_move_to` is the one\nplace they are written down: the engine asks before every change, the store refuses a\nmove it did not allow, and a client that reads a final state never sees it move again.\n\n```text\n  queued ──► running ──┬──► succeeded\n     │                 ├──► failed\n     │                 └──► cancelling ──┬──► cancelled\n     │                                   ├──► succeeded\n     └──► cancelled                      └──► failed\n```\n\nThere is no `starting`. An in-process engine claims an execution and enters its handler\nin the same instant, so a state between the two would be one no client could ever\nobserve and every client would have to handle."
    },
    "ExecutionError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "`invalid_input`, `not_found`, `refused`, `forbidden`, `internal`, `cancelled`, `unavailable`."
        },
        "message": {
          "type": "string",
          "description": "What went wrong, for a person."
        },
        "suggestion": {
          "type": [
            "string",
            "null"
          ],
          "description": "What to do about it, when there is something."
        },
        "correlation_id": {
          "type": "string",
          "description": "The execution this failure belongs to, so a log line and a UI agree."
        }
      },
      "required": [
        "code",
        "message",
        "correlation_id"
      ],
      "description": "Why an execution ended badly, in the repository's diagnostic vocabulary rather than in\nRust's: a code a program branches on, a sentence a person reads, and where to look.\n\nA panic message and a backtrace are never in here. The engine catches a panicking\nhandler and reports `internal` with the execution's correlation id; the panic itself is\non the process's own error stream, where the operator running the server can read it."
    },
    "ProgressView": {
      "type": "object",
      "properties": {
        "current": {
          "type": "integer",
          "format": "uint64",
          "minimum": 0,
          "description": "Units done."
        },
        "total": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint64",
          "minimum": 0,
          "description": "Units in total, when the handler knows how many."
        },
        "message": {
          "type": [
            "string",
            "null"
          ],
          "description": "What is being done, for a reader."
        }
      },
      "required": [
        "current"
      ],
      "description": "How far along an execution is."
    },
    "StepView": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "A stable name, unique within the execution."
        },
        "title": {
          "type": "string",
          "description": "One line for a reader."
        },
        "state": {
          "$ref": "#/$defs/StepState",
          "description": "Where it stands."
        },
        "started_at": {
          "type": "string",
          "description": "When it was entered, RFC 3339 in UTC."
        },
        "finished_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "When it finished, when it has."
        },
        "detail": {
          "type": [
            "string",
            "null"
          ],
          "description": "What it said when it finished, when it said anything."
        }
      },
      "required": [
        "name",
        "title",
        "state",
        "started_at"
      ],
      "description": "One named phase of an execution, as the handler reported it."
    },
    "StepState": {
      "oneOf": [
        {
          "type": "string",
          "const": "running",
          "description": "Entered and not finished."
        },
        {
          "type": "string",
          "const": "completed",
          "description": "Finished, and what it was asked to do happened."
        },
        {
          "type": "string",
          "const": "failed",
          "description": "Finished, and it did not."
        }
      ],
      "description": "Where a step of an execution stands."
    },
    "ExecutionDiagnostic": {
      "type": "object",
      "properties": {
        "severity": {
          "$ref": "#/$defs/Severity",
          "description": "How bad."
        },
        "code": {
          "type": "string",
          "description": "A stable machine-readable code."
        },
        "summary": {
          "type": "string",
          "description": "One line, for a person."
        },
        "detail": {
          "type": [
            "string",
            "null"
          ],
          "description": "The rest, when there is more."
        },
        "suggestion": {
          "type": [
            "string",
            "null"
          ],
          "description": "What to do about it, when there is something."
        }
      },
      "required": [
        "severity",
        "code",
        "summary"
      ],
      "description": "A structured finding an execution reported on its way, distinct from its outcome."
    },
    "Severity": {
      "oneOf": [
        {
          "type": "string",
          "const": "info",
          "description": "Worth knowing; changes nothing."
        },
        {
          "type": "string",
          "const": "warning",
          "description": "Something to look at; the object is still served."
        },
        {
          "type": "string",
          "const": "error",
          "description": "The file is excluded and the index is degraded."
        }
      ],
      "description": "How bad a diagnostic is. `Error` excludes the file it concerns from the index and puts\nthe index into the degraded state; `Warning` and `Info` do neither."
    },
    "Actor": {
      "type": "object",
      "properties": {
        "kind": {
          "$ref": "#/$defs/ActorKind",
          "description": "Where the request came from."
        },
        "peer": {
          "type": [
            "string",
            "null"
          ],
          "description": "The peer id, for a call that arrived through an MCP session."
        },
        "pid": {
          "type": [
            "integer",
            "null"
          ],
          "format": "uint32",
          "minimum": 0,
          "description": "The process that ran it, for an execution another process ran and reported to this\none: the work happened there, and this process holds what it was told about it."
        }
      },
      "required": [
        "kind"
      ],
      "description": "Who asked, and which peer they are when this process knows."
    },
    "ActorKind": {
      "oneOf": [
        {
          "type": "string",
          "const": "http",
          "description": "An HTTP client, which includes the Cockpit."
        },
        {
          "type": "string",
          "const": "mcp",
          "description": "An MCP client attached to this process."
        },
        {
          "type": "string",
          "const": "cli",
          "description": "A command line: this process's own, or `majordomus run` in another process of the\nsame checkout that reported its execution to this server, with its pid."
        },
        {
          "type": "string",
          "const": "internal",
          "description": "This executable's own tests and benchmarks."
        }
      ],
      "description": "Who asked for the execution. Not an authorisation decision — this server authenticates\nnobody — but a fact worth carrying into the audit line and the UI."
    },
    "RepositoryRef": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The repository's name: the last component of its root."
        },
        "id": {
          "type": "string",
          "description": "The stable identity two processes over one checkout both compute."
        },
        "branch": {
          "type": [
            "string",
            "null"
          ],
          "description": "The branch checked out, when git can say."
        }
      },
      "required": [
        "name",
        "id"
      ],
      "description": "Which repository, and which checkout of it, an execution ran against.\n\nAn execution is never run against \"wherever this process happens to be\": the engine\nstamps the repository the index was read from, and a request that names a different one\nis refused. The path itself is not here — this value is served to whoever can reach the\nsocket, and where the checkout sits on the host is of no use to them."
    },
    "ExecutionLinks": {
      "type": "object",
      "properties": {
        "self": {
          "type": "string",
          "description": "The snapshot: `GET /api/v1/executions/get?id=…`."
        },
        "events": {
          "type": "string",
          "description": "The retained history: `GET /api/v1/executions/events?id=…`."
        },
        "cancel": {
          "type": "string",
          "description": "Where to ask it to stop: `POST /api/v1/executions/cancel`."
        },
        "websocket": {
          "type": "string",
          "description": "The live channel, from the beginning: `GET /events?execution=…`."
        },
        "cockpit": {
          "type": "string",
          "description": "The page a person opens."
        }
      },
      "required": [
        "self",
        "events",
        "cancel",
        "websocket",
        "cockpit"
      ],
      "description": "Where to read more about one execution, in this server's own terms.\n\nEvery value is derived from the registry's declared routes and from the live channel's\nown constant, so a route that moves moves here too and no client holds a path this\nserver does not serve."
    }
  }
}