v1alpha1

package
v0.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 2, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package v1alpha1 contains API Schema definitions for the paddock v1alpha1 API group. +kubebuilder:object:generate=true +groupName=paddock.dev

Index

Constants

View Source 
const (
	AuditEventLabelRun       = "paddock.dev/run"
	AuditEventLabelDecision  = "paddock.dev/decision"
	AuditEventLabelKind      = "paddock.dev/kind"
	AuditEventLabelComponent = "paddock.dev/component"
)

Standard label keys on every AuditEvent, intended for ad-hoc queries (`kubectl get auditevents -l paddock.dev/run=…`). Keep in sync with the emitter code in the broker and proxy.

View Source 
const (
	BrokerPolicyConditionReady               = "Ready"
	BrokerPolicyConditionDiscoveryModeActive = "DiscoveryModeActive"
	BrokerPolicyConditionDiscoveryExpired    = "DiscoveryExpired"
)
View Source 
const (
	HarnessRunConditionTemplateResolved = "TemplateResolved"
	HarnessRunConditionWorkspaceBound   = "WorkspaceBound"
	HarnessRunConditionPromptResolved   = "PromptResolved"
	HarnessRunConditionJobCreated       = "JobCreated"
	HarnessRunConditionPodReady         = "PodReady"
	HarnessRunConditionCompleted        = "Completed"
	// BrokerReady indicates the broker issued every credential the
	// template's requires block declares. Wired in v0.3 M3 with the
	// broker skeleton.
	HarnessRunConditionBrokerReady = "BrokerReady"
	// EgressConfigured indicates the proxy sidecar's CA bundle is
	// mounted and the interception mode has been resolved (transparent
	// or cooperative). Wired in v0.3 M4 with the proxy sidecar.
	HarnessRunConditionEgressConfigured = "EgressConfigured"
	// BrokerCredentialsReady summarises whether all requires.credentials
	// were issued, and on True carries a short message like
	// "3 credentials issued: 2 proxy-injected, 1 in-container".
	HarnessRunConditionBrokerCredentialsReady = "BrokerCredentialsReady"
	// InterceptionUnavailable signals that the BrokerPolicy (explicitly
	// or by default) required transparent interception but the run's
	// namespace PSA or the manager's configuration cannot provide it.
	// The run is terminal Failed; no fallback to cooperative.
	HarnessRunConditionInterceptionUnavailable = "InterceptionUnavailable"
)

Condition types reported on HarnessRun.status.conditions.

View Source 
const (
	// HarnessRunConditionAttached is True when at least one client session
	// is currently attached to the Interactive run's prompt or shell
	// endpoint. Message breaks down session counts when more than one is
	// attached.
	HarnessRunConditionAttached = "Attached"
	// HarnessRunConditionIdle is True while the Interactive run is in the
	// Idle phase — pod alive, no prompt turn in progress.
	HarnessRunConditionIdle = "Idle"
	// HarnessRunConditionCredentialsRenewed is True after the broker has
	// completed at least one credential renewal for this Interactive run.
	HarnessRunConditionCredentialsRenewed = "CredentialsRenewed"
)

Condition types specific to Interactive HarnessRuns.

View Source 
const (
	WorkspaceConditionPVCBound = "PVCBound"
	WorkspaceConditionSeeded   = "Seeded"
	WorkspaceConditionReady    = "Ready"
)

Condition types reported on Workspace.status.conditions.

View Source 
const (
	HarnessTemplateConditionReady = "Ready"
)

Condition types for HarnessTemplate.

View Source 
const MaxInlinePromptBytes = 256 * 1024

MaxInlinePromptBytes caps spec.prompt at 256 KiB, well under the 1 MiB ConfigMap/Secret ceiling and leaving headroom for the materialisation wrapper. promptFrom sources are not size-checked at admission time — doing so would require cluster reads and make validation non-static; oversized Secret/ConfigMap-sourced prompts fail later at the reconciler's materialise step.

The CLI reuses this value to cap --prompt-file/stdin reads client-side (see internal/cli/submit.go) so an oversized file errors before being POSTed.

Variables

View Source 
var (
	// GroupVersion is group version used to register these objects.
	GroupVersion = schema.GroupVersion{Group: "paddock.dev", Version: "v1alpha1"}

	// SchemeBuilder is used to add go types to the GroupVersionKind scheme.
	SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion}

	// AddToScheme adds the types in this group-version to the given scheme.
	AddToScheme = SchemeBuilder.AddToScheme
)

Functions

This section is empty.

Types

type AuditCredentialRef 

type AuditCredentialRef struct {
	// Name is the credential's logical name (matches the template's
	// requires.credentials[*].name).
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Provider is the provider kind that handled (or would have handled)
	// the request. See ADR-0015.
	// +optional
	Provider string `json:"provider,omitempty"`

	// Purpose is the requested purpose ("llm", "gitforge", "generic").
	// +optional
	Purpose string `json:"purpose,omitempty"`
}

AuditCredentialRef names a logical credential involved in a decision.

func (*AuditCredentialRef) DeepCopy 

func (in *AuditCredentialRef) DeepCopy() *AuditCredentialRef

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new AuditCredentialRef.

func (*AuditCredentialRef) DeepCopyInto 

func (in *AuditCredentialRef) DeepCopyInto(out *AuditCredentialRef)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type AuditDecision 

type AuditDecision string

AuditDecision is the outcome recorded on an AuditEvent. +kubebuilder:validation:Enum=granted;denied;warned 

const (
	AuditDecisionGranted AuditDecision = "granted"
	AuditDecisionDenied  AuditDecision = "denied"
	AuditDecisionWarned  AuditDecision = "warned"
)

type AuditDestination 

type AuditDestination struct {
	// Host is the destination hostname.
	// +kubebuilder:validation:Required
	Host string `json:"host"`

	// Port is the destination TCP port.
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	// +optional
	Port int32 `json:"port,omitempty"`
}

AuditDestination describes an upstream target.

func (*AuditDestination) DeepCopy 

func (in *AuditDestination) DeepCopy() *AuditDestination

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new AuditDestination.

func (*AuditDestination) DeepCopyInto 

func (in *AuditDestination) DeepCopyInto(out *AuditDestination)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type AuditEvent 

type AuditEvent struct {
	metav1.TypeMeta `json:",inline"`
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`
	// +required
	Spec AuditEventSpec `json:"spec"`
}

AuditEvent records one security-relevant decision made by the broker, proxy, webhook, or reconciler. Write-once: spec is set at creation and immutable. A TTL reconciler in the controller-manager reaps events older than --audit-retention-days (default 30). See ADR-0016.

func (*AuditEvent) DeepCopy 

func (in *AuditEvent) DeepCopy() *AuditEvent

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new AuditEvent.

func (*AuditEvent) DeepCopyInto 

func (in *AuditEvent) DeepCopyInto(out *AuditEvent)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*AuditEvent) DeepCopyObject 

func (in *AuditEvent) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type AuditEventList 

type AuditEventList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []AuditEvent `json:"items"`
}

AuditEventList contains a list of AuditEvent.

func (*AuditEventList) DeepCopy 

func (in *AuditEventList) DeepCopy() *AuditEventList

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new AuditEventList.

func (*AuditEventList) DeepCopyInto 

func (in *AuditEventList) DeepCopyInto(out *AuditEventList)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*AuditEventList) DeepCopyObject 

func (in *AuditEventList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type AuditEventSpec 

type AuditEventSpec struct {
	// RunRef identifies the HarnessRun this decision pertains to. May be
	// empty for events emitted outside a run context (e.g. broker
	// startup diagnostics — not currently emitted).
	//
	// Names prefixed "seed-" denote a workspace-seed-time decision; the
	// suffix is the Workspace name (F-52).
	// +optional
	RunRef *LocalObjectReference `json:"runRef,omitempty"`

	// Decision is the outcome: granted, denied, or warned.
	// +kubebuilder:validation:Required
	Decision AuditDecision `json:"decision"`

	// Kind categorises the event. Shape of Destination, Credential, and
	// Policy fields depends on Kind.
	// +kubebuilder:validation:Required
	Kind AuditKind `json:"kind"`

	// Timestamp is when the decision was taken. Set by the emitter —
	// not metadata.creationTimestamp, which records when the object
	// landed in etcd (can lag materially under load).
	// +kubebuilder:validation:Required
	Timestamp metav1.Time `json:"timestamp"`

	// Destination is set for egress-* and credential-* kinds that target
	// an upstream service.
	// +optional
	Destination *AuditDestination `json:"destination,omitempty"`

	// Credential is set for credential-* kinds; names the logical
	// credential and the backing provider.
	// +optional
	Credential *AuditCredentialRef `json:"credential,omitempty"`

	// MatchedPolicy is the BrokerPolicy whose grant covered this
	// decision, or nil on a deny.
	// +optional
	MatchedPolicy *LocalObjectReference `json:"matchedPolicy,omitempty"`

	// Reason is a human-readable explanation. For denials, includes the
	// specific rule that failed.
	// +optional
	// +kubebuilder:validation:MaxLength=1024
	Reason string `json:"reason,omitempty"`

	// Count is the number of events collapsed into this record. Set
	// only for egress-block-summary and similar summary kinds; otherwise
	// implicitly 1.
	// +optional
	// +kubebuilder:validation:Minimum=1
	Count int32 `json:"count,omitempty"`

	// SampleDestinations carries up to three example destinations when
	// Kind is a summary. Purely diagnostic.
	// +optional
	// +kubebuilder:validation:MaxItems=3
	SampleDestinations []AuditDestination `json:"sampleDestinations,omitempty"`

	// WindowStart and WindowEnd delimit the time range a summary event
	// covers. Set only for summary kinds.
	// +optional
	WindowStart *metav1.Time `json:"windowStart,omitempty"`

	// +optional
	WindowEnd *metav1.Time `json:"windowEnd,omitempty"`

	// Detail carries kind-specific key-value pairs that do not fit the
	// structured fields above. Used by interactive lifecycle kinds
	// (prompt-submitted, shell-session-*, credential-renewal-failed,
	// interactive-run-terminated) and any future kinds that need
	// extensible metadata without CRD schema churn.
	// +optional
	Detail map[string]string `json:"detail,omitempty"`
}

AuditEventSpec records one security-relevant decision. Write-once: the admission webhook rejects updates to spec. Status is intentionally empty. See ADR-0016.

func (*AuditEventSpec) DeepCopy 

func (in *AuditEventSpec) DeepCopy() *AuditEventSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new AuditEventSpec.

func (*AuditEventSpec) DeepCopyInto 

func (in *AuditEventSpec) DeepCopyInto(out *AuditEventSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type AuditKind 

type AuditKind string

AuditKind names the category of a recorded decision. See spec 0002 §9 for the full taxonomy. +kubebuilder:validation:Enum=credential-issued;credential-denied;credential-renewed;credential-revoked;egress-allow;egress-block;egress-block-summary;egress-discovery-allow;policy-applied;policy-rejected;broker-unavailable;run-failed;run-completed;ca-projected;network-policy-enforcement-withdrawn;ca-misconfigured;broker-creds-tampered;interception-mode-cooperative-accepted;prompt-submitted;prompt-completed;shell-session-opened;shell-session-closed;credential-renewal-failed;interactive-run-terminated 

const (
	AuditKindCredentialIssued                  AuditKind = "credential-issued"
	AuditKindCredentialDenied                  AuditKind = "credential-denied"
	AuditKindCredentialRenewed                 AuditKind = "credential-renewed"
	AuditKindCredentialRevoked                 AuditKind = "credential-revoked"
	AuditKindEgressAllow                       AuditKind = "egress-allow"
	AuditKindEgressBlock                       AuditKind = "egress-block"
	AuditKindEgressBlockSummary                AuditKind = "egress-block-summary"
	AuditKindEgressDiscoveryAllow              AuditKind = "egress-discovery-allow"
	AuditKindPolicyApplied                     AuditKind = "policy-applied"
	AuditKindPolicyRejected                    AuditKind = "policy-rejected"
	AuditKindBrokerUnavailable                 AuditKind = "broker-unavailable"
	AuditKindRunFailed                         AuditKind = "run-failed"
	AuditKindRunCompleted                      AuditKind = "run-completed"
	AuditKindCAProjected                       AuditKind = "ca-projected"
	AuditKindNetworkPolicyEnforcementWithdrawn AuditKind = "network-policy-enforcement-withdrawn"
	AuditKindCAMisconfigured                   AuditKind = "ca-misconfigured"
	AuditKindBrokerCredsTampered               AuditKind = "broker-creds-tampered"
	// AuditKindInterceptionModeCooperativeAccepted is emitted once at proxy
	// startup when --mode=cooperative. Carries the BrokerPolicy reason for
	// the audit trail (F-19 residual).
	AuditKindInterceptionModeCooperativeAccepted AuditKind = "interception-mode-cooperative-accepted"

	AuditKindPromptSubmitted          AuditKind = "prompt-submitted"
	AuditKindPromptCompleted          AuditKind = "prompt-completed"
	AuditKindShellSessionOpened       AuditKind = "shell-session-opened"
	AuditKindShellSessionClosed       AuditKind = "shell-session-closed"
	AuditKindCredentialRenewalFailed  AuditKind = "credential-renewal-failed"
	AuditKindInteractiveRunTerminated AuditKind = "interactive-run-terminated"
)

type BasicAuthSubstitution 

type BasicAuthSubstitution struct {
	// +kubebuilder:validation:Required
	Username string `json:"username"`
}

BasicAuthSubstitution sets HTTP Basic authentication.

func (*BasicAuthSubstitution) DeepCopy 

func (in *BasicAuthSubstitution) DeepCopy() *BasicAuthSubstitution

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new BasicAuthSubstitution.

func (*BasicAuthSubstitution) DeepCopyInto 

func (in *BasicAuthSubstitution) DeepCopyInto(out *BasicAuthSubstitution)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type BrokerCredentialReference 

type BrokerCredentialReference struct {
	// Name of the broker-creds Secret (convention: <run>-broker-creds).
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Key inside Secret.Data. Matches the credential name declared on
	// the template's spec.requires.credentials.
	// +kubebuilder:validation:Required
	Key string `json:"key"`
}

BrokerCredentialReference names a Secret key inside the broker-issued credentials Secret (<run>-broker-creds). The value must be a Paddock bearer the proxy sidecar knows how to substitute.

func (*BrokerCredentialReference) DeepCopy 

func (in *BrokerCredentialReference) DeepCopy() *BrokerCredentialReference

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new BrokerCredentialReference.

func (*BrokerCredentialReference) DeepCopyInto 

func (in *BrokerCredentialReference) DeepCopyInto(out *BrokerCredentialReference)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type BrokerPolicy 

type BrokerPolicy struct {
	metav1.TypeMeta `json:",inline"`
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`
	// +required
	Spec BrokerPolicySpec `json:"spec"`
	// +optional
	Status BrokerPolicyStatus `json:"status,omitzero"`
}

BrokerPolicy declares the capabilities the broker will back for one or more templates in a namespace.

func (*BrokerPolicy) DeepCopy 

func (in *BrokerPolicy) DeepCopy() *BrokerPolicy

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new BrokerPolicy.

func (*BrokerPolicy) DeepCopyInto 

func (in *BrokerPolicy) DeepCopyInto(out *BrokerPolicy)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*BrokerPolicy) DeepCopyObject 

func (in *BrokerPolicy) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type BrokerPolicyGrants 

type BrokerPolicyGrants struct {
	// +optional
	Credentials []CredentialGrant `json:"credentials,omitempty"`
	// +optional
	Egress []EgressGrant `json:"egress,omitempty"`
	// +optional
	GitRepos []GitRepoGrant `json:"gitRepos,omitempty"`
	// Runs declares run-time interaction capabilities (interactive prompt
	// submission, shell open). Independent of Credentials, Egress,
	// GitRepos.
	// +optional
	Runs *GrantRunsCapabilities `json:"runs,omitempty"`
}

BrokerPolicyGrants enumerates the capabilities a BrokerPolicy backs.

func (*BrokerPolicyGrants) DeepCopy 

func (in *BrokerPolicyGrants) DeepCopy() *BrokerPolicyGrants

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new BrokerPolicyGrants.

func (*BrokerPolicyGrants) DeepCopyInto 

func (in *BrokerPolicyGrants) DeepCopyInto(out *BrokerPolicyGrants)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type BrokerPolicyList 

type BrokerPolicyList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []BrokerPolicy `json:"items"`
}

+kubebuilder:object:root=true

func (*BrokerPolicyList) DeepCopy 

func (in *BrokerPolicyList) DeepCopy() *BrokerPolicyList

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new BrokerPolicyList.

func (*BrokerPolicyList) DeepCopyInto 

func (in *BrokerPolicyList) DeepCopyInto(out *BrokerPolicyList)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*BrokerPolicyList) DeepCopyObject 

