Document the Context request cancel action

SI
5d ago
+35-4

Summary

Documents the new cancel action of the shared POST /api/context operation (and the MCP context tool). A saved Context request can be stopped while it is queued, failed or running; completed or partial requests are reported as not_cancellable and keep their saved evidence. The response text names the three persisted outcomes (cancelled, already_cancelled, not_cancellable), defines the returned request as the same record read returns (never including the worker claim token), and states that a cancelled request is never claimed again, that a workflow already dispatched (including one started by an ingest that raced the cancel) ends without further provider work, that a failed request keeps its saved error, that there is no un-cancel, and that cancellation changes no credits, provider settlement or accepted evidence. The operation summary and action list now name cancel, the other-workspace case is documented under 409 where it is returned, and a cancelRequest example is added. This is the contract for the ticket's "cancellation ... has deterministic persisted outcomes" item.

Refs recoupable/app#2122 (child of epic recoupable/app#2116).

Merge sequencing

docs (this PR) → database recoupable/database#106 (cancel_context_request migration) → api recoupable/api#1017 (cancel HTTP/MCP action). No app/chat PR. This PR depends on no open PR; it is an additive edit to the /api/context request oneOf and examples, the operation summary/description, and the 200/409 response descriptions. operate.mdx stays frontmatter-only (its title comes from frontmatter, not the summary).

Verification

  • Ran: python3 -c "import json;json.load(open('api-reference/openapi/context.json'))" → parses; the oneOf has 6 variants and exactly one has action.const == "cancel" with request_id required; examples are twoSongBrief, saveBrief, readBrief, cancelRequest.
  • Red → green: not applicable to the JSON contract; the API test lib/context/__tests__/cancelOperation.test.ts in the api PR failed first with ZodError: No matching discriminator for action: "cancel".
  • Not verified: Mintlify rendering of the updated page, hosted deployment, live providers, production database.

Out of scope / known gaps

  • Module executions only exist on completed or partial requests, which cancel reports not_cancellable; cancelling paid per-module execution (CE07 #2123/#2105) will need a contract revision when it lands.
  • A scheduled dispatch-gap sweep and a Chat UI cancel control.
  • Billing treatment of cancellation stays with the paid-execution safety lane.

🤖 Generated with Claude Code