skills

type ActiveSkill struct {
	Skill        *Skill    `json:"skill"`
	TriggerType  string    `json:"trigger_type"`
	TriggerValue string    `json:"trigger_value"`
	Confidence   float64   `json:"confidence"`
	ActivatedAt  time.Time `json:"activated_at"`
	SessionID    string    `json:"session_id"`
	AgentID      string    `json:"agent_id"`
}

type HotReloadConfig struct {
	Enabled    bool                // Enable hot-reload watching
	DebounceMs int                 // Debounce delay in milliseconds (default: 500ms)
	Logger     *zap.Logger         // Logger for reload events
	OnUpdate   SkillUpdateCallback // Callback for skill updates (optional)
}

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

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

type LibraryOption func(*Library)

type MatchResult struct {
	Skill        *Skill  `json:"skill"`
	Confidence   float64 `json:"confidence"`
	TriggerType  string  `json:"trigger_type"`
	TriggerValue string  `json:"trigger_value"`
}

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

type OrchestratorOption func(*Orchestrator)

type ScoredSkill struct {
	Skill *Skill  `json:"skill"`
	Score float64 `json:"score"`
}

type Skill struct {
	// Metadata
	Name        string            `json:"name"`
	Title       string            `json:"title"`
	Description string            `json:"description"`
	Version     string            `json:"version"`
	Domain      string            `json:"domain"`
	Labels      map[string]string `json:"labels,omitempty"`
	Author      string            `json:"author,omitempty"`

	// Confidence score 0.0-1.0. Hand-authored defaults to 1.0.
	Confidence      float64 `json:"confidence,omitempty"`
	Status          string  `json:"status,omitempty"`
	LastValidatedMs int64   `json:"last_validated_ms,omitempty"`
	RiskLevel       string  `json:"risk_level,omitempty"`

	// Trigger configuration
	Trigger SkillTrigger `json:"trigger"`

	// Prompt instructions
	Prompt SkillPrompt `json:"prompt"`

	// Tool requirements and preferences
	Tools SkillToolConfig `json:"tools"`

	// Co-inject these patterns when skill is active
	PatternRefs []string `json:"pattern_refs,omitempty"`

	// Compose with sub-skills (max depth: 2)
	SkillRefs []string `json:"skill_refs,omitempty"`

	// Token budget for this skill's prompt (0 = use default 1500)
	MaxPromptTokens int32 `json:"max_prompt_tokens,omitempty"`

	// Persist across turns once activated
	Sticky bool `json:"sticky,omitempty"`

	// Target backend (empty = agnostic)
	Backend string `json:"backend,omitempty"`

	// Optional explicit decomposition. When nil and EmitTasks resolves to true
	// (default), task.Decomposer is invoked at activation with the skill prompt
	// as goal. The emitter uses TaskTemplate.Steps to materialize tasks via
	// task.Manager.CreateTask + AddDependency.
	TaskTemplate *SkillTaskTemplate `json:"task_template,omitempty"`

	// Index path used by the hierarchical router to place this skill in the
	// SkillIndex tree, e.g. "enterprise/sql/optimization". Empty falls back to
	// "unclassified/<domain>".
	ParentIndexPath string `json:"parent_index_path,omitempty"`

	// Whether activation emits tracked tasks. Pointer mirrors proto3 optional:
	// nil = not specified (default true), &false = explicitly suppressed.
	// EffectiveEmitTasks() resolves this against zero-value semantics.
	EmitTasks *bool `json:"emit_tasks,omitempty"`
}

type SkillActivationMode string

type SkillBinding struct {
	// Name is an exact skill name or a path.Match-style glob ("enterprise/sql/*").
	Name string `json:"name"`
	// Mode controls when the skill is loaded into the orchestrator.
	Mode SkillBindingMode `json:"mode,omitempty"`
	// Priority breaks ties when context budget is tight (higher wins).
	Priority int32 `json:"priority,omitempty"`
	// LabelMatch is an optional AND-selector against Skill.Labels.
	LabelMatch map[string]string `json:"label_match,omitempty"`
	// MinVersion is a semver lower bound; empty means any version.
	MinVersion string `json:"min_version,omitempty"`
}

type SkillBindingMode string

type SkillExample struct {
	UserInput      string `json:"user_input"`
	ExpectedOutput string `json:"expected_output"`
	Explanation    string `json:"explanation,omitempty"`
}

type SkillExampleYAML struct {
	UserInput      string `yaml:"user_input"`
	ExpectedOutput string `yaml:"expected_output"`
	Explanation    string `yaml:"explanation"`
}

type SkillIndex struct {
	ID           string            `json:"id"`
	RootID       string            `json:"root_id"`
	Nodes        []*SkillIndexNode `json:"nodes,omitempty"`
	BuiltAtMs    int64             `json:"built_at_ms,omitempty"`
	BuiltByModel string            `json:"built_by_model,omitempty"`
}

