substrate

package
v0.0.0-...-a766d22 Latest Latest
Warning

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

 Go to latest Published: Jun 18, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultAtenetRouterURL = "http://atenet-router.ate-system.svc:80"

DefaultAtenetRouterURL is the in-cluster HTTP endpoint for Substrate's Envoy router.

View Source 
const GatewayTokenSecretKey = "token"

GatewayTokenSecretKey is the Secret data key used for per-harness OpenClaw gateway tokens.

View Source 
const HarnessLabelKey = "kagent.dev/agent-harness"

HarnessLabelKey labels substrate lifecycle managed for an AgentHarness.

View Source 
const (
	SandboxAgentLabelKey = "kagent.dev/sandbox-agent"
)

Variables

View Source 
var ErrNoFreeWorkers = errors.New("substrate worker pool has no free workers; try again later or increase WorkerPool replicas")

ErrNoFreeWorkers is returned when ate-api cannot assign a WorkerPool worker to resume an actor.

Functions

func ActorHost 

func ActorHost(actorID string, suffix string) string

ActorHost returns the atenet router Host header value for the actor.

func ActorID 

func ActorID(ah *v1alpha2.AgentHarness) string

ActorID returns a stable DNS-1123 actor id for this harness.

func ActorStatusLabel 

func ActorStatusLabel(status ateapipb.Actor_Status) string

ActorStatusLabel returns a stable human-readable actor status.

func GatewayRouterTarget 

func GatewayRouterTarget(routerURL, actorID string) (*url.URL, string, error)

GatewayRouterTarget returns the atenet-router reverse-proxy URL and Host header for an actor.

func HarnessNameFromLabels 

func HarnessNameFromLabels(labels map[string]string) string

HarnessNameFromLabels returns the AgentHarness name from generated lifecycle labels.

func ResolveGatewayToken 

func ResolveGatewayToken(ctx context.Context, kube client.Client, ah *v1alpha2.AgentHarness) (string, error)

ResolveGatewayToken returns the per-harness gateway token. Token source is validated at admission via AgentHarnessSubstrateSpec CEL rules.

func SandboxAgentActorID 

func SandboxAgentActorID(sa *v1alpha2.SandboxAgent) string

SandboxAgentActorID returns the legacy stable actor id prefix for a SandboxAgent.

func SandboxAgentActorTemplateName 

func SandboxAgentActorTemplateName(sa *v1alpha2.SandboxAgent) string

SandboxAgentActorTemplateName is the generated ActorTemplate name for a SandboxAgent.

func SandboxAgentNameFromLabels 

func SandboxAgentNameFromLabels(labels map[string]string) string

SandboxAgentNameFromLabels returns the SandboxAgent name from generated lifecycle labels.

func SandboxAgentSessionActorID 

func SandboxAgentSessionActorID(sa *v1alpha2.SandboxAgent, sessionID string) string

SandboxAgentSessionActorID returns a stable ate-api actor id for a SandboxAgent chat session.

Types

type AgentHarnessLifecycle 

type AgentHarnessLifecycle interface {
	EnsureGeneratedTemplate(ctx context.Context, ah *v1alpha2.AgentHarness) (LifecycleState, error)
	CleanupGeneratedTemplate(ctx context.Context, ah *v1alpha2.AgentHarness) (bool, error)
}

AgentHarnessLifecycle is the substrate lifecycle surface used by the AgentHarness controller.

type AgentsBackend 

type AgentsBackend struct {
	Lifecycle *Lifecycle
	AteClient *Client
}

AgentsBackend implements sandboxbackend.Backend for declarative/BYO SandboxAgents on Agent Substrate.

func NewAgentsBackend 

func NewAgentsBackend(lifecycle *Lifecycle, ate *Client) *AgentsBackend

NewAgentsBackend returns a substrate sandbox backend for SandboxAgent resources.

func (*AgentsBackend) BuildSandbox 

func (b *AgentsBackend) BuildSandbox(ctx context.Context, in sandboxbackend.BuildInput) ([]client.Object, error)

func (*AgentsBackend) ComputeReady 

