Documentation
¶
Index ¶
- func BatchFailure(err error) (index int, detail string, ok bool)
- type APIError
- type ActivationSummary
- type BatchResult
- type BundleManifest
- 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) CreateServiceAccount(name string) (*Response[ServiceAccount], error)
- func (c *Client) CreateServiceKey(accountID, name string, scopes []string, setID string) (*Response[CreatedServiceKey], error)
- func (c *Client) CreateSet(name, description string, entries []SetEntry) (*Response[Set], error)
- func (c *Client) CreateSkill(name, description string) (*Skill, error)
- func (c *Client) CreateSubmission(req SubmissionRequest) (*Response[Submission], *gate.Decision, error)
- func (c *Client) CreateWebhookEndpoint(in WebhookEndpointInput) (*Response[WebhookEndpointWithSecret], error)
- func (c *Client) DeleteOwnershipRule(id string) error
- func (c *Client) DeleteServiceAccount(id string) error
- func (c *Client) DeleteSet(name string) error
- func (c *Client) DeleteWebhookEndpoint(id string) error
- func (c *Client) DiffVersion(name string, version int) (*VersionDiff, error)
- func (c *Client) DownloadBundle(name, resolutionID string) (io.ReadCloser, 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) GetSet(name string) (*Response[SetDetail], error)
- func (c *Client) GetSkill(name string) (*Skill, error)
- func (c *Client) GetSkillOutcomes(name string) (*Response[SkillOutcomes], error)
- func (c *Client) GetSubmission(id string) (*Response[Submission], error)
- func (c *Client) GetWebhookEndpoint(id string) (*Response[WebhookEndpoint], 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) ListServiceAccounts() (..., error)
- func (c *Client) ListServiceKeys(accountID string) (..., error)
- func (c *Client) ListSets() (..., error)
- func (c *Client) ListSkills(limit, offset int) ([]Skill, int, error)
- func (c *Client) ListSubmissions(state string) (..., error)
- func (c *Client) ListVersions(name string) ([]Version, error)
- func (c *Client) ListWebhookDeliveries(id string) (..., error)
- func (c *Client) ListWebhookEndpoints() (..., 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) RedeliverWebhook(deliveryID string) error
- func (c *Client) ReportEvents(events []json.RawMessage, idempotencyKey string) (*Response[BatchResult], error)
- func (c *Client) ReportOutcome(report OutcomeReport) (*Response[RunRecord], error)
- func (c *Client) ResolveSet(name string) (*Response[Resolution], error)
- func (c *Client) Review(name string, version int, action, reason, holdReason string) (*Version, error)
- func (c *Client) ReviewQueue() ([]HeldVersion, error)
- func (c *Client) RevokeServiceKey(accountID, keyID string) error
- func (c *Client) RotateWebhookSecret(id string, windowHours *int) (*Response[WebhookEndpointWithSecret], 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) TestWebhookEndpoint(id string) error
- func (c *Client) UpdateSet(name, description string, entries []SetEntry) (*Response[Set], error)
- func (c *Client) UpdateWebhookEndpoint(id string, in WebhookEndpointInput) (*Response[WebhookEndpoint], 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 CreatedServiceKey
- type DiscoveredSkill
- type EvalJob
- type EvalSuiteCheck
- type EvalSuiteMeta
- type EvalSuiteUpload
- type EvalSuiteUploadRequest
- type ExcludedEntry
- type FailedSkill
- type FileChange
- type FileEntry
- type HeldVersion
- type ImportResponse
- type ImportSource
- type ImportSourceEntry
- type ImportedSkill
- type ManifestEntry
- type OutcomeReport
- type OwnershipRule
- type PublicUser
- type QualityState
- type Resolution
- type ResolveResponse
- type ResolvedEntry
- type Response
- type RunRecord
- type ServiceAccount
- type ServiceKey
- type Set
- type SetCaller
- type SetDetail
- type SetEntry
- type Skill
- type SkillOutcomes
- type SkillOwnersResult
- type Submission
- type SubmissionRequest
- type Version
- type VersionDiff
- type VersionOutcomes
- type WebhookAttempt
- type WebhookDelivery
- type WebhookEndpoint
- type WebhookEndpointInput
- type WebhookEndpointWithSecret
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 BatchResult ¶ added in v0.16.0
BatchResult is the answer to an event batch.
type BundleManifest ¶ added in v0.16.0
type BundleManifest struct {
Set string `json:"set"`
ResolutionID string `json:"resolution_id"`
Complete bool `json:"complete"`
Skills []struct {
Name string `json:"name"`
Version int `json:"version"`
SHA256 string `json:"sha256"`
Archive string `json:"archive"`
} `json:"skills"`
}
BundleManifest is the manifest.json a bundle carries.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client communicates with the skael platform API. Every request includes the Authorization 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) CreateServiceAccount ¶ added in v0.16.0
func (c *Client) CreateServiceAccount(name string) (*Response[ServiceAccount], error)
CreateServiceAccount calls POST /api/service-accounts.
func (*Client) CreateServiceKey ¶ added in v0.16.0
func (c *Client) CreateServiceKey(accountID, name string, scopes []string, setID string) (*Response[CreatedServiceKey], error)
CreateServiceKey calls POST /api/service-accounts/{id}/keys.
func (*Client) CreateSkill ¶
CreateSkill calls POST /api/skills to create a new skill record.
func (*Client) CreateSubmission ¶ added in v0.16.0
func (c *Client) CreateSubmission(req SubmissionRequest) (*Response[Submission], *gate.Decision, error)
CreateSubmission calls POST /api/submissions. On a blocking finding it also returns the decision, so the caller can show what blocked the archive.
func (*Client) CreateWebhookEndpoint ¶ added in v0.16.0
func (c *Client) CreateWebhookEndpoint(in WebhookEndpointInput) (*Response[WebhookEndpointWithSecret], error)
CreateWebhookEndpoint calls POST /api/webhooks/endpoints.
func (*Client) DeleteOwnershipRule ¶ added in v0.10.0
DeleteOwnershipRule calls DELETE /api/ownership/rules/{id}.
func (*Client) DeleteServiceAccount ¶ added in v0.16.0
DeleteServiceAccount calls DELETE /api/service-accounts/{id}.
func (*Client) DeleteWebhookEndpoint ¶ added in v0.16.0
DeleteWebhookEndpoint calls DELETE /api/webhooks/endpoints/{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) DownloadBundle ¶ added in v0.16.0
func (c *Client) DownloadBundle(name, resolutionID string) (io.ReadCloser, error)
DownloadBundle calls GET /api/sets/{name}/bundle?resolved={id}. The caller closes the returned stream.
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) GetSkillOutcomes ¶ added in v0.16.0
func (c *Client) GetSkillOutcomes(name string) (*Response[SkillOutcomes], error)
GetSkillOutcomes calls GET /api/skills/{name}/outcomes.
func (*Client) GetSubmission ¶ added in v0.16.0
func (c *Client) GetSubmission(id string) (*Response[Submission], error)
GetSubmission calls GET /api/submissions/{id}.
func (*Client) GetWebhookEndpoint ¶ added in v0.16.0
func (c *Client) GetWebhookEndpoint(id string) (*Response[WebhookEndpoint], error)
GetWebhookEndpoint calls GET /api/webhooks/endpoints/{id}.
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) ListServiceAccounts ¶ added in v0.16.0
func (c *Client) ListServiceAccounts() (*Response[struct { ServiceAccounts []ServiceAccount `json:"service_accounts"` }], error)
ListServiceAccounts calls GET /api/service-accounts.
func (*Client) ListServiceKeys ¶ added in v0.16.0
func (c *Client) ListServiceKeys(accountID string) (*Response[struct { Keys []ServiceKey `json:"keys"` }], error)
ListServiceKeys calls GET /api/service-accounts/{id}/keys.
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) ListSubmissions ¶ added in v0.16.0
func (c *Client) ListSubmissions(state string) (*Response[struct { Submissions []Submission `json:"submissions"` }], error)
ListSubmissions calls GET /api/submissions. An empty state lists all.
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) ListWebhookDeliveries ¶ added in v0.16.0
func (c *Client) ListWebhookDeliveries(id string) (*Response[struct { Deliveries []WebhookDelivery `json:"deliveries"` }], error)
ListWebhookDeliveries calls GET /api/webhooks/endpoints/{id}/deliveries.
func (*Client) ListWebhookEndpoints ¶ added in v0.16.0
func (c *Client) ListWebhookEndpoints() (*Response[struct { Endpoints []WebhookEndpoint `json:"endpoints"` }], error)
ListWebhookEndpoints calls GET /api/webhooks/endpoints.
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) RedeliverWebhook ¶ added in v0.16.0
RedeliverWebhook calls POST /api/webhooks/deliveries/{id}/redeliver.
func (*Client) ReportEvents ¶ added in v0.16.0
func (c *Client) ReportEvents(events []json.RawMessage, idempotencyKey string) (*Response[BatchResult], error)
ReportEvents calls POST /api/events/batch. Each event passes through as the caller wrote it, so the server is the one place that validates an event.
func (*Client) ReportOutcome ¶ added in v0.16.0
func (c *Client) ReportOutcome(report OutcomeReport) (*Response[RunRecord], error)
ReportOutcome calls POST /api/outcomes.
func (*Client) ResolveSet ¶ added in v0.16.0
func (c *Client) ResolveSet(name string) (*Response[Resolution], error)
ResolveSet calls GET /api/sets/{name}/resolve and always asks for the excluded entries, so a caller can say why a set is incomplete.
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) RevokeServiceKey ¶ added in v0.16.0
RevokeServiceKey calls DELETE /api/service-accounts/{id}/keys/{keyId}.
func (*Client) RotateWebhookSecret ¶ added in v0.16.0
func (c *Client) RotateWebhookSecret(id string, windowHours *int) (*Response[WebhookEndpointWithSecret], error)
RotateWebhookSecret calls POST /api/webhooks/endpoints/{id}/rotate-secret. A nil window takes the server's default.
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) TestWebhookEndpoint ¶ added in v0.16.0
TestWebhookEndpoint calls POST /api/webhooks/endpoints/{id}/test.
func (*Client) UpdateSet ¶ added in v0.16.0
UpdateSet calls PUT /api/sets/{name}, which replaces the description and the entries together.
func (*Client) UpdateWebhookEndpoint ¶ added in v0.16.0
func (c *Client) UpdateWebhookEndpoint(id string, in WebhookEndpointInput) (*Response[WebhookEndpoint], error)
UpdateWebhookEndpoint calls PUT /api/webhooks/endpoints/{id}.
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 CreatedServiceKey ¶ added in v0.16.0
type CreatedServiceKey struct {
ServiceKey
Key string `json:"key"`
}
CreatedServiceKey is a new key. Key is its secret, which the server returns only here.
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 ExcludedEntry ¶ added in v0.16.0
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 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 OutcomeReport ¶ added in v0.16.0
type OutcomeReport struct {
ExternalRunID string `json:"external_run_id"`
Outcome string `json:"outcome"`
Repairs int `json:"repairs,omitempty"`
ReviewVerdict string `json:"review_verdict,omitempty"`
EvidenceURL string `json:"evidence_url,omitempty"`
Set string `json:"set,omitempty"`
ResolutionID string `json:"resolution_id,omitempty"`
}
OutcomeReport is the request of POST /api/outcomes.
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 Resolution ¶ added in v0.16.0
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.
type ResolveResponse ¶
type ResolveResponse struct {
Source ImportSource `json:"source"`
Skills []DiscoveredSkill `json:"skills"`
PluginName string `json:"plugin_name,omitempty"`
}
type ResolvedEntry ¶ added in v0.16.0
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"`
}
ResolvedEntry is one exact version in a resolution.
type Response ¶ added in v0.16.0
type Response[T any] struct { Value T Raw json.RawMessage }
Response pairs a decoded API body with its exact bytes, so --json can print the API shape without a client struct dropping a field.
type RunRecord ¶ added in v0.16.0
type RunRecord struct {
ID string `json:"id"`
Consumer string `json:"consumer"`
ExternalRunID string `json:"external_run_id"`
Outcome *string `json:"outcome"`
Repairs int `json:"repairs"`
}
RunRecord is a stored run.
type ServiceAccount ¶ added in v0.16.0
type ServiceAccount struct {
ID string `json:"id"`
Name string `json:"name"`
KeyCount int `json:"key_count"`
LastUsedAt *time.Time `json:"last_used_at"`
CreatedAt time.Time `json:"created_at"`
}
ServiceAccount is a machine identity.
type ServiceKey ¶ added in v0.16.0
type ServiceKey struct {
ID string `json:"id"`
Name string `json:"name"`
Prefix string `json:"prefix"`
Scopes []string `json:"scopes"`
SetID *string `json:"set_id,omitempty"`
LastUsedAt *time.Time `json:"last_used_at"`
CreatedAt time.Time `json:"created_at"`
}
ServiceKey is a service account's key, without its secret.
type Set ¶ added in v0.16.0
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 ¶ added in v0.16.0
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 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 SkillOutcomes ¶ added in v0.16.0
type SkillOutcomes struct {
MinComparableRuns int `json:"min_comparable_runs"`
Consumers []struct {
Consumer string `json:"consumer"`
Versions []VersionOutcomes `json:"versions"`
} `json:"consumers"`
}
SkillOutcomes is the outcome panel of one skill.
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 Submission ¶ added in v0.16.0
type Submission struct {
ID string `json:"id"`
SkillName string `json:"skill_name"`
Consumer string `json:"consumer"`
State string `json:"state"`
DecidedBy string `json:"decided_by"`
Reason string `json:"reason"`
Version *int `json:"version"`
CreatedAt time.Time `json:"created_at"`
}
Submission is a skill archive awaiting or past a person's decision.
type SubmissionRequest ¶ added in v0.16.0
type SubmissionRequest struct {
Name string `json:"name"`
Rationale string `json:"rationale"`
RunLink string `json:"run_link,omitempty"`
ExternalRunID string `json:"external_run_id,omitempty"`
ArchiveBase64 string `json:"archive_base64"`
}
SubmissionRequest is the request of POST /api/submissions.
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).
type VersionOutcomes ¶ added in v0.16.0
type VersionOutcomes struct {
Version int `json:"version"`
Runs int `json:"runs"`
Succeeded int `json:"succeeded"`
Failed int `json:"failed"`
Cancelled int `json:"cancelled"`
NoOutcome int `json:"no_outcome"`
SuccessRate *float64 `json:"success_rate"`
MeanRepairs *float64 `json:"mean_repairs"`
SampleTooSmall bool `json:"sample_too_small"`
Comparison *struct {
PreviousVersion int `json:"previous_version"`
SuccessRateChange float64 `json:"success_rate_change"`
MeanRepairsChange float64 `json:"mean_repairs_change"`
} `json:"comparison"`
}
VersionOutcomes summarises one consumer's runs that loaded one version. The rates are nil below the sample the server needs.
type WebhookAttempt ¶ added in v0.16.0
type WebhookAttempt struct {
ResponseCode *int `json:"response_code"`
Error string `json:"error"`
Succeeded bool `json:"succeeded"`
CreatedAt time.Time `json:"created_at"`
}
WebhookAttempt is one try at a delivery.
type WebhookDelivery ¶ added in v0.16.0
type WebhookDelivery struct {
ID string `json:"id"`
EventID string `json:"event_id"`
EventType string `json:"event_type"`
State string `json:"state"`
CreatedAt time.Time `json:"created_at"`
Attempts []WebhookAttempt `json:"attempts"`
}
WebhookDelivery is one event for one endpoint, with every attempt.
type WebhookEndpoint ¶ added in v0.16.0
type WebhookEndpoint struct {
ID string `json:"id"`
Name string `json:"name"`
URL string `json:"url"`
EventTypes []string `json:"event_types"`
SetIDs []string `json:"set_ids"`
Enabled bool `json:"enabled"`
}
WebhookEndpoint is a registered receiver, without its secret.
type WebhookEndpointInput ¶ added in v0.16.0
type WebhookEndpointInput struct {
Name string `json:"name"`
URL string `json:"url"`
EventTypes []string `json:"event_types"`
SetIDs []string `json:"set_ids,omitempty"`
Enabled *bool `json:"enabled,omitempty"`
}
WebhookEndpointInput is what create and update send. The update route replaces every field but enabled, which stays when omitted.
type WebhookEndpointWithSecret ¶ added in v0.16.0
type WebhookEndpointWithSecret struct {
WebhookEndpoint
Secret string `json:"secret"`
PreviousExpiresAt *time.Time `json:"previous_secret_expires_at"`
}
WebhookEndpointWithSecret is an endpoint after create or rotate, the only responses that hold the secret.