modelcatalog

Documentation

Overview

Package modelcatalog serves advisory agent model suggestions (static + CLI probe). Catalog membership is never a config or runtime gate (ADR-0016).

Index

• Constants
• Variables
• type ListOptions
• type Model
• type Options
• type Result
• type Runner
• type Service
  • func NewService(opts Options) *Service
  • func (s *Service) List(ctx context.Context, opts ListOptions) (Result, error)
  • func (s *Service) Shutdown()
• type Sources

Constants

const (
	SourceStatic = "static"
	SourceProbe  = "probe"
	SourceMerged = "merged"

	ProbeOK          = "ok"
	ProbeSkipped     = "skipped"
	ProbeError       = "error"
	ProbeUnsupported = "unsupported"
)

Variables

var ErrUnknownVendor = errors.New("unknown agent vendor")

ErrUnknownVendor is returned when List is called with a non-enum vendor.

Types

type ListOptions

type ListOptions struct {
	Vendor  config.AgentVendor
	Params  map[string]any    // spawn-filtered agent.params (command override)
	Env     map[string]string // configured agent.env (auth/config for vendor CLIs)
	Refresh bool
}

ListOptions controls a single catalog request.

type Model

type Model struct {
	ID     string `json:"id"`
	Label  string `json:"label"`
	Source string `json:"source"`
}

Model is one suggested model id for a vendor CLI.

type Options

type Options struct {
	TTL     time.Duration
	Timeout time.Duration
	Now     func() time.Time
	Runner  Runner
	// BaseContext bounds shared probe lifetime. Request cancel (popup close)
	// must not cancel shared probes; BaseContext cancel (daemon BeginShutdown)
	// must. Defaults to a service-owned cancelable background context.
	BaseContext context.Context
	// Tracker registers probe containment handles with the Supervisor for
	// shutdown drain / retain-storage (ADR-0015 / #577). Optional.
	Tracker  processcontainment.LiveTracker
	LookPath func(string) (string, error)
}

Options configures a Service. Zero values use defaults.

type Result

type Result struct {
	Vendor   string  `json:"vendor"`
	Models   []Model `json:"models"`
	Sources  Sources `json:"sources"`
	ProbedAt string  `json:"probedAt,omitempty"`
}

Result is the GET /api/v1/agent/models data payload.

type Runner

type Runner interface {
	Run(ctx context.Context, env []string, name string, args ...string) (stdout []byte, err error)
}

Runner executes a short-lived CLI probe. Tests inject fakes; production uses defaultRunner (exec with timeout + process group kill + sanitized env). env is the full sanitized process environment (KEY=value entries), never nil for production probes — use buildProbeEnv.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service merges static catalog entries with on-demand CLI probes.

func NewService

func NewService(opts Options) *Service

NewService constructs a catalog service with embedded static data.

func (*Service) List

func (s *Service) List(ctx context.Context, opts ListOptions) (Result, error)

List returns merged model suggestions for vendor. Probe failures never error when vendor is valid — callers always get static baseline + probe status. Concurrent cold Lists for the same vendor+binary key share one in-flight probe.

func (*Service) Shutdown

func (s *Service) Shutdown()

Shutdown cancels the daemon-owned shared probe parent so in-flight vendor CLIs observe cancel and enter process-group Kill. Idempotent. Call from BeginShutdown before non-agent drain waits so probes drain promptly.

type Sources

type Sources struct {
	Static     bool   `json:"static"`
	Probe      string `json:"probe"`
	ProbeError string `json:"probeError,omitempty"`
}

Sources describes how the model list was assembled.