Files
archie/internal/infrastructure/kit/kit.go
T
sam a7edc0a5cd feat(kit): admit Kit v3 descriptors against archie's capability support
Decodes published descriptors from the manifest annotation, composes one
workload with its mixins through the Kit spec package, and applies the
runtime's support table: unsupported required capabilities refuse the
launch, optional ones are skipped and recorded, and forge or passthrough
credentials are refused. A composition must carry a headless prompt verb.
2026-09-26 02:23:11 +10:00

174 lines
5.4 KiB
Go

// Package kit decides whether archie can run a harness packaged as Kit v3
// images, and what it runs with. Descriptor grammar, validation and
// composition belong to the Kit spec package; this package owns only the
// runtime's half of the contract: which capability types archie implements,
// and the refusals that keep the host's guarantees intact.
package kit
import (
"errors"
"fmt"
"strings"
"github.com/docker/sandbox-kit-spec/v3/spec"
)
const (
typeCredential = "com.docker.sandbox/credential@1"
typeAgentSessions = "com.docker.sandbox/agent-sessions@1"
// contextPath is where the composed agent-context body is staged.
contextPath = "/usr/share/archie/agent-context.md"
)
// supported is every capability type archie provides. Anything else is
// refused when required and skipped when optional: approximating a type
// archie does not implement would grant a Kit something nobody reviewed.
var supported = map[string]bool{
typeCredential: true,
"com.docker.sandbox/network-policy@1": true,
"com.docker.sandbox/volume@1": true,
"com.docker.sandbox/lifecycle@1": true,
typeAgentSessions: true,
"com.docker.sandbox/agent-skills@1": true,
"com.docker.sandbox/agent-context@1": true,
"com.docker.sandbox/resources@1": true,
}
// forgeServices are credential services a harness never receives: the model
// never runs git, so it never holds a credential that could push.
var forgeServices = map[string]bool{
"github": true,
"gitlab": true,
"gitea": true,
"forgejo": true,
"bitbucket": true,
}
// Skip is an optional capability archie does not provide, recorded so the
// step that ran without it can say so.
type Skip struct {
Type string
Reason string
}
// Refusal is a required capability archie will not provide.
type Refusal struct {
Type string
Reason string
}
// RefusedError carries every refusal, so an operator fixes a Kit in one pass.
type RefusedError struct {
Refusals []Refusal
}
func (e *RefusedError) Error() string {
parts := make([]string, len(e.Refusals))
for i, r := range e.Refusals {
parts[i] = r.Type + ": " + r.Reason
}
return "kit refused: " + strings.Join(parts, "; ")
}
// Plan is what archie launches: the composed descriptor, the capabilities
// it provides, and what it skipped.
type Plan struct {
Descriptor *spec.Descriptor
Capabilities []spec.Capability
Skipped []Skip
Sessions *spec.AgentSessions
ContextSources []spec.ContextSource
}
// DecodePublished reads the descriptor from an image's manifest annotations
// and holds it to the published form: strict decoding, full validation, and
// no unexpanded build-phase args.
func DecodePublished(annotations map[string]string) (*spec.Descriptor, error) {
raw, ok := annotations[spec.AnnotationDescriptor]
if !ok {
return nil, fmt.Errorf("image is not a kit: no %s annotation", spec.AnnotationDescriptor)
}
d, err := spec.Decode([]byte(raw))
if err != nil {
return nil, err
}
if _, err := spec.ValidatePublished([]byte(raw), d); err != nil {
return nil, err
}
return d, nil
}
// Admit applies archie's capability support to one descriptor. Every
// required capability archie will not provide is collected into a
// RefusedError; optional ones are skipped.
func Admit(d *spec.Descriptor) (*Plan, error) {
plan := &Plan{Descriptor: d}
var refusals []Refusal
for _, c := range d.Capabilities {
reason, err := refusalReason(c)
if err != nil {
return nil, err
}
switch {
case reason == "":
plan.Capabilities = append(plan.Capabilities, c)
case c.Optional:
plan.Skipped = append(plan.Skipped, Skip{Type: c.Type, Reason: reason})
default:
refusals = append(refusals, Refusal{Type: c.Type, Reason: reason})
}
}
if len(refusals) > 0 {
return nil, &RefusedError{Refusals: refusals}
}
return plan, nil
}
// Compose merges one workload Kit and its mixins, in the order given, and
// admits the result. archie drives a harness headlessly, so the composition
// must carry an agent-sessions prompt verb.
func Compose(contributions []spec.Contribution) (*Plan, error) {
merged, err := spec.Merge(contributions, spec.MergeOptions{ContextPath: contextPath})
if err != nil {
return nil, err
}
if merged.Descriptor.Kind != spec.KindWorkload {
return nil, errors.New("kit composition has no workload: a harness needs exactly one base kit")
}
plan, err := Admit(merged.Descriptor)
if err != nil {
return nil, err
}
sessions, err := spec.AgentSessionsOf(plan.Capabilities)
if err != nil {
return nil, err
}
if sessions == nil || len(sessions.Prompt) == 0 {
return nil, fmt.Errorf("kit composition declares no %s prompt verb: archie cannot run it headlessly", typeAgentSessions)
}
plan.Sessions = sessions
plan.ContextSources = merged.ContextSources
return plan, nil
}
func refusalReason(c spec.Capability) (string, error) {
if !supported[c.Type] {
return "not provided by archie", nil
}
if c.Type != typeCredential {
return "", nil
}
var cred spec.Credential
if err := spec.DecodeCapabilityConfig(c, &cred); err != nil {
return "", err
}
if forgeServices[cred.Service] {
return fmt.Sprintf("service %q is a forge credential; harnesses never hold one", cred.Service), nil
}
if cred.OAuth != nil && cred.OAuth.Passthrough {
return fmt.Sprintf("service %q asks for OAuth passthrough; real tokens never enter the container", cred.Service), nil
}
return "", nil
}