Declare Runtime observation states once

contracts/agents-api/core.openapi.yaml

@@ -87,24 +87,15 @@ definitions:
       instance:
         $ref: '#/definitions/v1.RuntimeInstance'
       lifecycle_state:
-        enum:
-          - active
-          - sleeping
-          - transitioning
-          - pending
-          - stopped
-        type: string
+        allOf:
+          - $ref: '#/definitions/v1.RuntimeObservationLifecycleState'
         x-nullable: true
       memory:
         allOf:
           - $ref: '#/definitions/v1.RuntimeMemoryObservation'
         x-nullable: true
       mode:
-        enum:
-          - none
-          - self_hosted
-          - openai_hosted
-        type: string
+        $ref: '#/definitions/v1.RuntimeObservationMode'
       object:
         enum:
           - agent.runtime_observation
@@ -131,11 +122,7 @@ definitions:
         type: integer
         x-nullable: true
       status:
-        enum:
-          - observed
-          - unsupported
-          - unavailable
-        type: string
+        $ref: '#/definitions/v1.RuntimeObservationStatus'
     required:
       - allocation_created_at
       - cpu
@@ -1113,6 +1100,22 @@ definitions:
       - nodes_on_other_address
       - self_hosted_executors
     type: object
+  deployment.AllocationDiagnostic:
+    enum:
+      - ""
+      - node_unavailable
+      - resource_missing
+      - compute_unconfirmed
+      - ownership_mismatch
+      - provider_unavailable
+    type: string
+    x-enum-varnames:
+      - AllocationObserved
+      - AllocationNodeUnavailable
+      - AllocationResourceMissing
+      - AllocationComputeUnconfirmed
+      - AllocationOwnershipMismatch
+      - AllocationProviderUnavailable
   deployment.HostHistory:
     properties:
       points:
@@ -1237,14 +1240,7 @@ definitions:
       deployment_generation:
         type: integer
       diagnostic:
-        enum:
-          - ""
-          - node_unavailable
-          - resource_missing
-          - compute_unconfirmed
-          - ownership_mismatch
-          - provider_unavailable
-        type: string
+        $ref: '#/definitions/deployment.AllocationDiagnostic'
       environment_id:
         type: string
       id:
@@ -2879,16 +2875,22 @@ definitions:
         type: string
         x-nullable: true
       kind:
-        enum:
-          - managed_allocation
-          - self_hosted_connection
-          - none
-        type: string
+        $ref: '#/definitions/v1.RuntimeInstanceKind'
     required:
       - allocation_id
       - connection_generation
       - kind
     type: object
+  v1.RuntimeInstanceKind:
+    enum:
+      - managed_allocation
+      - self_hosted_connection
+      - none
+    type: string
+    x-enum-varnames:
+      - RuntimeInstanceManagedAllocation
+      - RuntimeInstanceSelfHostedConnection
+      - RuntimeInstanceNone
   v1.RuntimeMemoryObservation:
     properties:
       limit_bytes:
@@ -2923,24 +2925,15 @@ definitions:
       instance:
         $ref: '#/definitions/v1.RuntimeInstance'
       lifecycle_state:
-        enum:
-          - active
-          - sleeping
-          - transitioning
-          - pending
-          - stopped
-        type: string
+        allOf:
+          - $ref: '#/definitions/v1.RuntimeObservationLifecycleState'
         x-nullable: true
       memory:
         allOf:
           - $ref: '#/definitions/v1.RuntimeMemoryObservation'
         x-nullable: true
       mode:
-        enum:
-          - none
-          - self_hosted
-          - openai_hosted
-        type: string
+        $ref: '#/definitions/v1.RuntimeObservationMode'
       object:
         enum:
           - agent.runtime_observation
@@ -2967,11 +2960,7 @@ definitions:
         type: integer
         x-nullable: true
       status:
-        enum:
-          - observed
-          - unsupported
-          - unavailable
-        type: string
+        $ref: '#/definitions/v1.RuntimeObservationStatus'
     required:
       - allocation_created_at
       - cpu
@@ -2990,6 +2979,40 @@ definitions:
       - started_at
       - status
     type: object
+  v1.RuntimeObservationLifecycleState:
+    enum:
+      - active
+      - sleeping
+      - transitioning
+      - pending
+      - stopped
+    type: string
+    x-enum-varnames:
+      - RuntimeLifecycleActive
+      - RuntimeLifecycleSleeping
+      - RuntimeLifecycleTransitioning
+      - RuntimeLifecyclePending
+      - RuntimeLifecycleStopped
+  v1.RuntimeObservationMode:
+    enum:
+      - none
+      - self_hosted
+      - openai_hosted
+    type: string
+    x-enum-varnames:
+      - RuntimeModeNone
+      - RuntimeModeSelfHosted
+      - RuntimeModeManaged
+  v1.RuntimeObservationStatus:
+    enum:
+      - observed
+      - unsupported
+      - unavailable
+    type: string
+    x-enum-varnames:
+      - RuntimeStatusObserved
+      - RuntimeStatusUnsupported
+      - RuntimeStatusUnavailable
   v1.SavedAgent:
     properties:
       created_at:

