@shipeasy/openapi 2.4.0 → 2.5.0

package/openapi.yaml

@@ -207,6 +207,15 @@ tags:
       **Mentions.** `@teammate` in a body raises an in-app notification for that
       person; `@shipeasy` asks Jarvis (the AI agent) to read the item and reply.
       Comments authored by Jarvis carry `authorType: system`.
+  - name: Investigations
+    parent: Ops
+    description: |-
+      Investigation records on a queue item — the structured, read-only write-ups
+      an AI agent produces while working it (findings / a blocking question / QA
+      notes), plus the `working` run rows an ack or an AI hand-off opens. This is
+      the AI-write seam the cockpit's detail panel renders: `list` reads what a
+      previous run found, `create` appends a new record, and `update` fills in the
+      `working` run record you were handed (findings, PR, confidence) as you work.
   - name: Projects
     description: |-
       Projects: the account-level container every other resource is scoped to.
@@ -1997,7 +2006,7 @@ paths:
 
         - **Minimal create** — `name` + `schema`. Initial value defaults to `{}`.
         - **Seeded create** — supply a flat `value` to publish the same object on every env.
-        - **Per-env seed** — supply a `{ env: value }` map for different per-env starting values.
+        - **Per-env seed** — supply a `{ env: value }` map under `value`, or pass the env keys `dev`/`staging`/`prod` directly (each overrides `value` for that env and is published at version 1).
       tags:
         - Configs
       parameters:
@@ -2039,8 +2048,8 @@ paths:
                       - name: free
                       - name: pro
               perEnvSeed:
-                summary: Per-env seed
-                description: 'Pass a `{ env: value }` map to seed different initial values per env.'
+                summary: Per-env seed (env keys)
+                description: Pass the env keys directly to seed different initial values per env. Each overrides `value` for that env and is published at version 1.
                 value:
                   name: pricing.tiers
                   schema:
@@ -2050,20 +2059,15 @@ paths:
                         type: array
                     required:
                       - tiers
-                  value:
-                    dev:
-                      tiers:
-                        - name: free
-                        - name: pro
-                        - name: enterprise
-                    stage:
-                      tiers:
-                        - name: free
-                        - name: pro
-                    prod:
-                      tiers:
-                        - name: free
-                        - name: pro
+                  dev:
+                    tiers:
+                      - name: free
+                      - name: pro
+                      - name: enterprise
+                  prod:
+                    tiers:
+                      - name: free
+                      - name: pro
       responses:
         '201':
           description: Create a dynamic config
@@ -2216,15 +2220,13 @@ paths:
       operationId: updateConfig
       summary: Update a dynamic config
       description: |-
-        Partial update. When `value` is supplied it is **republished on every env** (new version per env). When `schema` is supplied it replaces the current schema; every existing value is re-validated.
-
-        For env-scoped edits, use the draft/publish flow (`PUT /{id}/drafts` then `POST /{id}/publish`) instead.
+        Partial update. When `value` is supplied it is **republished on every env** (new version per env). A per-env key (`dev`/`staging`/`prod`) publishes a new version to **only that env**, immediately, overriding `value` for it. When `schema` is supplied it replaces the current schema; every existing value is re-validated.
 
         **Use cases**
 
         - **Republish flat value** — `{ "value": {…} }` sets the same value on every env.
+        - **Publish one env** — `{ "prod": {…} }` publishes a new version to prod only, instantly.
         - **Schema migration** — `{ "schema": {…} }` replaces the schema; existing values are re-validated.
-        - **Env-scoped edits** — use `PUT /{id}/drafts` + `POST /{id}/publish` instead of PATCH.
       tags:
         - Configs
       parameters:
@@ -2250,6 +2252,15 @@ paths:
                     tiers:
                       - name: free
                       - name: pro
+              prodOnly:
+                summary: Per-env — publish prod only
+                description: Publishes a new version to prod only, immediately. dev/staging untouched.
+                value:
+                  prod:
+                    tiers:
+                      - name: free
+                      - name: pro
+                      - name: enterprise
               schemaOnly:
                 summary: Schema-only update
                 description: Replaces the schema. Existing values must still validate or the update fails.
@@ -2410,6 +2421,7 @@ paths:
         - VALIDATION
       x-cli:
         name: draft