func (in *BrokerPolicyList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type BrokerPolicySpec 

type BrokerPolicySpec struct {
	// AppliesToTemplates is a list of template name globs this policy
	// will back. "*" matches any template name; explicit names tighten
	// the operator-consent story. At least one entry is required.
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:Required
	AppliesToTemplates []string `json:"appliesToTemplates"`

	// Grants enumerates the capabilities this policy is willing to back.
	// +kubebuilder:validation:Required
	Grants BrokerPolicyGrants `json:"grants"`

	// Interception selects the egress-proxy interception mode for runs
	// governed by this policy. Absent the field admission defaults to
	// requiring transparent mode; a run whose namespace PSA forbids
	// NET_ADMIN (baseline/restricted) then fails closed rather than
	// silently falling back to cooperative. Set
	// spec.interception.cooperativeAccepted to opt into the weaker mode
	// with a written reason.
	// +optional
	Interception *InterceptionSpec `json:"interception,omitempty"`

	// EgressDiscovery, when present, opens a time-bounded window during
	// which denied egress is allowed-but-logged. Admission rejects
	// expiresAt values in the past or more than 7 days in the future.
	// After the window closes, the BrokerPolicy reconciler sets
	// DiscoveryExpired=True and the HarnessRun admission webhook
	// rejects new runs governed by this policy until the operator
	// updates expiresAt or removes the field. See spec 0003 §3.6.
	// +optional
	EgressDiscovery *EgressDiscoverySpec `json:"egressDiscovery,omitempty"`
}

BrokerPolicySpec declares, for one namespace, which capabilities the broker is willing to back for a set of templates. See spec 0003.

func (*BrokerPolicySpec) DeepCopy 

func (in *BrokerPolicySpec) DeepCopy() *BrokerPolicySpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new BrokerPolicySpec.

func (*BrokerPolicySpec) DeepCopyInto 

func (in *BrokerPolicySpec) DeepCopyInto(out *BrokerPolicySpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type BrokerPolicyStatus 

type BrokerPolicyStatus struct {
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

BrokerPolicyStatus reports the observed state of a BrokerPolicy.

func (*BrokerPolicyStatus) DeepCopy 

func (in *BrokerPolicyStatus) DeepCopy() *BrokerPolicyStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new BrokerPolicyStatus.

func (*BrokerPolicyStatus) DeepCopyInto 

func (in *BrokerPolicyStatus) DeepCopyInto(out *BrokerPolicyStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ClusterHarnessTemplate 

type ClusterHarnessTemplate struct {
	metav1.TypeMeta `json:",inline"`
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`
	// +required
	Spec HarnessTemplateSpec `json:"spec"`
	// +optional
	Status ClusterHarnessTemplateStatus `json:"status,omitzero"`
}

ClusterHarnessTemplate is a cluster-scoped blueprint for running an agent harness. Typically published by a platform team and inherited by namespaced HarnessTemplates; see ADR-0003. The spec is shared with HarnessTemplate via HarnessTemplateSpec.

func (*ClusterHarnessTemplate) DeepCopy 

func (in *ClusterHarnessTemplate) DeepCopy() *ClusterHarnessTemplate

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ClusterHarnessTemplate.

func (*ClusterHarnessTemplate) DeepCopyInto 

func (in *ClusterHarnessTemplate) DeepCopyInto(out *ClusterHarnessTemplate)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*ClusterHarnessTemplate) DeepCopyObject 

func (in *ClusterHarnessTemplate) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type ClusterHarnessTemplateList 

type ClusterHarnessTemplateList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []ClusterHarnessTemplate `json:"items"`
}

ClusterHarnessTemplateList contains a list of ClusterHarnessTemplate.

func (*ClusterHarnessTemplateList) DeepCopy 

func (in *ClusterHarnessTemplateList) DeepCopy() *ClusterHarnessTemplateList

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ClusterHarnessTemplateList.

func (*ClusterHarnessTemplateList) DeepCopyInto 

func (in *ClusterHarnessTemplateList) DeepCopyInto(out *ClusterHarnessTemplateList)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*ClusterHarnessTemplateList) DeepCopyObject 

func (in *ClusterHarnessTemplateList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type ClusterHarnessTemplateStatus 

type ClusterHarnessTemplateStatus struct {
	// ObservedGeneration is the last spec generation reconciled.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest observations of the template's state.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

ClusterHarnessTemplateStatus reports the observed state of a ClusterHarnessTemplate.

func (*ClusterHarnessTemplateStatus) DeepCopy 

func (in *ClusterHarnessTemplateStatus) DeepCopy() *ClusterHarnessTemplateStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ClusterHarnessTemplateStatus.

func (*ClusterHarnessTemplateStatus) DeepCopyInto 

func (in *ClusterHarnessTemplateStatus) DeepCopyInto(out *ClusterHarnessTemplateStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type CooperativeAcceptedInterception 

type CooperativeAcceptedInterception struct {
	// Accepted must be true.
	// +kubebuilder:validation:Required
	Accepted bool `json:"accepted"`

	// Reason explains why cooperative interception is necessary instead
	// of transparent. Typical reasons include cluster PSA=restricted
	// without a node-level DaemonSet proxy.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=20
	// +kubebuilder:validation:MaxLength=500
	Reason string `json:"reason"`
}

CooperativeAcceptedInterception opts the BrokerPolicy into cooperative interception, which is weaker than transparent because an agent can unset HTTPS_PROXY to bypass it. The user documents why that weakening is acceptable in Reason.

func (*CooperativeAcceptedInterception) DeepCopy 

func (in *CooperativeAcceptedInterception) DeepCopy() *CooperativeAcceptedInterception

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CooperativeAcceptedInterception.

func (*CooperativeAcceptedInterception) DeepCopyInto 

func (in *CooperativeAcceptedInterception) DeepCopyInto(out *CooperativeAcceptedInterception)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type CredentialGrant 

type CredentialGrant struct {
	// +kubebuilder:validation:Required
	Name string `json:"name"`
	// +kubebuilder:validation:Required
	Provider ProviderConfig `json:"provider"`
}

CredentialGrant supplies a provider + configuration for one logical credential name declared by templates' requires.credentials[*].name.

func (*CredentialGrant) DeepCopy 

func (in *CredentialGrant) DeepCopy() *CredentialGrant

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CredentialGrant.

func (*CredentialGrant) DeepCopyInto 

func (in *CredentialGrant) DeepCopyInto(out *CredentialGrant)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type CredentialRequirement 

type CredentialRequirement struct {
	// Name is the env-var key the agent reads. The broker-issued value
	// is exposed under this name inside the agent container.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MaxLength=253
	Name string `json:"name"`
}

CredentialRequirement names one credential a template needs at runtime.

func (*CredentialRequirement) DeepCopy 

func (in *CredentialRequirement) DeepCopy() *CredentialRequirement

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CredentialRequirement.

func (*CredentialRequirement) DeepCopyInto 

func (in *CredentialRequirement) DeepCopyInto(out *CredentialRequirement)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type CredentialStatus 

type CredentialStatus struct {
	// Name matches the template's requires.credentials[*].name.
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Provider is the backing provider kind (e.g. "UserSuppliedSecret",
	// "AnthropicAPI"). Copied from the matched grant.
	Provider string `json:"provider"`

	// DeliveryMode is "ProxyInjected" or "InContainer".
	// +kubebuilder:validation:Enum=ProxyInjected;InContainer
	DeliveryMode DeliveryModeName `json:"deliveryMode"`

	// Hosts lists the destination hostnames this credential substitutes
	// on, for ProxyInjected delivery. Empty for InContainer.
	// +optional
	Hosts []string `json:"hosts,omitempty"`

	// InContainerReason mirrors the policy grant's
	// deliveryMode.inContainer.reason when DeliveryMode is InContainer.
	// +optional
	InContainerReason string `json:"inContainerReason,omitempty"`
}

CredentialStatus describes one issued credential from the run's perspective.

func (*CredentialStatus) DeepCopy 

func (in *CredentialStatus) DeepCopy() *CredentialStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CredentialStatus.

func (*CredentialStatus) DeepCopyInto 

func (in *CredentialStatus) DeepCopyInto(out *CredentialStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type DeliveryMode 

type DeliveryMode struct {
	// +optional
	ProxyInjected *ProxyInjectedDelivery `json:"proxyInjected,omitempty"`
	// +optional
	InContainer *InContainerDelivery `json:"inContainer,omitempty"`
}

DeliveryMode selects how a UserSuppliedSecret's value reaches its consumer. Exactly one sub-field must be set.

func (*DeliveryMode) DeepCopy 

func (in *DeliveryMode) DeepCopy() *DeliveryMode

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new DeliveryMode.

func (*DeliveryMode) DeepCopyInto 

func (in *DeliveryMode) DeepCopyInto(out *DeliveryMode)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type DeliveryModeName 

type DeliveryModeName string

DeliveryModeName names one of the two status-reported delivery modes. 

const (
	DeliveryModeProxyInjected DeliveryModeName = "ProxyInjected"
	DeliveryModeInContainer   DeliveryModeName = "InContainer"
)

type EgressDiscoverySpec 

type EgressDiscoverySpec struct {
	// Accepted must be true; setting it documents that the operator
	// acknowledges egress will be allowed-but-logged rather than blocked
	// for the duration of ExpiresAt.
	// +kubebuilder:validation:Required
	Accepted bool `json:"accepted"`

	// Reason explains why a discovery window is necessary instead of
	// iterating per-denial via paddock policy suggest.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=20
	// +kubebuilder:validation:MaxLength=500
	Reason string `json:"reason"`

	// ExpiresAt closes the discovery window. Admission rejects values
	// in the past or more than 7 days in the future.
	// +kubebuilder:validation:Required
	ExpiresAt metav1.Time `json:"expiresAt"`
}

EgressDiscoverySpec opts the BrokerPolicy into a time-bounded "allow + log" window. While now < ExpiresAt, denied egress is allowed through and recorded as kind=egress-discovery-allow AuditEvents instead of kind=egress-block. After ExpiresAt, the reconciler marks the policy non-effective.

func (*EgressDiscoverySpec) DeepCopy 

func (in *EgressDiscoverySpec) DeepCopy() *EgressDiscoverySpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new EgressDiscoverySpec.

func (*EgressDiscoverySpec) DeepCopyInto 

func (in *EgressDiscoverySpec) DeepCopyInto(out *EgressDiscoverySpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type EgressGrant 

type EgressGrant struct {
	// +kubebuilder:validation:Required
	Host string `json:"host"`
	// +optional
	Ports []int32 `json:"ports,omitempty"`
}

EgressGrant permits an upstream destination. Pure allow/deny; the substituteAuth flag from v0.3 is removed — substitution is driven by credential grants' deliveryMode and built-in providers' Hosts defaults.

func (*EgressGrant) DeepCopy 

func (in *EgressGrant) DeepCopy() *EgressGrant

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new EgressGrant.

func (*EgressGrant) DeepCopyInto 

func (in *EgressGrant) DeepCopyInto(out *EgressGrant)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type EgressRequirement 

type EgressRequirement struct {
	// Host is a destination hostname. A leading "*." permits any
	// subdomain (e.g. "*.anthropic.com"). Case-insensitive.
	// +kubebuilder:validation:Required
	Host string `json:"host"`

	// Ports lists the TCP ports this destination uses. Empty or [0]
	// means any port; otherwise the run's proxy will only permit
	// connections on these ports.
	// +optional
	Ports []int32 `json:"ports,omitempty"`
}

EgressRequirement names one upstream destination a template needs.

func (*EgressRequirement) DeepCopy 

func (in *EgressRequirement) DeepCopy() *EgressRequirement

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new EgressRequirement.

func (*EgressRequirement) DeepCopyInto 

func (in *EgressRequirement) DeepCopyInto(out *EgressRequirement)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type EventAdapterSpec 

type EventAdapterSpec struct {
	// Image is the adapter sidecar image reference.
	// +kubebuilder:validation:Required
	Image string `json:"image"`

	// ImagePullPolicy overrides the default pull policy for the adapter.
	// +optional
	ImagePullPolicy corev1.PullPolicy `json:"imagePullPolicy,omitempty"`
}

EventAdapterSpec identifies the adapter sidecar image.

func (*EventAdapterSpec) DeepCopy 

func (in *EventAdapterSpec) DeepCopy() *EventAdapterSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new EventAdapterSpec.

func (*EventAdapterSpec) DeepCopyInto 

func (in *EventAdapterSpec) DeepCopyInto(out *EventAdapterSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type GitRepoAccess 

type GitRepoAccess string
const (
	GitRepoAccessRead  GitRepoAccess = "read"
	GitRepoAccessWrite GitRepoAccess = "write"
)

type GitRepoGrant 

type GitRepoGrant struct {
	// +kubebuilder:validation:Required
	Owner string `json:"owner"`
	// +kubebuilder:validation:Required
	Repo string `json:"repo"`
	// +kubebuilder:default=read
	// +kubebuilder:validation:Enum=read;write
	// +optional
	Access GitRepoAccess `json:"access,omitempty"`
}

GitRepoGrant permits a gitforge token scoped to one repo.

func (*GitRepoGrant) DeepCopy 

func (in *GitRepoGrant) DeepCopy() *GitRepoGrant

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new GitRepoGrant.

func (*GitRepoGrant) DeepCopyInto 

func (in *GitRepoGrant) DeepCopyInto(out *GitRepoGrant)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type GrantRunsCapabilities 

type GrantRunsCapabilities struct {
	// Interact enables prompt submission and event streaming for runs
	// matching this policy. Default false. Required for spec.mode:
	// Interactive admission.
	// +optional
	Interact bool `json:"interact,omitempty"`

	// Shell, when non-nil, enables shell-session open against runs
	// matching this policy. Nil means denied.
	// +optional
	Shell *ShellCapability `json:"shell,omitempty"`
}

GrantRunsCapabilities declares run-time capabilities granted to runs against templates this policy applies to. See docs/superpowers/specs/2026-04-29-interactive-harnessrun-design.md §1.4.

func (*GrantRunsCapabilities) DeepCopy 

func (in *GrantRunsCapabilities) DeepCopy() *GrantRunsCapabilities

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new GrantRunsCapabilities.

func (*GrantRunsCapabilities) DeepCopyInto 

func (in *GrantRunsCapabilities) DeepCopyInto(out *GrantRunsCapabilities)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type HarnessRun 

type HarnessRun struct {
	metav1.TypeMeta `json:",inline"`
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`
	// +required
	Spec HarnessRunSpec `json:"spec"`
	// +optional
	Status HarnessRunStatus `json:"status,omitzero"`
}

HarnessRun is a single invocation of a harness. It materialises into a batch/v1 Job with an agent container, an optional adapter sidecar, and a collector sidecar. Runs terminate — continuity across follow-up runs comes from the shared Workspace, not from long-lived processes.

func (*HarnessRun) DeepCopy 

func (in *HarnessRun) DeepCopy() *HarnessRun

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HarnessRun.

func (*HarnessRun) DeepCopyInto 

func (in *HarnessRun) DeepCopyInto(out *HarnessRun)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*HarnessRun) DeepCopyObject 

func (in *HarnessRun) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type HarnessRunList 

type HarnessRunList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []HarnessRun `json:"items"`
}

HarnessRunList contains a list of HarnessRun.

func (*HarnessRunList) DeepCopy 

func (in *HarnessRunList) DeepCopy() *HarnessRunList

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HarnessRunList.

func (*HarnessRunList) DeepCopyInto 

func (in *HarnessRunList) DeepCopyInto(out *HarnessRunList)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*HarnessRunList) DeepCopyObject 

func (in *HarnessRunList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type HarnessRunMode 

type HarnessRunMode string

HarnessRunMode is the run-mode selector. Empty (default) means Batch — today's behaviour, one prompt and the run terminates. Interactive runs keep the pod alive and accept multiple prompts over time via the broker's /v1/runs/{ns}/{name}/prompts endpoint. +kubebuilder:validation:Enum="";Batch;Interactive 

const (
	HarnessRunModeBatch       HarnessRunMode = "Batch"
	HarnessRunModeInteractive HarnessRunMode = "Interactive"
)

type HarnessRunOutputs 

type HarnessRunOutputs struct {
	// PullRequests opened by the run.
	// +optional
	PullRequests []string `json:"pullRequests,omitempty"`

	// FilesChanged is the count of files modified by the run.
	// +optional
	FilesChanged int32 `json:"filesChanged,omitempty"`

	// Summary is a human-readable summary of what the run accomplished.
	// +optional
	Summary string `json:"summary,omitempty"`

	// Artifacts are additional named outputs (URIs or file paths).
	// +optional
	Artifacts []string `json:"artifacts,omitempty"`
}

HarnessRunOutputs are structured outputs reported by the harness. Populated by the controller from the harness's result.json on the workspace at Job completion.

func (*HarnessRunOutputs) DeepCopy 

func (in *HarnessRunOutputs) DeepCopy() *HarnessRunOutputs

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HarnessRunOutputs.

func (*HarnessRunOutputs) DeepCopyInto 

func (in *HarnessRunOutputs) DeepCopyInto(out *HarnessRunOutputs)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type HarnessRunPhase 

type HarnessRunPhase string

HarnessRunPhase is the lifecycle phase of a HarnessRun. +kubebuilder:validation:Enum=Pending;Running;Idle;Succeeded;Failed;Cancelled 

const (
	HarnessRunPhasePending HarnessRunPhase = "Pending"
	HarnessRunPhaseRunning HarnessRunPhase = "Running"
	// HarnessRunPhaseIdle indicates an Interactive run is alive and waiting
	// for the next prompt. The pod is running; no turn is in progress.
	HarnessRunPhaseIdle      HarnessRunPhase = "Idle"
	HarnessRunPhaseSucceeded HarnessRunPhase = "Succeeded"
	HarnessRunPhaseFailed    HarnessRunPhase = "Failed"
	HarnessRunPhaseCancelled HarnessRunPhase = "Cancelled"
)

type HarnessRunSpec 

type HarnessRunSpec struct {
	// TemplateRef identifies which HarnessTemplate or ClusterHarnessTemplate
	// the run uses. Resolution tries namespaced first, then cluster.
	// +kubebuilder:validation:Required
	TemplateRef TemplateRef `json:"templateRef"`

	// WorkspaceRef names the Workspace this run mounts. Required when the
	// resolved template declares workspace.required=true and auto-provision
	// is disabled; otherwise the controller creates an ephemeral Workspace
	// (see ADR-0004).
	// +optional
	WorkspaceRef string `json:"workspaceRef,omitempty"`

	// Prompt is the inline prompt supplied to the agent. Exactly one of
	// Prompt or PromptFrom must be set (enforced by admission webhook).
	// Capped at 256 KiB — use PromptFrom for anything larger.
	//
	// Regardless of source, the controller materialises the prompt into
	// an owned Secret (<run>-prompt, SecretTypeOpaque, key "prompt.txt")
	// and mounts it at /paddock/prompt/prompt.txt. See ADR-0011.
	// +optional
	Prompt string `json:"prompt,omitempty"`

	// PromptFrom sources the prompt from a ConfigMap or Secret. The
	// resolved content is copied into an owned Secret (see Prompt).
	// +optional
	PromptFrom *PromptSource `json:"promptFrom,omitempty"`

	// Timeout overrides the template's default timeout.
	// +optional
	Timeout *metav1.Duration `json:"timeout,omitempty"`

	// Retries is the Job backoffLimit. Defaults to 0 — agent failures do
	// not re-run unless explicitly requested.
	// +kubebuilder:default=0
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=10
	// +optional
	Retries int32 `json:"retries,omitempty"`

	// Resources override the template's default resource requests/limits.
	// +optional
	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`

	// ExtraEnv adds env vars to the agent container, merged after the
	// template's defaults and the PADDOCK_* standard variables.
	// +optional
	ExtraEnv []corev1.EnvVar `json:"extraEnv,omitempty"`

	// Model overrides the template's default model (exported as
	// PADDOCK_MODEL).
	// +optional
	Model string `json:"model,omitempty"`

	// TTLSecondsAfterFinished, when set, deletes the HarnessRun that many
	// seconds after its terminal phase is reached. No default — matches
	// the batch/v1 Job convention.
	// +optional
	// +kubebuilder:validation:Minimum=0
	TTLSecondsAfterFinished *int32 `json:"ttlSecondsAfterFinished,omitempty"`

	// Mode selects Batch (default — one-shot) or Interactive (long-lived
	// pod, multi-prompt). When Interactive, the resolved template's
	// spec.interactive.mode must be non-empty (admission webhook
	// enforces). Immutable after creation, like the rest of the spec.
	// +optional
	Mode HarnessRunMode `json:"mode,omitempty"`

	// InteractiveOverrides allows per-run overrides of the template's
	// interactive timing values. Each override is bounded by the
	// template's value (override may not exceed the template's bound).
	// Ignored unless Mode == Interactive.
	// +optional
	InteractiveOverrides *InteractiveOverrides `json:"interactiveOverrides,omitempty"`
}

HarnessRunSpec is the desired state of a HarnessRun — a single, terminating invocation of a harness against an optional workspace. The spec is immutable after creation (enforced by the admission webhook): to change the configuration of a run, submit a new one.

func (*HarnessRunSpec) DeepCopy 

func (in *HarnessRunSpec) DeepCopy() *HarnessRunSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HarnessRunSpec.

func (*HarnessRunSpec) DeepCopyInto 

func (in *HarnessRunSpec) DeepCopyInto(out *HarnessRunSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type HarnessRunStatus 

type HarnessRunStatus struct {
	// ObservedGeneration is the spec generation last reconciled.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Phase summarises the run's lifecycle in a single token.
	// +optional
	Phase HarnessRunPhase `json:"phase,omitempty"`

	// Conditions report typed lifecycle signals. Known types:
	// TemplateResolved, WorkspaceBound, JobCreated, PodReady, Completed.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// JobName is the name of the backing batch/v1 Job, once created.
	// +optional
	JobName string `json:"jobName,omitempty"`

	// WorkspaceRef records which Workspace this run ended up bound to
	// (either user-supplied or ephemerally provisioned).
	// +optional
	WorkspaceRef string `json:"workspaceRef,omitempty"`

	// StartTime is when the run's Job entered Running.
	// +optional
	StartTime *metav1.Time `json:"startTime,omitempty"`

	// CompletionTime is when the run reached a terminal phase.
	// +optional
	CompletionTime *metav1.Time `json:"completionTime,omitempty"`

	// RecentEvents is a ring buffer of the most recent PaddockEvents
	// emitted during the run (capped by controller flag, default 50).
	// Full event history lives on the Workspace PVC at
	// /workspace/.paddock/runs/<name>/events.jsonl.
	// +optional
	RecentEvents []PaddockEvent `json:"recentEvents,omitempty"`

	// Outputs are structured outputs reported by the harness on exit.
	// +optional
	Outputs *HarnessRunOutputs `json:"outputs,omitempty"`

	// Credentials reports, per requires.credentials[*].name, which
	// provider backed it and how the value was delivered. Populated by
	// the controller after a successful Issue call to the broker. Lets
	// the user verify at runtime that the actual delivery matches the
	// policy's declaration.
	// +listType=map
	// +listMapKey=name
	// +optional
	Credentials []CredentialStatus `json:"credentials,omitempty"`

	// NetworkPolicyEnforced records whether per-run NetworkPolicy
	// enforcement was active when this run was admitted. Immutable after
	// admission. The reconciler honours this for the run's lifetime, so a
	// flag flip on the controller-manager
	// (--networkpolicy-enforce=on → off) does not weaken running pods.
	// F-43 / Phase 2d.
	// +optional
	NetworkPolicyEnforced *bool `json:"networkPolicyEnforced,omitempty"`

	// IssuedLeases records every credential lease the broker has minted
	// for this run. Populated by the controller after each successful
	// Issue call; consumed by the controller's broker-leases finalizer
	// to revoke leases at run-delete time, and by the broker on startup
	// to reconstruct PATPool slot reservations across restarts. F-11, F-14.
	// +listType=map
	// +listMapKey=leaseID
	// +optional
	IssuedLeases []IssuedLease `json:"issuedLeases,omitempty"`

	// Interactive carries live-session counters and timestamps for
	// Interactive runs. Nil for Batch runs.
	// +optional
	Interactive *InteractiveStatus `json:"interactive,omitempty"`
}

HarnessRunStatus reports the observed state of a HarnessRun.

func (*HarnessRunStatus) DeepCopy 

func (in *HarnessRunStatus) DeepCopy() *HarnessRunStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HarnessRunStatus.

func (*HarnessRunStatus) DeepCopyInto 

func (in *HarnessRunStatus) DeepCopyInto(out *HarnessRunStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type HarnessTemplate 

type HarnessTemplate struct {
	metav1.TypeMeta `json:",inline"`
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`
	// +required
	Spec HarnessTemplateSpec `json:"spec"`
	// +optional
	Status HarnessTemplateStatus `json:"status,omitzero"`
}

HarnessTemplate is a namespaced blueprint for running an agent harness as a HarnessRun. It may inherit a pod shape from a ClusterHarnessTemplate via baseTemplateRef; see ADR-0003.

func (*HarnessTemplate) DeepCopy 

func (in *HarnessTemplate) DeepCopy() *HarnessTemplate

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HarnessTemplate.

func (*HarnessTemplate) DeepCopyInto 

func (in *HarnessTemplate) DeepCopyInto(out *HarnessTemplate)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*HarnessTemplate) DeepCopyObject 

func (in *HarnessTemplate) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type HarnessTemplateDefaults 

type HarnessTemplateDefaults struct {
	// Model is the default model identifier exported to the agent as
	// PADDOCK_MODEL. Overridable per-run.
	// +optional
	Model string `json:"model,omitempty"`

	// Timeout is the default active deadline for a run. Overridable per-run.
	// +kubebuilder:default="30m"
	// +optional
	Timeout *metav1.Duration `json:"timeout,omitempty"`

	// Resources are the default resource requests/limits for the agent
	// container. Overridable per-run.
	// +optional
	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`

	// TerminationGracePeriodSeconds is the grace period for SIGTERM →
	// SIGKILL when a run is cancelled or times out.
	// +kubebuilder:default=60
	// +optional
	TerminationGracePeriodSeconds *int64 `json:"terminationGracePeriodSeconds,omitempty"`
}

HarnessTemplateDefaults are the run-time defaults a template applies.

func (*HarnessTemplateDefaults) DeepCopy 

func (in *HarnessTemplateDefaults) DeepCopy() *HarnessTemplateDefaults

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HarnessTemplateDefaults.

func (*HarnessTemplateDefaults) DeepCopyInto 

func (in *HarnessTemplateDefaults) DeepCopyInto(out *HarnessTemplateDefaults)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type HarnessTemplateList 

type HarnessTemplateList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []HarnessTemplate `json:"items"`
}

HarnessTemplateList contains a list of HarnessTemplate.

func (*HarnessTemplateList) DeepCopy 

func (in *HarnessTemplateList) DeepCopy() *HarnessTemplateList

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HarnessTemplateList.

func (*HarnessTemplateList) DeepCopyInto 

func (in *HarnessTemplateList) DeepCopyInto(out *HarnessTemplateList)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*HarnessTemplateList) DeepCopyObject 

func (in *HarnessTemplateList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type HarnessTemplateSpec 

type HarnessTemplateSpec struct {
	// BaseTemplateRef, when set on a namespaced HarnessTemplate, inherits
	// the referenced ClusterHarnessTemplate's pod shape. Locked fields
	// (Image, Command, Args, EventAdapter, Workspace) must be empty on
	// the inheriting template. Not valid on ClusterHarnessTemplate.
	// +optional
	BaseTemplateRef *LocalObjectReference `json:"baseTemplateRef,omitempty"`

	// Harness is a free-form label identifying the agent (codex, claude-code,
	// opencode, etc.). Used for observability and filtering only — the
	// controller has no per-harness logic.
	// +kubebuilder:validation:MaxLength=63
	// +optional
	Harness string `json:"harness,omitempty"`

	// Image is the agent container image. Required when BaseTemplateRef is
	// not set. Locked (must be empty) when inheriting.
	// +optional
	Image string `json:"image,omitempty"`

	// Command overrides the image's entrypoint. Env-var expansion via
	// $(VAR) is supported; the controller injects PADDOCK_PROMPT_PATH,
	// PADDOCK_RAW_PATH, PADDOCK_EVENTS_PATH, PADDOCK_RESULT_PATH,
	// PADDOCK_WORKSPACE, PADDOCK_RUN_NAME, and PADDOCK_MODEL. Required
	// when BaseTemplateRef is not set. Locked when inheriting.
	// +optional
	Command []string `json:"command,omitempty"`

	// Args are merged after Command. Locked when inheriting.
	// +optional
	Args []string `json:"args,omitempty"`

	// Defaults are per-template values that a HarnessRun may override.
	// Always overridable on namespaced templates.
	// +optional
	Defaults HarnessTemplateDefaults `json:"defaults,omitempty"`

	// EventAdapter is the per-harness sidecar image that converts raw
	// harness output to PaddockEvents. When unset, events.jsonl is not
	// produced and status.recentEvents carries only lifecycle events.
	// Locked when inheriting.
	// +optional
	EventAdapter *EventAdapterSpec `json:"eventAdapter,omitempty"`

	// Requires declares the capabilities the agent will exercise at
	// runtime: credentials it expects to be injected, and upstream
	// destinations it will connect to. A HarnessRun against this template
	// is admitted only if one or more BrokerPolicies in the run's
	// namespace grant a superset of Requires. See ADR-0014 and spec 0002
	// §8. Always overridable on namespaced templates.
	// +optional
	Requires RequireSpec `json:"requires,omitempty"`

	// Workspace declares the template's workspace requirement. Locked when
	// inheriting.
	// +optional
	Workspace WorkspaceRequirement `json:"workspace,omitempty"`

	// PodTemplateOverlay is strategically merged into the generated
	// PodSpec. Escape hatch for scheduling hints, tolerations, or extra
	// volumes. Always overridable on namespaced templates.
	// +optional
	// +kubebuilder:pruning:PreserveUnknownFields
	PodTemplateOverlay *corev1.PodTemplateSpec `json:"podTemplateOverlay,omitempty"`

	// Interactive declares the template's interactive-mode support and
	// lifecycle defaults. When nil, runs against this template may not
	// set spec.mode: Interactive (admission rejects). Always overridable
	// on namespaced templates that inherit a ClusterHarnessTemplate.
	// +optional
	Interactive *InteractiveSpec `json:"interactive,omitempty"`
}

HarnessTemplateSpec is the shared spec for ClusterHarnessTemplate and namespaced HarnessTemplate. A namespaced HarnessTemplate may reference a ClusterHarnessTemplate via BaseTemplateRef to inherit its pod shape; in that case only Defaults, Requires, and PodTemplateOverlay may be set. See docs/contributing/adr/0003-template-override-semantics.md.

func (*HarnessTemplateSpec) DeepCopy 

func (in *HarnessTemplateSpec) DeepCopy() *HarnessTemplateSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HarnessTemplateSpec.

func (*HarnessTemplateSpec) DeepCopyInto 

func (in *HarnessTemplateSpec) DeepCopyInto(out *HarnessTemplateSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type HarnessTemplateStatus 

type HarnessTemplateStatus struct {
	// ObservedGeneration is the last generation of the spec that the
	// controller has reconciled.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest observations of the template's state.
	// Known types: Ready.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

HarnessTemplateStatus reports the observed state of a HarnessTemplate.

func (*HarnessTemplateStatus) DeepCopy 

func (in *HarnessTemplateStatus) DeepCopy() *HarnessTemplateStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HarnessTemplateStatus.

func (*HarnessTemplateStatus) DeepCopyInto 

func (in *HarnessTemplateStatus) DeepCopyInto(out *HarnessTemplateStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type HeaderSubstitution 

type HeaderSubstitution struct {
	// +kubebuilder:validation:Required
	Name string `json:"name"`
	// ValuePrefix is prepended to the secret value (e.g. "Bearer ").
	// +optional
	ValuePrefix string `json:"valuePrefix,omitempty"`
}

HeaderSubstitution sets a header on outbound requests.

func (*HeaderSubstitution) DeepCopy 

func (in *HeaderSubstitution) DeepCopy() *HeaderSubstitution

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new HeaderSubstitution.

func (*HeaderSubstitution) DeepCopyInto 

func (in *HeaderSubstitution) DeepCopyInto(out *HeaderSubstitution)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type InContainerDelivery 

type InContainerDelivery struct {
	// Accepted must be true.
	// +kubebuilder:validation:Required
	Accepted bool `json:"accepted"`

	// Reason explains why in-container delivery is necessary.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=20
	// +kubebuilder:validation:MaxLength=500
	Reason string `json:"reason"`
}

InContainerDelivery opts the user into delivering the real secret value to the agent container's environment.

func (*InContainerDelivery) DeepCopy 

func (in *InContainerDelivery) DeepCopy() *InContainerDelivery

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new InContainerDelivery.

func (*InContainerDelivery) DeepCopyInto 

func (in *InContainerDelivery) DeepCopyInto(out *InContainerDelivery)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type InteractiveOverrides 

type InteractiveOverrides struct {
	// +optional
	IdleTimeout *metav1.Duration `json:"idleTimeout,omitempty"`
	// +optional
	DetachIdleTimeout *metav1.Duration `json:"detachIdleTimeout,omitempty"`
	// +optional
	DetachTimeout *metav1.Duration `json:"detachTimeout,omitempty"`
	// +optional
	MaxLifetime *metav1.Duration `json:"maxLifetime,omitempty"`
}

InteractiveOverrides are per-run knobs for an Interactive run.

func (*InteractiveOverrides) DeepCopy 

func (in *InteractiveOverrides) DeepCopy() *InteractiveOverrides

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new InteractiveOverrides.

func (*InteractiveOverrides) DeepCopyInto 

func (in *InteractiveOverrides) DeepCopyInto(out *InteractiveOverrides)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type InteractiveSpec 

type InteractiveSpec struct {
	// Mode declares which interactive implementation strategy the
	// template's adapter image supports. The adapter image must declare
	// a matching value via paddock.dev/interactive-modes annotation
	// (validated at pod-spec generation, not at template admission).
	// +kubebuilder:validation:Enum="";per-prompt-process;persistent-process
	// +optional
	Mode string `json:"mode,omitempty"`

	// IdleTimeout is the maximum time since the last completed prompt
	// before the run terminates, while at least one client is attached.
	// Default 30m.
	// +optional
	// +kubebuilder:default="30m"
	IdleTimeout *metav1.Duration `json:"idleTimeout,omitempty"`

	// DetachIdleTimeout is the maximum idle time when no client is
	// attached. Default 15m.
	// +optional
	// +kubebuilder:default="15m"
	DetachIdleTimeout *metav1.Duration `json:"detachIdleTimeout,omitempty"`

	// DetachTimeout is the maximum time with zero attached clients
	// before termination. Default 5m.
	// +optional
	// +kubebuilder:default="5m"
	DetachTimeout *metav1.Duration `json:"detachTimeout,omitempty"`

	// MaxLifetime is the absolute hard cap on run lifetime regardless
	// of activity. Default 24h. Non-negotiable upper bound.
	// +optional
	// +kubebuilder:default="24h"
	MaxLifetime *metav1.Duration `json:"maxLifetime,omitempty"`

	// MaxRecentEvents overrides HarnessRun.status.recentEvents ring size
	// for runs against this template. Default 50; bounded [10, 500].
	// +optional
	// +kubebuilder:validation:Minimum=10
	// +kubebuilder:validation:Maximum=500
	MaxRecentEvents *int32 `json:"maxRecentEvents,omitempty"`
}

InteractiveSpec declares interactive-mode support and lifecycle defaults for a HarnessTemplate. When nil or with empty Mode, the template does not support spec.mode: Interactive.

See docs/superpowers/specs/2026-04-29-interactive-harnessrun-design.md.

func (*InteractiveSpec) DeepCopy 

func (in *InteractiveSpec) DeepCopy() *InteractiveSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new InteractiveSpec.

func (*InteractiveSpec) DeepCopyInto 

func (in *InteractiveSpec) DeepCopyInto(out *InteractiveSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type InteractiveStatus 

type InteractiveStatus struct {
	// PromptCount is the total number of prompt turns submitted since the
	// run started. Always serialized (no omitempty) — zero is a real
	// observable value for status consumers.
	PromptCount int32 `json:"promptCount"`

	// LastPromptAt is the time the most recent prompt was received.
	// +optional
	LastPromptAt *metav1.Time `json:"lastPromptAt,omitempty"`

	// AttachedSessions is the current number of client sessions attached
	// to the run's prompt stream or shell endpoint. Always serialized.
	AttachedSessions int32 `json:"attachedSessions"`

	// LastAttachedAt is the time the most recent session attached.
	// +optional
	LastAttachedAt *metav1.Time `json:"lastAttachedAt,omitempty"`

	// IdleSince is the time the run entered the Idle phase most recently.
	// Nil if the run has never been idle.
	// +optional
	IdleSince *metav1.Time `json:"idleSince,omitempty"`

	// CurrentTurnSeq is the monotonically increasing sequence number of
	// the prompt turn currently in progress. Nil when no turn is active.
	// +optional
	CurrentTurnSeq *int32 `json:"currentTurnSeq,omitempty"`

	// RenewalCount is the total number of credential renewals completed
	// for this run. Always serialized.
	RenewalCount int32 `json:"renewalCount"`

	// LastRenewalAt is the time of the most recent credential renewal.
	// +optional
	LastRenewalAt *metav1.Time `json:"lastRenewalAt,omitempty"`
}

InteractiveStatus carries counters and timestamps for an Interactive run. Populated and updated by the controller as prompts arrive and sessions attach/detach.

func (*InteractiveStatus) DeepCopy 

func (in *InteractiveStatus) DeepCopy() *InteractiveStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new InteractiveStatus.

func (*InteractiveStatus) DeepCopyInto 

func (in *InteractiveStatus) DeepCopyInto(out *InteractiveStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type InterceptionMode 

type InterceptionMode string

InterceptionMode names one of the proxy interception strategies used at runtime by the reconciler when assembling a HarnessRun's Pod. The user-facing surface is spec.interception (below); this enum is the resolver's internal tag. 

const (
	InterceptionModeTransparent InterceptionMode = "transparent"
	InterceptionModeCooperative InterceptionMode = "cooperative"
)

type InterceptionSpec 

type InterceptionSpec struct {
	// +optional
	Transparent *TransparentInterception `json:"transparent,omitempty"`
	// +optional
	CooperativeAccepted *CooperativeAcceptedInterception `json:"cooperativeAccepted,omitempty"`
}

InterceptionSpec selects the egress-proxy interception mode for runs governed by a BrokerPolicy. Exactly one sub-field must be set.

transparent (iptables REDIRECT + SO_ORIGINAL_DST) cannot be bypassed from inside the agent container and is the recommended default. cooperativeAccepted (HTTPS_PROXY env) can be bypassed by a hostile or buggy agent unsetting the env vars; it exists for clusters whose Pod Security Admission policy forbids the CAP_NET_ADMIN the iptables init container needs.

func (*InterceptionSpec) DeepCopy 

func (in *InterceptionSpec) DeepCopy() *InterceptionSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new InterceptionSpec.

func (*InterceptionSpec) DeepCopyInto 

func (in *InterceptionSpec) DeepCopyInto(out *InterceptionSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type IssuedLease 

type IssuedLease struct {
	// Provider is the provider kind (matches BrokerPolicy
	// grant.provider.kind). The broker dispatches /v1/revoke to the
	// named provider's Revoke method.
	// +kubebuilder:validation:Required
	Provider string `json:"provider"`

	// LeaseID is the provider-supplied identifier returned from
	// IssueResult.LeaseID. Opaque to the controller; passed back unchanged.
	// +kubebuilder:validation:Required
	LeaseID string `json:"leaseID"`

	// CredentialName is the requirement name from the template's
	// spec.requires.credentials list. Used for audit correlation only —
	// never load-bearing for revocation.
	// +kubebuilder:validation:Required
	CredentialName string `json:"credentialName"`

	// ExpiresAt mirrors IssueResult.ExpiresAt. Reconstruction skips
	// entries with ExpiresAt < now (no point rebuilding state for an
	// already-dead lease). Optional: nil means "no expiry".
	// +optional
	ExpiresAt *metav1.Time `json:"expiresAt,omitempty"`

	// PoolRef carries PATPool-specific reconstruction metadata.
	// Populated only when Provider == "PATPool"; nil otherwise.
	// Anonymous tagged-union pattern; future providers add their own
	// optional ref alongside without breaking pre-1.0 in-place evolution.
	// +optional
	PoolRef *PoolLeaseRef `json:"poolRef,omitempty"`
}

IssuedLease records one credential lease the broker minted for this run. The controller appends one entry per successful broker.Issue call; reconcileDelete walks the slice and posts /v1/revoke for each entry before removing the broker-leases finalizer. Pre-1.0 evolves in place.

func (*IssuedLease) DeepCopy 

func (in *IssuedLease) DeepCopy() *IssuedLease

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new IssuedLease.

func (*IssuedLease) DeepCopyInto 

func (in *IssuedLease) DeepCopyInto(out *IssuedLease)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type LocalObjectReference 

type LocalObjectReference struct {
	// Name of the referenced object.
	// +kubebuilder:validation:Required
	Name string `json:"name"`
}

LocalObjectReference references another resource by name in the same namespace (or cluster scope for cluster-scoped kinds).

func (*LocalObjectReference) DeepCopy 

func (in *LocalObjectReference) DeepCopy() *LocalObjectReference

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new LocalObjectReference.

func (*LocalObjectReference) DeepCopyInto 

func (in *LocalObjectReference) DeepCopyInto(out *LocalObjectReference)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PaddockEvent 

type PaddockEvent struct {
	// SchemaVersion governs the semantics of this event. Bump when the
	// semantics of existing fields change; add optional fields without
	// bumping. See ADR-0001.
	// +kubebuilder:default="1"
	SchemaVersion string `json:"schemaVersion"`

	// Timestamp is when the event was produced.
	Timestamp metav1.Time `json:"ts"`

	// Type identifies the event category. Known types: ToolUse, Message,
	// FileEdit, Commit, Elicitation, Error, Result. Adapters may emit
	// custom types for harness-specific events; consumers should tolerate
	// unknown types.
	// +kubebuilder:validation:Required
	Type string `json:"type"`

	// Summary is a one-line human-readable description of the event.
	// Suitable for display in kubectl output without interpreting the
	// type-specific fields.
	// +optional
	Summary string `json:"summary,omitempty"`

	// Fields carries event-specific details as string-valued key/value
	// pairs. Its schema is determined by Type and SchemaVersion; consumers
	// should tolerate unknown keys.
	// +optional
	Fields map[string]string `json:"fields,omitempty"`
}

PaddockEvent is a structured event emitted by an adapter sidecar and persisted to the Workspace PVC as events.jsonl. A ring buffer of the most recent events is also surfaced on HarnessRun.status.recentEvents.

See docs/contributing/adr/0001-paddockevent-schema-version.md for versioning rules.

func (*PaddockEvent) DeepCopy 

func (in *PaddockEvent) DeepCopy() *PaddockEvent

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PaddockEvent.

func (*PaddockEvent) DeepCopyInto 

func (in *PaddockEvent) DeepCopyInto(out *PaddockEvent)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PoolLeaseRef 

type PoolLeaseRef struct {
	// +kubebuilder:validation:Required
	SecretRef SecretKeyReference `json:"secretRef"`
	// +kubebuilder:validation:Required
	SlotIndex int `json:"slotIndex"`
}

PoolLeaseRef is PATPool-specific metadata required to reconstruct in-memory pool state at broker startup. (secretRef, slotIndex) lets the broker re-acquire the slot; the existing LeasedPAT byte-equality check at substitute time catches any pool-edit drift between Issue and reconstruction.

func (*PoolLeaseRef) DeepCopy 

func (in *PoolLeaseRef) DeepCopy() *PoolLeaseRef

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PoolLeaseRef.

func (*PoolLeaseRef) DeepCopyInto 

func (in *PoolLeaseRef) DeepCopyInto(out *PoolLeaseRef)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type PromptSource 

type PromptSource struct {
	// +optional
	ConfigMapKeyRef *corev1.ConfigMapKeySelector `json:"configMapKeyRef,omitempty"`
	// +optional
	SecretKeyRef *corev1.SecretKeySelector `json:"secretKeyRef,omitempty"`
}

PromptSource sources the run's prompt from a ConfigMap or Secret. Exactly one field must be set (enforced by admission webhook).

func (*PromptSource) DeepCopy 

func (in *PromptSource) DeepCopy() *PromptSource

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PromptSource.

func (*PromptSource) DeepCopyInto 

func (in *PromptSource) DeepCopyInto(out *PromptSource)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ProviderConfig 

type ProviderConfig struct {
	// Kind names the provider implementation.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Enum=UserSuppliedSecret;AnthropicAPI;GitHubApp;PATPool
	Kind string `json:"kind"`

	// SecretRef identifies the Secret backing this provider.
	// +optional
	SecretRef *SecretKeyReference `json:"secretRef,omitempty"`

	// AppID is the GitHub App numeric ID (GitHubApp only). Must be a
	// positive integer of at most 20 digits when set; required for
	// GitHubApp providers (admission rejects empty for that kind).
	// +optional
	// +kubebuilder:validation:Pattern=`^[1-9][0-9]{0,19}$`
	AppID string `json:"appId,omitempty"`

	// InstallationID is the GitHub App installation ID (GitHubApp only).
	// Must be a positive integer of at most 20 digits when set;
	// required for GitHubApp providers.
	// +optional
	// +kubebuilder:validation:Pattern=`^[1-9][0-9]{0,19}$`
	InstallationID string `json:"installationId,omitempty"`

	// RotationSeconds optionally overrides the provider's default TTL.
	// +optional
	// +kubebuilder:validation:Minimum=60
	RotationSeconds *int32 `json:"rotationSeconds,omitempty"`

	// Hosts optionally overrides the destination host list used for
	// proxy substitution, for built-in providers (AnthropicAPI,
	// GitHubApp, PATPool). For UserSuppliedSecret with proxyInjected
	// delivery, hosts live under deliveryMode.proxyInjected instead and
	// this field must not be set.
	// +optional
	Hosts []string `json:"hosts,omitempty"`

	// DeliveryMode is required for UserSuppliedSecret and forbidden for
	// all other kinds.
	// +optional
	DeliveryMode *DeliveryMode `json:"deliveryMode,omitempty"`
}

ProviderConfig selects a broker provider and supplies its configuration.

func (*ProviderConfig) DeepCopy 

func (in *ProviderConfig) DeepCopy() *ProviderConfig

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ProviderConfig.

func (*ProviderConfig) DeepCopyInto 

func (in *ProviderConfig) DeepCopyInto(out *ProviderConfig)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ProxyInjectedDelivery 

type ProxyInjectedDelivery struct {
	// Hosts are the destination hostnames the proxy will substitute on.
	// A leading "*." permits any subdomain. At least one entry required.
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:Required
	Hosts []string `json:"hosts"`

	// Exactly one of Header / QueryParam / BasicAuth must be set.
	// +optional
	Header *HeaderSubstitution `json:"header,omitempty"`
	// +optional
	QueryParam *QueryParamSubstitution `json:"queryParam,omitempty"`
	// +optional
	BasicAuth *BasicAuthSubstitution `json:"basicAuth,omitempty"`
}

ProxyInjectedDelivery describes how the proxy should substitute the real secret value onto outbound requests.

func (*ProxyInjectedDelivery) DeepCopy 

func (in *ProxyInjectedDelivery) DeepCopy() *ProxyInjectedDelivery

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ProxyInjectedDelivery.

func (*ProxyInjectedDelivery) DeepCopyInto 

func (in *ProxyInjectedDelivery) DeepCopyInto(out *ProxyInjectedDelivery)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type QueryParamSubstitution 

type QueryParamSubstitution struct {
	// +kubebuilder:validation:Required
	Name string `json:"name"`
}

QueryParamSubstitution rewrites one URL query parameter.

func (*QueryParamSubstitution) DeepCopy 

func (in *QueryParamSubstitution) DeepCopy() *QueryParamSubstitution

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new QueryParamSubstitution.

func (*QueryParamSubstitution) DeepCopyInto 

func (in *QueryParamSubstitution) DeepCopyInto(out *QueryParamSubstitution)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type RequireSpec 

type RequireSpec struct {
	// Credentials are the credentials the agent expects to be injected
	// as env vars. Name is the env-var key inside the agent container.
	// Templates never name a provider directly — that is the
	// operator's choice via BrokerPolicy.
	// +optional
	Credentials []CredentialRequirement `json:"credentials,omitempty"`

	// Egress lists the upstream destinations the agent will open
	// connections to. A leading "*." on Host permits any subdomain.
	// +optional
	Egress []EgressRequirement `json:"egress,omitempty"`
}

RequireSpec declares the capabilities a template's agent exercises. Templates state needs; BrokerPolicies grant them; admission intersects. See ADR-0014.

func (*RequireSpec) DeepCopy 

func (in *RequireSpec) DeepCopy() *RequireSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new RequireSpec.

func (*RequireSpec) DeepCopyInto 

func (in *RequireSpec) DeepCopyInto(out *RequireSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type SecretKeyReference 

type SecretKeyReference struct {
	// +kubebuilder:validation:Required
	Name string `json:"name"`
	// +kubebuilder:validation:Required
	Key string `json:"key"`
}

SecretKeyReference is a pair (Secret name, key). Namespace is implicit.

func (*SecretKeyReference) DeepCopy 

func (in *SecretKeyReference) DeepCopy() *SecretKeyReference

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new SecretKeyReference.

func (*SecretKeyReference) DeepCopyInto 

func (in *SecretKeyReference) DeepCopyInto(out *SecretKeyReference)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ShellCapability 

type ShellCapability struct {
	// Target is which container the broker exec's into.
	// +kubebuilder:validation:Enum=agent;adapter
	// +kubebuilder:default=agent
	// +optional
	Target string `json:"target,omitempty"`

	// Command overrides the default shell-discovery (try /bin/bash, fall
	// back to /bin/sh). When set, the broker forwards Command verbatim
	// to the container's exec; missing binaries surface as a failed
	// shell session (the session opens, exec returns immediately with
	// the kubelet's error) rather than as an admission rejection.
	// +optional
	Command []string `json:"command,omitempty"`

	// AllowedPhases restricts which run phases can host a shell session.
	// Default (when empty): all phases that have a pod (Running, Idle,
	// Succeeded, Failed, Cancelled).
	// +optional
	AllowedPhases []HarnessRunPhase `json:"allowedPhases,omitempty"`

	// RecordTranscript captures the WebSocket bytestream to
	// <workspace>/.paddock/shell/<session-id>.log when true. Default
	// false — recording doubles disk I/O and stores potentially-sensitive
	// output.
	// +optional
	RecordTranscript bool `json:"recordTranscript,omitempty"`
}

ShellCapability declares the shape of granted shell access.

func (*ShellCapability) DeepCopy 

func (in *ShellCapability) DeepCopy() *ShellCapability

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ShellCapability.

func (*ShellCapability) DeepCopyInto 

func (in *ShellCapability) DeepCopyInto(out *ShellCapability)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type TemplateRef 

type TemplateRef struct {
	// Name of the template.
	// +kubebuilder:validation:Required
	Name string `json:"name"`

	// Kind restricts resolution. When empty, a namespaced HarnessTemplate
	// with this name is preferred over a cluster one.
	// +kubebuilder:validation:Enum=HarnessTemplate;ClusterHarnessTemplate
	// +optional
	Kind string `json:"kind,omitempty"`
}

TemplateRef identifies a HarnessTemplate or ClusterHarnessTemplate.

func (*TemplateRef) DeepCopy 

func (in *TemplateRef) DeepCopy() *TemplateRef

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new TemplateRef.

func (*TemplateRef) DeepCopyInto 

func (in *TemplateRef) DeepCopyInto(out *TemplateRef)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type TransparentInterception 

type TransparentInterception struct{}

TransparentInterception is an empty marker that selects transparent mode. No knobs are required; it exists as a distinct sub-field so admission can enforce exactly-one-of semantics with cooperativeAccepted.

func (*TransparentInterception) DeepCopy 

func (in *TransparentInterception) DeepCopy() *TransparentInterception

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new TransparentInterception.

func (*TransparentInterception) DeepCopyInto 

func (in *TransparentInterception) DeepCopyInto(out *TransparentInterception)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type Workspace 

type Workspace struct {
	metav1.TypeMeta `json:",inline"`
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`
	// +required
	Spec WorkspaceSpec `json:"spec"`
	// +optional
	Status WorkspaceStatus `json:"status,omitzero"`
}

Workspace is a persistent scratch area shared across HarnessRuns. The workspace outlives the runs that use it; at most one run mounts it at a time (ReadWriteOnce default).

func (*Workspace) DeepCopy 

func (in *Workspace) DeepCopy() *Workspace

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new Workspace.

func (*Workspace) DeepCopyInto 

func (in *Workspace) DeepCopyInto(out *Workspace)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*Workspace) DeepCopyObject 

func (in *Workspace) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type WorkspaceGitSource 

type WorkspaceGitSource struct {
	// URL is the clone URL (https or ssh).
	// +kubebuilder:validation:Required
	URL string `json:"url"`

	// Path is the relative directory under the workspace mount where the
	// repo is cloned. Empty means the workspace mount root (only allowed
	// when this is the only repo). When multiple repos are declared,
	// every Path must be set and unique.
	// +optional
	Path string `json:"path,omitempty"`

	// Branch to clone. Defaults to the remote's HEAD.
	// +optional
	Branch string `json:"branch,omitempty"`

	// Depth is the shallow-clone depth. Zero or unset means a full clone.
	// +kubebuilder:validation:Minimum=0
	// +optional
	Depth int32 `json:"depth,omitempty"`

	// BrokerCredentialRef, when set, routes git credentials through
	// the broker (ADR-0015) instead of a static Secret. The referenced
	// Secret must exist before the seed Job runs — typically the
	// <run>-broker-creds Secret the HarnessRun reconciler materialises
	// from broker.Issue responses. Data[Key] must be a Paddock-issued
	// bearer (pdk-github-… or pdk-patpool-…). The seed Pod gains a
	// proxy sidecar so MITM substitution swaps the bearer for the real
	// upstream token at git-HTTPS time — upstream git forges never
	// see the Paddock-issued value.
	//
	// Mutually exclusive with CredentialsSecretRef. Only valid on
	// https URLs (ssh URLs use key-based auth via CredentialsSecretRef).
	// +optional
	BrokerCredentialRef *BrokerCredentialReference `json:"brokerCredentialRef,omitempty"`

	// CredentialsSecretRef, when set, supplies git credentials to the
	// seed Job for this repo. For https URLs the Secret must carry
	// `username` and `password` keys (a personal access token goes in
	// `password`). For ssh URLs it must carry `ssh-privatekey`. Mounted
	// read-only into the seed Job only. See ADR-0006.
	// +optional
	CredentialsSecretRef *LocalObjectReference `json:"credentialsSecretRef,omitempty"`
}

WorkspaceGitSource clones one git repository into the workspace.

func (*WorkspaceGitSource) DeepCopy 

func (in *WorkspaceGitSource) DeepCopy() *WorkspaceGitSource

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new WorkspaceGitSource.

func (*WorkspaceGitSource) DeepCopyInto 

func (in *WorkspaceGitSource) DeepCopyInto(out *WorkspaceGitSource)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type WorkspaceList 

type WorkspaceList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []Workspace `json:"items"`
}

WorkspaceList contains a list of Workspace.

func (*WorkspaceList) DeepCopy 

func (in *WorkspaceList) DeepCopy() *WorkspaceList

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new WorkspaceList.

func (*WorkspaceList) DeepCopyInto 

func (in *WorkspaceList) DeepCopyInto(out *WorkspaceList)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (*WorkspaceList) DeepCopyObject 

func (in *WorkspaceList) DeepCopyObject() runtime.Object

DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.

type WorkspacePhase 

type WorkspacePhase string

WorkspacePhase is the lifecycle phase of a Workspace. +kubebuilder:validation:Enum=Seeding;Active;Failed;Terminating 

const (
	WorkspacePhaseSeeding     WorkspacePhase = "Seeding"
	WorkspacePhaseActive      WorkspacePhase = "Active"
	WorkspacePhaseFailed      WorkspacePhase = "Failed"
	WorkspacePhaseTerminating WorkspacePhase = "Terminating"
)

