cli

type AliasKind ¶ added in v1.0.52

type AliasKind string

AliasKind records how a reviewed alias path is represented by Cobra. A Cobra alias resolves to the primary command pointer; a compatibility leaf is a separately registered (usually hidden) runnable command. Keeping the two forms explicit prevents downstream code from assuming that every alias has its own Cobra leaf.

const (
	AliasKindCobraAlias        AliasKind = "cobra_alias"
	AliasKindCompatibilityLeaf AliasKind = "compatibility_leaf"
)

type BoundAlias ¶ added in v1.0.52

type BoundAlias struct {
	Path         string
	Command      *cobra.Command
	Kind         AliasKind
	Source       string
	ReviewReason string
}

BoundAlias is one reviewed alias path resolved against the live Cobra tree.

type BoundCommandRegistry ¶ added in v1.0.52

type BoundCommandRegistry struct {
	Commands    []BoundCommandSpec
	ByCanonical map[string]BoundCommandSpec
	ByCLIPath   map[string]BoundCommandSpec
}

BoundCommandRegistry is the only command input the Schema assembler should consume. Every entry has passed exact path, executable-leaf, collision, and native-annotation consistency checks.

func BindEffectiveCommandRegistry(root *cobra.Command, effective EffectiveCommandRegistry) (BoundCommandRegistry, error)

type BoundCommandSpec ¶ added in v1.0.52

type BoundCommandSpec struct {
	CommandSpec
	PrimaryCommand *cobra.Command
	AliasCommands  []BoundAlias
}

BoundCommandSpec joins one stable registry identity to its executable primary leaf and all executable alias paths.

type CLIFlagHint ¶ added in v1.0.48

type CLIFlagHint struct {
	Shorthand string `json:"shorthand,omitempty"`
	Alias     string `json:"alias,omitempty"`
}

CLIFlagHint holds CLI flag alias/shorthand metadata for a tool parameter.

type CanonicalProduct ¶ added in v1.0.48

type CanonicalProduct struct {
	ID          string           `json:"id"`
	DisplayName string           `json:"display_name"`
	Description string           `json:"description,omitempty"`
	ServerKey   string           `json:"server_key"`
	Endpoint    string           `json:"endpoint"`
	Source      string           `json:"source,omitempty"`
	Tools       []ToolDescriptor `json:"tools"`
}

CanonicalProduct represents a single MCP product in the catalog.

func (p CanonicalProduct) FindTool(name string) (ToolDescriptor, bool)

type Catalog ¶ added in v1.0.48

type Catalog struct {
	Products []CanonicalProduct `json:"products"`
}

Catalog holds the discovered MCP product surface.

func (c Catalog) FindProduct(id string) (CanonicalProduct, bool)

type CatalogDegraded ¶ added in v1.0.9

type CatalogDegraded struct {
	Reason      CatalogDegradedReason
	Hint        string
	ServerCount int
}

CatalogDegraded is returned by EnvironmentLoader.Load when discovery fails for a diagnosable reason. Callers that need graceful degradation (e.g. the runtime runner) can check errors.As and fall back to an empty catalog; callers like the schema command can surface the hint.

func (e *CatalogDegraded) Error() string

type CatalogDegradedReason ¶ added in v1.0.9

type CatalogDegradedReason string

CatalogDegradedReason identifies why catalog discovery returned empty.

const (
	DegradedUnauthenticated   CatalogDegradedReason = "unauthenticated"
	DegradedMarketUnreachable CatalogDegradedReason = "market_unreachable"
	DegradedRuntimeAllFailed  CatalogDegradedReason = "runtime_all_failed"
)

type CatalogLoader ¶

type CatalogLoader interface {
	Load(context.Context) (Catalog, error)
}

CatalogLoader loads the canonical catalog.

func CatalogLoaderFrom(catalog Catalog, err error) CatalogLoader

type CommandRegistry ¶ added in v1.0.52

type CommandRegistry struct {
	Commands    []CommandSpec
	ByCLIPath   map[string]CommandSpec
	ByCanonical map[string]CommandSpec
}

CommandRegistry is the decoded reviewed identity registry.

func ValidateCommandRegistrySource(data []byte) (CommandRegistry, error)

func (registry CommandRegistry) SourceHash() string

type CommandSpec ¶ added in v1.0.52

type CommandSpec struct {
	CanonicalPath   string
	SourceProductID string
	PrimaryCLIPath  string
	Aliases         []string
	Visibility      SchemaVisibility
	Source          string
	ReviewReason    string
}

CommandSpec is one reviewed command identity. Identity and navigation are deliberately kept together so no downstream renderer can independently invent a canonical name, primary path, or alias.

type DryRunSpec ¶ added in v1.0.52

type DryRunSpec struct {
	PreviewKind string `json:"preview_kind"`
	RemoteReads bool   `json:"remote_reads,omitempty"`
}

DryRunSpec is a positive capability declaration. A nil ToolSpec.DryRun means the command has not declared reviewed --dry-run support; the Schema does not publish a negative or inferred capability in that case.

The whole object is one atomic contract field. Runtime execution remains owned by the command runner; Schema only projects the reviewed capability.

func (d DryRunSpec) Validate(canonical string) error

type EffectiveCommandRegistry ¶ added in v1.0.52

type EffectiveCommandRegistry struct {
	Commands    []CommandSpec
	ByCLIPath   map[string]CommandSpec
	ByCanonical map[string]CommandSpec
}

EffectiveCommandRegistry is the reviewed registry after exact reviewed manual command additions have been merged. It remains independent of Cobra; binding is a separate fail-closed step.

func BuildEffectiveCommandRegistry(root *cobra.Command) (EffectiveCommandRegistry, error)

func (registry EffectiveCommandRegistry) SourceHash() string

type EnvironmentLoader ¶

type EnvironmentLoader struct {
	LookupEnv              func(string) (string, bool)
	CatalogBaseURLOverride string
	AuthTokenFunc          func(context.Context) string
	LoggerFunc             func() *slog.Logger
}

EnvironmentLoader provides catalog loading. In the post-discovery architecture this always returns an empty catalog; endpoint resolution is handled by the direct runtime path.

func NewEnvironmentLoader() EnvironmentLoader

func (l EnvironmentLoader) Load(_ context.Context) (Catalog, error)

type FieldCandidateProvenance ¶ added in v1.0.52

type FieldCandidateProvenance struct {
	Value        json.RawMessage `json:"value,omitempty"`
	Source       string          `json:"source"`
	SourceRef    string          `json:"source_ref,omitempty"`
	Precedence   string          `json:"precedence,omitempty"`
	ReviewReason string          `json:"review_reason,omitempty"`
	Selected     *bool           `json:"selected,omitempty"`
}

FieldCandidateProvenance retains one winning or non-winning source value.

type FieldProvenance ¶ added in v1.0.52

type FieldProvenance struct {
	Value                json.RawMessage            `json:"value,omitempty"`
	Source               string                     `json:"source"`
	SourceRef            string                     `json:"source_ref,omitempty"`
	Precedence           string                     `json:"precedence,omitempty"`
	Resolution           string                     `json:"resolution"`
	ReviewReason         string                     `json:"review_reason,omitempty"`
	Candidates           []FieldCandidateProvenance `json:"candidates,omitempty"`
	OverriddenCandidates []FieldCandidateProvenance `json:"overridden_candidates,omitempty"`
}

FieldProvenance records how one final field was selected. Value is raw JSON so provenance can describe strings, booleans and structured extension values without weakening the resolved ToolSpec itself.

type FlagKind ¶

type FlagKind string

type FlagSpec ¶

type FlagSpec struct {
	PropertyName string
	FlagName     string
	Alias        string
	Shorthand    string
	Kind         FlagKind
	Description  string
}

func BuildFlagSpecs(schema map[string]any, hints map[string]CLIFlagHint) []FlagSpec

type InterfaceRefKey ¶ added in v1.0.52

type InterfaceRefKey struct {
	ProductID string
	RPCName   string
}

InterfaceRefKey is the exact, typed identity of an embedded MCP operation. It is deliberately independent from a CLI canonical path: multiple commands may explicitly project the same operation.

type InterfaceRefSpec ¶ added in v1.0.52

type InterfaceRefSpec struct {
	ProductID string `json:"product_id"`
	RPCName   string `json:"rpc_name"`
}

InterfaceRefSpec identifies the backing operation, independently from the executable command identity.

type InterfaceRegistry ¶ added in v1.0.52

type InterfaceRegistry struct {
	ByCanonical    map[string]InterfaceRegistryEntry
	ByInterfaceRef map[InterfaceRefKey][]string
}

InterfaceRegistry is the typed interface fact model. ByCanonical supports exact metadata navigation; ByInterfaceRef answers whether an explicitly selected (product_id, rpc_name) exists. The latter retains every canonical projection because sharing one RPC is valid and intentional.

type InterfaceRegistryEntry ¶ added in v1.0.52

type InterfaceRegistryEntry struct {
	CanonicalPath string
	Ref           InterfaceRefSpec
	Metadata      embeddedMCPToolMetadata
}

InterfaceRegistryEntry is one operation projection from the fixed embedded MCP metadata. CanonicalPath is a metadata lookup key, not command identity.

type InterfaceSpec ¶ added in v1.0.52

type InterfaceSpec struct {
	Ref          *InterfaceRefSpec
	Mode         string
	Availability string
	Reason       string
}

InterfaceSpec describes whether and how the Agent may invoke the backing interface.

func (i InterfaceSpec) AgentExecutable() bool

func (i InterfaceSpec) Validate(canonical string) error

type ManualAgentExampleDisposition ¶ added in v1.0.52

type ManualAgentExampleDisposition struct {
	Index      *int                         `json:"index"`
	Mode       ManualAgentExampleMode       `json:"mode"`
	ReasonCode ManualAgentExampleReasonCode `json:"reason_code"`
	Reason     string                       `json:"reason"`
	Reviewed   bool                         `json:"reviewed"`
}

ManualAgentExampleDisposition narrows one exact example with an explicit typed dry-run capability to contract-only. Index is a pointer so a missing JSON field cannot silently select example zero.

type ManualAgentExampleDispositionSource ¶ added in v1.0.52

type ManualAgentExampleDispositionSource string

ManualAgentExampleDispositionSource distinguishes the normal typed-contract classification from narrow reviewed manual exceptions.

const (
	ManualAgentExampleDispositionDefault        ManualAgentExampleDispositionSource = "default"
	ManualAgentExampleDispositionReviewedManual ManualAgentExampleDispositionSource = "reviewed_manual"
)

type ManualAgentExampleExecution ¶ added in v1.0.52

type ManualAgentExampleExecution struct {
	CanonicalPath string
	Index         int
	Example       string
	Mode          ManualAgentExampleMode
	DryRun        *DryRunSpec
	ReasonCode    ManualAgentExampleReasonCode
	Reason        string
	Source        ManualAgentExampleDispositionSource
}

ManualAgentExampleExecution is one resolved example and its effective test mode. Contract validation has already succeeded when this value is returned.

type ManualAgentExampleExecutionPlan ¶ added in v1.0.52

type ManualAgentExampleExecutionPlan struct {
	Examples             []ManualAgentExampleExecution
	Total                int
	Contract             int
	DryRun               int
	ContractOnly         int
	ReviewedContractOnly int
	ContractOnlyByReason map[ManualAgentExampleReasonCode]int
}

ManualAgentExampleExecutionPlan is a stable, typed report used by the exhaustive real-Cobra dry-run test. Counts are derived only from the final typed dry-run capability and committed reviewed dispositions; runtime failures can never add implicit skips.

func BuildManualAgentExampleExecutionPlan(bound BoundCommandRegistry, registry SchemaRegistry, hints ManualAgentHintSet) (ManualAgentExampleExecutionPlan, error)

func ValidateEmbeddedManualAgentExampleDelivery(bound BoundCommandRegistry, registry SchemaRegistry) (ManualAgentExampleExecutionPlan, error)

type ManualAgentExampleMode ¶ added in v1.0.52

type ManualAgentExampleMode string

ManualAgentExampleMode controls only how an already contract-validated example is exercised. Contract validation is the default. dry_run is used only when the final ToolSpec publishes an explicit reviewed capability; contract_only remains a precise reviewed exception for such a capability whose runtime preconditions cannot be exercised safely and deterministically in the isolated test process.

const (
	ManualAgentExampleModeContract     ManualAgentExampleMode = "contract"
	ManualAgentExampleModeDryRun       ManualAgentExampleMode = "dry_run"
	ManualAgentExampleModeContractOnly ManualAgentExampleMode = "contract_only"
)

