agentmetadata

package
v1.0.63 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source 
const CurrentVersion = 1

Variables

This section is empty.

Functions

func Generate 

func Generate(opts Options) (File, Stats, error)

func GenerateFromCommandRoot added in v1.0.57 

func GenerateFromCommandRoot(rootPath string, commandRoot *cobra.Command, opts Options) (File, Stats, RegistryProjection, error)

GenerateFromCommandRoot is the Catalog in-memory Agent-metadata pipeline. It binds the EffectiveCommandRegistry, validates that ProductDecl/ContractFinal cover selection, and Generate()s metadata without reading or writing schema_agent_metadata/ or schema_hints/.

func SelectionCoverageProducts added in v1.0.57 

func SelectionCoverageProducts(projection RegistryProjection) map[string]bool

SelectionCoverageProducts returns product IDs that still lack a ProductDecl. Declared products are exempt.

func SelectionCoverageTools added in v1.0.57 

func SelectionCoverageTools(projection RegistryProjection) map[string]bool

SelectionCoverageTools returns canonical tools that still lack a ContractFinal selection declaration. Declared leaves are exempt.

func ValidateSelectionCoverage added in v1.0.57 

func ValidateSelectionCoverage(projection RegistryProjection) error

ValidateSelectionCoverage requires every projected product to have ProductDecl and every projected tool to have ContractFinal. Retired schema_hints/ overlays are not accepted as coverage.

Types

type Audit 

type Audit struct {
	Version                       int                     `json:"version"`
	SourceHash                    string                  `json:"source_hash"`
	SurfaceHash                   string                  `json:"surface_hash,omitempty"`
	SourceFiles                   int                     `json:"source_files"`
	InterfaceMetadata             *InterfaceMetadataAudit `json:"interface_metadata,omitempty"`
	Coverage                      Coverage                `json:"coverage"`
	SourceProducts                []string                `json:"source_products,omitempty"`
	SkillProductsOutsideSurface   []string                `json:"skill_products_outside_surface,omitempty"`
	SurfaceProductsWithoutRouting []string                `json:"surface_products_without_routing_metadata,omitempty"`
	UnmatchedReferences           []UnmatchedReference    `json:"unmatched_references,omitempty"`
}

Audit contains build-time diagnostics that are intentionally kept separate from the runtime Agent metadata contract.

func BuildAudit 

func BuildAudit(file File, stats Stats) Audit

type Coverage 

type Coverage struct {
	SurfaceProducts        int `json:"surface_products,omitempty"`
	ProductsWithMetadata   int `json:"products_with_metadata"`
	SurfaceTools           int `json:"surface_tools,omitempty"`
	ToolsWithMetadata      int `json:"tools_with_metadata"`
	ToolsWithSummary       int `json:"tools_with_agent_summary,omitempty"`
	ToolsWithUseWhen       int `json:"tools_with_use_when,omitempty"`
	ToolsWithAvoidWhen     int `json:"tools_with_avoid_when,omitempty"`
	ToolsWithExamples      int `json:"tools_with_examples,omitempty"`
	ToolsWithInterfaceMode int `json:"tools_with_interface_mode,omitempty"`
	UnmatchedSkillTools    int `json:"unmatched_skill_tools,omitempty"`
	UnreviewedSkillTools   int `json:"unreviewed_skill_tools,omitempty"`
}

type FieldCandidateProvenance 

type FieldCandidateProvenance struct {
	Value        any    `json:"value"`
	Source       string `json:"source"`
	Precedence   string `json:"precedence"`
	Selected     bool   `json:"selected"`
	ReviewReason string `json:"review_reason,omitempty"`
}

FieldCandidateProvenance preserves a non-winning input so precedence decisions remain auditable in the generated Agent contract.

type FieldProvenance 

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

FieldProvenance identifies the winning source and the deterministic rule used to resolve one final Agent-facing field.

type File 

type File struct {
	Version     int                        `json:"version"`
	SourceHash  string                     `json:"source_hash"`
	SurfaceHash string                     `json:"surface_hash,omitempty"`
	Coverage    Coverage                   `json:"coverage"`
	Products    map[string]ProductMetadata `json:"products"`
	Tools       map[string]ToolMetadata    `json:"tools"`
}

type InterfaceMetadataAudit 

type InterfaceMetadataAudit struct {
	Source             string   `json:"source,omitempty"`
	Revision           string   `json:"revision,omitempty"`
	SourceHash         string   `json:"source_hash,omitempty"`
	SourceTools        int      `json:"source_tools"`
	SurfaceTools       int      `json:"surface_tools"`
	EligibleSummaries  int      `json:"eligible_summaries"`
	AppliedSummaries   int      `json:"applied_summaries"`
	PreservedSummaries int      `json:"preserved_summaries"`
	RejectedTools      []string `json:"rejected_tools,omitempty"`
	OutsideSurface     []string `json:"outside_surface,omitempty"`
}

InterfaceMetadataAudit records how sanitized MCP descriptions contributed to Agent summaries. Interface metadata is fallback-only and never infers effect, risk, confirmation, or idempotency.

type InterfaceRef 

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

InterfaceRef links a stable public command to the MCP operation that implements it. It is interface identity, not runtime endpoint discovery.

type Options 

