@opensoha/contracts 0.1.18 → 0.1.20

package/openapi/soha-api.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Soha API
-  version: 0.1.18
+  version: 0.1.20
   description: >
     Public OpenSoha core API contract. This first contract focuses on stable
     cross-repository boundaries: auth, health, runner-facing control-plane
@@ -2163,6 +2163,7 @@ paths:
     delete:
       tags: [Applications]
       operationId: deleteApplication
+      description: Deletes the application and its owned configuration and history. Does not uninstall cluster workloads. Unfinished delivery tasks or external references prevent deletion.
       parameters:
         - $ref: "#/components/parameters/ApplicationID"
       responses:
@@ -2176,6 +2177,8 @@ paths:
           $ref: "#/components/responses/Error"
         "404":
           $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
   /applications/{applicationID}/detail:
     get:
       tags: [Applications, Delivery]
@@ -5456,8 +5459,13 @@ paths:
       parameters:
         - { name: connectionID, in: path, required: true, schema: { type: string } }
       responses:
+        "200":
+          description: Completed synchronous connection check. Each request probes the connection and returns its current health; no task or task log is created.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ConnectionCheckResultEnvelope" }
         "202":
-          description: Completed connection-test operation.
+          description: Legacy response for a completed connection check, retained for older servers. Read the operation result directly.
           content:
             application/json:
               schema: { $ref: "#/components/schemas/VirtualizationOperationEnvelope" }
@@ -10296,6 +10304,7 @@ paths:
     post:
       tags: [Docker]
       operationId: queryDockerProjectLogs
+      description: Requires docker.services.logs. Reads bounded logs directly from the runtime without submitting an operation.
       parameters:
         - $ref: "#/components/parameters/DockerProjectID"
       requestBody:
@@ -10325,6 +10334,7 @@ paths:
     post:
       tags: [Docker]
       operationId: issueDockerProjectLogStreamTicket
+      description: Requires docker.services.logs. The same permission is rechecked when opening the stream.
       parameters:
         - $ref: "#/components/parameters/DockerProjectID"
       requestBody:
@@ -13681,8 +13691,14 @@ paths:
             schema:
               $ref: "#/components/schemas/ComputeProviderReadRequest"
       responses:
+        "200":
+          description: Completed synchronous health check. Each request probes the connection and returns its current health; no task or task log is created. Idempotency-Key is accepted for request compatibility but does not replay an earlier check.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConnectionCheckResultEnvelope"
         "202":
-          description: Health check accepted as a source-domain task. The request never returns the Provider raw response.
+          description: Legacy health-check response retained for older servers. The task contains the completed result, never the Provider raw response.
           content:
             application/json:
               schema:
@@ -13773,6 +13789,10 @@ paths:
     post:
       tags: [Compute]
       operationId: executeComputeResourceAction
+      description: >-
+        Enqueue a supported resource mutation. Container service actions are start,
+        stop and restart. Log reads use the direct project log query API; action
+        logs is rejected without creating a task.
       parameters:
         - $ref: "#/components/parameters/ComputeDomain"
         - $ref: "#/components/parameters/ComputeResourceKind"
@@ -13952,6 +13972,11 @@ paths:
     post:
       tags: [Compute]
       operationId: retryComputeTask
+      description: >-
+        Retry an asynchronous operation when its returned state permits it.
+        Historical connection_test, port_reserve and service_action logs records
+        remain readable but cannot be requeued; use their direct check, metadata
+        or log query APIs instead.
       parameters:
         - $ref: "#/components/parameters/ComputeTaskDomain"
         - $ref: "#/components/parameters/ComputeTaskID"
@@ -13969,6 +13994,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ComputeTaskEnvelope"
+        "400":
+          $ref: "#/components/responses/ComputeError"
         "403":
           $ref: "#/components/responses/ComputeError"
         "404":
@@ -23379,6 +23406,25 @@ components:
           type: array
           items: { $ref: "#/components/schemas/ComputeResourceRef" }
       additionalProperties: false
+    ConnectionCheckResult:
+      type: object
+      description: Current connection health from a synchronous probe. This result is not a task and has no task identifier or lifecycle actions.
+      required: [healthy, status, checkedAt]
+      properties:
+        healthy: { type: boolean }
+        status: { type: string }
+        message: { type: string }
+        reason: { type: string }
+        nextAction: { type: string }
+        httpStatus: { type: integer }
+        checkedAt: { type: string, format: date-time }
+      additionalProperties: false
+    ConnectionCheckResultEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data: { $ref: "#/components/schemas/ConnectionCheckResult" }
+      additionalProperties: false
     ComputeTaskView:
       type: object
       required: [id, domain, sourceType, sourceId, kind, category, normalizedStatus, rawStatus, resources, attemptCount, cancelable, retryable, availableActions, createdAt]
@@ -25309,6 +25355,12 @@ components:
         loginLogoUrl: { type: string }
         expandedLogoUrl: { type: string }
         collapsedLogoUrl: { type: string }
+        darkExpandedLogoUrl:
+          type: string
+          description: Optional dark-theme expanded logo. Empty or absent uses expandedLogoUrl.
+        darkCollapsedLogoUrl:
+          type: string
+          description: Optional dark-theme compact logo. Empty or absent uses collapsedLogoUrl.
         faviconUrl: { type: string }
       additionalProperties: false
     BrandingSettingsEnvelope:
@@ -25328,6 +25380,12 @@ components:
         loginLogoUrl: { type: string }
         expandedLogoUrl: { type: string }
         collapsedLogoUrl: { type: string }
+        darkExpandedLogoUrl:
+          type: string
+          description: Optional dark-theme expanded logo. Empty or absent clears the override.
+        darkCollapsedLogoUrl:
+          type: string
+          description: Optional dark-theme compact logo. Empty or absent clears the override.
         faviconUrl: { type: string }
       additionalProperties: false
     BrandingAssetUpload:
@@ -34536,6 +34594,11 @@ components:
           type: boolean
         usesInformerCache:
           type: boolean
+        customResourceRules:
+          type: array
+          maxItems: 50
+          items:
+            $ref: "#/components/schemas/KubernetesAgentCustomResourceRule"
       additionalProperties: false
     KubernetesPrometheusDetail:
       type: object
@@ -34549,6 +34612,8 @@ components:
           type: string
         hasBearerToken:
           type: boolean
+        transport:
+          $ref: "#/components/schemas/KubernetesPrometheusTransport"
       additionalProperties: false
     KubernetesMonitoringDetail:
       type: object
@@ -40686,6 +40751,7 @@ components:
         action:
           type: string
           enum: [create]
+          x-enum-varnames: [Create]
       additionalProperties: false
     KubernetesResourceCreateScopeDecision:
       type: object
@@ -46864,3 +46930,251 @@ components:
       properties:
         data: { $ref: "#/components/schemas/NetworkPolicyPreviewResult" }
       additionalProperties: false