type SkillIndexNode struct {
	ID        string            `json:"id"`
	Title     string            `json:"title"`
	Summary   string            `json:"summary,omitempty"`
	Children  []string          `json:"children,omitempty"`
	SkillRefs []string          `json:"skill_refs,omitempty"`
	Depth     int32             `json:"depth"`
	Labels    map[string]string `json:"labels,omitempty"`
	// ContentHash dirties only this subtree on YAML hot-reload; full index
	// rebuilds happen only on bulk add/remove.
	ContentHash string `json:"content_hash,omitempty"`
}

type SkillLibraryMetadataYAML struct {
	Name        string            `yaml:"name"`
	Version     string            `yaml:"version"`
	Description string            `yaml:"description"`
	Labels      map[string]string `yaml:"labels"`
}

type SkillLibraryYAML struct {
	APIVersion string                   `yaml:"apiVersion"`
	Kind       string                   `yaml:"kind"`
	Metadata   SkillLibraryMetadataYAML `yaml:"metadata"`
	Skills     []SkillYAML              `yaml:"skills"`
}

type SkillMetadataYAML struct {
	Name            string            `yaml:"name"`
	Title           string            `yaml:"title"`
	Description     string            `yaml:"description"`
	Version         string            `yaml:"version"`
	Domain          string            `yaml:"domain"`
	Author          string            `yaml:"author"`
	Labels          map[string]string `yaml:"labels"`
	Confidence      float64           `yaml:"confidence"`
	Status          string            `yaml:"status"`
	LastValidatedMs int64             `yaml:"last_validated_ms"`
	RiskLevel       string            `yaml:"risk_level"`
}

type SkillPrompt struct {
	// Main prompt instructions (supports {{.var}} interpolation)
	Instructions string `json:"instructions"`

	// Rules and constraints to enforce
	Constraints []string `json:"constraints,omitempty"`

	// Expected output structure description
	OutputFormat string `json:"output_format,omitempty"`

	// Few-shot examples
	Examples []SkillExample `json:"examples,omitempty"`
}

type SkillPromptYAML struct {
	Instructions string             `yaml:"instructions"`
	Constraints  []string           `yaml:"constraints"`
	OutputFormat string             `yaml:"output_format"`
	Examples     []SkillExampleYAML `yaml:"examples"`
}

type SkillSummary struct {
	Name        string            `json:"name"`
	Title       string            `json:"title"`
	Description string            `json:"description"`
	Domain      string            `json:"domain"`
	Version     string            `json:"version"`
	Labels      map[string]string `json:"labels,omitempty"`
	Commands    []string          `json:"commands,omitempty"`
}

type SkillTaskStep struct {
	Title              string  `json:"title"`
	Objective          string  `json:"objective,omitempty"`
	AcceptanceCriteria string  `json:"acceptance_criteria,omitempty"`
	Category           string  `json:"category,omitempty"`
	Priority           string  `json:"priority,omitempty"`
	DependsOn          []int32 `json:"depends_on,omitempty"`
	EstimatedEffort    string  `json:"estimated_effort,omitempty"`
	// Tags propagate onto the materialized Task.
	Tags []string `json:"tags,omitempty"`
}

type SkillTaskStepYAML struct {
	Title              string   `yaml:"title"`
	Objective          string   `yaml:"objective"`
	AcceptanceCriteria string   `yaml:"acceptance_criteria"`
	Category           string   `yaml:"category"`
	Priority           string   `yaml:"priority"`
	DependsOn          []int32  `yaml:"depends_on"`
	EstimatedEffort    string   `yaml:"estimated_effort"`
	Tags               []string `yaml:"tags"`
}

type SkillTaskTemplate struct {
	Steps []SkillTaskStep `json:"steps,omitempty"`
	// RootTitle names the parent task created to group emitted children.
	// Empty defaults to the skill's title.
	RootTitle string `json:"root_title,omitempty"`
	// EphemeralOnDeactivate deletes unstarted (still-OPEN) tasks if the
	// skill deactivates before they are claimed. In-progress and done
	// tasks are always preserved.
	EphemeralOnDeactivate bool `json:"ephemeral_on_deactivate,omitempty"`
	// MaxTasks caps the emitted task count. Default 8. Applies to
	// authored Steps and to decomposer fallback output alike.
	MaxTasks int32 `json:"max_tasks,omitempty"`
}

type SkillTaskTemplateYAML struct {
	Steps                 []SkillTaskStepYAML `yaml:"steps"`
	RootTitle             string              `yaml:"root_title"`
	EphemeralOnDeactivate bool                `yaml:"ephemeral_on_deactivate"`
	MaxTasks              int32               `yaml:"max_tasks"`
}