type ManualAgentExampleReasonCode ¶ added in v1.0.52

type ManualAgentExampleReasonCode string

ManualAgentExampleReasonCode is a closed taxonomy for reviewed contract-only exceptions to an explicit dry-run capability. Safety and confirmation remain independently enforced and cannot be weakened through an example disposition. There is deliberately no generic "skip" value: a reviewer must identify the concrete precondition.

const (
	ManualAgentExampleReasonLocalState        ManualAgentExampleReasonCode = "local_state"
	ManualAgentExampleReasonStatefulPreflight ManualAgentExampleReasonCode = "stateful_preflight"
)

type ManualAgentHintRevision ¶ added in v1.0.52

type ManualAgentHintRevision struct {
	GeneratedBy   string `json:"generated_by"`
	Model         string `json:"model,omitempty"`
	PromptVersion string `json:"prompt_version,omitempty"`
	Reason        string `json:"reason"`
}

ManualAgentHintRevision records how one reviewed authoring batch was produced. Product and tool entries reference it by the enclosing map key so later focused revisions do not relabel unchanged prose.

type ManualAgentHintSet ¶ added in v1.0.52

type ManualAgentHintSet struct {
	Revisions map[string]ManualAgentHintRevision `json:"revisions,omitempty"`
	Products  map[string]ManualAgentProductHint  `json:"products,omitempty"`
	Tools     map[string]ManualAgentToolHint     `json:"tools,omitempty"`
}

ManualAgentHintSet keeps reviewed Agent-selection prose in the same manual source as command and parameter overrides without making that prose an identity annotation. Generators may read this section; they must never write it back or use it to change executable, parameter, safety, or interface facts.

func LoadAgentHintsFromSelectionForValidation(selectionFS fs.FS) (ManualAgentHintSet, error)

type ManualAgentProductHint ¶ added in v1.0.52

type ManualAgentProductHint struct {
	AgentSummary string   `json:"agent_summary"`
	UseWhen      []string `json:"use_when"`
	AvoidWhen    []string `json:"avoid_when"`
	Reviewed     bool     `json:"reviewed"`
	Revision     string   `json:"revision"`
	Reason       string   `json:"reason"`
	Evidence     []string `json:"evidence"`
}

ManualAgentProductHint defines product-level routing prose.

type ManualAgentSelectionCase ¶ added in v1.0.52

type ManualAgentSelectionCase struct {
	ID                  string   `json:"id"`
	ProductID           string   `json:"product_id"`
	Scenario            string   `json:"scenario"`
	ExpectedCanonical   string   `json:"expected_canonical,omitempty"`
	ForbiddenCanonical  string   `json:"forbidden_canonical,omitempty"`
	CandidateCanonicals []string `json:"candidate_canonicals"`
}

ManualAgentSelectionCase is one reproducible model-evaluation assertion derived from reviewed Manual Agent hints. Positive cases require one exact canonical result; negative cases only forbid the command that owns the avoid_when text. CandidateCanonicals contains every bound tool in the same product, in stable order.

type ManualAgentSelectionFixture ¶ added in v1.0.52

type ManualAgentSelectionFixture struct {
	Version int                        `json:"version"`
	Cases   []ManualAgentSelectionCase `json:"cases"`
}

ManualAgentSelectionFixture is the stable input to an optional live Agent evaluation. It is built from schema_hints/selection and the real bound command tree; it is not a second authored hint source.

type ManualAgentSelectionReport ¶ added in v1.0.52

type ManualAgentSelectionReport struct {
	Tools              int
	PositiveAssertions int
	NegativeAssertions int
	FixtureSHA256      string
}

ManualAgentSelectionReport records deterministic coverage and the exact fixture digest. It proves that all reviewed assertions are well-formed and executable; it deliberately does not claim that a language model understood their natural-language meaning.

func ValidateManualAgentSelectionContract(bound BoundCommandRegistry, hints ManualAgentHintSet) (ManualAgentSelectionReport, error)

type ManualAgentToolHint ¶ added in v1.0.52

