agentkit

Documentation

Overview

Package agentkit implements transport-independent control-plane invariants. Persistent stores and command surfaces can wrap this state machine; the wire records themselves are generated from schema/agent_control.cue.

Index

• func DelegationAllowed(team spec.AgentTeam, from, to, operation string) bool
• func NewID() spec.UUIDv7
• func ValidateTeam(team spec.AgentTeam) error
• type Store
  • func OpenStore(dir string) (*Store, error)
  • func (s *Store) AbortRequested(runID spec.UUIDv7) (*spec.AgentAbortControl, error)
  • func (s *Store) AppendEvent(v spec.AgentEvent) error
  • func (s *Store) AppendTerminalFrame(v spec.TerminalFrame) (spec.TerminalFrame, error)
  • func (s *Store) ClearAbort(runID spec.UUIDv7) error
  • func (s *Store) CreateRunOnce(v spec.AgentRunRequest) (spec.AgentRunRequest, bool, error)
  • func (s *Store) Events(runID spec.UUIDv7) ([]spec.AgentEvent, error)
  • func (s *Store) Federation() ([]spec.AgentFederationRecord, error)
  • func (s *Store) FindIdempotency(key string) (spec.AgentRunRequest, bool, error)
  • func (s *Store) Incident(id spec.UUIDv7) (spec.Incident, error)
  • func (s *Store) Incidents() ([]spec.Incident, error)
  • func (s *Store) PutFederation(v spec.AgentFederationRecord) error
  • func (s *Store) PutIncident(v spec.Incident) error
  • func (s *Store) PutRCA(v spec.RCARecord) error
  • func (s *Store) PutRecovery(v spec.RecoveryDecision) error
  • func (s *Store) PutRun(v spec.AgentRunRequest) error
  • func (s *Store) PutSession(v spec.AgentSession) error
  • func (s *Store) PutTeam(v spec.AgentTeamRecord) error
  • func (s *Store) RCA(id spec.UUIDv7) (spec.RCARecord, error)
  • func (s *Store) RCAs() ([]spec.RCARecord, error)
  • func (s *Store) Recoveries() ([]spec.RecoveryDecision, error)
  • func (s *Store) Recovery(id spec.UUIDv7) (spec.RecoveryDecision, error)
  • func (s *Store) RequestAbort(v spec.AgentAbortControl) error
  • func (s *Store) Run(id spec.UUIDv7) (spec.AgentRunRequest, error)
  • func (s *Store) Runs() ([]spec.AgentRunRequest, error)
  • func (s *Store) Session(id spec.UUIDv7) (spec.AgentSession, error)
  • func (s *Store) Sessions() ([]spec.AgentSession, error)
  • func (s *Store) Team(id spec.UUIDv7) (spec.AgentTeamRecord, error)
  • func (s *Store) Teams() ([]spec.AgentTeamRecord, error)
  • func (s *Store) TerminalFrames(runID spec.UUIDv7) ([]spec.TerminalFrame, error)
  • func (s *Store) WaitAbort(ctx context.Context, runID spec.UUIDv7) (*spec.AgentAbortControl, error)
• type Workflow
  • func NewWorkflow() *Workflow
  • func (w *Workflow) CompleteRCA(rcaID spec.UUIDv7, rootCause string, findings []string) (spec.RCARecord, error)
  • func (w *Workflow) DecideRecovery(incidentID, rcaID spec.UUIDv7, action string, emergencyAbort bool, ...) (spec.RecoveryDecision, error)
  • func (w *Workflow) RecordIncident(runID spec.UUIDv7, summary string, evidence []string) (spec.Incident, error)
  • func (w *Workflow) StartRCA(incidentID spec.UUIDv7) (spec.RCARecord, error)

Functions

func DelegationAllowed

func DelegationAllowed(team spec.AgentTeam, from, to, operation string) bool

func NewID

func NewID() spec.UUIDv7

NewID returns a UUIDv7 for durable agent-domain records.

func ValidateTeam

func ValidateTeam(team spec.AgentTeam) error

ValidateTeam enforces graph invariants that CUE cannot express: unique member identities and edges/coordinator that reference declared members. Cycles are permitted because peer review loops are valid; authority still comes only from explicitly authored edges and allow lists.

Types

type Store

type Store struct{ Dir string }

Store is a daemon-free durable agent state directory. Every record is a CUE-generated domain type; JSONL event logs are append-only and sequence checked under an advisory file lock so separate charly invocations compose.

func OpenStore

func OpenStore(dir string) (*Store, error)

func (*Store) AbortRequested

func (s *Store) AbortRequested(runID spec.UUIDv7) (*spec.AgentAbortControl, error)

func (*Store) AppendEvent

func (s *Store) AppendEvent(v spec.AgentEvent) error

func (*Store) AppendTerminalFrame

func (s *Store) AppendTerminalFrame(v spec.TerminalFrame) (spec.TerminalFrame, error)

AppendTerminalFrame assigns the next durable per-run sequence under the cross-process store lock and appends one generated terminal evidence frame.

func (*Store) ClearAbort

func (s *Store) ClearAbort(runID spec.UUIDv7) error

func (*Store) CreateRunOnce

func (s *Store) CreateRunOnce(v spec.AgentRunRequest) (spec.AgentRunRequest, bool, error)

CreateRunOnce atomically reserves an idempotency key across concurrent controller processes. It returns the existing record without overwriting it.

func (*Store) Events

func (s *Store) Events(runID spec.UUIDv7) ([]spec.AgentEvent, error)

func (*Store) Federation

func (s *Store) Federation() ([]spec.AgentFederationRecord, error)

func (*Store) FindIdempotency

func (s *Store) FindIdempotency(key string) (spec.AgentRunRequest, bool, error)

func (*Store) Incident

func (s *Store) Incident(id spec.UUIDv7) (spec.Incident, error)

func (*Store) Incidents

func (s *Store) Incidents() ([]spec.Incident, error)

func (*Store) PutFederation

func (s *Store) PutFederation(v spec.AgentFederationRecord) error

func (*Store) PutIncident

func (s *Store) PutIncident(v spec.Incident) error

func (*Store) PutRCA

func (s *Store) PutRCA(v spec.RCARecord) error

func (*Store) PutRecovery

func (s *Store) PutRecovery(v spec.RecoveryDecision) error

func (*Store) PutRun

func (s *Store) PutRun(v spec.AgentRunRequest) error

func (*Store) PutSession

func (s *Store) PutSession(v spec.AgentSession) error

func (*Store) PutTeam

func (s *Store) PutTeam(v spec.AgentTeamRecord) error

func (*Store) RCA

func (s *Store) RCA(id spec.UUIDv7) (spec.RCARecord, error)

func (*Store) RCAs

func (s *Store) RCAs() ([]spec.RCARecord, error)

func (*Store) Recoveries

func (s *Store) Recoveries() ([]spec.RecoveryDecision, error)

func (*Store) Recovery

func (s *Store) Recovery(id spec.UUIDv7) (spec.RecoveryDecision, error)

func (*Store) RequestAbort

func (s *Store) RequestAbort(v spec.AgentAbortControl) error

RequestAbort records cross-process cancellation intent for the synchronous, ephemeral controller currently owning a run. No agent daemon is involved.

func (*Store) Run

func (s *Store) Run(id spec.UUIDv7) (spec.AgentRunRequest, error)

func (*Store) Runs

func (s *Store) Runs() ([]spec.AgentRunRequest, error)

func (*Store) Session

func (s *Store) Session(id spec.UUIDv7) (spec.AgentSession, error)

func (*Store) Sessions

func (s *Store) Sessions() ([]spec.AgentSession, error)

func (*Store) Team

func (s *Store) Team(id spec.UUIDv7) (spec.AgentTeamRecord, error)

func (*Store) Teams

func (s *Store) Teams() ([]spec.AgentTeamRecord, error)

func (*Store) TerminalFrames

func (s *Store) TerminalFrames(runID spec.UUIDv7) ([]spec.TerminalFrame, error)

func (*Store) WaitAbort

func (s *Store) WaitAbort(ctx context.Context, runID spec.UUIDv7) (*spec.AgentAbortControl, error)

WaitAbort blocks on fsnotify's platform-native directory notification stream until the requested run's abort record exists. The pre/post-watch checks close the creation race without polling, sleeps, retries, or a permanent controller.

type Workflow

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

func NewWorkflow

func NewWorkflow() *Workflow

func (*Workflow) CompleteRCA

func (w *Workflow) CompleteRCA(rcaID spec.UUIDv7, rootCause string, findings []string) (spec.RCARecord, error)

func (*Workflow) DecideRecovery

func (w *Workflow) DecideRecovery(incidentID, rcaID spec.UUIDv7, action string, emergencyAbort bool, params *spec.RecoveryParams) (spec.RecoveryDecision, error)

DecideRecovery plans the recovery for an incident whose RCA completed (or an explicitly authorized emergency abort). The returned decision is deliberately NOT recorded here and the incident deliberately STAYS in awaiting_recovery: agentkit is the transport-independent invariant layer — executing a recovery action (reattach/resume/restart/…) is transport work, and durability is the agentkit.Store layer, so neither belongs in this state machine. The #Incident state enum has no state between awaiting_recovery and resolved, so an in-memory transition here would claim progress no execution produced.

The owning durable component is the agent control plane's recovery leg — candy/plugin-agent's applyRecovery — which persists the decision (Store.PutRecovery: planned → applied/failed with applied_at), executes the action, and only then moves the incident to resolved (Store.PutIncident).

func (*Workflow) RecordIncident

func (w *Workflow) RecordIncident(runID spec.UUIDv7, summary string, evidence []string) (spec.Incident, error)

func (*Workflow) StartRCA

func (w *Workflow) StartRCA(incidentID spec.UUIDv7) (spec.RCARecord, error)