@thinkai/tai-api-contract 2.143.0 → 2.144.1

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.143.0
+  version: 2.144.1
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -7767,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]
@@ -8102,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:
@@ -8121,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:
@@ -8189,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:
@@ -8196,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:
@@ -8271,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:
@@ -8278,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:
@@ -10712,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
@@ -11919,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"
@@ -11946,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:
@@ -12026,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.
@@ -20887,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
@@ -20909,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 }
@@ -20925,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 }
 
@@ -20939,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
@@ -20946,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 }
 
@@ -21011,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.143.0",
+  "version": "2.144.1",
   "private": false,
   "type": "module",
   "main": "dist/index.js",