@thinkai/tai-api-contract 2.142.0 → 2.144.1

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.142.0
+  version: 2.144.1
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -2600,6 +2600,7 @@ paths:
         - $ref: "#/components/parameters/InsightsProductivityFrom"
         - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - $ref: "#/components/parameters/InsightsAiUsageProvider"
         - name: team
           in: query
           description: Team name filter; send `All teams` to include every team.
@@ -2651,6 +2652,7 @@ paths:
         - $ref: "#/components/parameters/InsightsProductivityFrom"
         - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - $ref: "#/components/parameters/InsightsAiUsageProvider"
         - name: team
           in: query
           description: Team name filter; send `All teams` to include every team.
@@ -2701,6 +2703,7 @@ paths:
         - $ref: "#/components/parameters/InsightsProductivityFrom"
         - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - $ref: "#/components/parameters/InsightsAiUsageProvider"
         - name: team
           in: query
           description: Team name filter; send `All teams` to include every team.
@@ -2751,6 +2754,7 @@ paths:
         - $ref: "#/components/parameters/InsightsProductivityFrom"
         - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - $ref: "#/components/parameters/InsightsAiUsageProvider"
         - name: team
           in: query
           description: Team name filter; send `All teams` to include every team.
@@ -2804,6 +2808,7 @@ paths:
         - $ref: "#/components/parameters/InsightsProductivityFrom"
         - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - $ref: "#/components/parameters/InsightsAiUsageProvider"
         - name: team
           in: query
           description: Team name filter; send `All teams` to include every team.
@@ -2938,6 +2943,7 @@ paths:
         - $ref: "#/components/parameters/InsightsProductivityFrom"
         - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - $ref: "#/components/parameters/InsightsAiUsageProvider"
         - name: team
           in: query
           description: Team name filter; send `All teams` to include every team.
@@ -2989,6 +2995,7 @@ paths:
         - $ref: "#/components/parameters/InsightsProductivityFrom"
         - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - $ref: "#/components/parameters/InsightsAiUsageProvider"
         - name: team
           in: query
           description: Team name filter; send `All teams` to include every team.
@@ -3040,6 +3047,7 @@ paths:
         - $ref: "#/components/parameters/InsightsProductivityFrom"
         - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - $ref: "#/components/parameters/InsightsAiUsageProvider"
         - name: team
           in: query
           description: Team name filter; send `All teams` to include every team.
@@ -6375,6 +6383,53 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/report-center/exports:
+    post:
+      tags: [WorkspaceActivity]
+      summary: Record a Report Center PDF export
+      operationId: recordReportCenterExport
+      description: >
+        Workspace admin (or platform admin) records that a Report Center PDF was downloaded.
+        Inserts one `report.exported` activity-log row with the request body as secret-free metadata.
+        Does not store PDF bytes. Members who are not workspace admins receive 403.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ReportCenterExportRecordBodyDto"
+      responses:
+        "201":
+          description: Export recorded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReportCenterExportRecordResponseDto"
+        "400":
+          description: Invalid body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "501":
+          description: Activity log is not supported by this backend build
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/activity:
     get:
       tags: [WorkspaceActivity]
