executions.events
The retained events of one execution, oldest first, after a sequence number. This is what a browser reads after a reload and what a client reads after a reconnect: the page carries the cursor to open the live channel with, so nothing is missed between the history and the stream.
The retained events of one execution, oldest first, after a sequence number. This is what a browser reads after a reload and what a client reads after a reconnect: the page carries the cursor to open the live channel with, so nothing is missed between the history and the stream.
- query
- behaviorally_verified
- module executions
- #executions
- #control-plane
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | tool majordomus_execution_events |
| HTTP | GET /api/v1/executions/events operationId executions.events |
| command line | majordomus executions events |
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 · EventsInput
The input of `executions.events`.
| property | type | required | description |
|---|---|---|---|
| after | integer | null | no | Only events after this sequence number: the cursor a reconnecting client holds. |
| id | string | yes | The execution's id. |
| limit | integer | null | no | How many, oldest first; the default and the bound are both `500`. |
JSON Schema
{
"additionalProperties": false,
"description": "The input of `executions.events`.",
"properties": {
"after": {
"description": "Only events after this sequence number: the cursor a reconnecting client holds.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"id": {
"description": "The execution's id.",
"type": "string"
},
"limit": {
"description": "How many, oldest first; the default and the bound are both `500`.",
"format": "uint",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"id"
],
"title": "EventsInput",
"type": "object"
}output · EventHistory
The answer of `executions.events`: one page of an execution's retained history.
| property | type | required | description |
|---|---|---|---|
| events | array | yes | The events, oldest first. |
| execution_id | string | yes | The execution the events belong to. |
| last_sequence | integer | yes | The sequence of the last event here: the cursor for the next page, and the one to open the live channel with. |
| more | boolean | yes | Whether more events follow this page right now. |
| state | reference | yes | Where the execution stands now, so a client needs one request rather than two. |
| truncated | boolean | yes | Whether events before this page had already been dropped by the store's bound. |
JSON Schema
{
"$defs": {
"ExecutionDiagnostic": {
"description": "A structured finding an execution reported on its way, distinct from its outcome.",
"properties": {
"code": {
"description": "A stable machine-readable code.",
"type": "string"
},
"detail": {
"description": "The rest, when there is more.",
"type": [
"string",
"null"
]
},
"severity": {
"$ref": "#/$defs/Severity",
"description": "How bad."
},
"suggestion": {
"description": "What to do about it, when there is something.",
"type": [
"string",
"null"
]
},
"summary": {
"description": "One line, for a person.",
"type": "string"
}
},
"required": [
"severity",
"code",
"summary"
],
"type": "object"
},
"ExecutionError": {
"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.",
"properties": {
"code": {
"description": "`invalid_input`, `not_found`, `refused`, `internal`, `cancelled`, `unavailable`.",
"type": "string"
},
"correlation_id": {
"description": "The execution this failure belongs to, so a log line and a UI agree.",
"type": "string"
},
"message": {
"description": "What went wrong, for a person.",
"type": "string"
},
"suggestion": {
"description": "What to do about it, when there is something.",
"type": [
"string",
"null"
]
}
},
"required": [
"code",
"message",
"correlation_id"
],
"type": "object"
},
"ExecutionEvent": {
"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.",
"oneOf": [
{
"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.",
"properties": {
"data": {
"properties": {
"capability": {
"description": "The capability's canonical id.",
"type": "string"
},
"input": {
"description": "The input, with sensitive values already replaced."
},
"title": {
"description": "Its title.",
"type": "string"
}
},
"required": [
"capability",
"title",
"input"
],
"type": "object"
},
"type": {
"const": "execution.created",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "It is waiting for a worker.",
"properties": {
"data": {
"properties": {
"ahead": {
"description": "How many executions are ahead of it.",
"format": "uint",
"minimum": 0,
"type": "integer"
}
},
"required": [
"ahead"
],
"type": "object"
},
"type": {
"const": "execution.queued",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "A worker picked it up and is about to enter the handler.",
"properties": {
"type": {
"const": "execution.started",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
{
"description": "How far along it is.",
"properties": {
"data": {
"$ref": "#/$defs/ProgressView"
},
"type": {
"const": "execution.progress",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "A named phase was entered.",
"properties": {
"data": {
"properties": {
"name": {
"description": "The step's stable name.",
"type": "string"
},
"title": {
"description": "One line for a reader.",
"type": "string"
}
},
"required": [
"name",
"title"
],
"type": "object"
},
"type": {
"const": "execution.step.started",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "A named phase finished.",
"properties": {
"data": {
"properties": {
"detail": {
"description": "What it said, when it said anything.",
"type": [
"string",
"null"
]
},
"name": {
"description": "The step's stable name.",
"type": "string"
},
"ok": {
"description": "Whether what it was asked to do happened.",
"type": "boolean"
}
},
"required": [
"name",
"ok"
],
"type": "object"
},
"type": {
"const": "execution.step.completed",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "A line of output.",
"properties": {
"data": {
"properties": {
"message": {
"description": "The text, with control characters and terminal escapes already removed.",
"type": "string"
},
"stream": {
"$ref": "#/$defs/LogStream",
"description": "Which stream it came from."
}
},
"required": [
"stream",
"message"
],
"type": "object"
},
"type": {
"const": "execution.log",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "A structured finding, distinct from the outcome.",
"properties": {
"data": {
"$ref": "#/$defs/ExecutionDiagnostic"
},
"type": {
"const": "execution.diagnostic",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "Cancellation was asked for; the handler has not stopped yet.",
"properties": {
"data": {
"properties": {
"by": {
"description": "Who asked, in one word.",
"type": "string"
}
},
"required": [
"by"
],
"type": "object"
},
"type": {
"const": "execution.cancelling",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "It stopped because it was asked to.",
"properties": {
"type": {
"const": "execution.cancelled",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
{
"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.",
"properties": {
"data": {
"properties": {
"output": {
"description": "What the handler returned."
}
},
"required": [
"output"
],
"type": "object"
},
"type": {
"const": "execution.completed",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
},
{
"description": "It finished, and it did not.",
"properties": {
"data": {
"properties": {
"error": {
"$ref": "#/$defs/ExecutionError",
"description": "Why."
}
},
"required": [
"error"
],
"type": "object"
},
"type": {
"const": "execution.failed",
"type": "string"
}
},
"required": [
"type",
"data"
],
"type": "object"
}
],
"properties": {
"event_id": {
"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.",
"type": "string"
},
"execution_id": {
"$ref": "#/$defs/ExecutionId",
"description": "The execution it is about."
},
"schema_version": {
"description": "The protocol version, [`PROTOCOL_VERSION`].",
"type": "string"
},
"sequence": {
"description": "Its position in that execution's stream, from 1, without gaps.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"timestamp": {
"description": "When the event was produced, RFC 3339 in UTC.",
"type": "string"
}
},
"required": [
"schema_version",
"event_id",
"execution_id",
"sequence",
"timestamp"
],
"type": "object"
},
"ExecutionId": {
"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.",
"type": "string"
},
"ExecutionState": {
"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.",
"oneOf": [
{
"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.",
"type": "string"
}
]
},
"LogStream": {
"description": "Which stream a log line came from.",
"oneOf": [
{
"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.",
"type": "string"
}
]
},
"ProgressView": {
"description": "How far along an execution is.",
"properties": {
"current": {
"description": "Units done.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"message": {
"description": "What is being done, for a reader.",
"type": [
"string",
"null"
]
},
"total": {
"description": "Units in total, when the handler knows how many.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"current"
],
"type": "object"
},
"Severity": {
"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.",
"oneOf": [
{
"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.",
"type": "string"
}
]
}
},
"description": "The answer of `executions.events`: one page of an execution's retained history.",
"properties": {
"events": {
"description": "The events, oldest first.",
"items": {
"$ref": "#/$defs/ExecutionEvent"
},
"type": "array"
},
"execution_id": {
"description": "The execution the events belong to.",
"type": "string"
},
"last_sequence": {
"description": "The sequence of the last event here: the cursor for the next page, and the one to\nopen the live channel with.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"more": {
"description": "Whether more events follow this page right now.",
"type": "boolean"
},
"state": {
"$ref": "#/$defs/ExecutionState",
"description": "Where the execution stands now, so a client needs one request rather than two."
},
"truncated": {
"description": "Whether events before this page had already been dropped by the store's bound.",
"type": "boolean"
}
},
"required": [
"execution_id",
"state",
"events",
"last_sequence",
"more",
"truncated"
],
"title": "EventHistory",
"type": "object"
}Policies
- benchmark
- waived — waived: transient_state
- 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 | waived (transient_state) | 0 | |
| mcp | waived (transient_state) | 0 | |
| http | waived (transient_state) | 0 |