type WorkspaceRequirement 

type WorkspaceRequirement struct {
	// Required indicates the template must run against a Workspace. When
	// true and a HarnessRun omits workspaceRef, the controller provisions
	// an ephemeral Workspace (see ADR-0004).
	// +kubebuilder:default=true
	// +optional
	Required bool `json:"required,omitempty"`

	// MountPath is where the workspace PVC is mounted in the agent
	// container. Defaults to /workspace.
	// +kubebuilder:default="/workspace"
	// +optional
	MountPath string `json:"mountPath,omitempty"`
}

WorkspaceRequirement describes whether and how a run uses a Workspace.

func (*WorkspaceRequirement) DeepCopy 

func (in *WorkspaceRequirement) DeepCopy() *WorkspaceRequirement

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new WorkspaceRequirement.

func (*WorkspaceRequirement) DeepCopyInto 

func (in *WorkspaceRequirement) DeepCopyInto(out *WorkspaceRequirement)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type WorkspaceSeed 

type WorkspaceSeed struct {
	// Repos clones one or more git repositories into the workspace. With
	// a single entry an empty Path clones directly to the workspace
	// mount root; with multiple entries every Path must be set to a
	// distinct relative directory. See ADR-0006 for credential handling.
	// +optional
	Repos []WorkspaceGitSource `json:"repos,omitempty"`
}

