@thinkai/tai-api-contract 2.116.0 → 2.119.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.116.0
+  version: 2.119.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -7878,6 +7878,23 @@ paths:
         "409":
           description: No ready repository index in scope
 
+  /workspaces/{workspaceId}/knowledge-pages/generate/status:
+    get:
+      tags: [CodeChat]
+      summary: Get live workspace context generation progress
+      operationId: getWorkspaceContextGenerationStatus
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Current or most recent workspace context generation phase
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceContextGenerationStatusDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
   /workspaces/{workspaceId}/knowledge-pages/prd/generate:
     post:
       tags: [CodeChat]
@@ -7911,6 +7928,73 @@ paths:
         "409":
           description: No ready repository index in scope
 
+  /workspaces/{workspaceId}/knowledge-graph:
+    get:
+      tags: [CodeChat]
+      summary: Get the persisted workspace knowledge graph
+      description: >-
+        Cross-repository graph (repo nodes and dependency edges) built when workspace
+        knowledge pages are generated. Empty until the first successful generate.
+      operationId: getWorkspaceKnowledgeGraph
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Workspace knowledge graph
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceKnowledgeGraphDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Graph not generated yet
+
+  /workspaces/{workspaceId}/knowledge-pages/export:
+    get:
+      tags: [CodeChat]
+      summary: Export workspace knowledge for local use
+      description: >-
+        Download workspace context as `WORKSPACE.md` (markdown) or a structured
+        `wkg-pack` JSON bundle. Markdown rewrites `ecg://` deep links per `linkMode`.
+      operationId: exportWorkspaceKnowledgePages
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: format
+          in: query
+          required: false
+          schema:
+            type: string
+            enum: [markdown, wkg-pack, zip]
+            default: markdown
+        - name: linkMode
+          in: query
+          required: false
+          description: How to rewrite ecg:// links in markdown export
+          schema:
+            type: string
+            enum: [github, platform, relative]
+            default: github
+      responses:
+        "200":
+          description: Export payload (markdown body or wkg-pack JSON)
+          content:
+            text/markdown:
+              schema:
+                type: string
+                description: WORKSPACE.md body when format=markdown
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceKnowledgePackDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Code Intelligence is disabled for this workspace
+        "404":
+          description: No workspace knowledge pages to export
+        "501":
+          description: ZIP export not implemented (use markdown or wkg-pack)
+
   /workspaces/{workspaceId}/code-intelligence/repo-wiki-json:
     get:
       tags: [CodeChat]
@@ -9325,6 +9409,30 @@ paths:
         "503":
           $ref: "#/components/responses/ZenHrSyncInProgress"
 
+  /workspaces/{workspaceId}/ingest-coverage:
+    get:
+      tags: [Workspace]
+      summary: Ingest / backfill data coverage
+      operationId: getWorkspaceIngestCoverage
+      description: >
+        Read-only snapshot of historical ingest coverage for connected pipelines
+        (productivity GitHub, AI usage/spend per provider, SDLC components, monitoring, HRIS).
+        Aggregates existing watermarks and stored day/week evidence — does not trigger ingest or refresh.
+        Requires workspace membership. Disconnected sources are omitted.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Ingest coverage for connected pipelines
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/IngestCoverageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
   /workspaces/{workspaceId}/hris/status:
     get:
       tags: [HRIS]
@@ -17661,6 +17769,289 @@ components:
           nullable: true
           description: ISO timestamp of the most recent successful HRIS sync, or null if never synced.
 
