node

Documentation

Overview

Package node defines the agent execution node: the unit that consumes tasks and runs tools. The interfaces here say nothing about where a node runs — an in-process goroutine today, a Kubernetes pod or serverless container tomorrow — so the execution substrate can change without touching the control plane or the queue.

Index

• type Factory
• type Health
• type Node
• type Spawner
• type Spec

Types

type Factory

type Factory interface {
	New(ctx context.Context, spec Spec) (Node, error)
}

Factory creates nodes. Consumers call it when scaling out; it is the seam where new execution substrates plug in.

type Health

type Health string

Health is a node's reported condition.

const (
	Ready   Health = "ready"
	Stopped Health = "stopped"
)

type Node

type Node interface {
	// ID uniquely identifies the node within its deployment.
	ID() string
	// Run executes t and returns its result. Implementations must be safe
	// for concurrent Run calls.
	Run(ctx context.Context, t task.Task) (task.Result, error)
	// Health reports the node's current condition.
	Health(ctx context.Context) Health
	// Close releases the node's resources. A closed node reports Stopped
	// and rejects Run.
	Close(ctx context.Context) error
}

Node is one agent execution node.

type Spawner

type Spawner func(ctx context.Context, t task.Task) (string, error)

Spawner submits a sub-task back into the node's deployment and returns its task ID. The control plane injects it when creating nodes; locally it enqueues in memory, remotely it posts to the control plane API. Tools only reach it through their policy's spawn allowlist.

type Spec

type Spec struct {
	// Deployment is the owning deployment's name; node IDs derive from it.
	Deployment string
	// PDP decides every workspace operation and spawn attempt the node's
	// tools make. It is compiled from the deployment's access definition
	// (flat policies or an NGAC spec); nil denies everything.
	PDP sandbox.PDP
	// Spawn is how this node's tools submit sub-tasks. Nil disables
	// spawning entirely.
	Spawn Spawner
}

Spec describes the nodes a Factory should produce for one deployment.