WorkspaceSeed describes how a Workspace is initialised before any run. When set, at least one Repos entry is required. FromArchive lands in v0.2.

func (*WorkspaceSeed) DeepCopy 

func (in *WorkspaceSeed) DeepCopy() *WorkspaceSeed

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new WorkspaceSeed.

func (*WorkspaceSeed) DeepCopyInto 

func (in *WorkspaceSeed) DeepCopyInto(out *WorkspaceSeed)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type WorkspaceSpec 

type WorkspaceSpec struct {
	// Storage configures the backing PVC.
	// +kubebuilder:validation:Required
	Storage WorkspaceStorage `json:"storage"`

	// Seed describes how the workspace is initialised. When set, the
	// Workspace controller spawns a seed Job that populates the PVC
	// before any run may start.
	// +optional
	Seed *WorkspaceSeed `json:"seed,omitempty"`

	// Ephemeral marks a workspace auto-provisioned by a HarnessRun when
	// no workspaceRef was supplied. Ephemeral workspaces carry an
	// ownerReference to their HarnessRun and cascade-delete with it.
	// See ADR-0004.
	// +optional
	Ephemeral bool `json:"ephemeral,omitempty"`
}

WorkspaceSpec is the desired state of a Workspace — a persistent scratch area backed by a PVC, shared across one or more HarnessRuns. A Workspace outlives the runs that reference it: runs terminate, workspaces persist.

