feat: foundations — canonical types, Parse grammar, env DSNs, health, chains

Phase 1 of the majordomo build:
- llm/ canonical contract (messages, parts, tools, capabilities, streaming,
  Model/Provider, error classification)
- health/ clock-injected tracker (threshold bench, exponential capped
  cooldown, reset-on-success)
- root Registry + Parse (verbatim model ids, inline recursive alias
  expansion with cycle detection, chain dedup), LLM_* env-DSN providers
  (go-llm parity: lazy fallback + eager LoadEnv), health-aware chain
  executor behind the Model interface
- provider/fake scriptable test provider; hermetic test suite incl. the
  trailing-thinking chain and foreman:// env loading
- ADRs 0001-0008, CLAUDE.md, README (honest matrix), CI workflow,
  docs/phase-1-design.md

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

majordomo.go

@@ -0,0 +1,139 @@
+// Package majordomo is a clean-slate substrate for building LLM-backed
+// agents: target-agnostic model access, a parseable model naming /
+// failover / tiering system with health tracking, multimodality, tool calls
+// and structured output, and agents composed from a model + system prompt +
+// toolboxes + skills.
+//
+// The one-call entry point is Parse:
+//
+//	reg := majordomo.New()
+//	m, err := reg.Parse("ollama-cloud/minimax-m3:cloud,anthropic/opus-4.8,thinking")
+//	resp, err := m.Generate(ctx, majordomo.Request{
+//	    Messages: []majordomo.Message{majordomo.UserText("hello")},
+//	})
+//
+// A spec is a comma-separated failover chain. Each element is either a
+// "provider/model" target (built-in, client-registered, or defined via an
+// LLM_* env DSN) or a registered alias/tier, which expands inline. See
+// Registry.Parse for the full grammar.
+//
+// The canonical types (Message, Request, Response, Tool, Capabilities, ...)
+// are defined in the llm subpackage and re-exported here, so most consumers
+// only ever import this package (plus agent and skill).
+package majordomo
+
+import (
+	"encoding/json"
+	"sync"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+)
+
+// Re-exported canonical types. See the llm package for documentation.
+type (
+	Model        = llm.Model
+	Provider     = llm.Provider
+	Message      = llm.Message
+	Role         = llm.Role
+	Part         = llm.Part
+	TextPart     = llm.TextPart
+	ImagePart    = llm.ImagePart
+	Request      = llm.Request
+	Response     = llm.Response
+	Option       = llm.Option
+	ModelOption  = llm.ModelOption
+	ModelConfig  = llm.ModelConfig
+	Tool         = llm.Tool
+	ToolCall     = llm.ToolCall
+	ToolResult   = llm.ToolResult
+	Toolbox      = llm.Toolbox
+	Capabilities = llm.Capabilities
+	Stream       = llm.Stream
+	StreamEvent  = llm.StreamEvent
+	Usage        = llm.Usage
+	FinishReason = llm.FinishReason
+	APIError     = llm.APIError
+	ErrorClass   = llm.ErrorClass
+)
+
+// Re-exported role and finish-reason constants.
+const (
+	RoleSystem    = llm.RoleSystem
+	RoleUser      = llm.RoleUser
+	RoleAssistant = llm.RoleAssistant
+	RoleTool      = llm.RoleTool
+
+	FinishStop          = llm.FinishStop
+	FinishLength        = llm.FinishLength
+	FinishToolCalls     = llm.FinishToolCalls
+	FinishContentFilter = llm.FinishContentFilter
+	FinishOther         = llm.FinishOther
+
+	ClassTransient = llm.ClassTransient
+	ClassPermanent = llm.ClassPermanent
+)
+
+// ErrModelNotFound re-exports llm.ErrModelNotFound.
+var ErrModelNotFound = llm.ErrModelNotFound
+
+// Re-exported content and message constructors.
+func Text(s string) Part                              { return llm.Text(s) }
+func Image(mime string, data []byte) Part             { return llm.Image(mime, data) }
+func SystemText(s string) Message                     { return llm.SystemText(s) }
+func UserText(s string) Message                       { return llm.UserText(s) }
+func UserParts(parts ...Part) Message                 { return llm.UserParts(parts...) }
+func AssistantText(s string) Message                  { return llm.AssistantText(s) }
+func ToolResultsMessage(results ...ToolResult) Message { return llm.ToolResultsMessage(results...) }
+func NewToolbox(name string, tools ...Tool) *Toolbox  { return llm.NewToolbox(name, tools...) }
+
+// Re-exported request options.
+func WithSystem(s string) Option                        { return llm.WithSystem(s) }
+func WithTools(tools ...Tool) Option                    { return llm.WithTools(tools...) }
+func WithToolbox(b *Toolbox) Option                     { return llm.WithToolbox(b) }
+func WithToolChoice(choice string) Option               { return llm.WithToolChoice(choice) }
+func WithSchema(schema json.RawMessage, name string) Option { return llm.WithSchema(schema, name) }
+func WithTemperature(t float64) Option                  { return llm.WithTemperature(t) }
+func WithTopP(p float64) Option                         { return llm.WithTopP(p) }
+func WithMaxTokens(n int) Option                        { return llm.WithMaxTokens(n) }
+func WithStopSequences(stops ...string) Option          { return llm.WithStopSequences(stops...) }
+
+// WithModelCapabilities re-exports llm.WithCapabilities for Provider.Model
+// calls made through this package.
+func WithModelCapabilities(caps Capabilities) ModelOption { return llm.WithCapabilities(caps) }
+
+// Classify re-exports llm.Classify.
+func Classify(err error) ErrorClass { return llm.Classify(err) }
+
+// defaultRegistry backs the package-level convenience functions.
+var defaultRegistry = func() func() *Registry {
+	var (
+		once sync.Once
+		reg  *Registry
+	)
+	return func() *Registry {
+		once.Do(func() { reg = New() })
+		return reg
+	}
+}()
+
+// Default returns the lazily-initialized package-level Registry (built-in
+// providers plus LLM_* env providers from the process environment).
+func Default() *Registry { return defaultRegistry() }
+
+// Parse resolves a spec using the Default registry.
+func Parse(spec string) (Model, error) { return Default().Parse(spec) }
+
+// MustParse is Parse that panics on error; for wiring code and examples.
+func MustParse(spec string) Model {
+	m, err := Parse(spec)
+	if err != nil {
+		panic(err)
+	}
+	return m
+}
+
+// RegisterProvider registers a provider in the Default registry.
+func RegisterProvider(p Provider) { Default().RegisterProvider(p) }
+
+// RegisterAlias registers an alias/tier in the Default registry.
+func RegisterAlias(name, spec string) { Default().RegisterAlias(name, spec) }