tools

package
v1.4.25 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 7, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package tools defines shared metadata for read-only AI tool catalogs.

Index

Constants

View Source
const (
	VisibilityAlways     = "always"
	VisibilityNonDefault = "non_default"
	VisibilityInternal   = "internal"
)

Variables

View Source
var (
	ErrInvalidAgent       = errors.New("tools: invalid agent")
	ErrUnknownTool        = errors.New("tools: unknown tool")
	ErrUnknownToolset     = errors.New("tools: unknown toolset")
	ErrGroupedChild       = errors.New("tools: grouped child must be changed through its toolset")
	ErrConflict           = errors.New("tools: concurrent update conflict")
	ErrCatalogDrift       = errors.New("tools: runtime tool missing from catalog")
	ErrNewerPolicyVersion = errors.New("tools: newer toolset policy version")
)

Functions

func AddTimeRangeProperties

func AddTimeRangeProperties(properties map[string]any, defaultMinutes, maxMinutes int) map[string]any

AddTimeRangeProperties adds the shared time-range schema to properties.

func SetEntitlementResolver

func SetEntitlementResolver(resolver EntitlementResolver)

SetEntitlementResolver installs the process-wide entitlement adapter at boot.

func TimeRangeProperties

func TimeRangeProperties(defaultMinutes, maxMinutes int) map[string]any

TimeRangeProperties returns JSON-schema properties for the shared time range.

Types

type AgentKind

type AgentKind string

AgentKind identifies an independently configurable model tool list.

const (
	AgentChat    AgentKind = "chat"
	AgentAnalyze AgentKind = "analyze"
)

type CatalogSection

type CatalogSection string

CatalogSection identifies an operator-facing tool catalog section.

const (
	SectionConnector  CatalogSection = "connector"
	SectionDataSource CatalogSection = "datasource"
	SectionCommon     CatalogSection = "common"
	SectionInternal   CatalogSection = "internal"
)

type DependencyStatus

type DependencyStatus struct {
	Configured  bool
	Constructed bool
	Healthy     bool
	Name        string
	Health      string
}

DependencyStatus is a provider-neutral, bounded prerequisite observation.

type EntitlementDecision

type EntitlementDecision struct {
	Required    bool
	Reason      string
	Action      string
	ActionLabel string
}

EntitlementDecision lets an external module distinguish a purchase gate from an ordinary setup step without exposing its license implementation to OSS.

type EntitlementResolver

type EntitlementResolver func(Requirement, DependencyStatus) EntitlementDecision

EntitlementResolver derives entitlement from the requirement and the actual provider capability observation. Returning Required=false defers to OSS.

type Entry

type Entry struct {
	Group Group
	Tool  core.Tool
}

Entry binds a tool to the domain group that owns it.

type Group

type Group string

Group identifies a domain-scoped toolset.

const (
	GroupCommon Group = "common"
	GroupVersus Group = "versus"
	GroupK8s    Group = "k8s"
)

type Manager

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

Manager stores per-agent tool choices through the configured durable CAS provider. A nil provider remains readable with default-enabled state.

func NewManager

func NewManager(provider storage.Provider) *Manager

func (*Manager) Enabled

func (manager *Manager) Enabled(scope tenancy.OrgScope, agent AgentKind, name string) (bool, error)

func (*Manager) Filter

func (manager *Manager) Filter(scope tenancy.OrgScope, agent AgentKind, runtime []core.Tool, snapshot Snapshot) ([]core.Tool, error)

Filter removes unavailable and operator-disabled tools for one agent without changing the order supplied by runtime composition.

func (*Manager) Load

func (manager *Manager) Load(scope tenancy.OrgScope) (SettingsView, error)

Load reads and validates one settings generation for an operation.

func (*Manager) LoadToolsets

func (manager *Manager) LoadToolsets(scope tenancy.OrgScope) (ToolsetSettingsView, error)

LoadToolsets reads grouped policy and the one-release legacy overlay.

func (*Manager) Revision

func (manager *Manager) Revision(scope tenancy.OrgScope) (string, bool)

Revision returns a stable hash of the durable settings blob for holder rebuild signatures. Missing settings have the empty revision.

func (*Manager) SetEnabled

func (manager *Manager) SetEnabled(scope tenancy.OrgScope, agent AgentKind, name string, enabled bool) (bool, error)

SetEnabled durably updates one agent/tool resource. Repeating the same value is an idempotent success and does not rewrite storage.

func (*Manager) SetToolsetEnabled

func (manager *Manager) SetToolsetEnabled(scope tenancy.OrgScope, agent AgentKind, id string, enabled bool) (bool, error)

SetToolsetEnabled changes one group bit through a resumable mixed-version transition. Legacy child denies mask every intermediate grouped state.

func (*Manager) ToolsetEnabled

func (manager *Manager) ToolsetEnabled(scope tenancy.OrgScope, agent AgentKind, id string) (bool, error)

ToolsetEnabled returns fail-closed effective policy for one operator card.

type Metadata

type Metadata struct {
	Group       Group       `json:"group"`
	Name        string      `json:"name"`
	DisplayName string      `json:"display_name"`
	Description string      `json:"description"`
	DocsURL     string      `json:"docs_url,omitempty"`
	UIPath      string      `json:"ui_path,omitempty"`
	Requirement Requirement `json:"requirement"`
}

Metadata is the stable, complete catalog record for a known tool. It is independent of runtime construction so missing dependencies remain visible.

func Catalog

func Catalog() []Metadata

Catalog returns every known tool in UI order, including planned tools whose runtime implementation has not landed yet.