func (b *AgentsBackend) ComputeReady(ctx context.Context, cl client.Client, nn types.NamespacedName) (metav1.ConditionStatus, string, string)

func (*AgentsBackend) GetOwnedResourceTypes 

func (b *AgentsBackend) GetOwnedResourceTypes() []client.Object

func (*AgentsBackend) OwnedResourceTypesFor 

func (b *AgentsBackend) OwnedResourceTypesFor(_ v1alpha2.AgentObject) ([]client.Object, error)

type ClawBackend 

type ClawBackend struct {
	// contains filtered or unexported fields
}

ClawBackend implements AsyncBackend for OpenClaw/NemoClaw on Agent Substrate.

func NewOpenClawBackend 

func NewOpenClawBackend(client *Client, backend v1alpha2.AgentHarnessBackendType, recorder record.EventRecorder) *ClawBackend

NewOpenClawBackend returns a substrate backend for openclaw/nemoclaw harness types.

func (*ClawBackend) DeleteAgentHarness 

func (b *ClawBackend) DeleteAgentHarness(ctx context.Context, h sandboxbackend.Handle) (bool, error)

func (*ClawBackend) EnsureAgentHarness 

func (b *ClawBackend) EnsureAgentHarness(ctx context.Context, ah *v1alpha2.AgentHarness) (sandboxbackend.EnsureResult, error)

func (*ClawBackend) GetStatus 

func (b *ClawBackend) GetStatus(ctx context.Context, h sandboxbackend.Handle) (metav1.ConditionStatus, string, string)

func (*ClawBackend) Name 

func (b *ClawBackend) Name() v1alpha2.AgentHarnessBackendType

func (*ClawBackend) OnAgentHarnessReady 

func (b *ClawBackend) OnAgentHarnessReady(_ context.Context, _ *v1alpha2.AgentHarness, _ sandboxbackend.Handle) error

type Client 

type Client struct {
	ateapipb.ControlClient
	// contains filtered or unexported fields
}

Client wraps ate-api Control gRPC.

func Dial 

func Dial(ctx context.Context, cfg Config) (*Client, error)

Dial connects to the ate-api server.

func (*Client) Close 

func (c *Client) Close() error

func (*Client) CreateActor 

func (c *Client) CreateActor(ctx context.Context, actorID, tmplNS, tmplName string) (*ateapipb.Actor, error)

func (*Client) DeleteActor 

func (c *Client) DeleteActor(ctx context.Context, actorID string) error

func (*Client) GetActor 

func (c *Client) GetActor(ctx context.Context, actorID string) (*ateapipb.Actor, error)

func (*Client) ListActors 

func (c *Client) ListActors(ctx context.Context) ([]*ateapipb.Actor, error)

ListActors returns all actors reflected in ate-api.

func (*Client) ListWorkers 

func (c *Client) ListWorkers(ctx context.Context) ([]*ateapipb.Worker, error)

ListWorkers returns all workers reflected in ate-api.

func (*Client) ResumeActor 

func (c *Client) ResumeActor(ctx context.Context, actorID string) (*ateapipb.Actor, error)

func (*Client) SuspendActor 

func (c *Client) SuspendActor(ctx context.Context, actorID string) error

type Config 

type Config struct {
	// AteAPIEndpoint is a gRPC target (e.g. dns:///api.ate-system.svc:443).
	AteAPIEndpoint string
	// TokenFile is a path to a file containing a bearer token for ate-api.
	TokenFile   string
	Insecure    bool
	DialTimeout time.Duration
	CallTimeout time.Duration
}

Config holds connection settings for Agent Substrate ate-api.

type Lifecycle 

type Lifecycle struct {
	Client    client.Client
	Defaults  LifecycleDefaults
	AteClient *Client
}

Lifecycle reconciles the Kubernetes lifecycle that kagent owns for a substrate AgentHarness. WorkerPools are externally owned; this helper only resolves the selected WorkerPool.

func NewLifecycle 

func NewLifecycle(kube client.Client, defaults LifecycleDefaults, ateClient *Client) *Lifecycle

