Triggers, Kickoff Patterns & Cancellation

How jobs are triggered

There are two primary ways to start a K12 workflow:

HTTP tool kickoff (EOP) — k12-annex-editing-kickoff / k12-qrg-editing-kickoff invoked over the Mastra HTTP API or APIM. This is the canonical external trigger and accepts the validated payload, responds with requestId/sessionId, and either returns accepted (async) or success (sync wait).
Internal runner / CLI/test harness — The annex-editing-workflow-runner (EOP runner) exposes runAnnexWorkflowKickoff used by integration scripts and unit tests to execute synchronously without going through the tool wrapper.

waitForResult: true makes the kickoff attempt to finish and return the success envelope (useful for tests or APIs that want immediate results). Beware of timeouts in HTTP/APIM in this mode.
Default mode returns accepted and leaves the job to complete in the background; consumers poll status/result tools to obtain the final payload.

k12-cancel-task-request marks log_EOP_TaskStatus and log_EOP_TaskRequests as cancelled (and writes timestamps). It is a DB-driven cancellation and returns status: success or status: error when rows weren't affected.
If K12_ENABLE_WORKFLOW_CANCELLATION is enabled, the cancellation tool also attempts to stop in-progress Mastra workflow runs via API/handle. Workflow cancellation is best-effort; always verify DB rows after cancelling.

For long-running LLM operations, prefer async kickoff and poll; this avoids APIM/HTTP timeouts and provides better observability.
When cancelling, check both log_Jobs (job row) and log_EOP_TaskStatus to confirm the run has been marked cancelled.