Files
archie/internal/infrastructure/kit/kit.go
T
sam a053d98d7c
deploy / plan (push) Successful in 7s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
deploy / gate (push) Canceled after 2m24s
refactor(kit): update capability types to use spec constants and add test for known capabilities
2026-11-09 08:32:56 +11:00

130 lines
4.5 KiB
Go

// Package kit decides whether archie can run a Kit v3 harness and with what
// capabilities.
package kit
import (
"context"
"errors"
"fmt"
"github.com/docker/sandbox-kit-spec/v3/fetch"
"github.com/docker/sandbox-kit-spec/v3/spec"
)
const (
typeCredential = spec.CapabilityCredential
typeAgentSessions = spec.CapabilityAgentSessions
)
// 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.
// Keys are the spec package's constants, not literals, so a dependency bump
// that renames a type fails to compile here instead of silently unclaiming
// it; TestSupportedCapabilitiesAreKnown guards the reverse direction.
var supported = map[string]bool{
typeCredential: true,
spec.CapabilityNetworkPolicy: true,
spec.CapabilityVolume: true,
spec.CapabilityLifecycle: true,
typeAgentSessions: true,
spec.CapabilityAgentSkills: true,
spec.CapabilityAgentSkill: true,
spec.CapabilityAgentContext: true,
spec.CapabilityResources: 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,
}
// 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 []spec.SelectionRecord
Sessions *spec.AgentSessions
ContextSources []spec.ContextSource
}
// SelectCapability applies Archie's runtime policy before composition.
func SelectCapability(ctx context.Context, _ spec.SelectionTarget, _ spec.Descriptor, c spec.Capability) spec.CapabilityDecision {
if err := ctx.Err(); err != nil {
return spec.CapabilityDecision{Message: err.Error()}
}
reason, err := refusalReason(c)
if err != nil {
return spec.CapabilityDecision{Message: err.Error()}
}
return spec.CapabilityDecision{Accepted: reason == "", Message: reason}
}
// FromResolved reads the profile's selected Kit declarations:
// a workload Kit or a published Kit set, never a bare mixin. archie drives a
// harness headlessly, so it must carry an agent-sessions prompt verb.
func FromResolved(resolved *fetch.Resolved) (*Plan, error) {
if resolved.Descriptor.Kind != spec.KindWorkload {
return nil, errors.New("kit is a mixin: publish a Kit set composing it with a workload Kit, and name the set")
}
plan := &Plan{Descriptor: resolved.Descriptor, Capabilities: resolved.Descriptor.Capabilities}
for _, selection := range resolved.Selections {
plan.Skipped = append(plan.Skipped, selection.Selection.Skipped...)
}
for _, unit := range resolved.Kits {
contexts, err := spec.AgentContextsOf(unit.Descriptor.Capabilities)
if err != nil {
return nil, err
}
for _, ac := range contexts {
if ac.ContentFile != "" || ac.Content != "" {
plan.ContextSources = append(plan.ContextSources, spec.ContextSource{Reference: unit.Reference, Path: ac.ContentFile, Content: ac.Content})
}
}
}
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
return plan, nil
}
// ValidateNeeds rejects a Plan without a resume verb when the gate may
// retry.
func ValidateNeeds(plan *Plan, gateRetries int) error {
if gateRetries > 0 && (plan.Sessions == nil || len(plan.Sessions.Resume) == 0) {
return fmt.Errorf("needs.gate_retries is %d, but the kit declares no %s resume verb to retry with", gateRetries, typeAgentSessions)
}
return 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
}