func (*WorkspaceSpec) DeepCopy 

func (in *WorkspaceSpec) DeepCopy() *WorkspaceSpec

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new WorkspaceSpec.

func (*WorkspaceSpec) DeepCopyInto 

func (in *WorkspaceSpec) DeepCopyInto(out *WorkspaceSpec)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type WorkspaceStatus 

type WorkspaceStatus struct {
	// ObservedGeneration is the spec generation last reconciled.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Phase summarises the workspace's lifecycle.
	// +optional
	Phase WorkspacePhase `json:"phase,omitempty"`

	// PVCName is the backing PersistentVolumeClaim, once created.
	// +optional
	PVCName string `json:"pvcName,omitempty"`

	// SeedJobName is the backing seed Job, while it exists.
	// +optional
	SeedJobName string `json:"seedJobName,omitempty"`

	// ActiveRunRef names the HarnessRun currently using the workspace.
	// Empty when the workspace is idle. Used to serialise concurrent
	// runs against a ReadWriteOnce PVC without reliance on PVC attach
	// errors.
	// +optional
	ActiveRunRef string `json:"activeRunRef,omitempty"`

	// TotalRuns is a monotonic count of HarnessRuns that have bound to
	// this workspace. Informational only.
	// +optional
	TotalRuns int32 `json:"totalRuns,omitempty"`

	// LastCountedRun is the name of the most recently counted
	// HarnessRun for TotalRuns. Used by the binding logic to keep the
	// TotalRuns increment idempotent across cache-staleness re-
	// reconciles: a re-bind of the same run name is recognised here
	// and skips the increment that the (ActiveRunRef==run.Name) guard
	// can't catch when the controller-runtime informer cache hasn't
	// yet propagated the previous binding update. See bindWorkspace.
	// +optional
	LastCountedRun string `json:"lastCountedRun,omitempty"`

	// LastActivity is the time of the most recent run's last event. Used
	// by future archive-on-idle logic.
	// +optional
	LastActivity *metav1.Time `json:"lastActivity,omitempty"`

	// Conditions report typed lifecycle signals. Known types: PVCBound,
	// Seeded, Ready.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

WorkspaceStatus reports the observed state of a Workspace.

func (*WorkspaceStatus) DeepCopy 

func (in *WorkspaceStatus) DeepCopy() *WorkspaceStatus

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new WorkspaceStatus.

func (*WorkspaceStatus) DeepCopyInto 

func (in *WorkspaceStatus) DeepCopyInto(out *WorkspaceStatus)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type WorkspaceStorage 

type WorkspaceStorage struct {
	// Size is the requested storage capacity (e.g. "20Gi").
	// +kubebuilder:validation:Required
	Size resource.Quantity `json:"size"`

	// StorageClass names the StorageClass for the PVC. When empty, the
	// cluster's default StorageClass is used.
	// +optional
	StorageClass string `json:"storageClass,omitempty"`

	// AccessMode is the PVC access mode. Defaults to ReadWriteOnce.
	// ReadWriteMany is supported but requires a networked filesystem
	// StorageClass and is not exercised on Kind.
	// +kubebuilder:default=ReadWriteOnce
	// +kubebuilder:validation:Enum=ReadWriteOnce;ReadWriteMany
	// +optional
	AccessMode corev1.PersistentVolumeAccessMode `json:"accessMode,omitempty"`
}

WorkspaceStorage configures the backing PVC.

func (*WorkspaceStorage) DeepCopy 

func (in *WorkspaceStorage) DeepCopy() *WorkspaceStorage

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new WorkspaceStorage.

func (*WorkspaceStorage) DeepCopyInto 

func (in *WorkspaceStorage) DeepCopyInto(out *WorkspaceStorage)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.