func (*Lifecycle) ActorTemplateReady 

func (p *Lifecycle) ActorTemplateReady(ctx context.Context, key types.NamespacedName) (bool, error)

ActorTemplateReady reports whether the ActorTemplate golden snapshot is ready.

func (*Lifecycle) CleanupGeneratedTemplate 

func (p *Lifecycle) CleanupGeneratedTemplate(ctx context.Context, ah *v1alpha2.AgentHarness) (bool, error)

CleanupGeneratedTemplate removes external Substrate actors that Kubernetes garbage collection cannot see. The generated ActorTemplate CR is deleted by owner-reference garbage collection after the AgentHarness finalizer is removed. WorkerPools are externally owned and are never deleted here.

func (*Lifecycle) CleanupSandboxAgentTemplate 

func (p *Lifecycle) CleanupSandboxAgentTemplate(ctx context.Context, sa *v1alpha2.SandboxAgent) (bool, error)

CleanupSandboxAgentTemplate removes external Substrate actors tied to a generated SandboxAgent ActorTemplate.

func (*Lifecycle) EnsureGeneratedTemplate 

func (p *Lifecycle) EnsureGeneratedTemplate(ctx context.Context, ah *v1alpha2.AgentHarness) (LifecycleState, error)

EnsureGeneratedTemplate creates or updates the generated ActorTemplate and reports whether it is Ready.

type LifecycleDefaults 

type LifecycleDefaults struct {
	PauseImage           string
	RunscAMD64URL        string
	RunscAMD64SHA256     string
	RunscARM64URL        string
	RunscARM64SHA256     string
	DefaultWorkloadImage string
	DefaultWorkerPool    types.NamespacedName
}

LifecycleDefaults are cluster-wide defaults for generated ActorTemplate lifecycle.

type LifecycleState 

type LifecycleState struct {
	ActorTemplateReady bool
}

LifecycleState describes the generated Substrate lifecycle for an AgentHarness.

type SandboxAgentActorBackend 

type SandboxAgentActorBackend struct {
	// contains filtered or unexported fields
}

SandboxAgentActorBackend manages ate-api actors for SandboxAgent workloads.

func NewSandboxAgentActorBackend 

func NewSandboxAgentActorBackend(client *Client, atenetRouterURL string) *SandboxAgentActorBackend

NewSandboxAgentActorBackend returns a backend that ensures SandboxAgent actors on ate-api.

func (*SandboxAgentActorBackend) DeleteAllSandboxAgentActors 

func (b *SandboxAgentActorBackend) DeleteAllSandboxAgentActors(ctx context.Context, sa *v1alpha2.SandboxAgent) (bool, error)

DeleteAllSandboxAgentActors deletes legacy per-agent actors and all session actors for a SandboxAgent.

func (*SandboxAgentActorBackend) DeleteSandboxAgentActor 

func (b *SandboxAgentActorBackend) DeleteSandboxAgentActor(ctx context.Context, actorID string) (bool, error)

DeleteSandboxAgentActor deletes a substrate actor by id.

func (*SandboxAgentActorBackend) DeleteSandboxAgentSessionActor 

func (b *SandboxAgentActorBackend) DeleteSandboxAgentSessionActor(ctx context.Context, sa *v1alpha2.SandboxAgent, sessionID string) (bool, error)

DeleteSandboxAgentSessionActor deletes the actor for a single chat session.

func (*SandboxAgentActorBackend) EnsureSessionActor 

func (b *SandboxAgentActorBackend) EnsureSessionActor(ctx context.Context, sa *v1alpha2.SandboxAgent, sessionID string) (sandboxbackend.EnsureResult, error)

EnsureSessionActor creates and resumes the per-session actor for a SandboxAgent chat.

func (*SandboxAgentActorBackend) SuspendSessionActor 

func (b *SandboxAgentActorBackend) SuspendSessionActor(ctx context.Context, sa *v1alpha2.SandboxAgent, sessionID string) error

SuspendSessionActor checkpoints and frees the worker for a chat session actor.

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.