+        hidden: true
         positional:
           - id
     delete:
@@ -2469,6 +2481,7 @@ paths:
         - NOT_FOUND
       x-cli:
         name: discard-draft
+        hidden: true
         positional:
           - id
   /api/admin/configs/{id}/publish:
@@ -2540,6 +2553,7 @@ paths:
         - VALIDATION
       x-cli:
         name: publish
+        hidden: true
         positional:
           - id
   /api/admin/configs/{id}/activity:
@@ -2604,6 +2618,7 @@ paths:
         - NOT_FOUND
       x-cli:
         name: activity
+        hidden: true
         positional:
           - id
   /api/admin/configs/{id}/schema:
@@ -2739,6 +2754,7 @@ paths:
         - NOT_FOUND
       x-cli:
         name: versions
+        hidden: true
         positional:
           - id
   /api/admin/killswitches:
@@ -5531,7 +5547,7 @@ paths:
         **Use case:** Read what a previous agent run already found before starting
         your own investigation of the item.
       tags:
-        - Ops
+        - Investigations
       parameters:
         - $ref: '#/components/parameters/ProjectId'
         - name: handle
@@ -5562,6 +5578,10 @@ paths:
         - UNAUTHORIZED
         - FORBIDDEN
         - NOT_FOUND
+      x-cli:
+        name: list
+        positional:
+          - handle
     post:
       operationId: createOpsInvestigation
       summary: Record an investigation
@@ -5577,7 +5597,7 @@ paths:
         markdown findings, sources inspected, confidence) so the team — and the
         next agent run — sees what you learned.
       tags:
-        - Ops
+        - Investigations
       parameters:
         - $ref: '#/components/parameters/ProjectId'
         - name: handle
@@ -5635,6 +5655,85 @@ paths:
         - FORBIDDEN
         - NOT_FOUND
         - VALIDATION
+      x-cli:
+        name: create
+        positional:
+          - handle
+  /api/admin/ops/{handle}/investigation/{investigationId}:
+    patch:
+      operationId: updateOpsInvestigation
+      summary: Update an investigation record
+      description: |-
+        Update one existing investigation record in place — the write-back seam for
+        the `working` run record you were handed when a run was launched. Fill in
+        the `summary`/`findings`, attach the fixing PR, record your `confidence`
+        and the `sources` you inspected, or flip its `kind` off `working` once the
+        investigation is done. A partial patch: send only the fields you want to
+        change. Safe for restricted ops keys (it never reads or deletes).
+
+        **Use case:** A run started with an empty `working` record; as you work,
+        PATCH it with your findings so the cockpit's detail panel fills in live —
+        no need to append a second record.
+      tags:
+        - Investigations
+      parameters:
+        - $ref: '#/components/parameters/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/ResourceId'
+        - name: investigationId
+          in: path
+          required: true
+          description: The investigation record id (from `POST`/`GET .../investigation` or the `runId` an ack/launch returned).
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateOpsInvestigationRequest'
+            examples:
+              findings:
+                summary: Fill in the run record's findings
+                value:
+                  kind: investigated
+                  summary: Root cause is a stale KV read on the checkout flag.
+                  findings: The `checkout.cta` gate is rebuilt without a CDN purge, so…
+                  confidence: high
+                  prNumber: 4821
+                  prUrl: https://github.com/acme/web/pull/4821
+      responses:
+        '200':
+          description: The updated investigation record
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OpsInvestigation'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      x-error-codes:
+        - BAD_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+        - NOT_FOUND
+        - VALIDATION
+      x-cli:
+        name: update
+        positional:
+          - handle
+          - investigationId
   /api/admin/agent-profiles:
     get:
       operationId: listOpsAgents
@@ -9217,6 +9316,9 @@ components:
                       locked:
                         description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                         type: boolean
+                      whitelist:
+                        description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
+                        type: boolean
                     required:
                       - id
                       - type
@@ -9618,6 +9720,9 @@ components:
                       locked:
                         description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                         type: boolean
+                      whitelist:
+                        description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
+                        type: boolean
                     required:
                       - id
                       - type
@@ -9917,6 +10022,9 @@ components:
                       locked:
                         description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                         type: boolean
