sets

package
v0.21.3 Latest Latest
Warning

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

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

Documentation

Overview

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

Index

Constants

View Source
const (
	KindName      = "name"
	KindPattern   = "pattern"
	KindExclusion = "exclusion"
)

Entry kinds.

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 KindOf added in v0.21.0

func KindOf(name string) string

KindOf derives an entry's kind from its name.

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.

Exact names resolve as before: one that cannot be served makes the set incomplete. Patterns add every skill whose latest released version they match; a matched skill with nothing released is skipped, so a new skill never breaks a set. Exclusions apply last.

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" doc:"A skill name, a pattern such as payments:* or *, or an exclusion such as !payments:legacy."`
	Version int    `json:"version,omitempty" doc:"An exact version. Omit it for latest. Only a skill name takes one."`
	Kind    string `json:"kind,omitempty" readOnly:"true" enum:"name,pattern,exclusion" doc:"Derived from the name."`
}

SetEntry is one entry in a set: an exact skill name, a pattern such as "payments:*" or "*", or an exclusion such as "!payments:legacy". Version 0 means latest; only an exact name may pin one.

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