Documentation
¶
Index ¶
- func CanReadVersion(ctx context.Context, ver *Version) bool
- func DecidePublish(rep *scan.Report, o gate.OwnerState, floor float64, override bool) gate.Decision
- func ErrGitBound(name, where string) error
- func NewChiAPI() (chi.Router, huma.API)
- func ParseFrontmatter(content string) (map[string]interface{}, string, error)
- func RegisterReviewQueueRoutes(api huma.API, store *Store, owners OwnerResolver)
- func RegisterRoutes(api huma.API, router chi.Router, store *Store, storage platform.Storage, ...)
- func Unpack(r io.Reader, destDir string) error
- type Alias
- type ChangeNotifier
- type EvalJobRequest
- type Executor
- type FileChange
- type FileEntry
- type GitBoundary
- type HeldVersion
- type ListOptions
- type OutboundChange
- type OwnerResolver
- type PublishBody
- type PublishQuality
- type Publisher
- func (p *Publisher) OpenChange(ctx context.Context, name string, archive []byte, note string, git GitBoundary) (*PublishBody, error)
- func (p *Publisher) Publish(ctx context.Context, name string, rawBody []byte, override bool) (*PublishBody, error)
- func (p *Publisher) ScanArchive(ctx context.Context, rawBody []byte) (*scan.Report, gate.Decision, error)
- type QualityEvidence
- type QueueSubmitter
- type ReleaseEvent
- type Releaser
- type RouteOptions
- type Skill
- type SpecValidation
- type Store
- func (s *Store) ApproveReason(ctx context.Context, e Executor, name string, version int, reason string, ...) (bool, error)
- func (s *Store) BulkSetReview(ctx context.Context, names []string, reviewedBy string) (int, error)
- func (s *Store) ClearReview(ctx context.Context, name string) error
- func (s *Store) Create(ctx context.Context, name, displayName, description, content string, ...) (*Skill, error)
- func (s *Store) CreateAlias(ctx context.Context, alias, canonical string) error
- func (s *Store) CreateVersion(ctx context.Context, skillID, archivePath, checksum, changelog string, ...) (*Version, error)
- func (s *Store) Delete(ctx context.Context, name string) error
- func (s *Store) DeleteAlias(ctx context.Context, alias string) error
- func (s *Store) DiffAgainstServed(ctx context.Context, name string, version int) (*VersionDiff, error)
- func (s *Store) GetByName(ctx context.Context, name string) (*Skill, error)
- func (s *Store) GetVersion(ctx context.Context, skillName string, version int) (*Version, error)
- func (s *Store) List(ctx context.Context, opts ListOptions) ([]Skill, int, error)
- func (s *Store) ListAliases(ctx context.Context, canonical string) ([]Alias, error)
- func (s *Store) ListHeldVersions(ctx context.Context) ([]HeldVersion, error)
- func (s *Store) ListVersions(ctx context.Context, skillName string) ([]Version, error)
- func (s *Store) Merge(ctx context.Context, sourceName, targetName string) (*Skill, error)
- func (s *Store) OutstandingReasons(ctx context.Context, name string, version int) ([]string, error)
- func (s *Store) Pool() *pgxpool.Pool
- func (s *Store) RejectReason(ctx context.Context, name string, version int, reason, actorEmail, note string) error
- func (s *Store) RejectVersion(ctx context.Context, name string, version int, by, note string) error
- func (s *Store) ReleaseVersion(ctx context.Context, e Executor, name string, version int, by, note string) error
- func (s *Store) ResolveAlias(ctx context.Context, name string) (string, error)
- func (s *Store) Search(ctx context.Context, query string, limit int) ([]Skill, error)
- func (s *Store) SetNotifier(n ChangeNotifier)
- func (s *Store) SetReview(ctx context.Context, name, reviewedBy string) error
- func (s *Store) UpdateSpecFields(ctx context.Context, ...) error
- type SuiteLookup
- type SuiteRecord
- type Version
- type VersionDiff
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CanReadVersion ¶ added in v0.16.0
CanReadVersion is the read rule for a version's content. Any person may read any version, and the worker must reach a held version to score it. Another scoped key is a machine that would run what it fetches, so it gets only a released version.
func DecidePublish ¶ added in v0.10.0
DecidePublish is the one definition of "what does this scan report mean for this version" shared by every route that creates a version — publish and import alike. A version has no quality state yet by definition: the evaluation that could produce one runs against the bundle this call is creating, so q is always nil here. o carries the resolved ownership state; pass a zero OwnerState to skip the ownership dimension entirely (the CLI's local pre-scan does exactly that). floor and override are the resolved gate.Policy inputs; import has no interactive override and must always pass false.
func ErrGitBound ¶ added in v0.18.0
ErrGitBound answers a write that git owns.
func NewChiAPI ¶
NewChiAPI creates a new Chi router and Huma API suitable for production and tests. Returns both so callers can mount additional middleware on the router or serve it directly.
func ParseFrontmatter ¶
ParseFrontmatter parses YAML frontmatter from content delimited by "---\n" blocks. It returns the frontmatter as a map, the body (content after the closing delimiter), and any error.
If no frontmatter is found (content does not start with "---\n"), it returns nil, content, nil.
func RegisterReviewQueueRoutes ¶ added in v0.10.0
func RegisterReviewQueueRoutes(api huma.API, store *Store, owners OwnerResolver)
RegisterReviewQueueRoutes wires the cross-skill held-version listing. Reading is open to any authenticated member: a hold that only its approver can see is a hold nobody discovers. Acting on one stays owner/admin, on POST /api/skills/{name}/versions/{version}/review.
owners hydrates RulePattern/Owners/Unowned per row, same as the publish and per-version review handlers. A nil owners leaves every row's ownership fields zero-valued, matching how a nil RouteOptions.Ownership behaves elsewhere — no resolver means ownership contributes nothing.
func RegisterRoutes ¶
func RegisterRoutes(api huma.API, router chi.Router, store *Store, storage platform.Storage, opts RouteOptions)
RegisterRoutes wires up all skill-related HTTP endpoints onto the provided Huma API and Chi router. The router is needed for the two raw-response routes (download + scan) that stream bytes rather than returning JSON.
Types ¶
type ChangeNotifier ¶ added in v0.16.0
type ChangeNotifier interface {
VersionReleased(ctx context.Context, tx pgx.Tx, ev ReleaseEvent) error
SkillChanged(ctx context.Context, tx pgx.Tx, skill string) error
}
ChangeNotifier hears of a change inside the transaction that makes it. Declared here because internal/webhooks imports this package.
type EvalJobRequest ¶ added in v0.10.0
type EvalJobRequest struct {
SkillID string
SkillName string
Version int
SuiteRef string
Tier string
RequestedBy string
}
EvalJobRequest is what publish needs to enqueue an evaluation. It mirrors the fields of evalqueue.Job that publish sets, but is declared in this package rather than imported: internal/evalqueue imports internal/skill (for route wiring), so importing evalqueue back here would cycle. Callers adapt a real evalqueue.Executor to QueueSubmitter (see internal/server).
type Executor ¶ added in v0.10.0
type Executor 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)
}
Executor is the subset of *pgxpool.Pool that a gate transition needs. Declared here rather than reused from internal/quality to avoid a cycle.
type FileChange ¶ added in v0.10.0
type FileChange struct {
Path string `json:"path"`
Status string `json:"status"` // "added", "removed", or "modified"
}
FileChange describes how a single file differs between the version being diffed and the currently-served baseline.
type GitBoundary ¶ added in v0.18.0
type GitBoundary interface {
// Bound reports whether git owns the skill, and names its repo path.
Bound(ctx context.Context, name string) (bool, string, error)
// OpenChange commits archive to a new branch and opens a pull request,
// on behalf of the user in ctx.
OpenChange(ctx context.Context, name string, archive []byte, note string) (*OutboundChange, error)
}
GitBoundary knows which skills git owns and opens their changes as pull requests. An interface because git sync imports this package.
type HeldVersion ¶ added in v0.10.0
type HeldVersion struct {
SkillName string `json:"skill_name"`
Version int `json:"version"`
GateState string `json:"gate_state"`
GateDecision json.RawMessage `json:"gate_decision,omitempty"`
// ScanResult is included because the review screen shows the findings
// beside the decision: the decision says what may clear the hold, and the
// findings say what caused it. One request, both halves.
ScanResult json.RawMessage `json:"scan_result,omitempty"`
PublishedBy string `json:"published_by,omitempty"`
GatedAt *time.Time `json:"gated_at,omitempty"`
CreatedAt time.Time `json:"created_at"`
// HoldReasons is every reason the version was held for, in the order
// recorded at publish time. Outstanding is the subset with no approval
// row yet — these can differ once one reason clears but the version
// stays held on another, which is the case the review screen most needs
// to render honestly.
HoldReasons []string `json:"hold_reasons"`
Outstanding []string `json:"outstanding"`
// RulePattern, Owners and Unowned are hydrated per row from the
// OwnerResolver after the query runs — the query has no way to resolve
// ownership itself.
RulePattern string `json:"rule_pattern,omitempty"`
Owners []gate.OwnerRef `json:"owners"`
Unowned bool `json:"unowned"`
}
HeldVersion is one version the publish gate is holding, joined to the name of the skill it belongs to. A held version has a number and an archive but is not pointed at by skills.latest_version, so it is servable by nothing — this listing is the only place it is visible.
type ListOptions ¶ added in v0.7.0
ListOptions holds optional filter parameters for List.
type OutboundChange ¶ added in v0.18.0
type OutboundChange struct {
ID string `json:"id"`
PRNumber int `json:"pr_number"`
PRURL string `json:"pr_url"`
State string `json:"state"`
}
OutboundChange is the pull request Skael opened for a change to a git-bound skill. The skill gets a version when it merges.
type OwnerResolver ¶ added in v0.10.0
type OwnerResolver interface {
ResolveForPublish(ctx context.Context, skillName string, user *auth.User) (gate.OwnerState, error)
ClaimOnFirstPublish(ctx context.Context, skillName string, user *auth.User) error
}
OwnerResolver is the subset of the ownership store publish needs. It is declared here rather than imported because internal/ownership must stay free of internal/skill and the concrete wiring lives in internal/server — the same shape as QueueSubmitter and SuiteLookup.
ResolveForPublish folds instance privilege into IsOwner: an instance owner or admin is an implicit owner of everything, which is what makes O5's "admins are the reviewers of record" fall out without a special case.
type PublishBody ¶ added in v0.16.0
type PublishBody struct {
Version
Created bool `json:"created"`
Quality PublishQuality `json:"quality"`
Decision gate.Decision `json:"decision"`
// Change is set instead of a version for a git-bound skill: the pull
// request whose merge publishes it.
Change *OutboundChange `json:"change,omitempty"`
}
PublishBody is the result of a publish.
type PublishQuality ¶ added in v0.16.0
type PublishQuality struct {
State string `json:"state,omitempty"`
JobID string `json:"job_id,omitempty"`
}
PublishQuality reports whether a publish queued an evaluation.
type Publisher ¶ added in v0.16.0
type Publisher struct {
// contains filtered or unexported fields
}
Publisher runs an archive through the scan and the gate. It acts as the user in ctx, so every path that creates a version meets the same decision.
func NewPublisher ¶ added in v0.16.0
func NewPublisher(store *Store, storage platform.Storage, opts RouteOptions) *Publisher
NewPublisher constructs a Publisher.
func (*Publisher) OpenChange ¶ added in v0.18.0
func (p *Publisher) OpenChange(ctx context.Context, name string, archive []byte, note string, git GitBoundary) (*PublishBody, error)
OpenChange scans archive like a publish, refuses what a publish would block, and opens a pull request for a git-bound skill. The pull request's check and the merged folder's publish decide the rest.
type QualityEvidence ¶ added in v0.10.0
type QualityEvidence struct {
Verified bool
PanelComplete bool
Headline float64
CriticalForbidViolations int
// SuiteDerived: a machine-derived suite grades the skill against its own
// claims and cannot clear a scan hold.
SuiteDerived bool
}
QualityEvidence is the subset of quality.Record the gate depends on. Declared here to avoid a cycle with internal/quality.
type QueueSubmitter ¶ added in v0.10.0
type QueueSubmitter interface {
Submit(ctx context.Context, job EvalJobRequest) (string, error)
}
QueueSubmitter is the subset of evalqueue.Executor that publish needs.
type ReleaseEvent ¶ added in v0.16.0
type ReleaseEvent struct {
Skill string
Version int
Checksum string
// Approved is true when a review or a verified score released a held
// version, and false when the publish itself released it.
Approved bool
}
ReleaseEvent describes a version that became servable.
type Releaser ¶ added in v0.10.0
type Releaser struct {
// contains filtered or unexported fields
}
Releaser re-runs the publish decision for a held version once a quality record exists.
func NewReleaser ¶ added in v0.10.0
NewReleaser builds a Releaser over store.
type RouteOptions ¶ added in v0.10.0
type RouteOptions struct {
// External is the opt-in external scanner (Phase 2); nil disables it.
External *scan.ExternalScanner
// Queue, when set together with Suites, lets publish enqueue an
// evaluation for a skill that has a registered suite. A queue outage
// must never fail a publish — see the enqueue step below.
Queue QueueSubmitter
// Suites looks up the latest registered eval suite for a skill by name.
Suites SuiteLookup
// QualityFloor is the minimum headline quality score a verified
// evaluation must reach to clear a held version. It comes from
// platform.Config.QualityFloor; the zero value means any verified,
// complete, contract-clean report clears.
QualityFloor float64
// Ownership resolves and claims skill ownership for publish. A nil
// resolver leaves the zero gate.OwnerState, which contributes nothing —
// that is what keeps every test harness and the CLI's local pre-scan on
// the pre-ownership behaviour.
Ownership OwnerResolver
// Git routes a change to a git-bound skill into a pull request. Nil means
// every skill is native.
Git GitBoundary
}
RouteOptions carries the optional collaborators RegisterRoutes wires into the publish (and related) handlers. Each is independently optional (nil disables the behavior it powers) so a caller — including tests — can opt into only what it needs.
type Skill ¶
type Skill struct {
ID string `json:"id"`
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Description string `json:"description"`
Content string `json:"content,omitempty"`
LatestVersion int `json:"latest_version"`
Frontmatter json.RawMessage `json:"frontmatter"`
Author string `json:"author"`
License string `json:"license"`
Compatibility string `json:"compatibility"`
Tags []string `json:"tags"`
SpecCompliance string `json:"spec_compliance"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
ReviewedAt *time.Time `json:"reviewed_at"`
ReviewedBy string `json:"reviewed_by"`
}
Skill represents a skill entry in the registry.
type SpecValidation ¶ added in v0.7.0
type SpecValidation struct {
Compliance string
Author string
License string
Compat string
Tags []string
DisplayName string
Warnings []string
}
SpecValidation holds the result of validating a skill's frontmatter against the Agent Skills spec format.
func ValidateSpec ¶ added in v0.7.0
func ValidateSpec(fm map[string]interface{}, skillName string) *SpecValidation
ValidateSpec extracts spec-defined metadata from parsed frontmatter and computes a compliance level ("full", "partial", or "none").
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store handles Postgres persistence for skills and their versions.
func (*Store) ApproveReason ¶ added in v0.10.0
func (s *Store) ApproveReason( ctx context.Context, e Executor, name string, version int, reason string, actorID *string, actorEmail, note string, ) (bool, error)
ApproveReason records an approval for one hold reason and releases the version if that was the last one outstanding. It reports whether the version was released.
actorID is nil for an automated release — the verified-evaluation path — so "released by a score" and "released by a person" stay distinguishable forever. actorEmail is always written: it is an audit snapshot that survives the user being deleted.
It writes through e so a caller can compose the release with whatever justified it in one transaction. Report ingestion depends on that.
func (*Store) BulkSetReview ¶
BulkSetReview marks multiple skills as reviewed in a single UPDATE. Returns the number of rows actually updated.
func (*Store) ClearReview ¶
ClearReview removes the review mark from a skill.
func (*Store) Create ¶
func (s *Store) Create(ctx context.Context, name, displayName, description, content string, frontmatter json.RawMessage) (*Skill, error)
Create inserts a new skill row and returns the created record.
func (*Store) CreateAlias ¶
func (*Store) CreateVersion ¶
func (s *Store) CreateVersion( ctx context.Context, skillID, archivePath, checksum, changelog string, description, content string, frontmatter json.RawMessage, manifest []FileEntry, scanResult json.RawMessage, publishedBy string, decision gate.Decision, ) (*Version, error)
CreateVersion inserts a new skill_versions row, updates the parent skill's description/content/frontmatter, and advances skills.latest_version to the new version only when the gate decision releases it — all within a single transaction. A held version exists and is stored, but is not served.
func (*Store) DiffAgainstServed ¶ added in v0.10.0
func (s *Store) DiffAgainstServed(ctx context.Context, name string, version int) (*VersionDiff, error)
DiffAgainstServed compares the given version of a skill against the version currently served (skills.latest_version). Returns nil, nil if the skill or the target version does not exist, matching GetByName/GetVersion.
When the skill has no served version yet (LatestVersion == 0 — this is the first version ever created for it), Against is 0, SkillMD is empty, and every file in the target version's manifest is reported as "added": there is no baseline to render a text diff against, and rendering one against an empty phantom version would be misleading, not just unhelpful.
func (*Store) GetByName ¶
GetByName retrieves a skill by its unique name. Returns nil, nil when not found.
func (*Store) GetVersion ¶
GetVersion retrieves a specific version of a skill. Returns nil, nil if not found.
func (*Store) List ¶
List returns a paginated slice of skills along with the total row count. Filters are applied when the corresponding ListOptions fields are non-empty.
func (*Store) ListAliases ¶
func (*Store) ListHeldVersions ¶ added in v0.10.0
func (s *Store) ListHeldVersions(ctx context.Context) ([]HeldVersion, error)
ListHeldVersions returns every version awaiting review, newest first. A SQL NULL in gate_decision or scan_result (neither of which is expected in practice, since CreateVersion always marshals a decision and a report) is scanned into a nil byte slice and wrapped as an empty json.RawMessage rather than erroring the whole listing — one row's missing detail must not hide every other hold.
func (*Store) ListVersions ¶
ListVersions returns all versions for a skill ordered by version DESC.
func (*Store) OutstandingReasons ¶ added in v0.10.0
OutstandingReasons returns the hold reasons on a version that have no approval row yet, in the order they were recorded.
func (*Store) RejectReason ¶ added in v0.10.0
func (s *Store) RejectReason( ctx context.Context, name string, version int, reason, actorEmail, note string, ) error
RejectReason records a rejection for one reason and marks the version terminal. Rejecting any single reason rejects the version: there is no state in which a version is partly refused.
func (*Store) RejectVersion ¶ added in v0.10.0
RejectVersion marks a held version terminal.
func (*Store) ReleaseVersion ¶ added in v0.10.0
func (s *Store) ReleaseVersion(ctx context.Context, e Executor, name string, version int, by, note string) error
ReleaseVersion moves a version to released. Uses the caller's Executor so ingestion can compose it with the quality upsert in one transaction. Re-releasing is a no-op, not an error.
func (*Store) ResolveAlias ¶
func (*Store) Search ¶
Search returns skills matching the given query using a combination of Postgres full-text search (websearch_to_tsquery + ts_rank on search_vector) and pg_trgm fuzzy name matching (similarity()). Results are returned where either FTS matches OR name similarity exceeds 0.2, ordered by FTS rank then trigram rank. Limit caps the number of returned results.
func (*Store) SetNotifier ¶ added in v0.16.0
func (s *Store) SetNotifier(n ChangeNotifier)
SetNotifier attaches the receiver of changes.
type SuiteLookup ¶ added in v0.10.0
type SuiteLookup interface {
LatestForSkill(ctx context.Context, skillName string) (*SuiteRecord, error)
}
SuiteLookup is the subset of evalsuite.Registry that publish needs. It mirrors LatestForSkill's (nil, nil) contract: no error, nil record means no suite is registered for the skill.
type SuiteRecord ¶ added in v0.10.0
type SuiteRecord struct {
Ref string
}
SuiteRecord is the subset of evalsuite.Record that publish needs to build an EvalJobRequest.
type Version ¶
type Version struct {
ID string `json:"id"`
SkillID string `json:"skill_id"`
Version int `json:"version"`
ArchivePath string `json:"-"`
Checksum string `json:"checksum"`
Changelog string `json:"changelog"`
Frontmatter json.RawMessage `json:"frontmatter"`
FileManifest []FileEntry `json:"file_manifest"`
// Description and Content are the rendered prose this version would
// serve. They are carried on the version, not only on the skill row,
// because a held version writes nothing to the skill row: releasing it
// later has to get the prose from somewhere, and re-reading the archive
// to recover text the database already saw would be the wrong place.
//
// Both are json:"-" on purpose. The wire shape of a version is unchanged,
// and a version endpoint is not a second way to read a held version's
// body — the gate withholds exactly that.
Description string `json:"-"`
Content string `json:"-"`
ScanResult json.RawMessage `json:"scan_result,omitempty"`
PublishedBy string `json:"published_by"`
CreatedAt time.Time `json:"created_at"`
// GateState is one of "released", "needs_review", "rejected". Only a
// released version is pointed at by skills.latest_version.
GateState string `json:"gate_state"`
GateDecision json.RawMessage `json:"gate_decision,omitempty"`
GatedBy string `json:"gated_by,omitempty"`
GatedAt *time.Time `json:"gated_at,omitempty"`
GateNote string `json:"gate_note,omitempty"`
// HoldReasons are the reason kinds still standing between this version
// and release. Empty on a released or rejected version.
HoldReasons []string `json:"hold_reasons"`
// SubmissionID names the submission this version came from, if any.
SubmissionID *string `json:"submission_id,omitempty"`
// ContestID names the contest that evaluated this exact content as a pull
// request head before it merged.
ContestID *string `json:"contest_id,omitempty"`
}
Version represents a specific published version of a skill.
type VersionDiff ¶ added in v0.10.0
type VersionDiff struct {
// Against is the served version number this diff was computed against.
// 0 means there is no baseline — this is the skill's first version, so
// there is nothing to diff against rather than an empty phantom one.
Against int `json:"against"`
SkillMD string `json:"skill_md"`
Files []FileChange `json:"files"`
}
VersionDiff is what a reviewer sees when deciding whether to approve a version held for review: what changed in SKILL.md, and which files were added, removed, or modified relative to the version currently being served.
func DiffFolder ¶ added in v0.18.0
func DiffFolder(served *Version, body string, files []FileEntry, toLabel string) (*VersionDiff, error)
DiffFolder compares a served version with a folder outside the registry, such as a skill folder in a git repo, labelled toLabel. body is the folder's SKILL.md without its frontmatter, which is what a version's Content holds.