type ManualAgentToolHint struct {
	AgentSummary        string                          `json:"agent_summary"`
	UseWhen             []string                        `json:"use_when"`
	AvoidWhen           []string                        `json:"avoid_when"`
	Examples            []string                        `json:"examples"`
	ExampleDispositions []ManualAgentExampleDisposition `json:"example_dispositions,omitempty"`
	Reviewed            bool                            `json:"reviewed"`
	Revision            string                          `json:"revision"`
	Reason              string                          `json:"reason"`
	Evidence            []string                        `json:"evidence"`
}

ManualAgentToolHint defines the reviewed prose used to select and demonstrate one existing effective command. ExampleDispositions contains only test eligibility exceptions; it cannot change identity, parameters, safety, or interface disposition.

type ManualSchemaCommandHint ¶ added in v1.0.52

type ManualSchemaCommandHint struct {
	CLIPath       string                               `json:"cli_path"`
	CanonicalPath string                               `json:"canonical_path"`
	Reason        string                               `json:"reason"`
	Reviewed      bool                                 `json:"reviewed"`
	Parameters    map[string]ManualSchemaParameterHint `json:"parameters,omitempty"`
}

ManualSchemaCommandHint opts one exact existing Cobra leaf into Schema and optionally reviews its CLI-facing parameter projection.

type ManualSchemaHintReport ¶ added in v1.0.52

type ManualSchemaHintReport struct {
	Commands   []string
	Parameters []string
}

ManualSchemaHintReport records the exact reviewed inputs applied to a command tree. It is useful to generators and tests; no runtime discovery is performed.

func ApplyEmbeddedManualSchemaHints(root *cobra.Command) (ManualSchemaHintReport, error)

type ManualSchemaHintSnapshot ¶ added in v1.0.52

type ManualSchemaHintSnapshot struct {
	Schema     string                    `json:"$schema"`
	Version    int                       `json:"version"`
	Commands   []ManualSchemaCommandHint `json:"commands"`
	AgentHints ManualAgentHintSet        `json:"agent_hints"`
}

ManualSchemaHintSnapshot is the human-owned bridge from an existing public Cobra leaf to Schema. It cannot create commands, flags, exclusions, or interfaces: every referenced command and flag is checked against the live tree before any annotation is applied.

func DecodeManualSchemaHintSource(data []byte) (ManualSchemaHintSnapshot, error)

type ManualSchemaParameterHint ¶ added in v1.0.52

type ManualSchemaParameterHint struct {
	Description   *string `json:"description,omitempty"`
	Property      *string `json:"property,omitempty"`
	InterfaceType *string `json:"interface_type,omitempty"`
	Required      *bool   `json:"required,omitempty"`
	RequiredWhen  *string `json:"required_when,omitempty"`
}

ManualSchemaParameterHint changes only Schema annotations on a real flag. Pointer fields distinguish an omitted override from an explicit false.

type ParameterSchemaHint ¶ added in v1.0.52

type ParameterSchemaHint struct {
	FlagName     string
	Type         string
	Description  string
	Required     *bool
	RequiredWhen string
}

ParameterSchemaHint overrides the projected flat schema for one parameter. It can be keyed either by the original MCP parameter name (preferred) or by the final CLI flag name when a hint is purely CLI-facing.

type ParameterSpec ¶ added in v1.0.52

type ParameterSpec struct {
	Name                 string
	Type                 string
	Description          string
	Property             string
	Required             bool
	CLIRequired          bool
	RequiredWhen         string
	Default              json.RawMessage
	InterfaceDefault     json.RawMessage
	Example              json.RawMessage
	Format               string
	Enum                 []string
	InterfaceDescription string
	InterfaceType        string
	FieldProvenance      map[string]FieldProvenance
	Extensions           map[string]json.RawMessage
}

ParameterSpec is one resolved CLI flag projection. Name is the CLI flag key used in the legacy parameters object. Default and Example are RawMessage because JSON literals are polymorphic; they are still typed JSON values and never participate in precedence as map[string]any.

func (p ParameterSpec) ToPayload() (map[string]any, error)

type ProductSpec ¶ added in v1.0.52

type ProductSpec struct {
	ID              string
	Name            string
	Description     string
	Runtime         bool
	Tools           []ToolSpec
	Selection       SelectionSpec
	FieldProvenance map[string]FieldProvenance
	Extensions      map[string]json.RawMessage
}

