Implement AgentCapability CRD for service registration

## Summary

Define and implement the `AgentCapability` Custom Resource Definition (CRD) - a Kubernetes-native way to represent services that can be registered on-chain via ERC-8004.

## Background

The orchestrator needs a Kubernetes-native mechanism to discover and track services deployed in the stack. Following established patterns (ServiceMonitor for Prometheus, Certificate for cert-manager), we'll use a CRD that:

1. Networks emit when deployed (e.g., ethereum creates an RPC capability)
2. The orchestrator controller watches and reconciles
3. Drives ERC-8004 registration and HTTPRoute generation

See [Orchestrator PRD](./docs/prd-orchestrator.md) for full context.

## Requirements

### Must Have
- [ ] Define `AgentCapability` CRD schema (v1alpha1)
- [ ] Deploy CRD to cluster during `obol stack up`
- [ ] Support capability types: `rpc`, `inference`, `fine-tune`, `validator`
- [ ] Include pricing specification (model, amount, asset, network)
- [ ] Include endpoint specification (service, port, path)
- [ ] Include `publish` flag to control visibility
- [ ] Status subresource for registration state

### Should Have
- [ ] Validation webhooks for enum fields
- [ ] Default values for common fields
- [ ] Short name (`acap`) for kubectl

### Nice to Have
- [ ] Printer columns for `kubectl get agentcapabilities`
- [ ] OpenAPI schema documentation

## CRD Specification

```yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: agentcapabilities.obol.network
  annotations:
    controller-gen.kubebuilder.io/version: v0.14.0
spec:
  group: obol.network
  names:
    plural: agentcapabilities
    singular: agentcapability
    kind: AgentCapability
    shortNames:
      - acap
  scope: Namespaced
  versions:
    - name: v1alpha1
      served: true
      storage: true
      subresources:
        status: {}
      additionalPrinterColumns:
        - name: Type
          type: string
          jsonPath: .spec.type
        - name: Published
          type: boolean
          jsonPath: .spec.publish
        - name: Registered
          type: boolean
          jsonPath: .status.registered
        - name: Age
          type: date
          jsonPath: .metadata.creationTimestamp
      schema:
        openAPIV3Schema:
          type: object
          required:
            - spec
          properties:
            spec:
              type: object
              required:
                - type
                - endpoint
              properties:
                type:
                  type: string
                  description: "Type of capability being offered"
                  enum:
                    - rpc
                    - inference
                    - fine-tune
                    - validator
                protocol:
                  type: string
                  description: "Protocol identifier (e.g., ethereum-json-rpc, openai-chat)"
                chain:
                  type: object
                  description: "Blockchain network details (for rpc type)"
                  properties:
                    id:
                      type: integer
                      description: "Chain ID (e.g., 1 for mainnet)"
                    name:
                      type: string
                      description: "Human-readable network name"
                pricing:
                  type: object
                  description: "Payment requirements for this capability"
                  properties:
                    model:
                      type: string
                      description: "Pricing model"
                      enum:
                        - per-request
                        - per-token
                        - per-epoch
                        - per-hour
                        - free
                      default: per-request
                    amount:
                      type: string
                      description: "Price amount in asset units (e.g., '0.0001')"
                      default: "0"
                    asset:
                      type: string
                      description: "Payment asset symbol"
                      default: "USDC"
                    network:
                      type: string
                      description: "Payment network (e.g., base, base-sepolia)"
                      default: "base-sepolia"
                endpoint:
                  type: object
                  required:
                    - service
                    - port
                  description: "Kubernetes service endpoint"
                  properties:
                    service:
                      type: string
                      description: "Kubernetes service name"
                    port:
                      type: integer
                      description: "Service port number"
                    path:
                      type: string
                      description: "URL path prefix"
                      default: "/"
                publish:
                  type: boolean
                  description: "Whether to publish this capability to ERC-8004"
                  default: true
            status:
              type: object
              properties:
                registered:
                  type: boolean
                  description: "Whether capability is registered on-chain"
                agentId:
                  type: integer
                  description: "ERC-8004 agent NFT ID"
                registryTxHash:
                  type: string
                  description: "Transaction hash of registration"
                tunnelPath:
                  type: string
                  description: "Public URL path via cloudflared"
                httpRouteName:
                  type: string
                  description: "Generated HTTPRoute resource name"
                lastSync:
                  type: string
                  format: date-time
                  description: "Last successful reconciliation"
                conditions:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                      status:
                        type: string
                      lastTransitionTime:
                        type: string
                        format: date-time
                      reason:
                        type: string
                      message:
                        type: string
```

## Example Resources

### Ethereum RPC Capability

```yaml
apiVersion: obol.network/v1alpha1
kind: AgentCapability
metadata:
  name: execution-rpc
  namespace: ethereum-knowing-wahoo
spec:
  type: rpc
  protocol: ethereum-json-rpc
  chain:
    id: 1
    name: mainnet
  pricing:
    model: per-request
    amount: "0.0001"
    asset: USDC
    network: base-sepolia
  endpoint:
    service: ethereum-execution-reth-mainnet
    port: 8545
    path: /
  publish: true
```

### Inference Capability

```yaml
apiVersion: obol.network/v1alpha1
kind: AgentCapability
metadata:
  name: llama-inference
  namespace: unsloth
spec:
  type: inference
  protocol: openai-chat
  pricing:
    model: per-token
    amount: "0.00001"
    asset: USDC
    network: base-sepolia
  endpoint:
    service: unsloth-api
    port: 8000
    path: /v1/chat/completions
  publish: true
```

### Fine-tuning Capability

```yaml
apiVersion: obol.network/v1alpha1
kind: AgentCapability
metadata:
  name: unsloth-finetune
  namespace: unsloth
spec:
  type: fine-tune
  protocol: unsloth-v1
  pricing:
    model: per-epoch
    amount: "1.00"
    asset: USDC
    network: base-sepolia
  endpoint:
    service: unsloth-api
    port: 8000
    path: /v1/fine-tune
  publish: true
```

## Implementation

### Option A: Static YAML (MVP)

Add CRD manifest to `internal/embed/infrastructure/`:

```
internal/embed/infrastructure/
├── helmfile.yaml
├── crds/
│   └── agentcapability-crd.yaml  # NEW
└── ...
```

Deploy via raw chart in helmfile:
```yaml
- name: obol-crds
  namespace: kube-system
  chart: bedag/raw
  values:
    - resources:
        - {{ readFile "crds/agentcapability-crd.yaml" | nindent 10 }}
```

### Option B: Controller-gen (Production)

Use kubebuilder/controller-gen for type-safe Go types:

```go
// internal/api/v1alpha1/agentcapability_types.go
package v1alpha1

import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:printcolumn:name="Type",type=string,JSONPath=`.spec.type`
// +kubebuilder:printcolumn:name="Published",type=boolean,JSONPath=`.spec.publish`
// +kubebuilder:printcolumn:name="Registered",type=boolean,JSONPath=`.status.registered`

type AgentCapability struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec   AgentCapabilitySpec   `json:"spec,omitempty"`
    Status AgentCapabilityStatus `json:"status,omitempty"`
}

type AgentCapabilitySpec struct {
    Type     CapabilityType `json:"type"`
    Protocol string         `json:"protocol,omitempty"`
    Chain    *ChainSpec     `json:"chain,omitempty"`
    Pricing  *PricingSpec   `json:"pricing,omitempty"`
    Endpoint EndpointSpec   `json:"endpoint"`
    Publish  bool           `json:"publish,omitempty"`
}

// +kubebuilder:validation:Enum=rpc;inference;fine-tune;validator
type CapabilityType string

// ... rest of types
```

**Recommendation**: Start with Option A for MVP, migrate to Option B when building the controller.

## Files to Create/Modify

- `internal/embed/infrastructure/crds/agentcapability-crd.yaml` - CRD manifest
- `internal/embed/infrastructure/helmfile.yaml` - Add CRD deployment
- `internal/embed/networks/ethereum/helmfile.yaml.gotmpl` - Emit AgentCapability on install
- `internal/embed/networks/helios/helmfile.yaml.gotmpl` - Emit AgentCapability on install
- `internal/embed/networks/aztec/helmfile.yaml.gotmpl` - Emit AgentCapability on install

## Testing

```bash
# Deploy stack with CRD
obol stack up

# Verify CRD registered
obol kubectl get crd agentcapabilities.obol.network

# Install network (should create AgentCapability)
obol network install ethereum --network=mainnet

# List capabilities
obol kubectl get agentcapabilities -A
# or
obol kubectl get acap -A

# Describe capability
obol kubectl describe acap execution-rpc -n ethereum-<id>
```

## Dependencies

- Depends on: None (can be done in parallel with Traefik migration)
- Blocks: Orchestrator controller implementation

## Related

- #125 - Replace nginx-ingress with Traefik + Gateway API
- [Orchestrator PRD](./docs/prd-orchestrator.md)
- [Kubernetes CRD Documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)


Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Implement AgentCapability CRD for service registration #126

Summary

Background

Requirements

Must Have

Should Have

Nice to Have

CRD Specification

Example Resources

Ethereum RPC Capability

Inference Capability

Fine-tuning Capability

Implementation

Option A: Static YAML (MVP)

Option B: Controller-gen (Production)

Files to Create/Modify

Testing

Dependencies

Related

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Implement AgentCapability CRD for service registration #126

Description

Summary

Background

Requirements

Must Have

Should Have

Nice to Have

CRD Specification

Example Resources

Ethereum RPC Capability

Inference Capability

Fine-tuning Capability

Implementation

Option A: Static YAML (MVP)

Option B: Controller-gen (Production)

Files to Create/Modify

Testing

Dependencies

Related

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions