agentmetadata

package
v1.0.54 Latest Latest
Warning

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

 Go to latest Published: Jul 21, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const CurrentVersion = 1
View Source 
const HintFileVersion = 1
View Source 
const HintIndexFormat = "dws-agent-hint-index"

Variables

This section is empty.

Functions

func Generate 

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

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"`
	HintFiles                     int                     `json:"hint_files,omitempty"`
	HintProducts                  int                     `json:"hint_products,omitempty"`
	HintTools                     int                     `json:"hint_tools,omitempty"`
	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 HintCoverage 

type HintCoverage struct {
	SourceProducts  int `json:"source_products,omitempty"`
	MatchedProducts int `json:"matched_products,omitempty"`
	SourceTools     int `json:"source_tools,omitempty"`
	EligibleTools   int `json:"eligible_tools,omitempty"`
	MatchedTools    int `json:"matched_tools,omitempty"`
	UnmatchedTools  int `json:"unmatched_tools,omitempty"`
}

type HintFile 

type HintFile struct {
	Version         int                        `json:"version"`
	Source          HintSource                 `json:"source"`
	Coverage        HintCoverage               `json:"coverage,omitempty"`
	Products        map[string]HintProduct     `json:"products,omitempty"`
	Tools           map[string]HintTool        `json:"tools,omitempty"`
	ReferenceReview map[string]ReferenceReview `json:"reference_review,omitempty"`
}

HintFile is a versioned source contract. Imported files provide a reviewed baseline; explicit files can override scalar fields while Skills continue to supply routing and workflow context.

type HintIndex 

type HintIndex struct {
	Version         int                        `json:"version"`
	Format          string                     `json:"format"`
	Source          HintSource                 `json:"source"`
	Coverage        HintCoverage               `json:"coverage,omitempty"`
	Metadata        map[string]string          `json:"metadata"`
	Selection       map[string]string          `json:"selection"`
	ReferenceReview map[string]ReferenceReview `json:"reference_review,omitempty"`
}

HintIndex is the human-authored entrypoint. It maps product IDs to metadata (safety/interface/parameters/runtime_gate) and selection (Agent routing prose) HintFile paths. Index-level runtime_gates were removed; gates live on each metadata tool as runtime_gate.

type HintProduct 

type HintProduct struct {
	AgentSummary string   `json:"agent_summary,omitempty"`
	UseWhen      []string `json:"use_when,omitempty"`
	AvoidWhen    []string `json:"avoid_when,omitempty"`
	SourceRefs   []string `json:"source_refs,omitempty"`
	// contains filtered or unexported fields
}

func (*HintProduct) UnmarshalJSON 

func (hint *HintProduct) UnmarshalJSON(data []byte) error

type HintSource 

type HintSource struct {
	Kind       string `json:"kind"`
	Name       string `json:"name"`
	Reviewed   bool   `json:"reviewed,omitempty"`
	Repository string `json:"repository,omitempty"`
	Revision   string `json:"revision,omitempty"`
	Channel    string `json:"channel,omitempty"`
	SourceHash string `json:"source_hash,omitempty"`
}

type HintTool 

type HintTool struct {
	AgentSummary    string                     `json:"agent_summary,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"`
	Risk            string                     `json:"risk,omitempty"`
	Confirmation    string                     `json:"confirmation,omitempty"`
	Idempotency     string                     `json:"idempotency,omitempty"`
	RuntimeGate     string                     `json:"runtime_gate,omitempty"`
	CLIPath         string                     `json:"cli_path,omitempty"`
	Parameters      map[string]json.RawMessage `json:"parameters,omitempty"`
	WorkflowRefs    []string                   `json:"workflow_refs,omitempty"`
	Examples        []string                   `json:"examples,omitempty"`
	Reviewed        *bool                      `json:"reviewed,omitempty"`
	ReviewReason    string                     `json:"review_reason,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"`
	// contains filtered or unexported fields
}

func (*HintTool) UnmarshalJSON 

func (hint *HintTool) UnmarshalJSON(data []byte) error

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                 string
	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 the fixed disposition of a Skill command reference that is not a current public leaf. It prevents fuzzy matching from silently binding stale prose or command groups to an unrelated tool.

type Stats 

type Stats struct {
	SourceFiles                   int
	Products                      int
	Tools                         int
	ToolIntents                   int
	Examples                      int
	RiskRules                     int
	HintFiles                     int
	HintProducts                  int
	HintTools                     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.