+    KubernetesCustomResourceAccess:
+      type: object
+      required: [allowedActions]
+      properties:
+        allowedActions:
+          type: array
+          items: { type: string, enum: [list, view, create, update, delete] }
+      additionalProperties: false
+    KubernetesCustomResourceAccessEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data: { $ref: "#/components/schemas/KubernetesCustomResourceAccess" }
+      additionalProperties: false
+    KubernetesClusterRegistrationRequest:
+      type: object
+      properties:
+        id: { type: string }
+        name: { type: string }
+        region: { type: string }
+        environment: { type: string }
+        labels: { type: object, additionalProperties: { type: string } }
+        connectionMode: { $ref: "#/components/schemas/KubernetesConnectionMode" }
+        kubeconfig: { type: string }
+        context: { type: string }
+        agentEndpoint: { type: string }
+        agentToken: { type: string, writeOnly: true }
+        prometheusBaseUrl: { type: string }
+        prometheusBearerToken: { type: string, writeOnly: true }
+        prometheusClusterLabel: { type: string }
+        grafanaBaseUrl: { type: string }
+        prometheusTransport: { $ref: "#/components/schemas/KubernetesPrometheusTransport" }
+        agentCustomResourceRules:
+          type: array
+          maxItems: 50
+          items: { $ref: "#/components/schemas/KubernetesAgentCustomResourceRule" }
+      additionalProperties: false
+    KubernetesAgentCustomResourceRule:
+      type: object
+      required: [apiGroup, resources, verbs]
+      properties:
+        apiGroup: { type: string, pattern: '^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$', maxLength: 253 }
+        resources:
+          type: array
+          minItems: 1
+          maxItems: 50
+          uniqueItems: true
+          items: { type: string, pattern: '^[a-z]([a-z0-9-]*[a-z0-9])?$', maxLength: 63 }
+        verbs:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            type: string
+            enum: [get, list, watch, create, update, patch, delete]
+            x-enum-varnames: [KubernetesAgentCustomResourceRuleVerbsGet, KubernetesAgentCustomResourceRuleVerbsList, KubernetesAgentCustomResourceRuleVerbsWatch, KubernetesAgentCustomResourceRuleVerbsCreate, KubernetesAgentCustomResourceRuleVerbsUpdate, KubernetesAgentCustomResourceRuleVerbsPatch, KubernetesAgentCustomResourceRuleVerbsDelete]
+        namespaces:
+          description: Explicit namespaces; omitted or empty grants cluster-wide access to the named resources only.
+          type: array
+          maxItems: 50
+          uniqueItems: true
+          items: { type: string, pattern: '^[a-z0-9]([a-z0-9-]*[a-z0-9])?$', maxLength: 63 }
+      additionalProperties: false
+    KubernetesPrometheusTransport:
+      type: string
+      enum: [direct, agent]
+      default: direct
+    AgentPrometheusQueryRequest:
+      type: object
+      required: [endpoint, query, kind]
+      properties:
+        endpoint: { type: string, maxLength: 2048 }
+        query: { type: string, minLength: 1, maxLength: 16384 }
+        kind: { type: string, enum: [instant, range] }
+        start: { type: integer, format: int64, minimum: 1 }
+        end: { type: integer, format: int64, minimum: 1 }
+        step: { type: integer, minimum: 1 }
+      if:
+        properties:
+          kind: { const: range }
+        required: [kind]
+      then:
+        required: [start, end, step]
+      description: Range queries require start, end and step. The runtime also enforces end greater than start, a maximum 24-hour range and at most 11000 intervals.
+      additionalProperties: false
+    KubernetesNamespaceInput:
+      type: object
+      properties:
+        name: &a2
+          type: string
+        labels: &a1
+          $ref: "#/components/schemas/KubernetesStringMap"
+        annotations: *a1
+      additionalProperties: false
+    KubernetesNamespaceCreateInput:
+      type: object
+      required: [name]
+      properties:
+        name:
+          type: string
+          minLength: 1
+          pattern: "\\S"
+        labels: *a1
+        annotations: *a1
+      additionalProperties: false
+    KubernetesNamespaceEnvelope:
+      type: object
+      required:
+        - data
+      properties:
+        data:
+          $ref: "#/components/schemas/KubernetesNamespace"
+      additionalProperties: false
+    KubernetesNodeUpdateInput:
+      type: object
+      properties:
+        labels: *a1
+        taints:
+          type: array
+          items:
+            $ref: "#/components/schemas/KubernetesNodeTaint"
+      additionalProperties: false
+    KubernetesNodeSchedulabilityInput:
+      type: object
+      required:
+        - unschedulable
+      properties:
+        unschedulable:
+          type: boolean
+      additionalProperties: false
+    KubernetesNodeDrainInput:
+      type: object
+      properties:
+        force:
+          type: boolean
+        deleteEmptyDirData:
+          type: boolean
+        timeoutSeconds:
+          type: integer
+          minimum: 30
+          maximum: 1800
+          default: 300
+      additionalProperties: false
+    KubernetesResourceYamlInput:
+      type: object
+      required: [content]
+      properties:
+        content: {type: string, minLength: 1}
+      additionalProperties: false
+    KubernetesConfigMapDataInput:
+      type: object
+      properties:
+        data: *a1
+        binaryData: *a1
+      additionalProperties: false
+    KubernetesSecretDataInput:
+      description: Data values are plain text. The response detail returns Kubernetes Base64-encoded values.
+      type: object
+      properties:
+        data: *a1
+      additionalProperties: false
+    KubernetesCronJobSuspendInput:
+      type: object
+      required:
+        - suspend
+      properties:
+        suspend:
+          type: boolean
+      additionalProperties: false
+    KubernetesSecretDetail:
+      type: object
+      required:
+        - name
+        - namespace
+        - immutable
+        - ageSeconds
+        - type
+      properties:
+        name:
+          type: string
+        namespace:
+          type: string
+        labels:
+          $ref: "#/components/schemas/KubernetesStringMap"
+        annotations:
+          $ref: "#/components/schemas/KubernetesStringMap"
+        data:
+          $ref: "#/components/schemas/KubernetesStringMap"
+          description: Secret data values encoded with standard Base64. Requires secret-data.view.
+        immutable:
+          type: boolean
+        createdAt:
+          type: string
+        ageSeconds:
+          type: integer
+          format: int64
+          minimum: 0
+        type: *a2
+      additionalProperties: false
+    KubernetesSecretDetailEnvelope:
+      type: object
+      required:
+        - data
+      properties:
+        data:
+          $ref: "#/components/schemas/KubernetesSecretDetail"
+      additionalProperties: false
+    ClusterAgentUpgradeInput:
+      type: object
+      additionalProperties: false
+      required: [version]
+      properties:
+        version:
+          type: string
+          maxLength: 64
+          pattern: '^v?(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$'
+          description: Explicit stable official Agent version, such as v0.1.7. Registry and container identity cannot be overridden.
+    ClusterAgentUpgradeStatus:
+      type: object
+      additionalProperties: false
+      required: [version, image, recommendedVersion, rolloutStatus, message, canUpgrade]
+      properties:
+        version: {type: string, description: Version reported by the currently connected Agent process.}
+        image: {type: string, description: Desired image of the standard Agent Deployment.}
+        recommendedVersion: {type: string, description: Agent version bundled with this Core release.}
+        rolloutStatus: {type: string}
+        message: {type: string}
+        canUpgrade: {type: boolean}
+        upgradeDisabledReason: {type: string}
+    ClusterAgentUpgradeStatusEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/ClusterAgentUpgradeStatus"
+    ClusterAgentUpgradeResult:
+      type: object
+      additionalProperties: false
+      required: [previousImage, targetImage]
+      properties:
+        previousImage: {type: string}
+        targetImage: {type: string}
+    ClusterAgentUpgradeResultEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/ClusterAgentUpgradeResult"

