Skip to content

executions.start

Run any executable capability of this registry as an execution: the input is checked against that capability's own input schema, the work is queued, and this answers at once with the execution's id and the links to follow it. Nothing waits for the handler. The capability runs through the same executor every other interface calls, so there is no second implementation of anything.

Run any executable capability of this registry as an execution: the input is checked against that capability's own input schema, the work is queued, and this answers at once with the execution's id and the links to follow it. Nothing waits for the handler. The capability runs through the same executor every other interface calls, so there is no second implementation of anything.

Exposure

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

surfaceas
MCPtool majordomus_execution_start
HTTPPOST /api/v1/executions/start operationId executions.start
command linemajordomus run

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 · StartInput

The input of `executions.start`: which capability to run, and with what.

propertytyperequireddescription
capability string yes The canonical id of the capability to run (`health.report`, `objects.verify`).
input object no Its input, as its own input schema describes it; an empty object when it takes none. default null
JSON Schema 
{
  "additionalProperties": false,
  "description": "The input of `executions.start`: which capability to run, and with what.",
  "properties": {
    "capability": {
      "description": "The canonical id of the capability to run (`health.report`, `objects.verify`).",
      "type": "string"
    },
    "input": {
      "default": null,
      "description": "Its input, as its own input schema describes it; an empty object when it takes none."
    }
  },
  "required": [
    "capability"
  ],
  "title": "StartInput",
  "type": "object"
}

output · ExecutionView

One execution with the links to everything else about it.

propertytyperequireddescription
actor reference yes Who asked for it.
cancellable boolean yes Whether asking to cancel this execution will do anything: the capability's policy.
capability string yes The capability that ran, by its canonical id.
correlation_id string yes The id used in this process's logs and tracing spans for this execution; the execution id itself, carried under the name a reader of a log expects.
created_at string yes When it was accepted, RFC 3339 in UTC.
diagnostics array no The findings it reported.
duration_ms integer | null no How long it ran, in milliseconds, once it has finished.
error one of 2 no Why it failed, for a failed execution and never before.
event_count integer yes How many events it has produced, including the ones no longer retained.
events_truncated boolean yes Whether the retained event history has lost its oldest entries to the bound.
finished_at string | null no When it reached a final state.
id reference yes The identity.
input object yes The input it was given, with every value the input schema marks sensitive replaced.
last_sequence integer yes The sequence number of the last event: the cursor a client subscribes from.
links reference yes Where to read more.
output object no What the handler returned, for a succeeded execution and never before.
progress one of 2 no The last progress the handler reported.
repository reference yes Which repository it ran against.
started_at string | null no When the handler was entered.
state reference yes Where it is.
steps array no The steps it entered, in order.
title string yes That capability's title, so a list needs no second lookup.
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"
        }
      ]
    },
    "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": "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"
  ],
  "title": "ExecutionView",
  "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.

transportstatecasestargets
directcovered1demonstrate
mcpcovered1demonstrate
httpcovered1demonstrate