contracts/agents-api/v1/runtime_observations.go

@@ -1,28 +1,62 @@
 package v1
 
+type RuntimeObservationMode string
+
+const (
+	RuntimeModeNone       RuntimeObservationMode = "none"
+	RuntimeModeSelfHosted RuntimeObservationMode = "self_hosted"
+	RuntimeModeManaged    RuntimeObservationMode = "openai_hosted"
+)
+
+type RuntimeObservationStatus string
+
+const (
+	RuntimeStatusObserved    RuntimeObservationStatus = "observed"
+	RuntimeStatusUnsupported RuntimeObservationStatus = "unsupported"
+	RuntimeStatusUnavailable RuntimeObservationStatus = "unavailable"
+)
+
+type RuntimeObservationLifecycleState string
+
+const (
+	RuntimeLifecycleActive        RuntimeObservationLifecycleState = "active"
+	RuntimeLifecycleSleeping      RuntimeObservationLifecycleState = "sleeping"
+	RuntimeLifecycleTransitioning RuntimeObservationLifecycleState = "transitioning"
+	RuntimeLifecyclePending       RuntimeObservationLifecycleState = "pending"
+	RuntimeLifecycleStopped       RuntimeObservationLifecycleState = "stopped"
+)
+
+type RuntimeInstanceKind string
+
+const (
+	RuntimeInstanceManagedAllocation    RuntimeInstanceKind = "managed_allocation"
+	RuntimeInstanceSelfHostedConnection RuntimeInstanceKind = "self_hosted_connection"
+	RuntimeInstanceNone                 RuntimeInstanceKind = "none"
+)
+
 type RuntimeObservation struct {
-	ID                  string                    `json:"id" binding:"required" format:"uuid"`
-	Object              string                    `json:"object" enums:"agent.runtime_observation" binding:"required"`
-	SessionID           string                    `json:"session_id" binding:"required" format:"uuid"`
-	EnvironmentID       *string                   `json:"environment_id" extensions:"x-nullable" binding:"required" format:"uuid"`
-	Mode                string                    `json:"mode" enums:"none,self_hosted,openai_hosted" binding:"required"`
-	ProviderType        *string                   `json:"provider_type" extensions:"x-nullable" binding:"required" pattern:"^[a-z][a-z0-9_]{0,31}$"`
-	Instance            RuntimeInstance           `json:"instance" binding:"required"`
-	LifecycleState      *string                   `json:"lifecycle_state" extensions:"x-nullable" binding:"required" enums:"active,sleeping,transitioning,pending,stopped"`
-	Status              string                    `json:"status" enums:"observed,unsupported,unavailable" binding:"required"`
-	Reason              *string                   `json:"reason" extensions:"x-nullable" binding:"required" pattern:"^[a-z][a-z0-9_]{0,95}(?![\\s\\S])"`
-	AllocationCreatedAt *int64                    `json:"allocation_created_at" extensions:"x-nullable" binding:"required" minimum:"0"`
-	ResolvedAt          int64                     `json:"resolved_at" binding:"required" minimum:"0"`
-	ObservedAt          *int64                    `json:"observed_at" extensions:"x-nullable" binding:"required" minimum:"0"`
-	StartedAt           *int64                    `json:"started_at" extensions:"x-nullable" binding:"required" minimum:"0"`
-	CPU                 *RuntimeCPUObservation    `json:"cpu" extensions:"x-nullable" binding:"required"`
-	Memory              *RuntimeMemoryObservation `json:"memory" extensions:"x-nullable" binding:"required"`
+	ID                  string                            `json:"id" binding:"required" format:"uuid"`
+	Object              string                            `json:"object" enums:"agent.runtime_observation" binding:"required"`
+	SessionID           string                            `json:"session_id" binding:"required" format:"uuid"`
+	EnvironmentID       *string                           `json:"environment_id" extensions:"x-nullable" binding:"required" format:"uuid"`
+	Mode                RuntimeObservationMode            `json:"mode" binding:"required"`
+	ProviderType        *string                           `json:"provider_type" extensions:"x-nullable" binding:"required" pattern:"^[a-z][a-z0-9_]{0,31}$"`
+	Instance            RuntimeInstance                   `json:"instance" binding:"required"`
+	LifecycleState      *RuntimeObservationLifecycleState `json:"lifecycle_state" extensions:"x-nullable" binding:"required"`
+	Status              RuntimeObservationStatus          `json:"status" binding:"required"`
+	Reason              *string                           `json:"reason" extensions:"x-nullable" binding:"required" pattern:"^[a-z][a-z0-9_]{0,95}(?![\\s\\S])"`
+	AllocationCreatedAt *int64                            `json:"allocation_created_at" extensions:"x-nullable" binding:"required" minimum:"0"`
+	ResolvedAt          int64                             `json:"resolved_at" binding:"required" minimum:"0"`
+	ObservedAt          *int64                            `json:"observed_at" extensions:"x-nullable" binding:"required" minimum:"0"`
+	StartedAt           *int64                            `json:"started_at" extensions:"x-nullable" binding:"required" minimum:"0"`
+	CPU                 *RuntimeCPUObservation            `json:"cpu" extensions:"x-nullable" binding:"required"`
+	Memory              *RuntimeMemoryObservation         `json:"memory" extensions:"x-nullable" binding:"required"`
 }
 
 type RuntimeInstance struct {
-	Kind                 string  `json:"kind" enums:"managed_allocation,self_hosted_connection,none" binding:"required"`
-	AllocationID         *string `json:"allocation_id" extensions:"x-nullable" binding:"required" format:"uuid"`
-	ConnectionGeneration *string `json:"connection_generation" extensions:"x-nullable" binding:"required" format:"uuid"`
+	Kind                 RuntimeInstanceKind `json:"kind" binding:"required"`
+	AllocationID         *string             `json:"allocation_id" extensions:"x-nullable" binding:"required" format:"uuid"`
+	ConnectionGeneration *string             `json:"connection_generation" extensions:"x-nullable" binding:"required" format:"uuid"`
 }
 
 type RuntimeCPUObservation struct {

packages/agents-client/src/generated/core-api.ts

@@ -31,25 +31,19 @@ export interface AdminRuntimeObservationDetail {
   environment_id: string | null;
   id: string;
   instance: RuntimeInstance;
-  lifecycle_state: AdminRuntimeObservationDetailLifecycleState | null;
+  lifecycle_state: RuntimeObservationLifecycleState | null;
   memory: RuntimeMemoryObservation | null;
-  mode: AdminRuntimeObservationDetailMode;
+  mode: RuntimeObservationMode;
   object: "agent.runtime_observation";
   observed_at: number | null;
   provider_type: string | null;
   reason: string | null;
   resolved_at: number;
   session_id: string;
   started_at: number | null;
-  status: AdminRuntimeObservationDetailStatus;
+  status: RuntimeObservationStatus;
 }
 export const adminRuntimeObservationDetailFields = ["allocation_created_at", "cpu", "disk", "environment_id", "id", "instance", "lifecycle_state", "memory", "mode", "object", "observed_at", "provider_type", "reason", "resolved_at", "session_id", "started_at", "status"] as const;
-export const adminRuntimeObservationDetailLifecycleStateValues = ["active", "sleeping", "transitioning", "pending", "stopped"] as const;
-export type AdminRuntimeObservationDetailLifecycleState = (typeof adminRuntimeObservationDetailLifecycleStateValues)[number];
-export const adminRuntimeObservationDetailModeValues = ["none", "self_hosted", "openai_hosted"] as const;
-export type AdminRuntimeObservationDetailMode = (typeof adminRuntimeObservationDetailModeValues)[number];
-export const adminRuntimeObservationDetailStatusValues = ["observed", "unsupported", "unavailable"] as const;
-export type AdminRuntimeObservationDetailStatus = (typeof adminRuntimeObservationDetailStatusValues)[number];
 export interface AdminRuntimeObservationList {
   data: AdminRuntimeObservation[];
   first_id: string | null;
@@ -112,6 +106,8 @@ export interface AdminauditPage {
   next_cursor: string;
 }
 export const adminauditPageFields = ["data", "has_more", "next_cursor"] as const;
+export const allocationDiagnosticValues = ["", "node_unavailable", "resource_missing", "compute_unconfirmed", "ownership_mismatch", "provider_unavailable"] as const;
+export type AllocationDiagnostic = (typeof allocationDiagnosticValues)[number];
 export interface ConfigurationDiscoveryInput {
   configuration?: Record<string, unknown>;
   credential?: Record<string, unknown>;
@@ -429,7 +425,7 @@ export interface NodeAllocation {
   compute_phase_changed_at: string | null;
   created_at: string;
   deployment_generation: number;
-  diagnostic: NodeAllocationDiagnostic;
+  diagnostic: AllocationDiagnostic;
   environment_id: string;
   id: string;
   initialization: string;
@@ -439,8 +435,6 @@ export interface NodeAllocation {
   tenant_id: string;
 }
 export const nodeAllocationFields = ["compute_phase", "compute_phase_changed_at", "created_at", "deployment_generation", "diagnostic", "environment_id", "id", "initialization", "node_id", "session_id", "state", "tenant_id"] as const;
-export const nodeAllocationDiagnosticValues = ["", "node_unavailable", "resource_missing", "compute_unconfirmed", "ownership_mismatch", "provider_unavailable"] as const;
-export type NodeAllocationDiagnostic = (typeof nodeAllocationDiagnosticValues)[number];
 export interface NodeDetail {
   active: number;
   available_disk_bytes: number | null;

packages/agents-client/src/sandbox-client.ts

@@ -4,7 +4,7 @@ import { deploymentContract } from "./deployment-contract";
 import { hasOwn, isNonnegativeInteger, isOneOf, isRecord, onlyFields, sameResourceId, schemaFields } from "./response-projection";
 import {
   deploymentResourcesFields, deploymentSpecFields, deploymentSpecRequired, deploymentViewFields, deploymentModeValues, deploymentViewRequired,
-  hostHistoryFields, hostHistoryPointFields, nodeAllocationDiagnosticValues, nodeAllocationFields, nodeDetailFields, nodeDetailRequired,
+  hostHistoryFields, hostHistoryPointFields, allocationDiagnosticValues, nodeAllocationFields, nodeDetailFields, nodeDetailRequired,
   nodeDiagnosticCodeValues, nodeFields, nodeHostFields, nodeRequired, nodeRolloutFields, nodeRolloutRequired, nodeRolloutStateValues, resetModeValues,
   resetFields, resetOfflineNodeFields, resetRemainingFields, rolloutFields, rolloutNodesFields, rolloutStateValues, runtimeReleaseFields,
   sandboxAllocationListFields, sandboxNodeListFields, sandboxResourcesFields, sandboxResourcesRequired, suspensionFields,
@@ -218,7 +218,7 @@ function projectAllocations(value: unknown, nodeId: string): { data: SandboxAllo
   valid(Array.isArray(list.data));
   return { data: (list.data as unknown[]).map((entry) => {
     const allocation = members(entry, nodeAllocationFields);
-    valid(isNonnegativeInteger(allocation.deployment_generation) && strings(allocation, allocationStrings) && sameResourceId(allocation.node_id as string, nodeId) && isOneOf(nodeAllocationDiagnosticValues, allocation.diagnostic) &&
+    valid(isNonnegativeInteger(allocation.deployment_generation) && strings(allocation, allocationStrings) && sameResourceId(allocation.node_id as string, nodeId) && isOneOf(allocationDiagnosticValues, allocation.diagnostic) &&
       nullable(timestamp)(allocation.compute_phase_changed_at) && timestamp(allocation.created_at));
     return { ...allocation } as unknown as SandboxAllocation;
   }) };

services/core/internal/api/admin_runtime_test.go

@@ -9,6 +9,7 @@ import (
 	"testing"
 	"time"
 
+	v1 "github.com/MiniMax-AI/OpenAgentCore/contracts/agents-api/v1"
 	"github.com/MiniMax-AI/OpenAgentCore/services/core/internal/projects"
 	"github.com/MiniMax-AI/OpenAgentCore/services/core/internal/runtimeobs"
 	"github.com/MiniMax-AI/OpenAgentCore/services/core/internal/sessions"
@@ -65,8 +66,8 @@ func TestAdminRuntimeRoutesRejectHead(t *testing.T) {
 
 func unsupportedObservation(session string, at time.Time) runtimeobs.Observation {
 	return runtimeobs.Observation{
-		Target: runtimeobs.Target{SessionID: session, Mode: runtimeobs.ModeNone},
-		Status: runtimeobs.StatusUnsupported, Reason: "runtime_mode_not_observable", ResolvedAt: at,
+		Target: runtimeobs.Target{SessionID: session, Mode: v1.RuntimeModeNone},
+		Status: v1.RuntimeStatusUnsupported, Reason: "runtime_mode_not_observable", ResolvedAt: at,
 	}
 }
 
@@ -130,7 +131,7 @@ func TestAdminRuntimeObservationListRejectsWholePageOnIntegrityFailure(t *testin
 	valid, invalid := uuid.NewString(), uuid.NewString()
 	service := runtimeObservationServiceFunc(func(_ context.Context, _, session string) (runtimeobs.Observation, error) {
 		if session == invalid {
-			return runtimeobs.Observation{Target: runtimeobs.Target{Mode: runtimeobs.ModeNone}, Status: runtimeobs.StatusUnsupported, ResolvedAt: now}, nil
+			return runtimeobs.Observation{Target: runtimeobs.Target{Mode: v1.RuntimeModeNone}, Status: v1.RuntimeStatusUnsupported, ResolvedAt: now}, nil
 		}
 		return unsupportedObservation(session, now), nil
 	})