package/openapi/spec_generated.go

@@ -5,9 +5,9 @@ package openapi
 import _ "embed"
 
 const (
-	Version    = "0.1.18"
-	YAMLSHA256 = "d614ce858924d94da353c7a9380971a3e80964f3e6c865e8b27108e859500cf4"
-	JSONSHA256 = "a98ea9ad99b6f044ce14e42f37b90b42e28347d53e37c727a04210b076aba960"
+	Version    = "0.1.20"
+	YAMLSHA256 = "cbf0b3c1f47da982289c43ccdc76c5eb9e2c8d064aebfe92aa23e4b179ea136b"
+	JSONSHA256 = "6862030a09d680756adc6bff8cc1e6bf81318704bf957027f22e1b7655bb471e"
 )
 
 //go:embed soha-api.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoha/contracts",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "private": false,
   "description": "Shared OpenSoha API, agent, MCP, skill, event, and auth contracts.",
   "license": "Apache-2.0",

package/resource/agent_access.go

@@ -0,0 +1,23 @@
+package resource
+
+// CustomResourceAccessRequest checks the Agent's own Kubernetes identity.
+type CustomResourceAccessRequest struct {
+	Definition CRDResourceDefinition `json:"definition"`
+	Namespace  string                `json:"namespace"`
+	Name       string                `json:"name,omitempty"`
+}
+
+type CustomResourceAccess struct {
+	AllowedActions []string `json:"allowedActions"`
+}
+
+// PrometheusQuery carries a bounded query for an already configured endpoint.
+// Endpoint must match the Agent configuration; it is never a proxy destination.
+type PrometheusQuery struct {
+	Endpoint string `json:"endpoint"`
+	Query    string `json:"query"`
+	Kind     string `json:"kind"`
+	Start    int64  `json:"start,omitempty"`
+	End      int64  `json:"end,omitempty"`
+	Step     int64  `json:"step,omitempty"`
+}