{
  "openapi": "3.1.0",
  "info": {
    "title": "Tools — cat-harness-tools",
    "version": "0.1.0",
    "description": "The call contracts of the harness's Tools, one operation per Tool, generated from the Tool nodes (`schemas/tools/tool.ts`) so standard API tooling can read them. **No HTTP server serves these paths**: each Tool is reached as its `x-invoke` says — a command line, an MCP tool, or an in-process call. Tags are the skills each Tool satisfies."
  },
  "servers": [],
  "tags": [
    {
      "name": "process-state"
    }
  ],
  "paths": {
    "/tools/bpmn-engine": {
      "post": {
        "operationId": "bpmn-engine",
        "summary": "BPMN workflow engine",
        "description": "Run a declared BPMN process as an instance: `workflow_start` opens one for a subject, `workflow_next` reports what is enabled, `workflow_complete` records a step or answers a decision (a DMN-computed one from `facts`) and REFUSES a step that is not enabled. State is committed under the work plan, so which edge was taken is a record, not a memory.",
        "tags": [
          "process-state"
        ],
        "externalDocs": {
          "description": "The Tool's page",
          "url": "bpmn-engine/"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "process": {
                    "$ref": "#/components/schemas/ProcessId",
                    "description": "The process to run: a diagram's file stem or its `bpmn:process` id."
                  },
                  "node": {
                    "$ref": "#/components/schemas/NodeId",
                    "description": "The step or decision to complete, as `workflow_next` reported it."
                  }
                },
                "required": [
                  "process"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Tool's declared outputs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "enabled": {
                      "$ref": "#/components/schemas/NodeId",
                      "description": "What may be worked next, after each call."
                    }
                  }
                }
              }
            }
          }
        },
        "x-tool-iri": "https://litlfred.github.io/folio-assistant/cat-harness-tools/tools/bpmn-engine.jsonld",
        "x-invoke": {
          "mcp": {
            "tool": "workflow_*"
          },
          "inProcess": {
            "module": "src/tools/workflow.ts",
            "register": "registerWorkflowTools"
          }
        },
        "x-mcp-tools": [
          "workflow_complete",
          "workflow_gate",
          "workflow_list",
          "workflow_next",
          "workflow_start"
        ],
        "x-install": {
          "none": true
        },
        "x-requires": {
          "runtime": [
            "bun"
          ],
          "network": false
        },
        "x-satisfies": [
          "process-state"
        ],
        "x-selection": {
          "when": "Work follows a declared process and its order must be enforced and recorded: a step done out of order should be refused, not just discouraged.",
          "limits": "Reached over MCP; an agent without the server can walk the generated checklist (`bpmn-checklist`) by hand, but nothing then refuses a wrong turn.",
          "cost": "One diagram load per call; state is a small committed file."
        }
      }
    }
  },
  "components": {
    "schemas": {
      "NodeId": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[A-Za-z_][A-Za-z0-9_-]*$",
        "description": "A node id within a BPMN process, e.g. A_Implement",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/NodeId"
      },
      "ProcessId": {
        "type": "string",
        "minLength": 1,
        "pattern": "^[a-z][a-z0-9-]*$",
        "description": "A BPMN process id, e.g. crdm-requirements",
        "x-iri": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/ProcessId"
      }
    }
  }
}