+    IngestCoverageGapDto:
+      type: object
+      required: [from, to]
+      additionalProperties: false
+      properties:
+        from:
+          type: string
+          description: Inclusive gap start (ISO date or UTC Monday week start).
+        to:
+          type: string
+          description: Inclusive gap end (ISO date or UTC Monday week start).
+
+    IngestCoverageLastRunDto:
+      type: object
+      additionalProperties: false
+      properties:
+        startedAt:
+          type: string
+          format: date-time
+          nullable: true
+        completedAt:
+          type: string
+          format: date-time
+          nullable: true
+        durationMs:
+          type: integer
+          format: int64
+          nullable: true
+        mode:
+          type: string
+          nullable: true
+          description: Pipeline-specific run mode (e.g. recent, historical, refresh).
+        outcome:
+          type: string
+          enum: [ok, failed, in_progress]
+          nullable: true
+
+    IngestCoverageProductivityRepoDto:
+      type: object
+      required: [slug, queueStatus]
+      additionalProperties: false
+      properties:
+        slug:
+          type: string
+        queueStatus:
+          type: string
+          enum: [pending, complete, failed, skipped]
+        weeksWithData:
+          type: integer
+          minimum: 0
+          nullable: true
+        earliestWeek:
+          type: string
+          nullable: true
+        latestWeek:
+          type: string
+          nullable: true
+        missingWeeks:
+          type: integer
+          minimum: 0
+          nullable: true
+        gaps:
+          type: array
+          items:
+            $ref: "#/components/schemas/IngestCoverageGapDto"
+        lastErrorKind:
+          type: string
+          nullable: true
+
+    IngestCoverageProductivityDetailDto:
+      type: object
+      additionalProperties: false
+      properties:
+        phase:
+          type: string
+          enum: [recent, historical, complete]
+          nullable: true
+        historicalWeekStart:
+          type: string
+          nullable: true
+        pendingRepoCount:
+          type: integer
+          minimum: 0
+        skippedRepoCount:
+          type: integer
+          minimum: 0
+        failedRepoCount:
+          type: integer
+          minimum: 0
+        coveragePercent:
+          type: number
+          nullable: true
+        repos:
+          type: array
+          items:
+            $ref: "#/components/schemas/IngestCoverageProductivityRepoDto"
+
+    IngestCoverageFactFamilyDto:
+      type: object
+      required: [id]
+      additionalProperties: false
+      properties:
+        id:
+          type: string
+          enum: [daily_usage, spend_daily, model_daily, product_daily]
+        expectedDays:
+          type: integer
+          minimum: 0
+        daysPresent:
+          type: integer
+          minimum: 0
+        ingestedFrom:
+          type: string
+          nullable: true
+        ingestedTo:
+          type: string
+          nullable: true
+        missingDayCount:
+          type: integer
+          minimum: 0
+        gaps:
+          type: array
+          items:
+            $ref: "#/components/schemas/IngestCoverageGapDto"
+
+    IngestCoverageAiDetailDto:
+      type: object
+      additionalProperties: false
+      properties:
+        factFamilies:
+          type: array
+          items:
+            $ref: "#/components/schemas/IngestCoverageFactFamilyDto"
+        refreshInProgress:
+          type: boolean
+
+    IngestCoverageSdlcComponentDto:
+      type: object
+      required: [id]
+      additionalProperties: false
+      properties:
+        id:
+          type: string
+          enum:
+            [
+              rollup,
+              security_ingest,
+              governance_github,
+              governance_auditor,
+              financial_ingest,
+              cost_refresher,
+            ]
+        latestBucketDate:
+          type: string
+          nullable: true
+        lookbackDays:
+          type: integer
+          minimum: 0
+        mode:
+          type: string
+          nullable: true
+        gaps:
+          type: array
+          items:
+            $ref: "#/components/schemas/IngestCoverageGapDto"
+        missingCount:
+          type: integer
+          minimum: 0
+          nullable: true
+        lastSuccessAt:
+          type: string
+          format: date-time
+          nullable: true
+        staleForMs:
+          type: integer
+          format: int64
+          nullable: true
+        isStale:
+          type: boolean
+
+    IngestCoverageSdlcDetailDto:
+      type: object
+      additionalProperties: false
+      properties:
+        components:
+          type: array
+          items:
+            $ref: "#/components/schemas/IngestCoverageSdlcComponentDto"
+
+    IngestCoverageSyncDetailDto:
+      type: object
+      additionalProperties: false
+      properties:
+        provider:
+          type: string
+        syncStatus:
+          type: string
+          enum: [ok, error, never]
+
+    IngestCoveragePipelineDto:
+      type: object
+      required: [id, kind, status, targetWindowDays, isStale]
+      additionalProperties: false
+      properties:
+        id:
+          type: string
+        kind:
+          type: string
+          enum: [productivity_github, ai_usage, sdlc_github, monitoring, hris]
+        provider:
+          type: string
+          nullable: true
+        status:
+          type: string
+          enum: [not_started, backfilling, incremental, complete, failed, in_progress]
+        targetWindowDays:
+          type: integer
+          minimum: 0
+        ingestedFrom:
+          type: string
+          nullable: true
+        ingestedTo:
+          type: string
+          nullable: true
+        progressPercent:
+          type: number
+          nullable: true
+        lastSuccessAt:
+          type: string
+          format: date-time
+          nullable: true
+        lastAttemptAt:
+          type: string
+          format: date-time
+          nullable: true
+        lastErrorKind:
+          type: string
+          nullable: true
+        lastErrorMessage:
+          type: string
+          nullable: true
+        staleForMs:
+          type: integer
+          format: int64
+          nullable: true
+        isStale:
+          type: boolean
+        dataLagDays:
+          type: integer
+          minimum: 0
+          nullable: true
+        gaps:
+          type: array
+          items:
+            $ref: "#/components/schemas/IngestCoverageGapDto"
+        missingCount:
+          type: integer
+          minimum: 0
+          nullable: true
+        lastRun:
+          $ref: "#/components/schemas/IngestCoverageLastRunDto"
+        productivity:
+          $ref: "#/components/schemas/IngestCoverageProductivityDetailDto"
+        ai:
+          $ref: "#/components/schemas/IngestCoverageAiDetailDto"
+        sdlc:
+          $ref: "#/components/schemas/IngestCoverageSdlcDetailDto"
+        sync:
+          $ref: "#/components/schemas/IngestCoverageSyncDetailDto"
+
+    IngestCoverageDto:
+      type: object
+      required: [pipelines]
+      additionalProperties: false
+      properties:
+        pipelines:
+          type: array
+          items:
+            $ref: "#/components/schemas/IngestCoveragePipelineDto"
+        generatedAt:
+          type: string
+          format: date-time
+
     HrisSyncStatusDto:
       type: object
       required: [provider, lastSyncAt, status]
