agentcontrol

package

v1.0.0-beta.15 Latest Latest Go to latest Published: Sep 29, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/dagger/dagger

Links

Documentation ¶

Overview ¶

Package agentcontrol defines the authoritative, revisioned agent telemetry projection shared by producers, live consumers and archive verification. It contains no runtime lookup or discovery API.

Index ¶

Constants
func Decode(rec sdklog.Record) (*Agent, *Subscription, error)
func IsRecord(rec sdklog.Record) bool
type Agent
type EdgeKey
type Expectation
type Index
type Key
type Namespace
- func (ns Namespace) Validate() error
type Subscription
- func (s Subscription) Record() log.Record
- func (s Subscription) Validate() error

Constants ¶

View Source

const (
	VersionAttr      = "dagger.io/agent.control.version"
	KindAttr         = "dagger.io/agent.control.kind"
	SessionAttr      = "dagger.io/agent.control.session"
	TraceAttr        = "dagger.io/agent.control.trace"
	IncarnationAttr  = "dagger.io/agent.control.incarnation"
	RevisionAttr     = "dagger.io/agent.control.revision"
	ParentAttr       = "dagger.io/agent.parent"
	CaptureErrorAttr = "dagger.io/agent.capture.error"
	PreTeardownAttr  = "dagger.io/agent.pre_teardown_state"
	FailureAttr      = "dagger.io/agent.failure"
	ActivityAttr     = "dagger.io/agent.activity"
	SubscriberAttr   = "dagger.io/agent.subscription.subscriber"
	StatesAttr       = "dagger.io/agent.subscription.states"
)

View Source

const Version = 1

Variables ¶

This section is empty.

Functions ¶

func Decode ¶

func Decode(rec sdklog.Record) (*Agent, *Subscription, error)

Decode rejects missing or wrongly typed fields instead of manufacturing completeness. Optional facts are explicit empty strings on the wire.

func IsRecord ¶

func IsRecord(rec sdklog.Record) bool

IsRecord recognizes even unsupported/malformed control versions so they cannot leak into ordinary logs.

Types ¶

type Agent ¶

type Agent struct {
	Key
	Revision         int64
	Name             string
	Parent           string
	CallDigest       string
	Digest           string
	CaptureError     string
	State            string
	StopReason       string
	PreTeardownState string
	Failure          string
	Activity         time.Time
}

Agent is a complete projection, not a delta. A failed capture clears Digest: an earlier conversation must never masquerade as the new committed tip.

func (Agent) ClosureRoot ¶

func (a Agent) ClosureRoot() (string, bool)

ClosureRoot is the committed conversation leaf whose complete recipe closure an archive must carry. A recorded capture failure has none (Validate makes that the only way Digest is empty): it is still witnessed, but restore carries it as unrestorable.

func (Agent) Record ¶

func (a Agent) Record() log.Record

func (Agent) RestoreState ¶

func (a Agent) RestoreState() (string, error)

func (Agent) Validate ¶

func (a Agent) Validate() error

type EdgeKey ¶

type EdgeKey struct {
	Namespace
	Watched    string
	Subscriber string
}

type Expectation ¶

type Expectation struct {
	Agents        map[Key]int64
	Subscriptions map[EdgeKey]int64
}

Expectation is supplied by quiesced producers, never inferred from received records. It witnesses identities and final revisions, not a second state store. It must already be scoped to the archive reader's telemetry visibility.

type Index ¶

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

Index is a materialized view of control telemetry. Owners provide locking. Maps are private so every update uses the same revision and validation rules. Invalid and equivocal records fail closed, including during historical import.

func (*Index) Agents ¶

func (idx *Index) Agents() []Agent

func (*Index) ApplyAgent ¶

func (idx *Index) ApplyAgent(a Agent) (bool, error)

func (*Index) ApplyRecord ¶

func (idx *Index) ApplyRecord(rec sdklog.Record) (bool, error)

func (*Index) ApplySubscription ¶

func (idx *Index) ApplySubscription(s Subscription) (bool, error)

func (*Index) Subscriptions ¶

func (idx *Index) Subscriptions() []Subscription

func (*Index) Verify ¶

func (idx *Index) Verify(want Expectation) error

Verify checks roster/graph completeness. Payload closure and persistence are separate checks: success here alone never authorizes sealing an archive.

type Key ¶

type Key struct {
	Namespace
	Handle string
}

type Namespace ¶

type Namespace struct {
	Session     string
	Trace       string
	Incarnation string
}

Namespace separates independent revision sequences. Restoring a handle in a new session creates a new incarnation; its revision is never compared with the revision from the source session.

func (Namespace) Validate ¶

func (ns Namespace) Validate() error

type Subscription ¶

type Subscription struct {
	EdgeKey
	Revision int64
	States   []string
}

Subscription replaces the entire state filter. An empty filter is a removal tombstone, retained so importing old history cannot resurrect the edge.

func (Subscription) Record ¶

func (s Subscription) Record() log.Record

func (Subscription) Validate ¶

func (s Subscription) Validate() error

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL