@shipeasy/openapi 3.2.0 → 3.4.0

package/spec/paths/ops.yaml

@@ -3,18 +3,31 @@
     operationId: listOpsItems
     summary: List the operational queue
     description: |-
-      Returns the unified ops queue (bugs, feature requests, errors, alerts) in work order — highest priority first, oldest first within a priority — so consumers work it top-down. Filter by `type` and/or `status`, and cap with `limit`. Human-gated holding states (items awaiting human sign-off in the dashboard) are never returned by `all`/default status.
+      Returns the unified ops queue (bugs, feature requests, errors, alerts, measurement plans) in work order — highest priority first, oldest first within a priority — so consumers work it top-down. Every filter is applied in SQL before paging, and filters combine with AND. Human-gated holding states (items awaiting human sign-off in the dashboard) are never returned by `all`/default status.
+
+      **Filters:** `type` (one item type), `status` (one lifecycle status, or `unresolved` — everything not yet `resolved`/`wont_fix`), `priority` (one triage priority), `owner` (one person or agent), and `scope=ready` — the items ready to be picked up right now: `open`, with nobody working them (no open run), and either unowned or reopened (sent back to `open` after an earlier run finished).
+
+      **Paging:** `limit` is the page size and `offset` the number of items to skip. The order is stable, so walk the queue with `offset += limit`; a page shorter than `limit` is the last one.
 
       **Use case:** Pull the open queue to triage — e.g. every `bug` still `open` — before working items down one by one.
     tags:
       - Ops
     parameters:
       - $ref: ../components/parameters.yaml#/ProjectId
+      # This enum is the third hand-written copy of the item-type list (the two
+      # response schemas in components/schemas/ops.yaml hold the others — there is
+      # no OpsItemType component to $ref, since extracting one would retype `type`
+      # as a TS enum in every generated client). __tests__/spec.test.ts pins the
+      # copies together: it drifted once, and `measure_plan` reached both responses
+      # while the filter still rejected it.
       - name: type
         in: query
         required: false
-        description: Filter by item type (`bug`/`feature_request`/`error`/`alert`), or `all`.
+        description: >-
+          Filter by item type, or `all` (the default). Every type a returned item
+          can carry is filterable, including the auto-filed ones.
         schema:
+          default: all
           anyOf:
             - type: string
               enum:
@@ -22,29 +35,92 @@
                 - feature_request
                 - error
                 - alert
-              description: Queue item type. `bug` and `feature_request` are user-fileable; `error` and `alert` tickets are auto-filed by the platform.
+                - measure_plan
+              description: Queue item type. `bug` and `feature_request` are user-fileable; `error`, `alert`, and `measure_plan` tickets are auto-filed by the platform.
             - type: string
               const: all
       - name: status
         in: query
         required: false
         description: >-
-          Filter by lifecycle status, or `all`. The human-gated holding state
-          (`pending_approval`) is excluded from `all`/default and returned only
-          when requested as the exact status.
+          Filter by one lifecycle status, `unresolved` for every status that
+          is not `resolved` or `wont_fix`, or `all` for every status. Defaults
+          to `all` over HTTP; the CLI and MCP tool default to `unresolved`, so
+          pass `all` there to include resolved and won't-fix items. The
+          human-gated holding state (`pending_approval`) is excluded from
+          `unresolved` and `all`, and returned only when requested as the exact
+          status.
         schema:
+          default: all
           anyOf:
             - $ref: ../components/schemas/ops.yaml#/OpsItemStatus
+            - type: string
+              const: unresolved
+            - type: string
+              const: all
+        # The CLI and MCP send `unresolved` when the caller omits `status`: an
+        # agent asking for "the queue" wants the work still to do, not every
+        # resolved and won't-fix item ever filed. The HTTP API keeps `all` — the
+        # dashboard and the mobile app read the whole queue through it.
+        x-cli:
+          default: unresolved
+        x-mcp:
+          default: unresolved
+      - name: priority
+        in: query
+        required: false
+        description: >-
+          Filter by triage priority, or `all` (the default). Items with no
+          priority set are returned only under `all`.
+        schema:
+          default: all
+          anyOf:
+            - $ref: ../components/schemas/ops.yaml#/OpsItemPriority
             - type: string
               const: all
+      - name: scope
+        in: query
+        required: false
+        description: >-
+          `ready` narrows to the items ready to be picked up right now: status
+          `open`, no open run (nobody has acked it and is still working), and
+          either unowned (no person and no agent) or reopened (sent back to
+          `open` after an earlier run finished). Leave `status` unset with it.
+          `all` (the default) applies no such narrowing.
+        schema:
+          type: string
+          enum:
+            - all
+            - ready
+          default: all
       - name: limit
         in: query
         required: false