@@ -18197,7 +18588,10 @@ components:
         syncedAt:
           type: string
           format: date-time
-          description: ISO timestamp when numbers were computed server-side
+          description: >-
+            ISO timestamp when numbers were computed server-side. An empty string
+            means the workspace has no successful AI-tool refresh or productivity
+            ingest timestamp yet.
         isMock:
           type: boolean
           description: Must be false for production handlers
@@ -19069,6 +19463,11 @@ components:
           type: array
           description: Ready repository indexes to synthesize from. Omit or send empty for all ready indexes.
           items: { type: string, format: uuid }
+        deepResearch:
+          type: boolean
+          description: >-
+            When true and execution keys are configured, run a deeper LLM pass to
+            expand Key decisions with multi-repo citations (falls back to deterministic on failure).
 
     GenerateWorkspaceKnowledgePagesResultDto:
       type: object
@@ -19091,6 +19490,26 @@ components:
         usage:
           $ref: "#/components/schemas/CodeIntelligenceUsageDto"
 
+    WorkspaceContextGenerationStatusDto:
+      type: object
+      required: [phase, status, detail, updatedAt]
+      properties:
+        phase:
+          type: string
+          enum: [inventory, facts, contracts, integrations, clustering, llm, persisted]
+        status:
+          type: string
+          enum: [running, complete, failed]
+        detail: { type: string }
+        updatedAt: { type: string, format: date-time }
+        partial:
+          type: object
+          properties:
+            repoCount: { type: integer }
+            contractCount: { type: integer }
+            groupCount: { type: integer }
+            standaloneCount: { type: integer }
+
     GeneratePrdDraftBodyDto:
       type: object
       required: [featureIntent]
@@ -19144,7 +19563,11 @@ components:
       properties:
         id: { type: string, format: uuid }
         workspaceId: { type: string, format: uuid }