+                      whitelist:
+                        description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
+                        type: boolean
                     required:
                       - id
                       - type
@@ -11405,12 +11513,26 @@ components:
           additionalProperties: {}
           description: JSON Schema (draft 2020-12) describing the shape of the config value. Top-level `type` must be `'object'`; every published value is validated against this schema.
         value:
+          type: object
+          additionalProperties: {}
           description: 'Initial config value. Either a single JSON object applied to every env, or a `{ env: value }` map seeding per-env values. Must match `schema`. Defaults to `{}` on every env when omitted.'
+        dev:
+          type: object
+          additionalProperties: {}
+          description: Seed the **dev** env's initial value (version 1), overriding `value` for dev. Published immediately. Must match `schema`.
+        staging:
+          type: object
+          additionalProperties: {}
+          description: Seed the **staging** env's initial value (version 1), overriding `value` for staging. Published immediately. Must match `schema`.
+        prod:
+          type: object
+          additionalProperties: {}
+          description: Seed the **prod** env's initial value (version 1), overriding `value` for prod. Published immediately. Must match `schema`.
       required:
         - name
         - schema
       additionalProperties: false
-      description: Body for `POST /api/admin/configs`. `name` + `schema` required.
+      description: Body for `POST /api/admin/configs`. `name` + `schema` required. Per-env `dev`/`staging`/`prod` values are published to that env at version 1 (overriding `value`).
     CreateConfigResponse:
       type: object
       properties:
@@ -11540,11 +11662,25 @@ components:
           type: object
           additionalProperties: {}
         value:
-          description: Flat value applied to **every** env. Publishes a new version per env. To target one env, use `PUT /{id}/drafts` then `POST /{id}/publish`.
+          type: object
+          additionalProperties: {}
+          description: Flat value applied to **every** env. Publishes a new version per env. To publish one env only, pass that env's key (`dev`/`staging`/`prod`) instead.
+        dev:
+          type: object
+          additionalProperties: {}
+          description: Publish a new version to the **dev** env only, immediately (no draft). Overrides `value` for dev. Must match the effective schema.
+        staging:
+          type: object
+          additionalProperties: {}
+          description: Publish a new version to the **staging** env only, immediately (no draft). Overrides `value` for staging. Must match the effective schema.
+        prod:
+          type: object
+          additionalProperties: {}
+          description: Publish a new version to the **prod** env only, immediately (no draft). Overrides `value` for prod. Must match the effective schema.
         folder:
           $ref: '#/components/schemas/Folder'
       additionalProperties: false
-      description: Body for `PATCH /api/admin/configs/{id}`. Partial — only supplied fields change. `value` republishes on every env.
+      description: Body for `PATCH /api/admin/configs/{id}`. Partial — only supplied fields change. `value` republishes on every env; per-env `dev`/`staging`/`prod` publish a new version to just that env.
     UpdateConfigResponse:
       type: object
       properties:
@@ -11567,6 +11703,8 @@ components:
         env:
           $ref: '#/components/schemas/Env'
         value:
+          type: object
+          additionalProperties: {}
           description: Draft value to stage on `env`. Validated against the config's current schema.
       required:
         - env
@@ -13123,6 +13261,11 @@ components:
         - lower_better
         - neutral
       description: Desired direction of movement. `higher_better` (default), `lower_better`, or `neutral` (guardrail).
+    MetricDisplayUnit:
+      description: Display unit (e.g. `ms`, `%`, `$`), or `null` when unitless.
+      anyOf:
+        - type: string
+        - type: 'null'
     CreateMetricWithQuery:
       type: object
       properties:
@@ -13140,6 +13283,8 @@ components:
           $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
+        unit:
+          $ref: '#/components/schemas/MetricDisplayUnit'
       required:
         - name
         - event_name
@@ -13163,6 +13308,8 @@ components:
           $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
+        unit:
+          $ref: '#/components/schemas/MetricDisplayUnit'
       required:
         - name
         - event_name
@@ -13300,6 +13447,8 @@ components:
           $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
+        unit:
+          $ref: '#/components/schemas/MetricDisplayUnit'
       required:
         - query
       additionalProperties: false
@@ -13319,6 +13468,8 @@ components:
           $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
