openapi: 3.1.0
info:
  title: SarmadAi API
  version: 1.3.3
  summary: Standalone SarmadAi API with DI model selection and cross-project memory.
servers:
  - url: https://localhost:7213
  - url: http://localhost:5020
paths:
  /api/intelligent-rag/ask:
    post:
      summary: Ask through the full Intelligent RAG pipeline
      operationId: intelligentRagAsk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
      responses:
        '200':
          description: SarmadAi response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
        '400':
          description: SarmadAi context/configuration error
        '503':
          description: Model backend unavailable
  /api/intelligent-rag/test/full:
    post:
      summary: Single-request full capability test
      operationId: intelligentRagFullTest
      security:
        - microsoftEntraCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
      responses:
        '200':
          description: Full integration diagnostics payload
          content:
            application/json:
              schema:
                type: object
  /api/intelligent-rag/self-awareness/status:
    get:
      summary: Check self-awareness archive readiness
      operationId: selfAwarenessStatus
      security:
        - microsoftEntraCookie: []
      parameters:
        - name: providerId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Self-awareness status
  /api/intelligent-rag/self-awareness/initialize:
    post:
      summary: Trigger self-awareness reindex
      operationId: selfAwarenessInitialize
      security:
        - microsoftEntraCookie: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReindexRequest'
      responses:
        '200':
          description: Reindex completed
        '500':
          description: Reindex failed
  /api/intelligent-rag/models/providers:
    get:
      summary: List public capability tiers
      operationId: publicCapabilities
      responses:
        '200':
          description: Providers catalog
  /api/intelligent-rag/memory/search:
    post:
      summary: Semantic search over cross-project memory
      operationId: memorySearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sessionId, query]
              properties:
                sessionId: { type: string }
                query: { type: string }
                topK: { type: integer, default: 6 }
                minSimilarity: { type: number, default: 0.2 }
                projectKey: { type: string }
      responses:
        '200':
          description: Memory search hits
  /api/intelligent-rag/memory/timeline:
    get:
      summary: Get session memory timeline
      operationId: memoryTimeline
      parameters:
        - name: sessionId
          in: query
          required: true
          schema: { type: string }
        - name: projectKey
          in: query
          schema: { type: string }
        - name: take
          in: query
          schema: { type: integer, default: 50 }
      responses:
        '200':
          description: Timeline entries
  /api/intelligent-rag/memory/feedback:
    post:
      summary: Record feedback and trigger self-learning promotion
      operationId: memoryFeedback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sessionId, interactionId]
              properties:
                sessionId: { type: string }
                interactionId: { type: string }
                rating: { type: integer, minimum: 1, maximum: 5, default: 3 }
                correction: { type: string }
                projectKey: { type: string }
      responses:
        '200':
          description: Learning event saved
  /api/intelligent-rag/sessions/{sessionId}/statistics:
    get:
      summary: Get session statistics
      operationId: sessionStatistics
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Session statistics payload
        '404':
          description: Session has no statistics
  /api/intelligent-rag/sessions/{sessionId}/dominance:
    get:
      summary: Get model dominance for a session
      operationId: sessionDominance
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Dominance map
        '404':
          description: Session has no interactions
  /api/intelligent-rag/statistics/global:
    get:
      summary: Get global SarmadAi statistics
      operationId: globalStatistics
      responses:
        '200':
          description: Global statistics payload
  /api/intelligent-rag/sessions/{sessionId}:
    delete:
      summary: Clear session interaction tracking
      operationId: clearSession
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Session data cleared
  /mcp/ask:
    post:
      summary: MCP compatibility alias mapped to IntelligentRAGController pipeline
      operationId: mcpAskAlias
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
          text/plain:
            schema:
              type: string
      responses:
        '200':
          description: SarmadAi response
  /api/telemetry/snapshot:
    get:
      summary: Get current telemetry snapshot and optional engineering insight
      operationId: telemetrySnapshot
      parameters:
        - name: focus
          in: query
          schema: { type: string, default: overview }
        - name: query
          in: query
          schema: { type: string }
        - name: section
          in: query
          schema: { type: string }
        - name: sessionId
          in: query
          schema: { type: string }
        - name: projectKey
          in: query
          schema: { type: string }
        - name: insight
          in: query
          schema: { type: boolean, default: true }
      responses:
        '200':
          description: Telemetry report envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelemetryReportEnvelope'
  /api/telemetry/report:
    post:
      summary: Generate telemetry report for a focused section
      operationId: telemetryReport
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelemetryReportRequest'
      responses:
        '200':
          description: Telemetry report envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelemetryReportEnvelope'
  /api/telemetry/stream:
    get:
      summary: Stream live telemetry snapshots via SSE
      operationId: telemetryStream
      parameters:
        - name: focus
          in: query
          schema: { type: string, default: overview }
        - name: sessionId
          in: query
          schema: { type: string }
        - name: projectKey
          in: query
          schema: { type: string }
        - name: intervalSeconds
          in: query
          schema: { type: integer, default: 5, minimum: 2, maximum: 30 }
      responses:
        '200':
          description: text/event-stream with `start` and periodic `snapshot` events
  /api/model-telemetry/snapshot:
    get:
      summary: Get compliance-safe active-model telemetry for Kubernetes/CPOLY
      operationId: activeModelTelemetrySnapshot
      responses:
        '200':
          description: Active model usage, current-visitor live requests, council events, and container counters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveModelTelemetrySnapshot'
  /api/model-telemetry/stream:
    get:
      summary: Stream compliance-safe active-model telemetry via SSE
      operationId: activeModelTelemetryStream
      responses:
        '200':
          description: text/event-stream with periodic `snapshot` events scoped to the current visitor
          content:
            text/event-stream:
              schema:
                type: string
  /api/model-telemetry/landing-audit:
    post:
      summary: Compare displayed telemetry indicators with actual Sarmad system values
      operationId: activeModelTelemetryLandingAudit
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LandingTelemetryAuditRequest'
      responses:
        '200':
          description: Isolated landing-page telemetry comparison
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LandingTelemetryAuditSnapshot'
  /api/admin/me:
    get:
      summary: Get the verified Global Administrator identity
      operationId: administrationMe
      security:
        - microsoftEntraCookie: []
      responses:
        '200':
          description: Organization identity and authoritative Global Administrator evaluation
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority was not proven }
  /api/admin/overview:
    get:
      summary: Get privileged administration counts, platform state, Graph status, and CPOLY identity
      operationId: administrationOverview
      security:
        - microsoftEntraCookie: []
      responses:
        '200':
          description: Privileged administration overview
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority was not proven }
  /api/admin/telemetry:
    get:
      summary: Get raw privileged telemetry and actual CPOLY model usage
      operationId: administrationTelemetry
      security:
        - microsoftEntraCookie: []
      parameters:
        - name: usageLimit
          in: query
          schema: { type: integer, minimum: 1, maximum: 1000, default: 250 }
      responses:
        '200':
          description: Raw telemetry, CPOLY runtime identity, and actual model audit records
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority was not proven }
  /api/admin/users:
    get:
      summary: List local activity profiles and Microsoft Entra directory users
      operationId: administrationListUsers
      security:
        - microsoftEntraCookie: []
      parameters:
        - { name: ownerType, in: query, schema: { type: string, enum: [authenticated, anonymous] } }
        - { name: search, in: query, schema: { type: string } }
        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
        - { name: pageSize, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 50 } }
        - { name: directoryLimit, in: query, schema: { type: integer, minimum: 1, maximum: 500, default: 200 } }
      responses:
        '200':
          description: Local and Entra user projections
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority was not proven }
    post:
      summary: Create a Microsoft Entra organization user
      operationId: administrationCreateUser
      security:
        - microsoftEntraCookie: []
      parameters:
        - $ref: '#/components/parameters/AdminMutationHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdministrationCreateUserRequest'
      responses:
        '200':
          description: Created user with one-time temporary password
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400': { description: Invalid user or mutation request }
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority or mutation origin was rejected }
  /api/admin/sign-ins:
    get:
      summary: List local authentication audits and Microsoft Entra sign-in logs
      operationId: administrationSignIns
      security:
        - microsoftEntraCookie: []
      parameters:
        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
        - { name: pageSize, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 100 } }
        - { name: graphLimit, in: query, schema: { type: integer, minimum: 1, maximum: 500, default: 200 } }
      responses:
        '200':
          description: Local and Entra sign-in events
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority was not proven }
  /api/admin/roles:
    get:
      summary: List authoritative role state persisted in SARMADAIDB
      operationId: administrationRoles
      security:
        - microsoftEntraCookie: []
      parameters:
        - { name: subjectId, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 500, default: 200 } }
      responses:
        '200':
          description: Current role assignment state from SARMADAIDB
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority was not proven }
        '503': { description: SARMADAIDB is unavailable }
  /api/admin/role-events:
    get:
      summary: List append-only role modification events persisted in SARMADAIDB
      operationId: administrationRoleEvents
      security:
        - microsoftEntraCookie: []
      parameters:
        - { name: subjectId, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 500, default: 200 } }
      responses:
        '200':
          description: Role modification audit events from SARMADAIDB
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority was not proven }
        '503': { description: SARMADAIDB is unavailable }
  /api/admin/chats:
    get:
      summary: List all registered and anonymous chat sessions
      operationId: administrationChats
      security:
        - microsoftEntraCookie: []
      parameters:
        - { name: ownerType, in: query, schema: { type: string, enum: [authenticated, anonymous] } }
        - { name: ownerId, in: query, schema: { type: string } }
        - { name: ipAddress, in: query, schema: { type: string } }
        - { name: search, in: query, schema: { type: string } }
        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
        - { name: pageSize, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 50 } }
      responses:
        '200':
          description: Privileged all-owner chat page
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority was not proven }
  /api/admin/chats/{sessionId}:
    get:
      summary: Get every message in one chat session
      operationId: administrationChat
      security:
        - microsoftEntraCookie: []
      parameters:
        - { name: sessionId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Privileged chat detail
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority was not proven }
        '404': { description: Chat session was not found }
  /api/admin/models:
    get:
      summary: Get the real CPOLY model catalog and routing policies
      operationId: administrationModels
      security:
        - microsoftEntraCookie: []
      parameters:
        - { name: refresh, in: query, schema: { type: boolean, default: false } }
      responses:
        '200':
          description: CPOLY catalog and current policies
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority was not proven }
  /api/admin/cpoly/runtime-identity:
    put:
      summary: Verify and rotate the GitHub Copilot runtime identity inside CPOLY
      operationId: administrationRotateCpolyRuntimeIdentity
      security:
        - microsoftEntraCookie: []
      parameters:
        - $ref: '#/components/parameters/AdminMutationHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdministrationCpolyRuntimeIdentityMutation'
      responses:
        '200':
          description: The replacement account was verified, activated, and persisted securely
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdministrationCpolyRuntimeIdentityRotation'
        '400': { description: Invalid expected login, credential, or mutation request }
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority or mutation origin was rejected }
        '409': { description: Runtime is busy, another rotation is active, or login confirmation mismatched }
        '422': { description: GitHub identity or Copilot entitlement could not be verified }
        '502': { description: CPOLY rejected the operation or returned an invalid response }
  /api/admin/model-policies:
    put:
      summary: Create or update a strict CPOLY model-routing policy
      operationId: administrationUpsertModelPolicy
      security:
        - microsoftEntraCookie: []
      parameters:
        - $ref: '#/components/parameters/AdminMutationHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdministrationModelPolicyMutation'
      responses:
        '200':
          description: Stored routing policy
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400': { description: Invalid policy or mutation request }
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority or mutation origin was rejected }
  /api/admin/model-policies/{id}:
    delete:
      summary: Delete a model-routing policy
      operationId: administrationDeleteModelPolicy
      security:
        - microsoftEntraCookie: []
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
        - $ref: '#/components/parameters/AdminMutationHeader'
      responses:
        '204': { description: Policy deleted }
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority or mutation origin was rejected }
        '404': { description: Policy was not found }
  /api/admin/platform:
    get:
      summary: Get the current platform availability state
      operationId: administrationPlatform
      security:
        - microsoftEntraCookie: []
      responses:
        '200':
          description: Platform availability state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdministrationPlatformState'
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority was not proven }
    put:
      summary: Suspend or resume the public platform
      operationId: administrationSetPlatform
      security:
        - microsoftEntraCookie: []
      parameters:
        - $ref: '#/components/parameters/AdminMutationHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdministrationPlatformMutation'
      responses:
        '200':
          description: Updated platform availability state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdministrationPlatformState'
        '400': { description: Mutation header is missing }
        '401': { description: Microsoft Entra authentication is required }
        '403': { description: Global Administrator authority or mutation origin was rejected }
  /api/newsboy/health:
    get:
      summary: Check the sanitized Newsboy bridge readiness
      operationId: newsboyHealth
      responses:
        '200':
          description: Newsboy bridge state
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled: { type: boolean }
                  ready: { type: boolean }
  /api/newsboy/feed:
    get:
      summary: Get the client-safe analyzed Newsboy briefing
      operationId: newsboyFeed
      responses:
        '200':
          description: Sanitized analyzed news/disclosure feed
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '502':
          description: Both the configured primary and fallback Newsboy endpoints are unavailable
        '503':
          description: Newsboy integration is disabled
components:
  securitySchemes:
    microsoftEntraCookie:
      type: apiKey
      in: cookie
      name: .SarmadAi.MicrosoftOrg.Auth
      description: Server-issued cookie after Microsoft Entra organization-member authentication.
  parameters:
    AdminMutationHeader:
      name: X-Sarmad-Admin-Request
      in: header
      required: true
      schema:
        type: string
        const: "1"
      description: Explicit anti-CSRF marker required by every administrative mutation.
  schemas:
    AdministrationCreateUserRequest:
      type: object
      required: [displayName, userPrincipalName]
      properties:
        displayName: { type: string, maxLength: 256 }
        userPrincipalName: { type: string, maxLength: 256 }
        mailNickname: { type: string, maxLength: 64 }
        temporaryPassword:
          type: string
          maxLength: 256
          description: Optional; generated server-side when omitted and never audited.
        forceChangePasswordNextSignIn: { type: boolean, default: true }
    AdministrationModelPolicyMutation:
      type: object
      required: [subjectType, capability, modelIds]
      properties:
        subjectType: { type: string, enum: [public, entra-user, owner] }
        subjectId:
          type: [string, "null"]
          description: "Null for public; Entra object GUID or opaque acct:/anon: owner id otherwise."
        capability: { type: string, enum: [auto, fast, thinker, deep] }
        modelIds:
          type: array
          minItems: 1
          maxItems: 5
          items: { type: string, maxLength: 160 }
        enabled: { type: boolean, default: true }
    AdministrationCpolyRuntimeIdentityMutation:
      type: object
      additionalProperties: false
      required: [githubToken, expectedLogin]
      properties:
        githubToken:
          type: string
          minLength: 20
          maxLength: 4096
          writeOnly: true
          description: Replacement GitHub credential; never returned or written to administration audit details.
        expectedLogin:
          type: string
          minLength: 1
          maxLength: 39
          pattern: '^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$'
    AdministrationCpolyRuntimeAccount:
      type: object
      additionalProperties: false
      required: [login]
      properties:
        login: { type: string, minLength: 1, maxLength: 39 }
        id: { type: [integer, "null"], format: int64 }
        name: { type: [string, "null"] }
        type: { type: [string, "null"] }
        copilotEntitled: { type: [boolean, "null"] }
        checkedAtUtc: { type: [string, "null"], format: date-time }
    AdministrationCpolyRuntimeIdentityRotation:
      type: object
      additionalProperties: false
      required:
        - ok
        - credentialRotated
        - persisted
        - runtimeAccount
        - copilotEntitled
        - sessionsClosed
        - terminalSessionsClosed
        - webSocketTerminalsClosed
      properties:
        ok: { type: boolean, const: true }
        credentialRotated: { type: boolean, const: true }
        persisted: { type: boolean }
        previousRuntimeAccount:
          oneOf:
            - $ref: '#/components/schemas/AdministrationCpolyRuntimeAccount'
            - type: "null"
        runtimeAccount:
          $ref: '#/components/schemas/AdministrationCpolyRuntimeAccount'
        copilotEntitled: { type: boolean, const: true }
        identityCheckedAtUtc: { type: [string, "null"], format: date-time }
        credentialSource: { type: [string, "null"] }
        sessionsClosed: { type: integer, minimum: 0 }
        terminalSessionsClosed: { type: integer, minimum: 0 }
        webSocketTerminalsClosed: { type: integer, minimum: 0 }
    AdministrationPlatformMutation:
      type: object
      required: [suspended]
      properties:
        suspended: { type: boolean }
        reason: { type: [string, "null"], maxLength: 500 }
    AdministrationPlatformState:
      type: object
      required: [suspended, changedAtUtc]
      properties:
        suspended: { type: boolean }
        reason: { type: [string, "null"] }
        changedAtUtc: { type: string, format: date-time }
        changedByOwnerId: { type: [string, "null"] }
    AskRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
        sessionId:
          type: string
        capability:
          type: string
          enum: [auto, fast, thinker, deep]
          default: auto
        useSelfAwareness:
          type: boolean
          default: true
        useMemory:
          type: boolean
          default: true
        topK:
          type: integer
          default: 6
          minimum: 1
        temperature:
          type: number
          default: 0.7
        maxTokens:
          type: integer
        topP:
          type: number
        stopSequences:
          type: array
          items:
            type: string
        projectKey:
          type: string
        conversationHistory:
          type: array
          items:
            $ref: '#/components/schemas/ConversationMessage'
    ConversationMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum: [user, assistant, system]
        content:
          type: string
    AskResponse:
      type: object
      properties:
        answer:
          type: string
        queryType:
          type: string
        selectedModel:
          type: string
          description: Public capability label; never a backend model identity.
        contextChunks:
          type: integer
        elapsedMs:
          type: number
        interactionId:
          type: string
        sources:
          type: array
          items:
            type: object
    ReindexRequest:
      type: object
      properties:
        rootPath:
          type: string
        extensions:
          type: array
          items:
            type: string
        dimensions:
          type: integer
        providerId:
          type: string
    TelemetryReportRequest:
      type: object
      properties:
        focus:
          type: string
        query:
          type: string
        section:
          type: string
        sessionId:
          type: string
        projectKey:
          type: string
        includeEngineerInsight:
          type: boolean
        persistToMemory:
          type: boolean
    TelemetryReportEnvelope:
      type: object
      properties:
        ok:
          type: boolean
        focus:
          type: string
        summary:
          type: string
        reportMarkdown:
          type: string
        engineeringInsight:
          type: string
          nullable: true
        snapshot:
          type: object
          additionalProperties: true
    ActiveModelTelemetrySnapshot:
      type: object
      properties:
        enabled: { type: boolean }
        activeProviderLabel:
          type: string
          description: Compliance-safe provider abbreviation such as `cp`
        scope: { type: string }
        startedUtc: { type: string, format: date-time }
        generatedUtc: { type: string, format: date-time }
        capabilityRoutes:
          type: array
          items:
            $ref: '#/components/schemas/ActiveCapabilityRoute'
        summary:
          $ref: '#/components/schemas/ActiveTelemetrySummary'
        models:
          type: array
          items:
            $ref: '#/components/schemas/ActiveModelUsage'
        series:
          type: array
          items:
            $ref: '#/components/schemas/ModelTokenSeries'
        liveRequests:
          type: array
          description: Active requests belonging only to the current visitor identity
          items:
            $ref: '#/components/schemas/LiveModelRequest'
        expertCouncil:
          $ref: '#/components/schemas/ExpertCouncilTelemetry'
        thinkingEvents:
          type: array
          items:
            $ref: '#/components/schemas/ModelThinkingEvent'
        landingAudit:
          $ref: '#/components/schemas/LandingTelemetryAuditSnapshot'
        container:
          $ref: '#/components/schemas/CpolyContainerTelemetry'
        message: { type: string }
    ActiveCapabilityRoute:
      type: object
      properties:
        capability: { type: string, enum: [auto, fast, thinker, deep] }
        displayName: { type: string }
        complianceModelId:
          type: string
          examples: [cp#a-s+46, cp#o-g+55]
        description: { type: string }
    ActiveTelemetrySummary:
      type: object
      properties:
        activeModels: { type: integer }
        activeRequests: { type: integer }
        totalRequests: { type: integer, format: int64 }
        failedRequests: { type: integer, format: int64 }
        totalTokens: { type: integer, format: int64 }
        authoritativeTokens: { type: integer, format: int64 }
        estimatedTokens: { type: integer, format: int64 }
        aiCredits: { type: number, format: double }
        successRate: { type: number, minimum: 0, maximum: 1 }
        thinkingEvents: { type: integer }
    ActiveModelUsage:
      type: object
      properties:
        complianceModelId: { type: string }
        capability: { type: string }
        totalRequests: { type: integer, format: int64 }
        failedRequests: { type: integer, format: int64 }
        totalTokens: { type: integer, format: int64 }
        promptTokens: { type: integer, format: int64 }
        completionTokens: { type: integer, format: int64 }
        authoritativeTokens: { type: integer, format: int64 }
        estimatedTokens: { type: integer, format: int64 }
        aiCredits: { type: number, format: double }
        firstObservedUtc: { type: string, format: date-time }
        lastObservedUtc: { type: string, format: date-time }
        lastDurationMs: { type: integer, format: int64 }
        lastSuccess: { type: boolean }
        lastError: { type: string, nullable: true }
    ModelTokenSeries:
      type: object
      properties:
        complianceModelId: { type: string }
        points:
          type: array
          items:
            type: object
            properties:
              timestampUtc: { type: string, format: date-time }
              tokenDelta: { type: integer }
              kind: { type: string }
    LiveModelRequest:
      type: object
      properties:
        requestId: { type: string }
        complianceModelId: { type: string }
        capability: { type: string }
        promptTokens: { type: integer }
        completionTokens: { type: integer }
        totalTokens: { type: integer }
        startedUtc: { type: string, format: date-time }
        updatedUtc: { type: string, format: date-time }
        elapsedMs: { type: integer, format: int64 }
        status: { type: string }
        tokenMeasurement: { type: string }
    ExpertCouncilTelemetry:
      type: object
      properties:
        protocol: { type: string }
        rosterMode: { type: string }
        members:
          type: array
          items:
            $ref: '#/components/schemas/ExpertCouncilMember'
        recentEvents:
          type: array
          items:
            $ref: '#/components/schemas/ModelThinkingEvent'
    ExpertCouncilMember:
      type: object
      properties:
        name: { type: string }
        role: { type: string }
        complianceModelId: { type: string }
        capability: { type: string, nullable: true }
        status: { type: string }
    ModelThinkingEvent:
      type: object
      properties:
        timestampUtc: { type: string, format: date-time }
        requestId: { type: string, nullable: true }
        complianceModelId: { type: string }
        capability: { type: string }
        role: { type: string }
        title: { type: string }
        text:
          type: string
          description: Sanitized execution/council signal with raw model identities removed
        status: { type: string }
        rosterMode:
          type: string
          nullable: true
          description: Contextual roster mode or explicit fallback mode
        members:
          type: array
          items:
            $ref: '#/components/schemas/ExpertCouncilMember'
    CpolyContainerTelemetry:
      type: object
      properties:
        available: { type: boolean }
        generatedUtc: { type: string, format: date-time, nullable: true }
        uptimeSeconds: { type: number }
        cpuCount: { type: integer }
        memoryRssBytes: { type: integer, format: int64 }
        activeCommands: { type: integer }
        queuedCommands: { type: integer }
        copilotSessions: { type: integer }
        completedCommands: { type: integer, format: int64 }
        failedCommands: { type: integer, format: int64 }
        promptRequests: { type: integer, format: int64 }
        promptFailures: { type: integer, format: int64 }
        averagePromptLatencyMs: { type: number }
        maxPromptLatencyMs: { type: number }
        error: { type: string, nullable: true }
    LandingTelemetryAuditRequest:
      type: object
      properties:
        displayedMetrics:
          type: object
          additionalProperties:
            type: number
    LandingTelemetryAuditSnapshot:
      type: object
      properties:
        observations:
          type: array
          items:
            type: object
            properties:
              timestampUtc: { type: string, format: date-time }
              metricKey: { type: string }
              displayedValue: { type: number }
              actualValue: { type: number }
              unit: { type: string, nullable: true }
        maxAbsoluteDeviation: { type: number }
        verdict: { type: string }
