client

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: 14 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BatchFailure added in v0.16.0

func BatchFailure(err error) (index int, detail string, ok bool)

BatchFailure reads which event made a batch invalid. The batch route names the index itself, and the request schema names it in the error location.

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.

func (*APIError) Error

func (e *APIError) Error() string

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

type BatchResult struct {
	Stored int `json:"stored"`
	Runs   int `json:"runs"`
}

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 New

func New(endpoint, apiKey string) *Client

New creates a Client with a 30-second HTTP timeout.

func (*Client) ClaimEvalJob added in v0.10.0

func (c *Client) ClaimEvalJob(workerID string, leaseSeconds int) (*EvalJob, string, bool, error)

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) CreateSet added in v0.16.0

func (c *Client) CreateSet(name, description string, entries []SetEntry) (*Response[Set], error)

CreateSet calls POST /api/sets.

func (*Client) CreateSkill

func (c *Client) CreateSkill(name, description string) (*Skill, error)

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

func (c *Client) DeleteOwnershipRule(id string) error

DeleteOwnershipRule calls DELETE /api/ownership/rules/{id}.

func (*Client) DeleteServiceAccount added in v0.16.0

func (c *Client) DeleteServiceAccount(id string) error

DeleteServiceAccount calls DELETE /api/service-accounts/{id}.

func (*Client) DeleteSet added in v0.16.0

func (c *Client) DeleteSet(name string) error

DeleteSet calls DELETE /api/sets/{name}.

func (*Client) DeleteWebhookEndpoint added in v0.16.0

func (c *Client) DeleteWebhookEndpoint(id string) error

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

func (c *Client) DownloadVersion(name string, version int) ([]byte, error)

DownloadVersion calls GET /api/skills/{name}/versions/{v}/download and returns the raw archive bytes.

func (*Client) FailEvalJob added in v0.10.0

func (c *Client) FailEvalJob(id, token, cause string) error

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

func (c *Client) FetchEvalSuite(ref string) ([]byte, error)

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) FetchPRHead added in v0.18.0

func (c *Client) FetchPRHead(id string) ([]byte, error)

FetchPRHead calls GET /api/git/pr-heads/{id}/archive: the stored archive of a skill folder at a pull request head, which a contest candidate evaluates.

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

func (c *Client) GetContest(id string) (*Contest, error)

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) GetSet added in v0.16.0

func (c *Client) GetSet(name string) (*Response[SetDetail], error)

GetSet calls GET /api/sets/{name}.

func (*Client) GetSkill

func (c *Client) GetSkill(name string) (*Skill, error)

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

func (c *Client) Health() error

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

func (c *Client) HeartbeatEvalJob(id, token string) error

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

func (c *Client) ListContests(name string) ([]Contest, error)

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) ListSets added in v0.16.0

func (c *Client) ListSets() (*Response[struct {
	Sets []Set `json:"sets"`
}], error)

ListSets calls GET /api/sets.

func (*Client) ListSkills

func (c *Client) ListSkills(limit, offset int) ([]Skill, int, error)

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

func (c *Client) ListVersions(name string) ([]Version, error)

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

func (c *Client) PostContestReport(contestID, token string, body []byte) error

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) PostEvalJobEvents added in v0.20.0

func (c *Client) PostEvalJobEvents(id, token string, body []byte) error

PostEvalJobEvents calls POST /api/eval/jobs/{id}/events with a batch of job events, already JSON-encoded as {"events": [...]}.

func (*Client) PostEvalReport added in v0.10.0

func (c *Client) PostEvalReport(id, token string, body []byte) error

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

func (c *Client) RedeliverWebhook(deliveryID string) error

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

func (c *Client) RevokeServiceKey(accountID, keyID string) error

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

func (c *Client) SearchSkills(query string, limit int) ([]Skill, error)

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

func (c *Client) TestWebhookEndpoint(id string) error

TestWebhookEndpoint calls POST /api/webhooks/endpoints/{id}/test.

func (*Client) UpdateSet added in v0.16.0

func (c *Client) UpdateSet(name, description string, entries []SetEntry) (*Response[Set], error)

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.

func (*Client) WorkerCheckin added in v0.19.0

func (c *Client) WorkerCheckin(body, out any) error

WorkerCheckin calls POST /api/eval/workers/checkin with body and decodes the reply into out. Both are the server's workers wire types.

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 DiscoveredSkill struct {
	Name              string      `json:"name"`
	Description       string      `json:"description"`
	Path              string      `json:"path"`
	Files             []FileEntry `json:"files"`
	ScanStatus        string      `json:"scan_status"`
	ScanFindingsCount int         `json:"scan_findings_count"`
	ExistingVersion   int         `json:"existing_version"`
}

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"`
	// A contest job carries every candidate and the attempts per task. A
	// client that drops them runs the contest as a plain eval of the first.
	ContestID       string             `json:"contest_id,omitempty"`
	Candidates      []EvalJobCandidate `json:"candidates,omitempty"`
	ContestAttempts int                `json:"contest_attempts,omitempty"`
	// Eval is the claim's judge and panel, raw, for the worker to decode.
	Eval json.RawMessage `json:"-"`
}

EvalJob is the client-side representation of an eval queue job, as the claim/status endpoints return it.

type EvalJobCandidate added in v0.18.0

type EvalJobCandidate struct {
	SkillID      string          `json:"skill_id"`
	SkillName    string          `json:"skill_name"`
	Version      int             `json:"version"`
	Label        string          `json:"label"`
	ReusedReport json.RawMessage `json:"reused_report,omitempty"`
	ReusedFrom   string          `json:"reused_from,omitempty"`
	PRHeadID     string          `json:"pr_head_id,omitempty"`
}

EvalJobCandidate is one contest entry as the claim returns 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

type EvalSuiteUpload struct {
	Ref       string `json:"ref"`
	TaskCount int    `json:"task_count"`
}

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 FailedSkill struct {
	Name  string `json:"name"`
	Error string `json:"error"`
}

type FileChange added in v0.10.0

type FileChange struct {
	Path   string `json:"path"`
	Status string `json:"status"`
}

FileChange is one file whose presence or size differs between a held version and the currently served one.

type FileEntry

type FileEntry struct {
	Path string `json:"path"`
	Size int64  `json:"size"`
}

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 ImportSource struct {
	Type      string `json:"type"`
	Owner     string `json:"owner"`
	Repo      string `json:"repo"`
	Ref       string `json:"ref"`
	Path      string `json:"path"`
	CommitSHA string `json:"commit_sha"`
}

type ImportSourceEntry

type ImportSourceEntry struct {
	SkillName  string `json:"skill_name"`
	SourceType string `json:"source_type"`
	SourceURL  string `json:"source_url"`
	SourcePath string `json:"source_path"`
	SourceRef  string `json:"source_ref"`
	CommitSHA  string `json:"commit_sha"`
	ImportedAt string `json:"imported_at"`
}

type ImportedSkill

type ImportedSkill struct {
	Name       string `json:"name"`
	Version    int    `json:"version"`
	ScanStatus string `json:"scan_status"`
	Created    bool   `json:"created"`
}

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 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 the server opened for a git-bound 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 SetDetail added in v0.16.0

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

SetDetail is a set with who last used it.

type SetEntry added in v0.16.0

type SetEntry struct {
	Name    string `json:"name"`
	Version int    `json:"version,omitempty"`
	Kind    string `json:"kind,omitempty"`
}

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

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"`
	// Change is set instead of a version when the skill is git-bound: the
	// pull request whose merge publishes it.
	Change *OutboundChange `json:"change,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.

Jump to

Keyboard shortcuts

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