+        unit:
+          $ref: '#/components/schemas/MetricDisplayUnit'
       required:
         - query_ir
       additionalProperties: false
@@ -13336,8 +13487,10 @@ components:
           $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
+        unit:
+          $ref: '#/components/schemas/MetricDisplayUnit'
       additionalProperties: false
-      description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction).
+      description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction, display unit).
     UpdateMetricRequest:
       oneOf:
         - $ref: '#/components/schemas/UpdateMetricWithQuery'
@@ -14329,6 +14482,19 @@ components:
         - agent
       additionalProperties: false
       description: 'The fully-resolved owner of a queue item — a person and/or an AI agent. The two halves are independent: an item may have a person, an agent, both, or neither (both `null`).'
+    OpsRunAction:
+      type: string
+      enum:
+        - link_pr
+        - notify
+        - status
+        - superseded
+      description: The final action that closed a run record — `link_pr`/`notify` are the agent's terminal ops actions, `status` a completion status flip (ready_for_qa/resolved), `superseded` a newer ack replacing an open run.
+    OpsRunActionOrNull:
+      anyOf:
+        - $ref: '#/components/schemas/OpsRunAction'
+        - type: 'null'
+      description: Which final action closed the run, or `null` while it is open (or a non-run record).
     OpsRun:
       type: object
       properties:
@@ -14355,6 +14521,11 @@ components:
             - type: string
             - type: 'null'
           description: The agent-run session id recorded on the ack (dashboard deep-links to the run page), or `null`.
+        sessionUrl:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: 'The run''s session-page deep link, or `null`. DERIVED (never stored): rebuilt from `sessionId` + the run''s trigger connector — Claude''s routine id (`?trigger=`), Copilot''s repo (`/tasks/`), Cursor/Jules from the id alone.'
         startedAt:
           type: string
           description: ISO-8601 timestamp the run started (the ack time).
@@ -14364,15 +14535,7 @@ components:
             - type: 'null'
           description: ISO-8601 timestamp the run closed, or `null` while still open.
         completedAction:
-          anyOf:
-            - type: string
-              enum:
-                - link_pr
-                - notify
-                - status
-                - superseded
-            - type: 'null'
-          description: Which final action closed the run — `link_pr`/`notify` are the agent's terminal ops actions, `status` a completion status flip (ready_for_qa/resolved), `superseded` a newer ack replacing it. `null` while the run is open.
+          $ref: '#/components/schemas/OpsRunActionOrNull'
         prNumber:
           anyOf:
             - type: number
@@ -14389,6 +14552,7 @@ components:
         - connectorId
         - ackedBy
         - sessionId
+        - sessionUrl
         - startedAt
         - completedAt
         - completedAction
@@ -14562,6 +14726,28 @@ components:
             - $ref: '#/components/schemas/OpsItemPriority'
             - type: 'null'
           description: Initial triage priority, or `null`.
+        status:
+          anyOf:
+            - $ref: '#/components/schemas/OpsItemStatus'
+          description: Initial lifecycle status; defaults to `open` when omitted.
+        assigneeId:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: The `users.id` of the person to assign as owner at creation, or `null`.
+        subscribers:
+          type: array
+          items:
+            type: string
+            format: email
+          default: []
+          description: Emails of teammates to subscribe to this item's Slack pings at creation.
+        tags:
+          type: array
+          items:
+            type: string
+          default: []
+          description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
         reporterEmail:
           anyOf:
             - type: string
@@ -14631,6 +14817,28 @@ components:
             - $ref: '#/components/schemas/OpsItemPriority'
             - type: 'null'
           description: Initial triage priority, or `null`.
+        status:
+          anyOf:
+            - $ref: '#/components/schemas/OpsItemStatus'
+          description: Initial lifecycle status; defaults to `open` when omitted.
+        assigneeId:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: The `users.id` of the person to assign as owner at creation, or `null`.
+        subscribers:
+          type: array
+          items:
+            type: string
+            format: email
+          default: []
+          description: Emails of teammates to subscribe to this item's Slack pings at creation.
+        tags:
+          type: array
+          items:
+            type: string
+          default: []
+          description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
         reporterEmail:
           anyOf:
             - type: string
@@ -15210,21 +15418,18 @@ components:
             - type: string
             - type: 'null'
           description: The agent-run session id, or `null`.
-        ackedBy:
+        sessionUrl:
           anyOf:
             - type: string
             - type: 'null'
-          description: Email of the human who acked (run records for a human ack), or `null`.
-        completedAction:
+          description: 'The run''s session-page deep link, or `null`. DERIVED (never stored): rebuilt from `sessionId` + the run''s trigger connector — Claude''s routine id (`?trigger=`), Copilot''s repo (`/tasks/`), Cursor/Jules from the id alone. Only `working` run records carry one.'
+        ackedBy:
           anyOf:
             - type: string
-              enum:
-                - link_pr
-                - notify
-                - status
-                - superseded
             - type: 'null'
-          description: Which final action closed a `working` run record, or `null` (open run / non-run record).
+          description: Email of the human who acked (run records for a human ack), or `null`.
+        completedAction:
+          $ref: '#/components/schemas/OpsRunActionOrNull'
         createdAt:
           type: string
           description: ISO-8601 creation timestamp.
@@ -15252,6 +15457,7 @@ components:
         - startedAt
         - completedAt
         - sessionId
+        - sessionUrl
         - ackedBy
         - completedAction
         - createdAt
@@ -15368,6 +15574,94 @@ components:
         - kind
       additionalProperties: false
       description: Body for `POST /api/admin/ops/{handle}/investigation`. `kind` is required; include at least one content field (`summary`/`findings`/`question`/`qaNotes`) — the panel renders whatever it gets.
+    UpdateOpsInvestigationRequest:
+      type: object
+      properties:
+        kind:
+          type: string
+          enum:
+            - investigated
+            - detected
+            - question
+            - ready_for_qa
+            - working
+            - note
+          description: Reclassify the record's lifecycle stage (e.g. flip a `working` run into `investigated` once findings land).
+        summary:
+          type: string
+          maxLength: 2000
+          description: One-line summary of the record.
+        findings:
+          type: string
+          maxLength: 50000
+          description: The full findings write-up (markdown).
+        question:
+          type: string
+          maxLength: 10000
+          description: A blocking question for the team (markdown).
+        qaNotes:
+          type: string
+          maxLength: 50000
+          description: How to verify the fix — QA notes (markdown).
+        model:
+          type: string
+          maxLength: 200
+          description: The model the agent ran on.
+        prNumber:
+          type: integer
+          description: A PR the record references.
+        prUrl:
+          type: string
+          format: uri
+          maxLength: 2000
+          description: HTML URL of that PR.
+        sources:
+          type: array
+          maxItems: 200
+          items:
+            type: object
+            properties:
+              path:
+                type: string
+                description: Repo-relative file path inspected.
+              url:
+                type: string
+                description: External link consulted.
+              label:
+                type: string
+                description: Human-readable label for the source.
+            additionalProperties: false
+            description: One file/link inspected while producing the record.
+          description: The files/links inspected.
+        confidence:
+          type: string
+          enum:
+            - low
+            - medium
+            - high
+          description: Self-reported confidence in the record.
+        tokensUsed:
+          type: integer
+          description: Tokens the run consumed.
+        durationMs:
+          type: integer
+          description: Run duration in milliseconds.
+        visibility:
+          type: string
+          enum:
+            - draft
+            - published
+          description: Record visibility. `draft` keeps it out of the panel; `published` surfaces it.
+        completedAt:
+          type: string
+          description: ISO-8601 timestamp the work finished. Set it (or flip `kind` off `working`) to mark a run record done.
+        sessionId:
+          type: string
+          maxLength: 300
+          description: The agent-run session id, so the dashboard can deep-link to the run.
+      additionalProperties: false
+      minProperties: 1
+      description: Body for `PATCH /api/admin/ops/{handle}/investigation/{investigationId}` — a partial update of one existing investigation record (typically the `working` run record you were handed). Send only the fields you want to change; at least one is required.
     OpsAgentProfile:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/openapi",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Shipeasy admin OpenAPI 3.2 spec (hand-authored, single source of truth) + the generated TypeScript client, Zod schemas, and types. Consumed by @shipeasy/cli and @shipeasy/mcp.",
   "type": "module",
   "main": "./dist/index.js",