@thinkai/tai-api-contract 2.116.0 → 2.118.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.116.0
+  version: 2.118.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]
@@ -19069,6 +19153,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 +19180,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 +19253,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 +19305,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 +19446,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]

package/package.json

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