sets

package
v0.20.0 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Overview

Package sets holds named lists of skills and their immutable resolutions.

Index

Constants

View Source
const (
	ReasonSkillNotFound     = "skill_not_found"
	ReasonNoReleasedVersion = "no_released_version"
	ReasonVersionNotFound   = "version_not_found"
	ReasonHeld              = "held"
	ReasonRejected          = "rejected"
)

The reasons an entry is excluded.

View Source
const BundleRoot = ".agents/skills"

BundleRoot is where a bundle places skills, for any agent to read.

Variables

View Source
var ErrNameTaken = errors.New("set name already exists")

ErrNameTaken reports a duplicate set name.

Functions

func CheckKeySet

func CheckKeySet(ctx context.Context, set *Set) error

CheckKeySet applies a set-limited key's limit. A deleted set gives 403, so the key never becomes unrestricted and never learns which sets exist.

func RegisterRoutes

func RegisterRoutes(api huma.API, router chi.Router, store *Store, storage platform.Storage)

RegisterRoutes wires the set endpoints.

func ResolutionID

func ResolutionID(entries []ResolvedEntry) string

ResolutionID hashes the sorted name, version and digest list.

func WriteBundle

func WriteBundle(ctx context.Context, w io.Writer, storage platform.Storage, res *Resolution, paths map[string]string) error

WriteBundle writes the tar.gz of one resolution to w. It builds on demand, because the skill archives it copies are already content-addressed.

Types

type BundleManifest

type BundleManifest struct {
	Set          string                `json:"set"`
	ResolutionID string                `json:"resolution_id"`
	Complete     bool                  `json:"complete"`
	Skills       []BundleManifestSkill `json:"skills"`
}

BundleManifest is written at BundleRoot/manifest.json.

type BundleManifestSkill

type BundleManifestSkill struct {
	Name    string `json:"name"`
	Version int    `json:"version"`
	SHA256  string `json:"sha256"`
	Archive string `json:"archive"`
}

BundleManifestSkill names one skill in a bundle. SHA256 is the digest of the skill's archive, which the bundle carries at Archive so a consumer can check it: an unpacked tree cannot reproduce the digest of an uploaded archive.

type ChangeNotifier

type ChangeNotifier interface {
	SetChanged(ctx context.Context, tx pgx.Tx, setID string) error
}

ChangeNotifier hears of a set edit inside its transaction.

type ExcludedEntry

type ExcludedEntry struct {
	Name      string `json:"name"`
	Requested string `json:"requested"`
	Reason    string `json:"reason"`
}

ExcludedEntry is a set entry that a resolve could not serve.

type GoneError

type GoneError struct{ Skill string }

GoneError names the skill a stored resolution can no longer serve.

func (*GoneError) Error

func (e *GoneError) Error() string

type Querier

type Querier interface {
	Exec(ctx context.Context, sql string, args ...any) (pgconn.CommandTag, error)
	QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
}

Querier runs against a pool or a transaction.

type Resolution

type Resolution struct {
	ID       string          `json:"id"`
	Set      string          `json:"set"`
	Complete bool            `json:"complete"`
	Entries  []ResolvedEntry `json:"entries"`
	Excluded []ExcludedEntry `json:"excluded,omitempty"`
}

Resolution is the immutable result of resolving a set.

func Resolve

func Resolve(ctx context.Context, q Querier, set *Set) (*Resolution, error)

Resolve computes the set's current resolution through q. It stores nothing, so a caller can compare it inside a transaction.

func ResolveAndRecord

func ResolveAndRecord(ctx context.Context, store *Store, set *Set) (*Resolution, error)

ResolveAndRecord resolves a set, stores the resolution and notes the caller. Only an API key counts as a caller: a person browsing the UI consumes nothing.

type ResolvedEntry

type ResolvedEntry struct {
	Name          string `json:"name"`
	Version       int    `json:"version"`
	SHA256        string `json:"sha256"`
	ScanVerdict   string `json:"scan_verdict"`
	ApprovalState string `json:"approval_state"`
	// RemovedFromGit warns that the skill's folder left its git repo. The
	// last version stays served until someone deletes the skill.
	RemovedFromGit bool `json:"removed_from_git,omitempty"`
}