-        description: Max items to return (1–500).
+        description: >-
+          Page size — max items to return (1–500). A page shorter than `limit`
+          is the last one.
         schema:
           type: integer
           minimum: 1
           maximum: 500
+          default: 200
+        # The MCP tool makes the page size a required input (and refuses the call
+        # without it) so an agent sizes its own page instead of silently pulling
+        # 200 hydrated rows into its context. The HTTP API and the CLI keep the
+        # default.
+        x-mcp:
+          required: true
+      - name: offset
+        in: query
+        required: false
+        description: >-
+          Number of items to skip before the page starts. Defaults to 0. The
+          order is stable, so `offset += limit` walks the queue page by page.
+        schema:
+          type: integer
+          minimum: 0
+          maximum: 100000
+          default: 0
       - name: owner
         in: query
         required: false
@@ -52,8 +128,7 @@
           Narrow to items owned by one person OR one agent. Matches a person by
           `users.id`, email, or display name, and an agent by connector id,
           display name, or kebab-case handle — e.g. `owner=Claude` or
-          `owner=alice@acme.dev`. Case-insensitive exact match, applied over the
-          returned page.
+          `owner=alice@acme.dev`. Case-insensitive exact match.
         schema:
           type: string
     responses:
@@ -99,6 +174,30 @@
       - FORBIDDEN
     x-cli:
       name: list
+    # The MCP tool description, verbatim — the generator otherwise keeps only the
+    # first paragraph (capped), which is too short to say how to filter and page.
+    x-mcp:
+      description: >-
+        List the operational queue (bugs, feature requests, errors, alerts,
+        measurement plans) in work order — highest priority first, oldest first
+        within a priority.
+        PAGING: `limit` (page size, 1–500) is REQUIRED — the call fails without
+        it. Start at `offset: 0` and add `limit` to `offset` for the next page;
+        a page shorter than `limit` is the last one.
+        FILTERS (all optional, combined with AND, applied before paging):
+        `type` = bug | feature_request | error | alert | measure_plan;
+        `status` = open | in_progress | investigating_by_ai | blocked |
+        ready_for_qa | resolved | wont_fix | pending_approval | unresolved |
+        all — DEFAULTS TO `unresolved` (omitted = items still being worked:
+        open, in_progress, blocked, ready_for_qa…; no resolved or wont_fix
+        ones). Pass `status: "all"` to include resolved and wont_fix too
+        (pending_approval is only returned when asked for exactly);
+        `priority` = critical | high | medium | nice_to_have;
+        `owner` = a person (id, email or name) or an agent (connector id, name
+        or handle, e.g. "Claude");
+        `scope: "ready"` = what to work on now — open items nobody is working
+        (no open run) that are unowned or were reopened after an earlier run.
+        Use `scope: "ready"` to pick the next item, then `ops_ack` it.
   post:
     operationId: createOpsItem
     summary: File a queue item
@@ -195,6 +294,8 @@
 
       The project is the key's own project; there is no `X-Project-Id` to pass and no way to file into someone else's queue. Repeat submissions of the same title dedupe against the open ticket already tracking it, which returns `200` with `deduped: true` instead of filing again.
 
+      Send a `dedupKey` to own that grain yourself — the same key from a monitor, a job, or a retried install re-triggers its open ticket: the ticket's fields are refreshed from the new payload and a "re-triggered" comment is appended (`200` with `deduped: true, updated: true`), so one recurring failure stays one ticket with its history intact.
+
       This endpoint is served by the Shipeasy **edge worker** (`api.shipeasy.ai`), not the admin API — see `servers` below.
 
       **Use case:** `shipeasy setup` fails on a customer's machine and self-reports the failure with the user's consent — `{ "title": "Setup failed at Feature installs", "stepsToReproduce": "…", "actualResult": "…" }`.
@@ -281,7 +382,7 @@
     description: |-
       Files one feature request onto a project's queue, awaiting human approval. The feature-request counterpart to `POST /ops/bug`, with the same three gates: a `client` key carrying `tickets:public_create`, a project that has opted in, and a `pending_approval` state forced server-side.
 
-      The project is the key's own project; there is no `X-Project-Id` to pass. Repeat submissions of the same title dedupe against the open ticket already tracking it, which returns `200` with `deduped: true` instead of filing again.
+      The project is the key's own project; there is no `X-Project-Id` to pass. Repeat submissions of the same title dedupe against the open ticket already tracking it, which returns `200` with `deduped: true` instead of filing again. A `dedupKey` works exactly as on `POST /ops/bug`: a repeat carrying the same key refreshes the open ticket and comments that it was re-triggered.
 
       This endpoint is served by the Shipeasy **edge worker** (`api.shipeasy.ai`), not the admin API — see `servers` below.
 
