Documentation
¶
Index ¶
- type APIError
- type ActivationSummary
- type Client
- func (c *Client) ClaimEvalJob(workerID string, leaseSeconds int) (*EvalJob, string, bool, error)
- func (c *Client) CreateContest(candidates []ContestCandidate, suiteRef, tier string, attempts int) (*Contest, error)
- func (c *Client) CreateSkill(name, description string) (*Skill, error)
- func (c *Client) DeleteOwnershipRule(id string) error
- func (c *Client) DiffVersion(name string, version int) (*VersionDiff, error)
- func (c *Client) DownloadVersion(name string, version int) ([]byte, error)
- func (c *Client) FailEvalJob(id, token, cause string) error
- func (c *Client) FetchEvalSuite(ref string) ([]byte, error)
- func (c *Client) FetchEvalSuiteMeta(ref string) (*EvalSuiteMeta, error)
- func (c *Client) GetActivations(name string) (*ActivationSummary, error)
- func (c *Client) GetContest(id string) (*Contest, error)
- func (c *Client) GetManifest() ([]ManifestEntry, error)
- func (c *Client) GetSkill(name string) (*Skill, error)
- func (c *Client) Health() error
- func (c *Client) HeartbeatEvalJob(id, token string) error
- func (c *Client) ImportResolve(url string) (*ResolveResponse, error)
- func (c *Client) ImportSkills(source ImportSource, skillNames []string, namespace string) (*ImportResponse, error)
- func (c *Client) ImportSources() ([]ImportSourceEntry, error)
- func (c *Client) ImportUpload(archive []byte) (*ResolveResponse, error)
- func (c *Client) ListContests(name string) ([]Contest, error)
- func (c *Client) ListOwnershipRules() ([]OwnershipRule, error)
- func (c *Client) ListSkills(limit, offset int) ([]Skill, int, error)
- func (c *Client) ListVersions(name string) ([]Version, error)
- func (c *Client) PostContestReport(contestID, token string, body []byte) error
- func (c *Client) PostEvalReport(id, token string, body []byte) error
- func (c *Client) PublishVersion(name string, archive []byte, override bool) (*Version, *scan.Report, *gate.Decision, error)
- func (c *Client) Review(name string, version int, action, reason, holdReason string) (*Version, error)
- func (c *Client) ReviewQueue() ([]HeldVersion, error)
- func (c *Client) SearchSkills(query string, limit int) ([]Skill, error)
- func (c *Client) SearchUsers(q string) ([]PublicUser, error)
- func (c *Client) SkillOwners(name string) (*SkillOwnersResult, error)
- func (c *Client) UploadEvalSuite(req EvalSuiteUploadRequest) (*EvalSuiteUpload, error)
- func (c *Client) UpsertOwnershipRule(pattern string, members []string) (*OwnershipRule, error)
- type Contest
- type ContestCandidate
- type ContestLoss
- type ContestPairing
- type ContestTask
- type DiscoveredSkill
- type EvalJob
- type EvalSuiteCheck
- type EvalSuiteMeta
- type EvalSuiteUpload
- type EvalSuiteUploadRequest
- type FailedSkill
- type FileChange
- type FileEntry
- type HeldVersion
- type ImportResponse
- type ImportSource
- type ImportSourceEntry
- type ImportedSkill
- type ManifestEntry
- type OwnershipRule
- type PublicUser
- type QualityState
- type ResolveResponse
- type Skill
- type SkillOwnersResult
- type Version
- type VersionDiff
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type APIError ¶
type APIError struct {
StatusCode int
Message string
// Raw is the unparsed response body. Some endpoints attach a structured
// payload — the publish endpoint embeds its scan report — that does not
// survive being flattened into Message.
Raw []byte
}
APIError is returned when the server responds with a non-2xx status code.
type ActivationSummary ¶ added in v0.7.0
type ActivationSummary struct {
TotalCount int `json:"total_count"`
UniqueDevs int `json:"unique_devs"`
LastTriggered *time.Time `json:"last_triggered"`
ByAgent map[string]int `json:"by_agent"`
}
ActivationSummary holds the activation analytics for a single skill.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client communicates with the skael platform API. Every request includes the X-API-Key header for authentication.
func (*Client) ClaimEvalJob ¶ added in v0.10.0
ClaimEvalJob calls POST /api/eval/jobs/claim. It returns (nil, "", false, nil) when the server responds 204 — the queue is empty, not an error.
func (*Client) CreateContest ¶ added in v0.14.0
func (c *Client) CreateContest(candidates []ContestCandidate, suiteRef, tier string, attempts int) (*Contest, error)
CreateContest queues a contest between candidates.
func (*Client) CreateSkill ¶
CreateSkill calls POST /api/skills to create a new skill record.
func (*Client) DeleteOwnershipRule ¶ added in v0.10.0
DeleteOwnershipRule calls DELETE /api/ownership/rules/{id}.
func (*Client) DiffVersion ¶ added in v0.10.0
func (c *Client) DiffVersion(name string, version int) (*VersionDiff, error)
DiffVersion calls GET /api/skills/{name}/versions/{version}/diff.
func (*Client) DownloadVersion ¶
DownloadVersion calls GET /api/skills/{name}/versions/{v}/download and returns the raw archive bytes.
func (*Client) FailEvalJob ¶ added in v0.10.0
FailEvalJob calls POST /api/eval/jobs/{id}/fail, recording cause as the reason the job did not complete.
func (*Client) FetchEvalSuite ¶ added in v0.10.0
FetchEvalSuite calls GET /api/eval/suites/{ref} and returns the raw gzip-compressed suite archive.
func (*Client) FetchEvalSuiteMeta ¶ added in v0.10.0
func (c *Client) FetchEvalSuiteMeta(ref string) (*EvalSuiteMeta, error)
FetchEvalSuiteMeta calls GET /api/eval/suites/{ref}/meta and returns the oracle-gate checks and spec recorded for the suite. Both live on one call because every consumer of one needs the other: an eval cannot run without the checks, and a worker rebuilding a workspace from a downloaded bundle has no other source for the spec.
func (*Client) GetActivations ¶ added in v0.7.0
func (c *Client) GetActivations(name string) (*ActivationSummary, error)
GetActivations calls GET /api/skills/{name}/activations and returns the activation summary for the given skill. Returns a zero-value summary when the server responds with 404.
func (*Client) GetContest ¶ added in v0.14.0
GetContest fetches a contest and its verdict.
func (*Client) GetManifest ¶
func (c *Client) GetManifest() ([]ManifestEntry, error)
GetManifest calls GET /api/sync/manifest and returns the list of manifest entries used for client-side sync diffing.
func (*Client) GetSkill ¶
GetSkill calls GET /api/skills/{name}. It returns (nil, nil) when the server responds with 404.
func (*Client) Health ¶
Health calls GET /api/health and returns an error if the server is not reachable or returns a non-ok status.
func (*Client) HeartbeatEvalJob ¶ added in v0.10.0
HeartbeatEvalJob calls POST /api/eval/jobs/{id}/heartbeat, extending the lease named by token.
func (*Client) ImportResolve ¶
func (c *Client) ImportResolve(url string) (*ResolveResponse, error)
func (*Client) ImportSkills ¶
func (c *Client) ImportSkills(source ImportSource, skillNames []string, namespace string) (*ImportResponse, error)
func (*Client) ImportSources ¶
func (c *Client) ImportSources() ([]ImportSourceEntry, error)
func (*Client) ImportUpload ¶
func (c *Client) ImportUpload(archive []byte) (*ResolveResponse, error)
func (*Client) ListContests ¶ added in v0.14.0
ListContests returns the contests a skill entered, newest first.
func (*Client) ListOwnershipRules ¶ added in v0.10.0
func (c *Client) ListOwnershipRules() ([]OwnershipRule, error)
ListOwnershipRules calls GET /api/ownership/rules and returns every rule.
func (*Client) ListSkills ¶
ListSkills calls GET /api/skills?limit=&offset= and returns the slice of skills together with the total count reported by the server.
func (*Client) ListVersions ¶ added in v0.7.0
ListVersions calls GET /api/skills/{name}/versions and returns all versions for the skill in ascending order.
func (*Client) PostContestReport ¶ added in v0.14.0
PostContestReport calls POST /api/eval/contests/{id}/report with every candidate's report. The claim token authenticates the claim, the same way an eval report is ingested.
func (*Client) PostEvalReport ¶ added in v0.10.0
PostEvalReport calls POST /api/eval/jobs/{id}/report with body, the JSON bytes of a completed eval report (see internal/eval/report.Report.Save).
func (*Client) PublishVersion ¶
func (c *Client) PublishVersion(name string, archive []byte, override bool) (*Version, *scan.Report, *gate.Decision, error)
PublishVersion uploads archive (a gzip-compressed tar) to POST /api/skills/{name}/versions. Set override to publish despite blocking scan findings; the server accepts it only from an owner or admin and records it.
On success it returns the new Version record, which carries its own Decision. When the server rejects the archive outright (a Block outcome, always 422) it returns the parsed scan report and decision alongside the error, so the caller can show the findings that actually blocked the publish instead of guessing.
func (*Client) Review ¶ added in v0.10.0
func (c *Client) Review(name string, version int, action, reason, holdReason string) (*Version, error)
Review calls POST /api/skills/{name}/versions/{version}/review to approve or reject a version held by the publish gate. action must be "approve" or "reject"; the server enforces owner/admin privilege and rejects any other action. holdReason names which held reason this decision targets — "scan" or "ownership" — and may be empty, in which case the server infers it when exactly one reason is outstanding and 422s naming all of them otherwise. It carries ",omitempty" on the wire so an empty holdReason produces the exact same request body every already-deployed caller sends today. Returns the updated Version record.
func (*Client) ReviewQueue ¶ added in v0.10.0
func (c *Client) ReviewQueue() ([]HeldVersion, error)
ReviewQueue calls GET /api/review/queue and returns every version currently held for review, newest first.
func (*Client) SearchSkills ¶
SearchSkills calls GET /api/search?q=&limit= and returns the matching skills.
func (*Client) SearchUsers ¶ added in v0.10.0
func (c *Client) SearchUsers(q string) ([]PublicUser, error)
SearchUsers calls GET /api/users/search?q= and returns matching user accounts, identity fields only.
func (*Client) SkillOwners ¶ added in v0.10.0
func (c *Client) SkillOwners(name string) (*SkillOwnersResult, error)
SkillOwners calls GET /api/skills/{name}/owners and returns the resolved owners for the skill name and the rule that matched.
func (*Client) UploadEvalSuite ¶ added in v0.10.0
func (c *Client) UploadEvalSuite(req EvalSuiteUploadRequest) (*EvalSuiteUpload, error)
UploadEvalSuite uploads an evaluation suite archive, together with the oracle-gate check results recorded for it and the spec it was checked against, to POST /api/eval/suites. archive is a gzip-compressed tar (see internal/evalsuite.PackDir); it is base64-encoded here because the endpoint's body is JSON, not raw bytes — unlike PublishVersion's skill archives, which travel as the request body itself. specJSON is the spec.SkillSpec that was checked, marshaled to JSON by the caller (may be nil) — a published bundle never carries spec.yaml, so this is the only channel a worker rebuilding a workspace from a downloaded bundle has to recover it. JobID/ClaimToken are the eval worker's proof that it is deriving this suite for a job it currently holds the claim on; the server stamps such a suite as machine-derived at push time. An authored push from whetstone leaves both empty. Unreviewed declares that this suite is exactly what the generator wrote and that nobody has read it. The server records such a suite as machine-derived, so a skill cannot clear a scan hold on its own eval set.
func (*Client) UpsertOwnershipRule ¶ added in v0.10.0
func (c *Client) UpsertOwnershipRule(pattern string, members []string) (*OwnershipRule, error)
UpsertOwnershipRule calls POST /api/ownership/rules, which creates a rule for pattern or replaces the member list of one that already exists at that pattern — the server's Upsert contract. members is always sent in full; there is no partial-update form, because the server always replaces wholesale.
type Contest ¶ added in v0.14.0
type Contest struct {
ID string `json:"id"`
Status string `json:"status"`
Outcome string `json:"outcome"`
Winner string `json:"winner"`
Detail string `json:"detail"`
SuiteRef string `json:"suite_ref"`
SuiteNote string `json:"suite_note"`
Tier string `json:"tier"`
Attempts int `json:"attempts"`
JobID string `json:"job_id"`
ChainLink bool `json:"chain_link"`
Candidates []ContestCandidate `json:"candidates"`
Pairings []ContestPairing `json:"pairings"`
Losses []ContestLoss `json:"losses"`
LastError string `json:"last_error"`
}
Contest is a contest and, once it finishes, its verdict.
type ContestCandidate ¶ added in v0.14.0
type ContestCandidate struct {
Skill string `json:"skill"`
Version int `json:"version,omitempty"`
Label string `json:"label,omitempty"`
}
ContestCandidate is one entry in a contest request or result.
type ContestLoss ¶ added in v0.14.0
type ContestLoss struct {
Label string `json:"label"`
TaskID string `json:"task_id"`
Missed []string `json:"missed"`
Evidence string `json:"evidence,omitempty"`
}
ContestLoss is one task a candidate lost, and what it missed.
type ContestPairing ¶ added in v0.14.0
type ContestPairing struct {
A string `json:"a"`
B string `json:"b"`
AWins int `json:"a_wins"`
BWins int `json:"b_wins"`
Ties int `json:"ties"`
PValue float64 `json:"p_value"`
Outcome string `json:"outcome"`
Winner string `json:"winner"`
Tasks []ContestTask `json:"tasks"`
}
ContestPairing is the result between two candidates.
type ContestTask ¶ added in v0.14.0
type ContestTask struct {
TaskID string `json:"task_id"`
A string `json:"a"`
B string `json:"b"`
ARate float64 `json:"a_rate"`
BRate float64 `json:"b_rate"`
Winner string `json:"winner"`
}
ContestTask is one task's head-to-head result.
type DiscoveredSkill ¶
type EvalJob ¶ added in v0.10.0
type EvalJob struct {
ID string `json:"id"`
SkillID string `json:"skill_id"`
SkillName string `json:"skill_name"`
Version int `json:"version"`
SuiteRef string `json:"suite_ref"`
Tier string `json:"tier"`
// Agents and Models are the requested panel — see evalqueue.Panel. The
// whole point of the re-run endpoint is choosing a panel, so a wire
// format that could not carry it back to the worker would silently
// evaluate every job against the worker's default instead.
Agents []string `json:"agents,omitempty"`
Models []string `json:"models,omitempty"`
Status string `json:"status"`
Attempts int `json:"attempts"`
MaxAttempts int `json:"max_attempts"`
WorkerID string `json:"worker_id,omitempty"`
LastError string `json:"last_error,omitempty"`
RequestedBy string `json:"requested_by,omitempty"`
}
EvalJob is the client-side representation of an eval queue job, as the claim/status endpoints return it.
type EvalSuiteCheck ¶ added in v0.10.0
type EvalSuiteCheck struct {
TaskID string `json:"task_id"`
OK bool `json:"ok"`
Void bool `json:"void,omitempty"`
Reason string `json:"reason,omitempty"`
}
EvalSuiteCheck is one task's oracle-gate result, as the eval suite upload endpoint expects it.
type EvalSuiteMeta ¶ added in v0.10.0
type EvalSuiteMeta struct {
Checks []EvalSuiteCheck `json:"checks"`
SpecVersion int `json:"spec_version"`
Spec json.RawMessage `json:"spec,omitempty"`
Origin string `json:"origin"`
// MachineGenerated says a worker built this suite, which is what decides
// void tolerance. Origin does not: an unreviewed push is derived too.
MachineGenerated bool `json:"machine_generated"`
}
EvalSuiteMeta is the response to GET /api/eval/suites/{ref}/meta: the oracle-gate checks recorded for a suite, and the spec it was checked against (nil if the pusher didn't send one).
type EvalSuiteUpload ¶ added in v0.10.0
EvalSuiteUpload is the response to a successful eval suite upload.
type EvalSuiteUploadRequest ¶ added in v0.11.0
type EvalSuiteUploadRequest struct {
Skill string
SpecVersion int
Checks []EvalSuiteCheck
Spec json.RawMessage
Archive []byte
JobID string
ClaimToken string
Unreviewed bool
}
EvalSuiteUploadRequest is one suite upload. Spec may be nil; JobID and ClaimToken are set only by the eval worker's derive path; Unreviewed declares that nobody has read this suite. See UploadEvalSuite.
type FailedSkill ¶
type FileChange ¶ added in v0.10.0
FileChange is one file whose presence or size differs between a held version and the currently served one.
type HeldVersion ¶ added in v0.10.0
type HeldVersion struct {
SkillName string `json:"skill_name"`
Version int `json:"version"`
GateState string `json:"gate_state"`
HoldReasons []string `json:"hold_reasons"`
Outstanding []string `json:"outstanding"`
RulePattern string `json:"rule_pattern,omitempty"`
Owners []gate.OwnerRef `json:"owners"`
Unowned bool `json:"unowned"`
}
HeldVersion is one version awaiting review, as returned by the review queue. HoldReasons is every reason it was ever held for, in publish order; Outstanding is the subset with no approval recorded yet — the two can differ once one reason clears but the version stays held on another, which is exactly the case `skael review` must render honestly rather than collapse into a single "released" or "held" verdict.
type ImportResponse ¶
type ImportResponse struct {
Imported []ImportedSkill `json:"imported"`
Failed []FailedSkill `json:"failed"`
}
type ImportSource ¶
type ImportSourceEntry ¶
type ImportedSkill ¶
type ManifestEntry ¶
type ManifestEntry struct {
Name string `json:"name"`
Version int `json:"version"`
Checksum string `json:"checksum"`
}
ManifestEntry holds the sync metadata for a single skill.
type OwnershipRule ¶ added in v0.10.0
type OwnershipRule struct {
ID string `json:"id"`
Pattern string `json:"pattern"`
Members []PublicUser `json:"members"`
}
OwnershipRule is the client-side representation of an ownership rule: a pattern and the users that own everything it matches, hydrated with name and email so a caller never has to look each member up separately.
type PublicUser ¶ added in v0.10.0
type PublicUser struct {
ID string `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
}
PublicUser is the identity-only projection of a user account returned by the directory search and the resolved-owners lookup.
type QualityState ¶ added in v0.10.0
type QualityState struct {
State string `json:"state,omitempty"`
JobID string `json:"job_id,omitempty"`
}
QualityState is the publish response's report on the evaluation, if any, that was queued for the new version.
type ResolveResponse ¶
type ResolveResponse struct {
Source ImportSource `json:"source"`
Skills []DiscoveredSkill `json:"skills"`
PluginName string `json:"plugin_name,omitempty"`
}
type Skill ¶
type Skill struct {
Name string `json:"name"`
DisplayName string `json:"display_name,omitempty"`
Description string `json:"description"`
LatestVersion int `json:"latest_version"`
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"`
Frontmatter json.RawMessage `json:"frontmatter"`
}
Skill is the client-side representation of a skill returned by the API.
type SkillOwnersResult ¶ added in v0.10.0
type SkillOwnersResult struct {
RulePattern string `json:"rule_pattern,omitempty"`
Owners []PublicUser `json:"owners"`
Unowned bool `json:"unowned"`
}
SkillOwnersResult is the resolved owners for a skill name, and which rule (if any) produced them.
type Version ¶
type Version struct {
Version int `json:"version"`
Checksum string `json:"checksum"`
Changelog string `json:"changelog"`
ScanResult json.RawMessage `json:"scan_result,omitempty"`
CreatedAt time.Time `json:"created_at"`
Created bool `json:"created"`
// Decision is the publish gate's verdict for this version. Always
// present on a response from a gate-aware server; zero-value on an
// older one (Outcome "" is treated the same as Allow by callers).
//
// Decision is a fresh recomputation on a new publish, but on an
// unchanged-checksum republish it is the version's persisted snapshot —
// GateState is the only field that tells the two apart from the
// outside, which is why the unchanged-checksum message below branches
// on GateState, not on Decision.Held().
Decision gate.Decision `json:"decision,omitempty"`
// GateState is the version's persisted state: "released", "needs_review",
// or "rejected". Unlike Decision, it cannot go stale — it is read back
// from the row itself, not recomputed — so it is the source of truth
// for whether a version is actually being served.
GateState string `json:"gate_state,omitempty"`
// Quality reports whether publishing this version enqueued an
// evaluation. State is "pending" when a job was queued and "none" when
// no suite is registered for the skill — in which case an admin
// approval is the only thing that can clear a held version, and telling
// the publisher to wait for a score would be telling them to wait
// forever.
Quality QualityState `json:"quality,omitempty"`
// HoldReasons are every reason kind this version was ever held for, in
// publish order. It does not shrink as reasons clear — it is the raw set
// recorded at publish time, not the outstanding subset — so a caller
// that already knows which reason it just cleared (e.g. because it named
// one explicitly) can compute what remains by subtracting it, but must
// not treat this field alone as "what still blocks release."
HoldReasons []string `json:"hold_reasons,omitempty"`
}
Version is the client-side representation of a published skill version.
type VersionDiff ¶ added in v0.10.0
type VersionDiff struct {
Against int `json:"against"`
SkillMD string `json:"skill_md"`
Files []FileChange `json:"files"`
}
VersionDiff is the response to GET /api/skills/{name}/versions/{version}/diff: a unified diff of SKILL.md against the currently served version, plus the changed non-SKILL.md files. Against is the served version number the diff was computed against; 0 means no baseline exists yet (this is the skill's first version).