type Options struct {
	Root            string
	SkillPath       string
	ProductsDir     string
	IntentGuidePath string
	// HintsDir is a fail-closed anti-regression valve. The field name and the
	// "schema_hints/" error text are intentional: policy and callers still probe
	// this retired path. Non-empty values must keep failing; do not rename away.
	HintsDir string
	// ManualHintsPath is a fail-closed anti-regression valve for the retired
	// manual-hints file path. Keep the field name; non-empty values must fail.
	ManualHintsPath          string
	InterfaceMetadataPath    string
	MaxExamples              int
	MaxInterfaceSummaryRunes int
	ToolPaths                map[string]string
	CanonicalToolPaths       map[string]string
	BoundCommands            cli.BoundCommandRegistry
	ProductIDs               map[string]bool
	SurfaceHash              string
	SurfaceToolCount         int
}

type ProductMetadata 

type ProductMetadata struct {
	AgentSummary       string                     `json:"agent_summary,omitempty"`
	AgentSummarySource string                     `json:"agent_summary_source,omitempty"`
	UseWhen            []string                   `json:"use_when,omitempty"`
	AvoidWhen          []string                   `json:"avoid_when,omitempty"`
	SourceRefs         []string                   `json:"source_refs,omitempty"`
	FieldProvenance    map[string]FieldProvenance `json:"field_provenance,omitempty"`
	// contains filtered or unexported fields
}

func (ProductMetadata) MarshalJSON 

func (metadata ProductMetadata) MarshalJSON() ([]byte, error)

MarshalJSON preserves the distinction between an omitted authored list and an explicitly authored empty list. The latter is a real precedence value: it intentionally clears a lower-ranked non-empty list and must be emitted as [] rather than being removed by omitempty.

type ReferenceReview 

type ReferenceReview struct {
	Status string `json:"status"`
	Target string `json:"target,omitempty"`
	Reason string `json:"reason"`
}

ReferenceReview is an optional disposition of a Skill command reference that is not a current public leaf. Production no longer loads reviewed HintFile reference_review maps; unmatched Skill paths are recorded in the build-time audit without requiring a reviewed disposition.

type RegistryProjection added in v1.0.57 

type RegistryProjection struct {
	ToolPaths          map[string]string
	CanonicalToolPaths map[string]string
	ProductIDs         map[string]bool
	Hash               string
	ToolCount          int
	Bound              cli.BoundCommandRegistry
}

RegistryProjection is the EffectiveCommandRegistry view required by Generate. Catalog assembly and the optional diagnostic Agent-metadata CLI both build this in-memory; neither path reads schema_agent_metadata/ from disk.

func ProjectEffectiveRegistry added in v1.0.57 

func ProjectEffectiveRegistry(effective cli.EffectiveCommandRegistry) RegistryProjection

ProjectEffectiveRegistry builds the Generate projection from a public Effective registry. Keeping projection below the post-manual boundary prevents a base-registry allowlist from silently dropping reviewed manual-only commands.

type Stats 

type Stats struct {
	SourceFiles                   int
	Products                      int
	Tools                         int
	ToolIntents                   int
	Examples                      int
	RiskRules                     int
	InterfaceMetadata             *InterfaceMetadataAudit
	UnmatchedTools                int
	SourceProducts                []string
	SkillProductsOutsideSurface   []string
	SurfaceProductsWithoutRouting []string
	UnmatchedReferences           []UnmatchedReference
	// contains filtered or unexported fields
}

type ToolMetadata 

type ToolMetadata struct {
	AgentSummary       string                     `json:"agent_summary,omitempty"`
	AgentSummarySource string                     `json:"agent_summary_source,omitempty"`
	UseWhen            []string                   `json:"use_when,omitempty"`
	AvoidWhen          []string                   `json:"avoid_when,omitempty"`
	Prerequisites      []string                   `json:"prerequisites,omitempty"`
	Tips               []string                   `json:"tips,omitempty"`
	Effect             string                     `json:"effect,omitempty"`
	EffectSource       string                     `json:"effect_source,omitempty"`
	Risk               string                     `json:"risk,omitempty"`
	Confirmation       string                     `json:"confirmation,omitempty"`
	Idempotency        string                     `json:"idempotency,omitempty"`
	WorkflowRefs       []string                   `json:"workflow_refs,omitempty"`
	Examples           []string                   `json:"examples,omitempty"`
	Reviewed           *bool                      `json:"reviewed,omitempty"`
	SourceRefs         []string                   `json:"source_refs,omitempty"`
	InterfaceRef       *InterfaceRef              `json:"interface_ref,omitempty"`
	InterfaceMode      string                     `json:"interface_mode,omitempty"`
	Availability       string                     `json:"availability,omitempty"`
	InterfaceReason    string                     `json:"interface_reason,omitempty"`
	FieldProvenance    map[string]FieldProvenance `json:"field_provenance,omitempty"`
	// contains filtered or unexported fields
}

func (ToolMetadata) MarshalJSON 

func (metadata ToolMetadata) MarshalJSON() ([]byte, error)

MarshalJSON preserves explicit empty authored lists for the same reason as ProductMetadata.MarshalJSON. Unset lists remain omitted.

type UnmatchedReference 

type UnmatchedReference struct {
	ToolPath   string           `json:"tool_path"`
	Source     string           `json:"source,omitempty"`
	Line       int              `json:"line,omitempty"`
	Candidates []string         `json:"candidates,omitempty"`
	Review     *ReferenceReview `json:"review,omitempty"`
}

UnmatchedReference identifies one Skill command reference that cannot be resolved against the versioned command surface. It is emitted only in the build-time audit and is not embedded in the runtime Agent schema.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.