ProductSpec is one deterministic product grouping in SchemaRegistry.

func (p ProductSpec) ToPayload() (map[string]any, error)

func (p ProductSpec) ToSummaryPayload() (map[string]any, error)

type ResolvedSchemaBuild ¶ added in v1.0.52

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

ResolvedSchemaBuild is the single source-to-delivery hand-off used by the Catalog generator. Effective, Bound, and Registry are three views of one resolution pass: reviewed identity, executable Cobra binding, and the final typed Agent contract. Downstream gates and serializers must consume this value instead of rebuilding any view from the command tree.

The command root is intentionally private. It lets delivery completeness inspect the same executable tree without allowing callers to construct a seemingly resolved build by assembling the exported fields themselves.

func ResolveSchemaBuild(root *cobra.Command) (ResolvedSchemaBuild, error)

func (resolved ResolvedSchemaBuild) CommandCount() int

func (resolved ResolvedSchemaBuild) RegistryHash() string

type RuntimeCompatibilityEquivalence ¶ added in v1.0.52

type RuntimeCompatibilityEquivalence struct {
	ID       string `json:"id"`
	Reason   string `json:"reason"`
	Reviewed bool   `json:"reviewed"`
}

RuntimeCompatibilityEquivalence is an implementation-side review record for two separately registered Cobra leaves that intentionally share one Schema identity despite using different execution handlers. Registry alias review alone is not enough: different handlers may inject fixed arguments or route to different business operations while exposing identical flags.

type RuntimeSchemaCompletenessReport ¶ added in v1.0.52

type RuntimeSchemaCompletenessReport struct {
	Covered           []string
	Excluded          []string
	Missing           []string
	InvalidExclusions []string
	StaleExclusions   []string
	DeliveryErrors    []string
}

RuntimeSchemaCompletenessReport compares the public executable Cobra leaves with a reviewed Schema command set, such as runtime annotations or the final generated Catalog.

func RuntimeSchemaCompleteness(root *cobra.Command, exclusions []RuntimeSchemaExclusion) RuntimeSchemaCompletenessReport

type RuntimeSchemaConstraints ¶ added in v1.0.52

type RuntimeSchemaConstraints struct {
	MutuallyExclusive [][]string `json:"mutually_exclusive,omitempty"`
	RequireOneOf      [][]string `json:"require_one_of,omitempty"`
	RequireTogether   [][]string `json:"require_together,omitempty"`
}

RuntimeSchemaConstraints describes cross-parameter rules that cannot be represented by an individual parameter's required bit.

type RuntimeSchemaExclusion ¶ added in v1.0.52

type RuntimeSchemaExclusion struct {
	CLIPath  string `json:"cli_path"`
	Reason   string `json:"reason"`
	Reviewed bool   `json:"reviewed"`
}

RuntimeSchemaExclusion records a reviewed reason why a public executable command is intentionally not advertised as an Agent tool.

func EmbeddedRuntimeSchemaExclusions() ([]RuntimeSchemaExclusion, error)

type RuntimeSchemaParameterMetadata ¶ added in v1.0.52

type RuntimeSchemaParameterMetadata struct {
	Inherited    []string
	Required     []string
	RequiredWhen map[string]string
	Formats      map[string]string
	Enums        map[string][]string
	Examples     map[string]string
}

RuntimeSchemaParameterMetadata contains reviewed CLI parameter semantics that Cobra cannot represent by itself. It is an independent generation input: generated Catalog data is never read back into this registry.

type RuntimeSchemaPositional ¶ added in v1.0.52

type RuntimeSchemaPositional struct {
	Name        string `json:"name"`
	Type        string `json:"type,omitempty"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required"`
	Variadic    bool   `json:"variadic,omitempty"`
	Index       int    `json:"index"`
}

RuntimeSchemaPositional describes one ordered CLI argument. Name is also used by RuntimeSchemaConstraints when a one-of group mixes flags and args.

type RuntimeToolSpecInput ¶ added in v1.0.52

