feat(agents): add versioned soul prompts across AI and built-in runtimes

api/v1alpha1/agent_types.go

@@ -15,7 +15,6 @@ import (
 
 // AgentSpec defines the desired state of Agent
 // +kubebuilder:validation:XValidation:rule="!has(self.execution) || !has(self.execution.workspace) || !has(self.execution.workspace.classRef)",message="execution.workspace.classRef is only supported on Task specs"
-// +kubebuilder:validation:XValidation:rule="!(has(self.runtime) && has(self.runtime.type) && self.runtime.type == 'opencode' && has(self.runtime.contractVersion) && self.runtime.contractVersion == 'orka.harness.v2' && has(self.systemPrompt) && ((has(self.systemPrompt.inline) && self.systemPrompt.inline.size() > 0) || has(self.systemPrompt.configMapRef)))",message="opencode orka.harness.v2 runtime does not support spec.systemPrompt"
 type AgentSpec struct {
 	// ProviderRef references a Provider CRD for LLM configuration
 	// If set, model.provider is optional (inherited from Provider)
@@ -31,6 +30,11 @@ type AgentSpec struct {
 	// +optional
 	SystemPrompt *PromptSource `json:"systemPrompt,omitempty"`
 
+	// Soul supplies persistent persona and communication defaults, separate from the role prompt.
+	// Supported by AI workers and built-in harness v2 runtimes, not runtimeRef runtimes.
+	// +optional
+	Soul *SoulSource `json:"soul,omitempty"`
+
 	// Tools lists the default tools available to this agent
 	// +optional
 	Tools []ToolReference `json:"tools,omitempty"`
@@ -215,6 +219,28 @@ type PromptSource struct {
 	ConfigMapRef *ConfigMapKeySelector `json:"configMapRef,omitempty"`
 }
 
+// SoulSource is non-secret, versioned persona text. ConfigMap sources require an
+// expected content digest so replacing a named ConfigMap cannot publish a new soul.
+// +kubebuilder:validation:XValidation:rule="(has(self.inline) && self.inline.size() > 0) != has(self.configMapRef)",message="soul must use exactly one of inline or configMapRef"
+// +kubebuilder:validation:XValidation:rule="!has(self.configMapRef) || (has(self.digest) && self.digest.size() > 0)",message="ConfigMap-backed souls require an expected digest"
+type SoulSource struct {
+	// Inline is UTF-8 Markdown, limited to 8192 bytes by the controller.
+	// +kubebuilder:validation:MaxLength=8192
+	// +optional
+	Inline string `json:"inline,omitempty"`
+
+	// ConfigMapRef selects non-secret text in the Agent's namespace.
+	// +optional
+	ConfigMapRef *ConfigMapKeySelector `json:"configMapRef,omitempty"`
+
+	// Digest is the expected SHA-256 digest of the exact UTF-8 source bytes.
+	// Required for ConfigMap sources; optional for inline text.
+	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
+	// +kubebuilder:validation:MaxLength=71
+	// +optional
+	Digest string `json:"digest,omitempty"`
+}
+
 // ConfigMapKeySelector selects a key from a ConfigMap
 type ConfigMapKeySelector struct {
 	// Name is the name of the ConfigMap

api/v1alpha1/task_types.go

@@ -428,6 +428,7 @@ type SkillReference struct {
 // TaskStatus defines the observed state of Task
 // +kubebuilder:validation:XValidation:rule="!has(oldSelf.executionOutcome) || self.executionOutcome == oldSelf.executionOutcome",message="executionOutcome is immutable once recorded"
 // +kubebuilder:validation:XValidation:rule="!has(oldSelf.agentExecutionBinding) || (has(self.agentExecutionBinding) && self.agentExecutionBinding == oldSelf.agentExecutionBinding)",message="agentExecutionBinding is write-once and immutable"
+// +kubebuilder:validation:XValidation:rule="!has(oldSelf.soulBinding) || (has(self.soulBinding) && self.soulBinding == oldSelf.soulBinding)",message="soulBinding is write-once and immutable"
 // +kubebuilder:validation:XValidation:rule="!has(self.agentExecutionBinding) || self.agentExecutionBinding.contractVersion != 'orka.harness.v1' || ((!has(self.execution) || (has(oldSelf.execution) && self.execution == oldSelf.execution)) && (!has(self.delivery) || (has(oldSelf.delivery) && self.delivery == oldSelf.delivery)))",message="a v1-bound Task cannot acquire new v2 execution or delivery state"
 // +kubebuilder:validation:XValidation:rule="!has(self.agentExecutionBinding) || self.agentExecutionBinding.contractVersion != 'orka.harness.v2' || !has(self.harnessRuntime) || (has(oldSelf.harnessRuntime) && self.harnessRuntime == oldSelf.harnessRuntime)",message="a v2-bound Task cannot acquire new v1 harness state"
 type TaskStatus struct {
@@ -486,6 +487,11 @@ type TaskStatus struct {
 	// +optional
 	AgentExecutionBinding *AgentExecutionBinding `json:"agentExecutionBinding,omitempty"`
 
+	// SoulBinding pins an AI Task's resolved persona and role prompt. It contains
+	// digests only, never prompt text. Retries reject configuration drift.
+	// +optional
+	SoulBinding *TaskSoulBinding `json:"soulBinding,omitempty"`
+
 	// ExecutionOutcome records the immutable outcome of a non-ACP workload before
 	// provider-neutral execution-workspace finalization completes.
 	// +optional
@@ -528,6 +534,27 @@ type TaskStatus struct {
 	NextScheduleTime *metav1.Time `json:"nextScheduleTime,omitempty"`
 }
 
+// TaskSoulBinding is the non-secret, write-once identity of AI prompt configuration.
+type TaskSoulBinding struct {
+	// TaskGeneration is the Task spec generation whose prompt was resolved.
+	// +kubebuilder:validation:Minimum=1
+	TaskGeneration int64 `json:"taskGeneration"`
+	// AgentUID and AgentGeneration identify the exact Agent revision.
+	// +kubebuilder:validation:MinLength=1
+	// +kubebuilder:validation:MaxLength=128
+	AgentUID string `json:"agentUID"`
+	// +kubebuilder:validation:Minimum=1
+	AgentGeneration int64 `json:"agentGeneration"`
+	// SoulDigest identifies the exact persona source bytes.
+	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
+	// +kubebuilder:validation:MaxLength=71
+	SoulDigest string `json:"soulDigest"`
+	// PromptDigest identifies the composed role and persona prompt.
+	// +kubebuilder:validation:Pattern=`^sha256:[0-9a-f]{64}$`
+	// +kubebuilder:validation:MaxLength=71
+	PromptDigest string `json:"promptDigest"`
+}
+
 // TaskWorkloadExecutionOutcome records the immutable result of non-ACP workload
 // execution before provider-neutral workspace finalization. ACP agent attempts use
 // TaskStatus.Execution, whose stronger fencing and OutcomeUnknown semantics are
@@ -704,7 +731,7 @@ type ChildTaskStatus struct {
 // +kubebuilder:printcolumn:name="Priority",type=integer,JSONPath=`.spec.priority`
 // +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
 // +kubebuilder:selectablefield:JSONPath=.spec.sessionRef.name
-// +kubebuilder:validation:XValidation:rule="!has(oldSelf.status) || (!has(oldSelf.status.agentExecutionBinding) || self.spec == oldSelf.spec)",message="Task spec is immutable after execution authority is recorded"
+// +kubebuilder:validation:XValidation:rule="!has(oldSelf.status) || ((!has(oldSelf.status.agentExecutionBinding) && !has(oldSelf.status.soulBinding)) || self.spec == oldSelf.spec)",message="Task spec is immutable after execution authority is recorded"
 
 // Task is the Schema for the tasks API
 type Task struct {

cmd/main.go

@@ -1604,6 +1604,7 @@ func main() {
 			BearerTokenFile: acpProviderProxyTokenFile,
 		}
 		runtimePoolReconciler.Epochs = controllerEpochManager
+		runtimePoolReconciler.ControlStore = durableControlStore
 		runtimePoolReconciler.EnablePDB = true
 		runtimePoolReconciler.EnableTelemetry = enableTracing
 		runtimePoolReconciler.E2EPromptWriteAmbiguityMarker = acpE2EPromptWriteAmbiguityMarker

config/crd/bases/core.orka.ai_agents.yaml

@@ -1535,6 +1535,44 @@ spec:
                       type: string
                   type: object
                 type: array
+              soul:
+                description: |-
+                  Soul supplies persistent persona and communication defaults, separate from the role prompt.
+                  Supported by AI workers and built-in harness v2 runtimes, not runtimeRef runtimes.
+                properties:
+                  configMapRef:
+                    description: ConfigMapRef selects non-secret text in the Agent's
+                      namespace.
+                    properties:
+                      key:
+                        description: Key is the key within the ConfigMap
+                        type: string
+                      name:
+                        description: Name is the name of the ConfigMap
+                        type: string
+                    required:
+                    - key
+                    - name
+                    type: object
+                  digest:
+                    description: |-
+                      Digest is the expected SHA-256 digest of the exact UTF-8 source bytes.
+                      Required for ConfigMap sources; optional for inline text.
+                    maxLength: 71
+                    pattern: ^sha256:[0-9a-f]{64}$
+                    type: string
+                  inline:
+                    description: Inline is UTF-8 Markdown, limited to 8192 bytes by
+                      the controller.
+                    maxLength: 8192
+                    type: string
+                type: object
+                x-kubernetes-validations:
+                - message: soul must use exactly one of inline or configMapRef
+                  rule: (has(self.inline) && self.inline.size() > 0) != has(self.configMapRef)
+                - message: ConfigMap-backed souls require an expected digest
+                  rule: '!has(self.configMapRef) || (has(self.digest) && self.digest.size()
+                    > 0)'
               systemPrompt:
                 description: SystemPrompt defines the system prompt configuration
                 properties:
@@ -1586,11 +1624,6 @@ spec:
             x-kubernetes-validations:
             - message: execution.workspace.classRef is only supported on Task specs
               rule: '!has(self.execution) || !has(self.execution.workspace) || !has(self.execution.workspace.classRef)'
-            - message: opencode orka.harness.v2 runtime does not support spec.systemPrompt
-              rule: '!(has(self.runtime) && has(self.runtime.type) && self.runtime.type
-                == ''opencode'' && has(self.runtime.contractVersion) && self.runtime.contractVersion
-                == ''orka.harness.v2'' && has(self.systemPrompt) && ((has(self.systemPrompt.inline)
-                && self.systemPrompt.inline.size() > 0) || has(self.systemPrompt.configMapRef)))'
           status:
             description: AgentStatus defines the observed state of Agent
             properties:

config/crd/bases/core.orka.ai_tasks.yaml

@@ -3262,6 +3262,45 @@ spec:
                 required:
                 - available
                 type: object
+              soulBinding:
+                description: |-
+                  SoulBinding pins an AI Task's resolved persona and role prompt. It contains
+                  digests only, never prompt text. Retries reject configuration drift.
+                properties:
+                  agentGeneration:
+                    format: int64
+                    minimum: 1
+                    type: integer
+                  agentUID:
+                    description: AgentUID and AgentGeneration identify the exact Agent
+                      revision.
+                    maxLength: 128
+                    minLength: 1
+                    type: string
+                  promptDigest:
+                    description: PromptDigest identifies the composed role and persona
+                      prompt.
+                    maxLength: 71
+                    pattern: ^sha256:[0-9a-f]{64}$
+                    type: string
+                  soulDigest:
+                    description: SoulDigest identifies the exact persona source bytes.
+                    maxLength: 71
+                    pattern: ^sha256:[0-9a-f]{64}$
+                    type: string
+                  taskGeneration:
+                    description: TaskGeneration is the Task spec generation whose
+                      prompt was resolved.
+                    format: int64
+                    minimum: 1
+                    type: integer
+                required:
+                - agentGeneration
+                - agentUID
+                - promptDigest
+                - soulDigest
+                - taskGeneration
+                type: object
               startTime:
                 description: StartTime is when the task started running
                 format: date-time
@@ -3277,6 +3316,9 @@ spec:
             - message: agentExecutionBinding is write-once and immutable
               rule: '!has(oldSelf.agentExecutionBinding) || (has(self.agentExecutionBinding)
                 && self.agentExecutionBinding == oldSelf.agentExecutionBinding)'
+            - message: soulBinding is write-once and immutable
+              rule: '!has(oldSelf.soulBinding) || (has(self.soulBinding) && self.soulBinding
+                == oldSelf.soulBinding)'
             - message: a v1-bound Task cannot acquire new v2 execution or delivery
                 state
               rule: '!has(self.agentExecutionBinding) || self.agentExecutionBinding.contractVersion
@@ -3290,8 +3332,8 @@ spec:
         type: object
         x-kubernetes-validations:
         - message: Task spec is immutable after execution authority is recorded
-          rule: '!has(oldSelf.status) || (!has(oldSelf.status.agentExecutionBinding)
-            || self.spec == oldSelf.spec)'
+          rule: '!has(oldSelf.status) || ((!has(oldSelf.status.agentExecutionBinding)
+            && !has(oldSelf.status.soulBinding)) || self.spec == oldSelf.spec)'
     selectableFields:
     - jsonPath: .spec.sessionRef.name
     served: true