feat(assistant): implement spec 021 chat assistant flow with semantic contracts

specs/021-llm-project-assistant/contracts/assistant-api.openapi.yaml

@@ -0,0 +1,270 @@
+openapi: 3.0.3
+info:
+  title: Assistant Chat API
+  version: 1.0.0
+  description: API contract for LLM chat assistant command orchestration.
+
+servers:
+  - url: /api
+
+paths:
+  /assistant/messages:
+    post:
+      summary: Send user message to assistant
+      description: Parses command, applies safety checks, and returns assistant response state.
+      operationId: sendAssistantMessage
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssistantMessageRequest'
+      responses:
+        '200':
+          description: Assistant response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AssistantMessageResponse'
+        '400':
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden
+
+  /assistant/confirmations/{confirmation_id}/confirm:
+    post:
+      summary: Confirm dangerous operation
+      description: Confirms one pending risky command and executes it once.
+      operationId: confirmAssistantOperation
+      parameters:
+        - in: path
+          name: confirmation_id
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Confirmation handled
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AssistantMessageResponse'
+        '400':
+          description: Invalid or expired confirmation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden
+        '404':
+          description: Confirmation not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /assistant/confirmations/{confirmation_id}/cancel:
+    post:
+      summary: Cancel dangerous operation
+      description: Cancels pending confirmation and prevents execution.
+      operationId: cancelAssistantOperation
+      parameters:
+        - in: path
+          name: confirmation_id
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Confirmation cancelled
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AssistantMessageResponse'
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden
+        '404':
+          description: Confirmation not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /assistant/history:
+    get:
+      summary: Get assistant conversation history
+      description: Returns paginated history for current user.
+      operationId: getAssistantHistory
+      parameters:
+        - in: query
+          name: page
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - in: query
+          name: page_size
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+      responses:
+        '200':
+          description: Conversation history page
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AssistantHistoryPage'
+        '401':
+          description: Unauthorized
+
+components:
+  schemas:
+    AssistantResponseState:
+      type: string
+      enum:
+        - started
+        - success
+        - failed
+        - denied
+        - needs_confirmation
+        - needs_clarification
+
+    RiskLevel:
+      type: string
+      enum:
+        - safe
+        - guarded
+        - dangerous
+
+    CommandIntent:
+      type: object
+      properties:
+        domain:
+          type: string
+        operation:
+          type: string
+        entities:
+          type: object
+          additionalProperties: true
+        confidence:
+          type: number
+          minimum: 0
+          maximum: 1
+        risk_level:
+          $ref: '#/components/schemas/RiskLevel'
+      required: [domain, operation, confidence, risk_level]
+
+    AssistantMessageRequest:
+      type: object
+      properties:
+        conversation_id:
+          type: string
+          nullable: true
+        message:
+          type: string
+          minLength: 1
+          maxLength: 4000
+      required: [message]
+
+    AssistantAction:
+      type: object
+      properties:
+        type:
+          type: string
+          enum: [confirm, cancel, open_task, open_reports, rephrase]
+        label:
+          type: string
+        target:
+          type: string
+          nullable: true
+      required: [type, label]
+
+    AssistantMessageResponse:
+      type: object
+      properties:
+        conversation_id:
+          type: string
+        response_id:
+          type: string
+        state:
+          $ref: '#/components/schemas/AssistantResponseState'
+        text:
+          type: string
+        intent:
+          $ref: '#/components/schemas/CommandIntent'
+        confirmation_id:
+          type: string
+          nullable: true
+        task_id:
+          type: string
+          nullable: true
+        actions:
+          type: array
+          items:
+            $ref: '#/components/schemas/AssistantAction'
+        created_at:
+          type: string
+          format: date-time
+      required: [conversation_id, response_id, state, text, created_at]
+
+    AssistantMessage:
+      type: object
+      properties:
+        message_id:
+          type: string
+        conversation_id:
+          type: string
+        role:
+          type: string
+          enum: [user, assistant]
+        text:
+          type: string
+        state:
+          $ref: '#/components/schemas/AssistantResponseState'
+        task_id:
+          type: string
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+      required: [message_id, conversation_id, role, text, created_at]
+
+    AssistantHistoryPage:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/AssistantMessage'
+        total:
+          type: integer
+          minimum: 0
+        page:
+          type: integer
+          minimum: 1
+        page_size:
+          type: integer
+          minimum: 1
+        has_next:
+          type: boolean
+      required: [items, total, page, page_size, has_next]
+
+    ErrorResponse:
+      type: object
+      properties:
+        detail:
+          type: string
+      required: [detail]