executions.cancel
Set the execution's cancellation flag and say so on its stream. Cancellation is cooperative: a task looks at its flag and stops, and a capability whose policy says it is not cancellable runs to completion — which the answer says rather than pretending otherwise.
Set the execution's cancellation flag and say so on its stream. Cancellation is cooperative: a task looks at its flag and stops, and a capability whose policy says it is not cancellable runs to completion — which the answer says rather than pretending otherwise.
- command
- 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_cancel |
| HTTP | POST /api/v1/executions/cancel operationId executions.cancel |
| command line | majordomus executions cancel |
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 · CancelInput
The input of `executions.cancel`.
| property | type | required | description |
|---|---|---|---|
| id | string | yes | The execution's id. |
JSON Schema
{
"additionalProperties": false,
"description": "The input of `executions.cancel`.",
"properties": {
"id": {
"description": "The execution's id.",
"type": "string"
}
},
"required": [
"id"
],
"title": "CancelInput",
"type": "object"
}output · CancelReport
The answer of `executions.cancel`.
| property | type | required | description |
|---|---|---|---|
| cancellable | boolean | yes | Whether the capability declares that it looks at its cancellation flag. When it does not, the request is recorded and the execution runs to completion. |
| execution | reference | yes | The execution as it stands after the request. |
| outcome | string | yes | What asking achieved: `requested`, `already_requested` or `already_finished`. |
JSON Schema
{
"$defs": {
"Actor": {
"description": "Who asked, and which peer they are when this process knows.",
"properties": {
"kind": {
"$ref": "#/$defs/ActorKind",
"description": "Where the request came from."
},
"peer": {
"description": "The peer id, for a call that arrived through an MCP session.",
"type": [
"string",
"null"
]
}
},
"required": [
"kind"
],
"type": "object"
},
"ActorKind": {
"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.",
"oneOf": [
{
"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": "The command line of this process.",
"type": "string"
},
{
"const": "internal",
"description": "This executable's own tests and benchmarks.",
"type": "string"
}
]
},
"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"
},
"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"
},
"ExecutionLinks": {
"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.",
"properties": {
"cancel": {
"description": "Where to ask it to stop: `POST /api/v1/executions/cancel`.",
"type": "string"
},
"cockpit": {
"description": "The page a person opens.",
"type": "string"
},
"events": {
"description": "The retained history: `GET /api/v1/executions/events?id=…`.",
"type": "string"
},
"self": {
"description": "The snapshot: `GET /api/v1/executions/get?id=…`.",
"type": "string"
},
"websocket": {
"description": "The live channel, from the beginning: `GET /events?execution=…`.",
"type": "string"
}
},
"required": [
"self",
"events",
"cancel",
"websocket",
"cockpit"
],
"type": "object"
},
"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"
}
]
},
"ExecutionView": {
"description": "One execution with the links to everything else about it.",
"properties": {
"actor": {
"$ref": "#/$defs/Actor",
"description": "Who asked for it."
},
"cancellable": {
"description": "Whether asking to cancel this execution will do anything: the capability's policy.",
"type": "boolean"
},
"capability": {
"description": "The capability that ran, by its canonical id.",
"type": "string"
},
"correlation_id": {
"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.",
"type": "string"
},
"created_at": {
"description": "When it was accepted, RFC 3339 in UTC.",
"type": "string"
},
"diagnostics": {
"description": "The findings it reported.",
"items": {
"$ref": "#/$defs/ExecutionDiagnostic"
},
"type": "array"
},
"duration_ms": {
"description": "How long it ran, in milliseconds, once it has finished.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"error": {
"anyOf": [
{
"$ref": "#/$defs/ExecutionError"
},
{
"type": "null"
}
],
"description": "Why it failed, for a failed execution and never before."
},
"event_count": {
"description": "How many events it has produced, including the ones no longer retained.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"events_truncated": {
"description": "Whether the retained event history has lost its oldest entries to the bound.",
"type": "boolean"
},
"finished_at": {
"description": "When it reached a final state.",
"type": [
"string",
"null"
]
},
"id": {
"$ref": "#/$defs/ExecutionId",
"description": "The identity."
},
"input": {
"description": "The input it was given, with every value the input schema marks sensitive replaced."
},
"last_sequence": {
"description": "The sequence number of the last event: the cursor a client subscribes from.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"links": {
"$ref": "#/$defs/ExecutionLinks",
"description": "Where to read more."
},
"output": {
"description": "What the handler returned, for a succeeded execution and never before."
},
"progress": {
"anyOf": [
{
"$ref": "#/$defs/ProgressView"
},
{
"type": "null"
}
],
"description": "The last progress the handler reported."
},
"repository": {
"$ref": "#/$defs/RepositoryRef",
"description": "Which repository it ran against."
},
"started_at": {
"description": "When the handler was entered.",
"type": [
"string",
"null"
]
},
"state": {
"$ref": "#/$defs/ExecutionState",
"description": "Where it is."
},
"steps": {
"description": "The steps it entered, in order.",
"items": {
"$ref": "#/$defs/StepView"
},
"type": "array"
},
"title": {
"description": "That capability's title, so a list needs no second lookup.",
"type": "string"
}
},
"required": [
"id",
"capability",
"title",
"state",
"created_at",
"input",
"last_sequence",
"event_count",
"events_truncated",
"cancellable",
"actor",
"repository",
"correlation_id",
"links"
],
"type": "object"
},
"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"
},
"RepositoryRef": {
"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.",
"properties": {
"branch": {
"description": "The branch checked out, when git can say.",
"type": [
"string",
"null"
]
},
"id": {
"description": "The stable identity two processes over one checkout both compute.",
"type": "string"
},
"name": {
"description": "The repository's name: the last component of its root.",
"type": "string"
}
},
"required": [
"name",
"id"
],
"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"
}
]
},
"StepState": {
"description": "Where a step of an execution stands.",
"oneOf": [
{
"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.",
"type": "string"
}
]
},
"StepView": {
"description": "One named phase of an execution, as the handler reported it.",
"properties": {
"detail": {
"description": "What it said when it finished, when it said anything.",
"type": [
"string",
"null"
]
},
"finished_at": {
"description": "When it finished, when it has.",
"type": [
"string",
"null"
]
},
"name": {
"description": "A stable name, unique within the execution.",
"type": "string"
},
"started_at": {
"description": "When it was entered, RFC 3339 in UTC.",
"type": "string"
},
"state": {
"$ref": "#/$defs/StepState",
"description": "Where it stands."
},
"title": {
"description": "One line for a reader.",
"type": "string"
}
},
"required": [
"name",
"title",
"state",
"started_at"
],
"type": "object"
}
},
"description": "The answer of `executions.cancel`.",
"properties": {
"cancellable": {
"description": "Whether the capability declares that it looks at its cancellation flag. When it\ndoes not, the request is recorded and the execution runs to completion.",
"type": "boolean"
},
"execution": {
"$ref": "#/$defs/ExecutionView",
"description": "The execution as it stands after the request."
},
"outcome": {
"description": "What asking achieved: `requested`, `already_requested` or `already_finished`.",
"type": "string"
}
},
"required": [
"outcome",
"cancellable",
"execution"
],
"title": "CancelReport",
"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 |