func Lookup

func Lookup(name string) (Metadata, bool)

Lookup returns the immutable catalog metadata for a known tool name.

type Registry

type Registry []Entry

Registry is an ordered collection of grouped tools.

type Requirement

type Requirement struct {
	Kind         RequirementKind `json:"kind"`
	SignalKind   string          `json:"signal_kind,omitempty"`
	Integration  string          `json:"integration,omitempty"`
	Capabilities []string        `json:"capabilities,omitempty"`
}

Requirement describes one prerequisite. Capability requirements may contain more than one capability; all listed capabilities are required.

type RequirementKind

type RequirementKind string

RequirementKind identifies the external condition a tool needs before it can be offered to an agent.

const (
	RequirementNone        RequirementKind = "none"
	RequirementDataSource  RequirementKind = "datasource"
	RequirementIntegration RequirementKind = "integration"
	RequirementCapability  RequirementKind = "capability"
)

type Resolution

type Resolution struct {
	State       State  `json:"state"`
	Reason      string `json:"reason"`
	Action      string `json:"action"`
	ActionLabel string `json:"action_label"`
	Health      string `json:"health,omitempty"`
}

Resolution is safe display copy for one tool card.

func Resolve

func Resolve(requirement Requirement, snapshot Snapshot, enabled bool) Resolution

Resolve evaluates requirements before operator state, so a disabled toggle can never mask a missing or unhealthy prerequisite.

type SettingsView

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

SettingsView is one validated, immutable settings generation.

func (SettingsView) Enabled

func (view SettingsView) Enabled(agent AgentKind, name string) (bool, error)

Enabled returns operator state from this generation without storage I/O.

func (SettingsView) Filter

func (view SettingsView) Filter(agent AgentKind, runtime []core.Tool, snapshot Snapshot) ([]core.Tool, error)

Filter resolves a runtime tool list from this settings generation.

func (SettingsView) Revision

func (view SettingsView) Revision() string

Revision returns the stable digest for this already-loaded generation.

type Snapshot

type Snapshot struct {
	DataSources  map[string]DependencyStatus
	Integrations map[string]DependencyStatus
	Capabilities map[string]DependencyStatus
}

Snapshot contains the current prerequisite state keyed by catalog values.

type State

type State string

State is the server-resolved availability state rendered by admin clients.

const (
	StateNeedsLicense       State = "needs_license"
	StateNeedsDataSource    State = "needs_datasource"
	StateNeedsIntegration   State = "needs_integration"
	StateNeedsCapability    State = "needs_capability"
	StateNeedsPermission    State = "needs_permission"
	StateUnhealthy          State = "unhealthy"
	StateDisabledByOperator State = "disabled_by_operator"
	StateAvailable          State = "available"
)

type TimeRange

type TimeRange struct {
	Start   time.Time
	End     time.Time
	Minutes int
}

TimeRange is an absolute, bounded query interval.

func ResolveTimeRange

func ResolveTimeRange(args TimeRangeArgs, now time.Time, defaultMinutes, maxMinutes int) (TimeRange, error)

ResolveTimeRange resolves absolute bounds and relative aliases into one interval.

type TimeRangeArgs

type TimeRangeArgs struct {
	TimeRangeMinutes int    `json:"time_range_minutes"`
	WindowMinutes    int    `json:"window_minutes"`
	Start            string `json:"start"`
	End              string `json:"end"`
}

TimeRangeArgs is the shared model-facing time-range contract.

type ToolsetMetadata

type ToolsetMetadata struct {
	ID          string          `json:"id"`
	Section     CatalogSection  `json:"section"`
	DisplayName string          `json:"display_name"`
	Description string          `json:"description"`
	IconKey     string          `json:"icon_key"`
	ToolNames   []string        `json:"-"`
	Requirement Requirement     `json:"requirement"`
	DocsURL     string          `json:"docs_url,omitempty"`
	UIPath      string          `json:"ui_path,omitempty"`
	Visibility  string          `json:"visibility"`
	Permission  core.Permission `json:"permission,omitempty"`
}

ToolsetMetadata is the server-owned operator policy and presentation record. ToolNames remain hidden from the product API and are used for runtime policy.

func Toolsets

func Toolsets() []ToolsetMetadata

Toolsets returns the normal operator cards in canonical section and card order.

type ToolsetSettingsView

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

ToolsetSettingsView is one immutable generation of grouped policy combined with the compatibility generation of individual policy.

func (ToolsetSettingsView) Enabled

func (view ToolsetSettingsView) Enabled(agent AgentKind, id string) (bool, error)

Enabled resolves a group bit together with all current legacy child bits.

func (ToolsetSettingsView) Filter

func (view ToolsetSettingsView) Filter(agent AgentKind, runtime []core.Tool, snapshot Snapshot) ([]core.Tool, error)

Filter applies grouped policy, legacy overlay, and runtime capability gates.

func (ToolsetSettingsView) NewerPolicy

func (view ToolsetSettingsView) NewerPolicy() bool

NewerPolicy reports a readable policy generation this binary must not edit.

func (ToolsetSettingsView) Revision

func (view ToolsetSettingsView) Revision() string

Revision hashes grouped and compatibility policy as one runtime generation.

Directories

Path Synopsis
Package tools contains cross-cutting read-only AI tools backed by external sources.
Package tools contains cross-cutting read-only AI tools backed by external sources.
Package k8s contains read-only Kubernetes AI tools.
Package k8s contains read-only Kubernetes AI tools.
Package tools contains read-only AI tools backed by Versus state.
Package tools contains read-only AI tools backed by Versus state.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL