executions.cancel

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "The execution's id."
    }
  },
  "required": [
    "id"
  ],
  "description": "The input of `executions.cancel`.",
  "title": "CancelInput"
}

{
  "type": "object",
  "properties": {
    "outcome": {
      "type": "string",
      "description": "What asking achieved: `requested`, `already_requested` or `already_finished`."
    },
    "cancellable": {
      "type": "boolean",
      "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."
    },
    "execution": {
      "$ref": "#/$defs/ExecutionView",
      "description": "The execution as it stands after the request."
    }
  },
  "required": [
    "outcome",
    "cancellable",
    "execution"
  ],
  "description": "The answer of `executions.cancel`.",
  "title": "CancelReport",
  "$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."
    }
  }
}