-        slug: { type: string }
+        slug:
+          type: string
+          description: >-
+            Page slug. `workspace-agent` is the canonical hub; supporting pages include
+            `workspace-overview`, `cross-repo-map`, `shared-concepts`, and `prd-*` drafts.
         title: { type: string }
         bodyMd: { type: string }
         sortOrder: { type: integer }
@@ -19192,6 +19615,136 @@ components:
         platformSnippet:
           type: string
           description: Bounded markdown summary of platform evidence for the system panel
+        insights:
+          $ref: "#/components/schemas/WorkspaceContextInsightsDto"
+
+    WorkspaceContextInsightsDto:
+      type: object
+      required:
+        [
+          kind,
+          version,
+          generatedAt,
+          repoRoles,
+          emergentInsights,
+          sharedConcepts,
+          crossRepoLinks,
+          contracts,
+          groups,
+          standaloneRepos,
+          coverage,
+          integrationFootprints,
+          integrationOpportunities,
+        ]
+      properties:
+        kind: { type: string, enum: [workspace-insights] }
+        version: { type: integer, enum: [2] }
+        generatedAt: { type: string, format: date-time }
+        repoRoles:
+          type: array
+          items:
+            type: object
+            required: [repoId, repoName, role, rationale]
+            properties:
+              repoId: { type: string, format: uuid }
+              repoName: { type: string }
+              role: { type: string }
+              rationale: { type: string }
+        emergentInsights:
+          type: array
+          items:
+            type: object
+            required: [kind, title, detail, repoIds, certainty]
+            properties:
+              kind: { type: string }
+              title: { type: string }
+              detail: { type: string }
+              repoIds: { type: array, items: { type: string, format: uuid } }
+              certainty: { type: string, enum: [fact, inference, possibility] }
+              evidenceRefs: { type: array, items: { type: string } }
+        sharedConcepts:
+          type: array
+          items:
+            type: object
+            required: [term, repoNames, kind]
+            properties:
+              term: { type: string }
+              repoNames: { type: array, items: { type: string } }
+              kind: { type: string }
+        crossRepoLinks:
+          type: array
+          items: { $ref: "#/components/schemas/WorkspaceKnowledgeCrossRepoLinkDto" }
+        contracts:
+          type: array
+          items:
+            type: object
+            required: [id, kind, specKey, producers, consumers, certainty, score]
+            properties:
+              id: { type: string }
+              kind: { type: string }
+              specKey: { type: string }
+              producers: { type: array, items: { type: object, additionalProperties: true } }
+              consumers: { type: array, items: { type: object, additionalProperties: true } }
+              certainty: { type: string, enum: [fact, inference, possibility] }
+              score: { type: number, minimum: 0, maximum: 1 }
+        groups:
+          type: array
+          items:
+            type: object
+            required:
+              [
+                id,
+                kind,
+                label,
+                repoIds,
+                backboneContractIds,
+                possibilityLinkCount,
+                integrationSummary,
+                summary,
+              ]
+            properties:
+              id: { type: string }
+              kind: { type: string }
+              label: { type: string }
+              repoIds: { type: array, items: { type: string, format: uuid } }
+              backboneContractIds: { type: array, items: { type: string } }
+              possibilityLinkCount: { type: integer }
+              integrationSummary: { type: string }
+              summary: { type: string }
+        standaloneRepos:
+          type: array
+          items:
+            type: object
+            required: [repoId, repoName, summary]
+            properties:
+              repoId: { type: string, format: uuid }
+              repoName: { type: string }
+              summary: { type: string }
+        coverage:
+          type: array
+          items:
+            type: object
+            required: [repoId, detected, resolved, external, unresolved]
+            properties:
+              repoId: { type: string, format: uuid }
+              detected: { type: integer }
+              resolved: { type: integer }
+              external: { type: integer }
+              unresolved: { type: integer }
+        integrationFootprints:
+          type: array
+          items:
+            type: object
+            required: [repoId, repoName, availableSignals, missingSignals, gaps]
+            properties:
+              repoId: { type: string, format: uuid }
+              repoName: { type: string }
+              availableSignals: { type: array, items: { type: string } }
+              missingSignals: { type: array, items: { type: string } }
+              gaps: { type: array, items: { type: string } }
+        integrationOpportunities:
+          type: array
+          items: { type: string }
 
     WorkspaceKnowledgePageListDto:
       type: object