@@ -607,6 +708,11 @@
       list` and use one of those (or connect the agent under Settings →
       Triggers).
 
+      **Launching.** When the named agent has a connected trigger and you pass
+      no `sessionId`, the ack also fires that trigger — a new provider run
+      starts working the item. Pass `launch: false` to only claim the item and
+      record the run (you are doing the work yourself), without starting one.
+
       **Completion.** The run closes automatically on the loop's final actions —
       linking the fixing PR (`link-pr`), an ops-notify escalation, or a
       completion status change (`ready_for_qa`/`resolved`) — and the dashboard
@@ -728,7 +834,9 @@
       (`kind: investigated`), a blocking question for the team (`kind:
       question`), or how to verify the fix (`kind: ready_for_qa` with
       `qaNotes`). Append-only and create-only, so it is safe for restricted ops
-      keys.
+      keys. For a decision between options you can name, ask a structured
+      question instead (`ops questions ask`) — it is answerable in one tap and
+      the answer comes back to your run.
 
       **Use case:** After working an item, leave a findings write-up (summary,
       markdown findings, sources inspected, confidence) so the team — and the
@@ -871,6 +979,401 @@
       positional:
         - handle
         - investigationId
+/api/admin/ops/{handle}/questions:
+  get:
+    operationId: listOpsQuestions
+    summary: List an item's questions
+    description: |-
+      The structured questions asked on a queue item, with their answers —
+      newest first (max 100). Pull this to read the answers to questions you
+      asked: an answered question reads `status: completed` and carries
+      `answer.selected` (the option labels picked) and `answer.other` (the
+      free-text "Other" reply, or `null`).
+
+      **Use case:** You asked with `delivery: poll` from a live session — poll
+      this until your questions read `completed`, then continue with the answers.
+    tags:
+      - Questions
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: handle
+        in: path
+        required: true
+        description: Per-project item number (e.g. `7`) or the full ops item id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+      - name: status
+        in: query
+        required: false
+        description: Filter by question status, or `all` (the default).
+        schema:
+          default: all
+          anyOf:
+            - $ref: ../components/schemas/ops.yaml#/OpsQuestionStatus
+            - type: string
+              const: all
+    responses:
+      "200":
+        description: List an item's questions
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/ListOpsQuestionsResponse
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: list
+      positional:
+        - handle
+  post:
+    operationId: askOpsQuestions
+    summary: Ask the team questions about an item
+    description: |-
+      Ask 1–4 structured questions about a queue item — the way to get a
+      decision from a person when the implementation needs one. Each question
+      is the `AskUserQuestion` shape: a short `header` chip, the full
+      `question`, 2–4 `options` (`label` + `description`), and `multiSelect`
+      (checkboxes instead of radios). The person can always answer "Other" in
+      free text, so never add an "Other" option yourself. The questions render
+      at the very top of the item's detail panel and mark the row in the queue.
+
+      **Delivery.** `resume` re-fires your trigger-connector run on the item
+      once every question it asked is answered, continuing the same run record
+      with the answers in the prompt — stop after asking. `poll` fires nothing;
+      poll `GET .../questions` instead. Omitted, it is `resume` when `runId`
+      names a run launched through a trigger connector, else `poll`.
+
+      **Use case:** Blocked on a product decision (which behaviour to keep,
+      which of two fixes to ship) — ask instead of guessing, then wait for the
+      answer.
+    tags:
+      - Questions
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: handle
+        in: path
+        required: true
+        description: Per-project item number (e.g. `7`) or the full ops item id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/ops.yaml#/AskOpsQuestionsRequest
+          examples:
+            single:
+              summary: Ask one radio question
+              value:
+                runId: 0d3f4c8e-7a51-4c2e-9b1f-1e2d3c4b5a69
+                questions:
+                  - header: Legacy param
+                    question: Should the fix keep honouring the legacy `?v=1` query param?
+                    multiSelect: false
+                    options:
+                      - label: Keep it
+                        description: Old links keep working; the redirect stays
+                      - label: Drop it
+                        description: Simpler code; old links land on the default view
+    responses:
+      "200":
+        description: The created questions, in the order asked
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/AskOpsQuestionsResponse
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: ask
+      positional:
+        - handle
+/api/admin/ops/{handle}/questions/{questionId}/answer:
+  post:
+    operationId: answerOpsQuestion
+    summary: Answer a question
+    description: |-
+      Answer one open question on a queue item — pick option labels in
+      `selected` (exactly one unless the question is `multiSelect`) and/or
+      write a free-text `other`. The question moves to `completed`. When it was
+      the last open question of a `resume` run, that agent is re-fired on the
+      item with every answer. A person's action: never allow-listed for
+      restricted ops keys.
+
+      **Use case:** Unblock an agent from the CLI instead of the dashboard.
+    tags:
+      - Questions
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: handle
+        in: path
+        required: true
+        description: Per-project item number (e.g. `7`) or the full ops item id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+      - name: questionId
+        in: path
+        required: true
+        description: The question id (from `ask` or `list`).
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/ops.yaml#/AnswerOpsQuestionRequest
+          examples:
+            option:
+              summary: Pick an option
+              value:
+                selected:
+                  - Keep it
+            other:
+              summary: Answer in free text
+              value:
+                other: Keep it for a release, then drop it
+    responses:
+      "200":
+        description: The answered question
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/OpsQuestion
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - INVALID_TRANSITION
+      - VALIDATION
+    x-cli:
+      name: answer
+      positional:
+        - handle
+        - questionId
+/api/admin/ops/{handle}/questions/{questionId}/cancel:
+  post:
+    operationId: cancelOpsQuestion
+    summary: Withdraw a question
+    description: |-
+      Withdraw one open question you asked — it no longer needs an answer
+      (you found it out yourself, or the item moved on). The question moves to
+      `cancelled` and leaves the detail panel. Withdrawing the last open
+      question of a run delivers nothing.
+
+      **Use case:** You asked, then answered it yourself from the code — take
+      it off the person's plate.
+    tags:
+      - Questions
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: handle
+        in: path
+        required: true
+        description: Per-project item number (e.g. `7`) or the full ops item id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+      - name: questionId
+        in: path
+        required: true
+        description: The question id (from `ask` or `list`).
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: The withdrawn question
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/OpsQuestion
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - INVALID_TRANSITION
+    x-cli:
+      name: cancel
+      positional:
+        - handle
+        - questionId
+/api/admin/ops/{handle}/qa-notes:
+  get:
+    operationId: listOpsQaNotes
+    summary: List an item's QA notes
+    description: |-
+      The typed QA notes on a queue item, newest first (max 200) — narrowing,
+      clarification, verification and correction notes, each with its author and
+      time. They are separate from the comment thread: read these to learn the
+      CURRENT QA state of a ticket (what remains failing, what "fixed" now means,
+      the last verification verdict) without parsing prose comments.
+
+      **Use case:** A coding agent picks an item up and checks the latest
+      `verification` verdict and any `narrowing` note before touching the code.
+    tags:
+      - QA notes
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: handle
+        in: path
+        required: true
+        description: Per-project item number (e.g. `7`) or the full ops item id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+      - name: kind
+        in: query
+        required: false
+        description: Only notes of this kind.
+        schema:
+          $ref: ../components/schemas/ops.yaml#/OpsQaNoteKind
+    responses:
+      "200":
+        description: List an item's QA notes
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/ListOpsQaNotesResponse
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: list
+      positional:
+        - handle
+  post:
+    operationId: createOpsQaNote
+    summary: Add a QA note to an item
+    description: |-
+      Append one typed QA note to a queue item. `kind` is `narrowing` (what now
+      passes vs what still fails), `clarification` (what "fixed" now means),
+      `verification` (requires a `verdict` of `pass` or `fail`, and `body` says
+      what was checked) or `correction` (withdraws an earlier framing). Notes
+      are append-only and appear in the item's QA notes section, not in the
+      comment thread. The author is the caller's identity; pass `agent` to
+      record the note as written by that agent type's QA automation. A `fail` verdict never changes the item's
+      status by itself: the dashboard offers an explicit "Reopen item" action,
+      and `ops update --status open` does the same from the CLI.
+
+      **Use case:** QA automation records "verified on production: FAIL, the
+      second facet still errors" as data an agent can read back.
+    tags:
+      - QA notes
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: handle
+        in: path
+        required: true
+        description: Per-project item number (e.g. `7`) or the full ops item id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/ops.yaml#/CreateOpsQaNoteRequest
+          examples:
+            verification:
+              summary: A failing verification
+              value:
+                kind: verification
+                verdict: fail
+                body: Retested on production after the deploy — the export still drops the second sheet
+            narrowing:
+              summary: Narrow a bug to the facet that still fails
+              value:
+                kind: narrowing
+                body: The list view is fixed; only the detail panel still shows the stale count
+    responses:
+      "200":
+        description: The created note
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/OpsQaNote
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: create
+      positional:
+        - handle
 /api/admin/agent-profiles:
   get:
     operationId: listOpsAgents