type SkillToolConfig struct {
	// Ensure these tools are registered when skill is active
	RequiredTools []string `json:"required_tools,omitempty"`

	// Suggested tool execution ordering
	PreferredOrder []string `json:"preferred_order,omitempty"`

	// Tools to hide when skill is active
	ExcludedTools []string `json:"excluded_tools,omitempty"`

	// MCP servers to enable when skill is active
	MCPServers []string `json:"mcp_servers,omitempty"`
}

type SkillToolsYAML struct {
	RequiredTools  []string `yaml:"required_tools"`
	PreferredOrder []string `yaml:"preferred_order"`
	ExcludedTools  []string `yaml:"excluded_tools"`
	MCPServers     []string `yaml:"mcp_servers"`
}

type SkillTrigger struct {
	// Slash commands that activate this skill: ["/review", "/code-review"]
	SlashCommands []string `json:"slash_commands,omitempty"`

	// Keywords for auto-detection from user messages
	Keywords []string `json:"keywords,omitempty"`

	// Freeform intent labels for intent-based activation (matched against pattern intents)
	IntentCategories []string `json:"intent_categories,omitempty"`

	// How this skill can be activated
	Mode SkillActivationMode `json:"mode,omitempty"`

	// Minimum confidence for AUTO/HYBRID activation (default: 0.7)
	MinConfidence float64 `json:"min_confidence,omitempty"`
}

type SkillTriggerYAML struct {
	SlashCommands    []string `yaml:"slash_commands"`
	Keywords         []string `yaml:"keywords"`
	IntentCategories []string `yaml:"intent_categories"`
	Mode             string   `yaml:"mode"`
	MinConfidence    float64  `yaml:"min_confidence"`
}

type SkillUpdateCallback func(eventType string, skillName string, err error)

type SkillYAML struct {
	APIVersion      string                 `yaml:"apiVersion"`
	Kind            string                 `yaml:"kind"`
	Metadata        SkillMetadataYAML      `yaml:"metadata"`
	Trigger         SkillTriggerYAML       `yaml:"trigger"`
	Prompt          SkillPromptYAML        `yaml:"prompt"`
	Tools           SkillToolsYAML         `yaml:"tools"`
	PatternRefs     []string               `yaml:"pattern_refs"`
	SkillRefs       []string               `yaml:"skill_refs"`
	MaxPromptTokens int32                  `yaml:"max_prompt_tokens"`
	Sticky          bool                   `yaml:"sticky"`
	Backend         string                 `yaml:"backend"`
	TaskTemplate    *SkillTaskTemplateYAML `yaml:"task_template,omitempty"`
	ParentIndexPath string                 `yaml:"parent_index_path,omitempty"`
	// EmitTasks uses *bool so we can distinguish "not specified" (default-true)
	// from "explicitly false". yaml.v3 leaves the pointer nil when the key is absent.
	EmitTasks *bool `yaml:"emit_tasks,omitempty"`
}

type SkillsConfig struct {
	Enabled bool
	// Deprecated: prefer Bindings. Resolver synthesizes EAGER-mode bindings
	// from this list when Bindings is empty.
	EnabledSkills []string
	// Deprecated: prefer Bindings. Resolver excludes these names when
	// synthesizing the implicit binding set.
	DisabledSkills       []string
	MinAutoConfidence    float64
	MaxConcurrentSkills  int
	SkillsDir            string
	ContextBudgetPercent int

	// Bindings declares the skills attached to this agent. Empty falls back
	// to the legacy EnabledSkills/DisabledSkills filter pair via the resolver
	// shim. When non-empty, Bindings takes full precedence.
	Bindings []SkillBinding

	// RouterEnabled gates the hierarchical PageIndex-style discovery path.
	// nil mirrors proto3 optional default-true; pointer so callers can
	// distinguish "not specified" from "explicitly false".
	RouterEnabled *bool
	// RouterMaxCandidates caps candidates returned per router walk (default 5).
	RouterMaxCandidates int
	// RouterCacheTTLSeconds is the per-session decision cache TTL (default 300).
	RouterCacheTTLSeconds int
	// RouterModelOverride names a specific LLM provider for routing decisions.
	// Empty falls back to AgentConfig.classifier_llm.
	RouterModelOverride string

	// SkillTaskBoardID names the task board for skill-emitted tasks.
	// Empty reuses the agent's primary board.
	SkillTaskBoardID string
	// TasksEnabled is the agent-level master switch for skill task emission.
	// nil mirrors proto3 optional default-true. Per-skill EmitTasks overrides
	// this for individual skills.
	TasksEnabled *bool

	// Hygiene controls end-of-turn task-board hygiene enforcement for
	// skill-emitted tasks. nil falls back to defaults (enabled, REQUIRE_FIX
	// policy, max_retries=2). The agent layer constructs the auditor when
	// both skillOrchestrator and taskManager are present.
	Hygiene *loomv1.HygieneConfig
}

type StickinessChecker func(skillName, sessionID string) bool