@@ -19203,6 +19756,106 @@ components:
         systemContext:
           $ref: "#/components/schemas/WorkspaceKnowledgeSystemContextDto"
 
+    WorkspaceKnowledgeGraphNodeDto:
+      type: object
+      required: [id, label, kind]
+      properties:
+        id: { type: string }
+        label: { type: string }
+        score: { type: number, minimum: 0, maximum: 1 }
+        contractId: { type: string }
+        kind:
+          type: string
+          enum: [repo, package, protocol]
+
+    WorkspaceKnowledgeGraphEdgeDto:
+      type: object
+      required: [from, to, relation]
+      properties:
+        from: { type: string, description: Source node id (usually repoId) }
+        to: { type: string, description: Target node id (usually repoId) }
+        relation: { type: string }
+        label: { type: string }
+        certainty:
+          type: string
+          enum: [fact, inference, possibility]
+
+    WorkspaceKnowledgeGraphDto:
+      type: object
+      required: [kind, version, exportedAt, nodes, edges]
+      properties:
+        kind: { type: string, enum: [workspace-kg] }
+        version: { type: integer }
+        exportedAt: { type: string, format: date-time }
+        nodes:
+          type: array
+          items: { $ref: "#/components/schemas/WorkspaceKnowledgeGraphNodeDto" }
+        edges:
+          type: array
+          items: { $ref: "#/components/schemas/WorkspaceKnowledgeGraphEdgeDto" }
+
+    WorkspaceKnowledgeCrossRepoLinkDto:
+      type: object
+      required: [fromRepoId, toRepoId, relation, certainty, evidence, label]
+      properties:
+        fromRepoId: { type: string, format: uuid }
+        toRepoId: { type: string, format: uuid }
+        fromRepoName: { type: string }
+        toRepoName: { type: string }
+        relation: { type: string }
+        certainty:
+          type: string
+          enum: [fact, inference, possibility]
+        evidence: { type: string }
+        label: { type: string }
+
+    WorkspaceKnowledgePackRepoDto:
+      type: object
+      required: [repoId, repoName]
+      properties:
+        repoId: { type: string, format: uuid }
+        repoName: { type: string }
+        commitSha: { type: string, nullable: true }
+        providerSlug: { type: string, nullable: true }
+        wikiOutline:
+          type: array
+          items:
+            type: object
+            required: [slug, title]
+            properties:
+              slug: { type: string }
+              title: { type: string }
+
+    WorkspaceKnowledgePackPageDto:
+      type: object
+      required: [slug, title, bodyMd]
+      properties:
+        slug: { type: string }
+        title: { type: string }
+        bodyMd: { type: string }
+
+    WorkspaceKnowledgePackDto:
+      type: object
+      required: [kind, version, exportedAt, pages, crossRepoLinks, repos]
+      properties:
+        kind: { type: string, enum: [wkg-pack] }
+        version: { type: integer }
+        exportedAt: { type: string, format: date-time }
+        workspaceName: { type: string }
+        pages:
+          type: array
+          items: { $ref: "#/components/schemas/WorkspaceKnowledgePackPageDto" }
+        crossRepoLinks:
+          type: array
+          items: { $ref: "#/components/schemas/WorkspaceKnowledgeCrossRepoLinkDto" }
+        repos:
+          type: array
+          items: { $ref: "#/components/schemas/WorkspaceKnowledgePackRepoDto" }
+        graph:
+          $ref: "#/components/schemas/WorkspaceKnowledgeGraphDto"
+        workspaceContext:
+          $ref: "#/components/schemas/WorkspaceContextInsightsDto"
+
     CodeIntelligenceUsageDto:
       type: object
       required: [operation, provider, inputTokens, outputTokens]