type RuntimeToolSpecInput struct {
	Identity        ToolIdentitySpec
	Display         string
	Title           string
	Description     string
	MetadataSource  string
	Parameters      []ParameterSpec
	Constraints     RuntimeSchemaConstraints
	Positionals     []RuntimeSchemaPositional
	DryRun          *DryRunSpec
	Safety          SafetySpec
	Interface       InterfaceSpec
	Selection       SelectionSpec
	FieldProvenance map[string]FieldProvenance
	Extensions      map[string]json.RawMessage
}

RuntimeToolSpecInput is the typed hand-off from runtime source resolution to contract assembly. Adapters resolve candidates first, then call ToolSpecFromRuntime exactly once; payload rendering does no further merging.

type SafetySpec ¶ added in v1.0.52

type SafetySpec struct {
	Effect       string
	EffectSource string
	Risk         string
	Confirmation string
	Idempotency  string
}

SafetySpec is the resolved operation behavior. This model deliberately does not impose a value lattice: precedence policy belongs to the resolver, so a reviewed higher-priority source may intentionally raise or lower a value.

type SchemaCatalogBuildOptions ¶ added in v1.0.52

type SchemaCatalogBuildOptions struct {
	RegistryHash string
}

SchemaCatalogBuildOptions carries release-envelope inputs which are checked against the effective reviewed CommandRegistry. The command set is not an option: visibility is resolved by EffectiveCommandRegistry before assembly, and every public command must be delivered.

type SchemaCatalogSnapshot ¶ added in v1.0.52

type SchemaCatalogSnapshot struct {
	Version     int                       `json:"version"`
	SourceHash  string                    `json:"source_hash"`
	SurfaceHash string                    `json:"surface_hash,omitempty"`
	Catalog     map[string]any            `json:"catalog"`
	Tools       map[string]map[string]any `json:"tools"`
}

SchemaCatalogSnapshot is the release-stable Agent contract. Catalog holds the progressive product/tool index; Tools holds full leaf parameter schemas. It intentionally contains no endpoint, credential, or runtime cache data.

func BuildSchemaCatalogSnapshot(resolved ResolvedSchemaBuild, options SchemaCatalogBuildOptions) (SchemaCatalogSnapshot, error)

type SchemaHintRegistry ¶ added in v1.0.52

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

func (r *SchemaHintRegistry) Lookup(canonicalPath string) (ToolSchemaHint, bool)

func (r *SchemaHintRegistry) RegisterProduct(productID string, tools map[string]ToolSchemaHint)

type SchemaIndex ¶ added in v1.0.52

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

SchemaIndex is the immutable navigation view over one normalized registry. It mirrors Lark's typed catalog split: SchemaRegistry owns data, SchemaIndex owns deterministic identity/path resolution, and serializers only render a resolved ToolSpec.

func (i SchemaIndex) CanonicalPaths() []string

func (i SchemaIndex) Product(id string) (ProductSpec, bool)

func (i SchemaIndex) Registry() SchemaRegistry

func (i SchemaIndex) Resolve(path string) (ToolSpec, bool)

func (i SchemaIndex) ResolveQuery(path string) (ToolSpec, bool)

type SchemaMetadataLoadCounts ¶ added in v1.0.52

type SchemaMetadataLoadCounts struct {
	Catalog          uint64
	AgentMetadata    uint64
	MCPMetadata      uint64
	ParameterBinding uint64
}

SchemaMetadataLoadCounts exposes read-only diagnostics for startup tests and profiling. Counts are incremented only when a lazy embedded snapshot is parsed for the first time.

func RuntimeSchemaMetadataLoadCounts() SchemaMetadataLoadCounts

type SchemaRegistry ¶ added in v1.0.52

type SchemaRegistry struct {
	Kind              string
	Level             string
	Source            string
	Products          []ProductSpec
	InterfaceMetadata json.RawMessage
	AgentMetadata     json.RawMessage
	Extensions        map[string]json.RawMessage
}

SchemaRegistry is the resolved, typed Agent contract. Source adapters and precedence resolvers populate this model; wire payloads are rendered only at the outer boundary by ToPayload. This keeps map[string]any out of the contract assembly path.

func AssembleSchemaRegistry(root *cobra.Command) (SchemaRegistry, error)

func AssembleSchemaRegistryFromBound(bound BoundCommandRegistry) (SchemaRegistry, error)

func SchemaRegistryFromRuntime(source string, products []ProductSpec) (SchemaRegistry, error)

func (r SchemaRegistry) Index() (SchemaIndex, error)

func (r SchemaRegistry) Sorted() SchemaRegistry

func (r SchemaRegistry) ToOverviewPayload() (map[string]any, error)

func (r SchemaRegistry) ToPayload() (map[string]any, error)

func (r SchemaRegistry) ToSnapshotPayload() (SchemaSnapshotPayload, error)

type SchemaSnapshotPayload ¶ added in v1.0.52

type SchemaSnapshotPayload struct {
	Catalog map[string]any
	Tools   map[string]map[string]any
}

SchemaSnapshotPayload is the final wire boundary for the release snapshot. Catalog summaries and full Tools are both derived from the same typed ToolSpec instances, preventing the two snapshot layers from drifting.

type SchemaVisibility ¶ added in v1.0.52

type SchemaVisibility string

const (
	SchemaVisibilityPublic   SchemaVisibility = "public"
	SchemaVisibilityCompat   SchemaVisibility = "compat"
	SchemaVisibilityInternal SchemaVisibility = "internal"
)

type SelectionSpec ¶ added in v1.0.52

type SelectionSpec struct {
	AgentSummary       string
	AgentSummarySource string
	UseWhen            []string
	AvoidWhen          []string
	Prerequisites      []string
	Tips               []string
	WorkflowRefs       []string
	Examples           []string
	Reviewed           *bool
	SourceRefs         []string
	MetadataSource     string
}

SelectionSpec contains Agent command-selection guidance. Product specs use the common summary/use/avoid/source subset; tool specs may use every field.

type StaticLoader ¶

type StaticLoader struct {
	Catalog Catalog
}

StaticLoader returns a pre-built catalog.

func (l StaticLoader) Load(_ context.Context) (Catalog, error)

type StdinGuard ¶

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

StdinGuard ensures stdin is consumed at most once per command invocation. Multiple flags using @- or implicit stdin fallback would race on the same reader; StdinGuard detects and rejects the second claim with a clear error.

func NewStdinGuard() *StdinGuard

func (g *StdinGuard) Claim(source string) error

func (g *StdinGuard) Claimed() bool

type ToolDescriptor ¶ added in v1.0.48

type ToolDescriptor struct {
	RPCName       string `json:"rpc_name"`
	CanonicalPath string `json:"canonical_path"`
}

ToolDescriptor represents a single tool in a canonical product.

type ToolIdentitySpec ¶ added in v1.0.52

type ToolIdentitySpec struct {
	ProductID       string
	SourceProductID string
	Name            string
	CLIName         string
	CanonicalPath   string
	Path            string
	CLIPath         string
	PrimaryCLIPath  string
	Group           string
	Aliases         []string
	IsAlias         bool
	Source          string
}

ToolIdentitySpec contains only command identity. It is intentionally separate from interface identity: an executable Cobra leaf and an RPC are related by InterfaceSpec, but are not interchangeable sources of truth.

type ToolSchemaHint ¶ added in v1.0.52

type ToolSchemaHint struct {
	Title       string
	Description string
	Parameters  map[string]ParameterSchemaHint
}

ToolSchemaHint is reviewed field metadata for an existing registry-owned tool. It intentionally has no command path, alias, visibility, or canonical identity fields: all identity/navigation comes from CommandRegistry.

type ToolSpec ¶ added in v1.0.52

type ToolSpec struct {
	Identity        ToolIdentitySpec
	Display         string
	Title           string
	Description     string
	MetadataSource  string
	Parameters      []ParameterSpec
	Constraints     RuntimeSchemaConstraints
	Positionals     []RuntimeSchemaPositional
	DryRun          *DryRunSpec
	Safety          SafetySpec
	Interface       InterfaceSpec
	Selection       SelectionSpec
	FieldProvenance map[string]FieldProvenance
	Extensions      map[string]json.RawMessage
}

ToolSpec is the single assembled representation of a command contract. Safety, interface and selection are typed sub-models even though ToPayload preserves the historical flat JSON shape for compatibility.

func ToolSpecFromRuntime(input RuntimeToolSpecInput) (ToolSpec, error)

func (t ToolSpec) ToPayload() (map[string]any, error)

func (t ToolSpec) ToSummaryPayload() (map[string]any, error)

func (t ToolSpec) Validate() error