ResolvedEntry is one exact version in a resolution.

type Set

type Set struct {
	ID          string     `json:"id"`
	Name        string     `json:"name"`
	Description string     `json:"description"`
	Entries     []SetEntry `json:"entries"`
	CreatedBy   string     `json:"created_by"`
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
}

Set is a named list of skills.

type SetCaller

type SetCaller struct {
	Name         string    `json:"name"`
	ResolutionID string    `json:"resolution_id"`
	LastSeenAt   time.Time `json:"last_seen_at"`
}

SetCaller is the last use of a set by one identity.

type SetDetail

type SetDetail struct {
	Set
	Callers []SetCaller `json:"callers"`
}

SetDetail is a set with who last used it.

type SetEntry

type SetEntry struct {
	Name    string `json:"name"`
	Version int    `json:"version,omitempty" doc:"An exact version. Omit it for latest."`
}

SetEntry is one skill in a set. Version 0 means latest.

type Store

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

Store persists sets.

func NewStore

func NewStore(pool *pgxpool.Pool) *Store

NewStore constructs a Store.

func (*Store) ArchivePath

func (s *Store) ArchivePath(ctx context.Context, name string, version int) (string, error)

ArchivePath returns where a resolved version's archive lives, or "" when its skill or version has gone.

func (*Store) Callers

func (s *Store) Callers(ctx context.Context, set *Set) ([]SetCaller, error)

Callers lists who last used a set, newest first.

func (*Store) CheckAvailable

func (s *Store) CheckAvailable(ctx context.Context, res *Resolution) (map[string]string, error)

CheckAvailable returns the archive path of each entry, or a GoneError before any byte of the response is written.

func (*Store) Create

func (s *Store) Create(ctx context.Context, name, description string, entries []SetEntry, actor string) (*Set, error)

Create inserts a set and records it in the audit log.

func (*Store) Delete

func (s *Store) Delete(ctx context.Context, name, actor string) (bool, error)

Delete removes a set and reports whether it existed.

func (*Store) Get

func (s *Store) Get(ctx context.Context, name string) (*Set, error)

Get returns a set with its entries, or nil.

func (*Store) GetByID

func (s *Store) GetByID(ctx context.Context, id string) (*Set, error)

GetByID returns a set with its entries, or nil.

func (*Store) GetResolution

func (s *Store) GetResolution(ctx context.Context, set *Set, id string) (*Resolution, error)

GetResolution returns a stored resolution, or nil.

func (*Store) List

func (s *Store) List(ctx context.Context) ([]Set, error)

List returns every set with its entries.

func (*Store) Recheck

func (s *Store) Recheck(ctx context.Context, tx pgx.Tx, setID string) (*Set, *Resolution, bool, error)

Recheck recomputes a set's resolution inside tx and reports whether its id differs from the last one recorded. The row lock serialises two changes to one set, so each sees the other's result. A changed id is saved in the same transaction, so a consumer told of it can fetch it at once.

func (*Store) RecordCaller

func (s *Store) RecordCaller(ctx context.Context, set *Set, userID, name, resolutionID string) error

RecordCaller notes the last use of a set by a key's identity.

func (*Store) SaveResolution

func (s *Store) SaveResolution(ctx context.Context, set *Set, res *Resolution) error

SaveResolution stores a resolution. The row for an id never changes.

func (*Store) SetNotifier

func (s *Store) SetNotifier(n ChangeNotifier)

SetNotifier attaches the receiver of set edits.

func (*Store) SkillVersionExists

func (s *Store) SkillVersionExists(ctx context.Context, name string, version int) (bool, error)

SkillVersionExists supports validating an entry at edit time.

func (*Store) Update

func (s *Store) Update(ctx context.Context, name, description string, entries []SetEntry, actor string) (*Set, error)

Update replaces a set's description and entries. It returns nil when no set has the name. The audit record keeps the old entries.

Jump to

Keyboard shortcuts

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