@@ -6405,7 +6460,7 @@ paths:
           required: false
           description: >
             Coarse product-area grouping filter (#156). `integration` = GitHub + AI-tool key events;
-            `agentic_foundation` = repos, readiness scans, fixes; `workspace_team` = members + HRIS;
+            `agentic_foundation` = repos, readiness scans, fixes; `workspace_team` = members + HRIS + report exports;
             `productivity` = productivity ingest lifecycle events. Omit (or pass `all`) for every area.
           schema:
             type: string
@@ -7712,6 +7767,107 @@ paths:
         "403":
           $ref: "#/components/responses/Forbidden"
 
+  /workspaces/{workspaceId}/code-intelligence/agent-md:
+    get:
+      tags: [CodeChat]
+      summary: Read the workspace agent.md
+      description: >
+        Any workspace member. Returns the persisted workspace agent file, or null fields when
+        none has been written. 403 `code_intelligence_disabled` when Engineering Context Graph is off.
+      operationId: getCodeIntelligenceAgentMd
+      x-test-coverage-skip: thin read of persisted config; covered by readiness and maintain unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Persisted agent.md
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeIntelligenceAgentMdDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Engineering Context Graph is off, or the caller is not a member
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    put:
+      tags: [CodeChat]
+      summary: Save an admin edit of the workspace agent.md
+      description: >
+        Admin only. Body is 1 to 12,000 characters. Saves source `admin`. Auto-generate and the
+        cadence tick do not overwrite this text until an admin regenerates it. A non-admin receives 403.
+      operationId: putCodeIntelligenceAgentMd
+      x-test-coverage-skip: admin write of persisted config; covered by store and maintain unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PutCodeIntelligenceAgentMdDto"
+      responses:
+        "200":
+          description: Saved agent.md
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeIntelligenceAgentMdDto"
+        "400":
+          description: Body missing or outside 1 to 12,000 characters
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller is not an admin, or Engineering Context Graph is off
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/code-intelligence/agent-md/regenerate:
+    post:
+      tags: [CodeChat]
+      summary: Rewrite workspace agent.md from ready code graphs
+      description: >
+        Admin only. Rewrites the file from current ready eligible graphs and sets source
+        `generated`. Returns 409 `agent_md_not_ready` when no eligible repository index is ready.
+        Does not call an LLM and does not clone repositories.
+      operationId: regenerateCodeIntelligenceAgentMd
+      x-test-coverage-skip: wraps regenerateWorkspaceAgentMd; covered by wave maintain unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Regenerated agent.md
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeIntelligenceAgentMdDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller is not an admin, or Engineering Context Graph is off
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: No ready eligible index
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: No ready repository index is available to write the workspace agent file.
+                code: agent_md_not_ready
+
   /workspaces/{workspaceId}/code-intelligence/token-usage/summary:
     get:
       tags: [CodeChat]
@@ -8047,6 +8203,10 @@ paths:
     post:
       tags: [CodeChat]
       summary: Enqueue indexing for all (or selected) readiness GitHub repos
+      description: >
+        `indexOnly: true` enqueues a graph-only job. `{ "indexOnly": true, "force": true }` with
+        no `repoIds` is admin-only and opens one index wave for every eligible GitHub repository.
+        A single-repo indexOnly sync does not open a wave. Members who send that admin body receive 403.
       operationId: syncCodeChatIndexes
       x-test-coverage-skip: lightweight MVP; covered by package unit tests
       parameters:
@@ -8066,6 +8226,47 @@ paths:
                 $ref: "#/components/schemas/CodeChatSyncIndexesResultDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: >
+            Engineering Context Graph is off, or a member sent the admin force body
+            (`indexOnly` and `force` with no `repoIds`).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/code-chat/readiness:
+    get:
+      tags: [CodeChat]
+      summary: Workspace chat readiness
+      description: >
+        Any workspace member. 403 `code_intelligence_disabled` when Engineering Context Graph is off.
+        `status` is `indexing`, `generating_agent_md`, `failed`, or `ready`. Chat stays closed
+        until `ready`: create thread and post message return `409 chat_not_ready` with
+        `progressMessage` when status is not ready. An open index wave reports `indexing` until
+        every job in that wave is terminal.
+      operationId: getCodeChatReadiness
+      x-test-coverage-skip: thin HTTP over deriveCodeChatReadiness; covered by code-chat-readiness unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Readiness snapshot
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatReadinessDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Engineering Context Graph is off
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Code Intelligence is disabled for this workspace
+                code: code_intelligence_disabled
 
   /workspaces/{workspaceId}/code-chat/indexes/{indexId}:
     get:
@@ -8134,6 +8335,12 @@ paths:
                 $ref: "#/components/schemas/CodeChatThreadDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Engineering Context Graph is off
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "404":
           description: Not found
           content:
@@ -8141,7 +8348,23 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
         "409":
-          description: Index not ready
+          description: Chat not ready, or no ready corpus for a repo-scoped thread
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              examples:
+                chat_not_ready:
+                  value:
+                    error: Indexing repositories (0/2).
+                    code: chat_not_ready
+                    progressMessage: Indexing repositories (0/2).
+        "422":
+          description: Execution key required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
   /workspaces/{workspaceId}/code-chat/threads/{threadId}:
     get:
@@ -8216,6 +8439,12 @@ paths:
                 $ref: "#/components/schemas/CodeChatMessageReplyDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Engineering Context Graph is off
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "404":
           description: Not found
           content:
@@ -8223,7 +8452,17 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
         "409":
-          description: Index not ready
+          description: Chat not ready, or no ready corpus in thread scope
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "422":
+          description: Execution key required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
   /workspaces/{workspaceId}/code-chat/indexes/{indexId}/wiki:
     get:
@@ -10426,6 +10665,19 @@ components:
           type: string
       style: form
       explode: true
+    InsightsAiUsageProvider:
+      name: provider
+      in: query
+      description: >
+        AI provider ids to include. Repeat the parameter or send comma-separated values.
+        Empty or omitted includes all supported providers.
+      schema:
+        type: array
+        items:
+          type: string
+          enum: [cursor, claude]
+      style: form
+      explode: true
     InsightsRecommendationsIncludeUnmapped:
       name: includeUnmapped
       in: query
@@ -10644,6 +10896,11 @@ components:
         code:
           type: string
           description: Machine-readable error code when present (for example `last_admin`).
+        progressMessage:
+          type: string
+          description: >
+            Human-readable progress when `code` is `chat_not_ready` (same text as `error`
+            for that response).
 
     TeamMemberDto:
       type: object
@@ -11851,6 +12108,17 @@ components:
           type: string
           nullable: true
           minLength: 1
+        indexingEnabled:
+          type: boolean
+          description: >
+            When false, turning Engineering Context Graph on and the cadence tick do not enqueue
+            index jobs. Stored graphs, wiki pages, and agent.md stay. Defaults to true.
+        indexingCadence:
+          type: string
+          enum: [daily, weekly, manual]
+          description: >
+            How often the code-knowledge worker enqueues an index-only wave for eligible GitHub
+            repositories. `manual` never ticks. Defaults to `daily`.
         wikiGuidance:
           allOf:
             - $ref: "#/components/schemas/CodeWikiGuidanceDto"
@@ -11878,6 +12146,71 @@ components:
           maxLength: 120
           description: Title of the parent topic for hierarchy (must match another topic title).
 
+    PutCodeIntelligenceAgentMdDto:
+      type: object
+      required: [body]
+      properties:
+        body:
+          type: string
+          minLength: 1
+          maxLength: 12000
+
+    CodeIntelligenceAgentMdDto:
+      type: object
+      required: [body, source, updatedAt]
+      properties:
+        body:
+          type: string
+          nullable: true
+        source:
+          type: string
+          nullable: true
+          enum: [generated, admin]
+        updatedAt:
+          type: string
+          format: date-time
+          nullable: true
+
+    CodeChatReadinessDto:
+      type: object
+      required:
+        - status
+        - progressMessage
+        - eligibleCount
+        - readyCount
+        - failedCount
+        - inProgressCount
+        - indexingEnabled
+        - indexingCadence
+        - agentMdSource
+      properties:
+        status:
+          type: string
+          enum: [indexing, generating_agent_md, failed, ready]
+        progressMessage:
+          type: string
+        eligibleCount:
+          type: integer
+          minimum: 0
+        readyCount:
+          type: integer
+          minimum: 0
+        failedCount:
+          type: integer
+          minimum: 0
+        inProgressCount:
+          type: integer
+          minimum: 0
+        indexingEnabled:
+          type: boolean
+        indexingCadence:
+          type: string
+          enum: [daily, weekly, manual]
+        agentMdSource:
+          type: string
+          nullable: true
+          enum: [generated, admin]
+
     CodeWikiGuidanceDto:
       type: object
       properties:
@@ -11958,6 +12291,15 @@ components:
           type: string
           nullable: true
           description: Optional Claude model override for Code Intelligence (null/empty → env default).
+        codeIntelligenceIndexingEnabled:
+          type: boolean
+          description: >
+            When false, enable-enqueue and the cadence tick do not start an index wave.
+            Defaults to true.
+        codeIntelligenceIndexingCadence:
+          type: string
+          enum: [daily, weekly, manual]
+          description: Index wave cadence. `manual` does not tick. Defaults to `daily`.
         hasCodeIntelligenceExecutionToken:
           type: boolean
           description: True when a dedicated `code_intelligence` source has a stored executionToken.
@@ -18967,6 +19309,94 @@ components:
         - integrations.grafana.sync_failed
         - integrations.zelt.added
         - integrations.zelt.removed
+        - report.exported
+
+    ReportCenterExportRecordBodyDto:
+      type: object
+      description: >
+        Metadata for a successful Report Center PDF download. Secret-free; no table payloads.
+        Recorded as `report.exported` on the workspace activity log.
+      required:
+        - rangeId
+        - department
+        - team
+        - sectionIds
+        - preset
+        - customized
+        - timezone
+        - filename
+      properties:
+        rangeId:
+          type: string
+          minLength: 1
+          maxLength: 128
+          description: Applied insights range id (e.g. `30d`, `cr:2026-01-01:2026-01-31`).
+        department:
+          type: string
+          minLength: 1
+          maxLength: 256
+        team:
+          type: string
+          minLength: 1
+          maxLength: 256
+        selectedProductivityTeamIds:
+          type: array
+          maxItems: 256
+          items:
+            type: string
+            minLength: 1
+            maxLength: 128
+        sectionIds:
+          type: array
+          minItems: 1
+          maxItems: 64
+          items:
+            type: string
+            minLength: 1
+            maxLength: 128
+        preset:
+          type: string
+          minLength: 1
+          maxLength: 64
+          description: >
+            Preset id used as the starting point (e.g. `leadership`, `productivity`, `full`, `custom`).
+        customized:
+          type: boolean
+          description: True when the admin changed section checks after picking a preset.
+        timezone:
+          type: string
+          minLength: 1
+          maxLength: 128
+          description: IANA timezone printed on the PDF cover.
+        filename:
+          type: string
+          minLength: 1
+          maxLength: 256
+        providerIds:
+          type: array
+          maxItems: 32
+          items:
+            type: string
+            minLength: 1
+            maxLength: 64
+        repoIds:
+          type: array
+          maxItems: 512
+          items:
+            type: string
+            minLength: 1
+            maxLength: 256
+
+    ReportCenterExportRecordResponseDto:
+      type: object
+      required: [ok, activityEntryId]
+      properties:
+        ok:
+          type: boolean
+          enum: [true]
+        activityEntryId:
+          type: string
+          format: uuid
 
     ActivityLogActorDto:
       type: object
@@ -20731,6 +21161,7 @@ components:
             Omit or false to keep the full pipeline, including wiki. Distinct from
             skipLlm, which still writes a skeleton wiki. A job that is already
             queued or running keeps the options it was enqueued with.
+            Together with `force: true` and no `repoIds`, this opens an admin index wave.
 
     CodeChatSyncIndexesResultDto:
       type: object
@@ -20753,12 +21184,15 @@ components:
         repoName: { type: string }
         code:
           type: string
-          enum: [repo_ineligible, indexed_recently, index_in_progress]
-          description: Stable machine-readable skip reason
+          enum: [repo_ineligible, indexed_recently, index_in_progress, ecg_source_off]
+          description: >
+            Stable machine-readable skip reason. `ecg_source_off` covers a source turned off
+            for Engineering Context Graph and non-GitHub providers that stay listed but are
+            never indexed.
 
     CodeChatThreadDto:
       type: object
-      required: [id, workspaceId, repoIds, title, createdAt, updatedAt]
+      required: [id, workspaceId, repoIds, title, scope, createdAt, updatedAt]
       properties:
         id: { type: string, format: uuid }
         workspaceId: { type: string, format: uuid }
@@ -20769,6 +21203,12 @@ components:
           description: Empty means all ready repos in the workspace.
         revisionRef: { type: string, nullable: true }
         title: { type: string }
+        scope:
+          type: string
+          enum: [workspace, repo]
+          description: >
+            `workspace` when `repoIds` is empty or has more than one id (Conversations).
+            `repo` when exactly one repository is bound (System / Wiki).
         createdAt: { type: string, format: date-time }
         updatedAt: { type: string, format: date-time }
 
@@ -20783,6 +21223,12 @@ components:
     CodeChatCreateThreadBodyDto:
       type: object
       properties:
+        scope:
+          type: string
+          enum: [workspace]
+          description: >
+            Create a workspace conversation with empty `repoIds`. Does not reuse an older
+            thread. Requires chat readiness and an execution key.
         indexId:
           type: string
           format: uuid
@@ -20790,7 +21236,7 @@ components:
         repoIds:
           type: array
           items: { type: string, format: uuid }
-          description: Empty or omitted = all ready repos.
+          description: Empty or omitted = all ready repos. Ignored when scope is workspace.
         revisionRef: { type: string }
         title: { type: string }
 
@@ -20855,10 +21301,11 @@ components:
           properties:
             mode:
               type: string
-              enum: [llm, retrieval, inventory]
+              enum: [llm, retrieval, inventory, failed]
               description: >
                 How the assistant answer was produced. `inventory` returns a deterministic
-                catalog (APIs or modules) rather than LLM synthesis.
+                catalog (APIs or modules) rather than LLM synthesis. `failed` is a short
+                assistant message after provider timeout or error (no retrieval substitute).
             structured:
               description: Optional typed inventory payload for rich UI tables
               allOf:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.142.0",
+  "version": "2.144.1",
   "private": false,
   "type": "module",
   "main": "dist/index.js",