capability

Documentation

Overview

Package capability defines provider-neutral operation catalog metadata and structural validation. Providers own the catalog values and their semantics.

Index

• func EmbeddedOperationSchema(schema map[string]any) map[string]any
• func MCPToolSchema(descriptor Descriptor, options SurfaceOptions) map[string]any
• func MCPTools(options SurfaceOptions) []map[string]any
• func RequireSchemaPaths(schema map[string]any, paths []string)
• func RequiredPropertyNames(schema map[string]any) []string
• func ResolveSchemaPointer(root map[string]any, reference string) (map[string]any, bool)
• func SchemaBranches(value any) []map[string]any
• func SchemaPathRequirements(root, current map[string]any, path []string) ([]bool, bool)
• func SchemaRequiresProperty(schema map[string]any, name string) bool
• func SplitSealedArgumentsSchema(schema map[string]any, paths []string) (map[string]any, map[string]any)
• func Validate(values []Descriptor, options ValidationOptions) error
• type AuthorizationMode
• type DefaultPolicyEffect
• type Descriptor
  • func AgentFacing(descriptors []Descriptor) []Descriptor
  • func MatchCLICommand(descriptors []Descriptor, args []string) (Descriptor, int, bool)
• type ImplementationStatus
• type InputSchemas
• type Risk
• type SurfaceOptions
• type ValidationOptions

Functions

func EmbeddedOperationSchema

func EmbeddedOperationSchema(schema map[string]any) map[string]any

EmbeddedOperationSchema clones a schema and resolves local references for a standalone generated CLI or MCP surface.

func MCPToolSchema

func MCPToolSchema(descriptor Descriptor, options SurfaceOptions) map[string]any

MCPToolSchema generates the closed submission schema for one descriptor.

func MCPTools

func MCPTools(options SurfaceOptions) []map[string]any

MCPTools generates one typed MCP tool per agent-facing descriptor.

func RequireSchemaPaths

func RequireSchemaPaths(schema map[string]any, paths []string)

RequireSchemaPaths marks all properties along each path as required.

func RequiredPropertyNames

func RequiredPropertyNames(schema map[string]any) []string

RequiredPropertyNames returns a cloned string view of a decoded required list.

func ResolveSchemaPointer

func ResolveSchemaPointer(root map[string]any, reference string) (map[string]any, bool)

ResolveSchemaPointer resolves one local JSON Schema pointer.

func SchemaBranches

func SchemaBranches(value any) []map[string]any

SchemaBranches returns object branches from a combinator value.

func SchemaPathRequirements

func SchemaPathRequirements(root, current map[string]any, path []string) ([]bool, bool)

SchemaPathRequirements reports required-property state along one schema path.

func SchemaRequiresProperty

func SchemaRequiresProperty(schema map[string]any, name string) bool

SchemaRequiresProperty reports whether an object schema requires a property.

func SplitSealedArgumentsSchema

func SplitSealedArgumentsSchema(schema map[string]any, paths []string) (map[string]any, map[string]any)

SplitSealedArgumentsSchema separates write-only schema paths from public operation arguments while preserving their validation requirements.

func Validate

func Validate(values []Descriptor, options ValidationOptions) error

Validate rejects catalog drift that could weaken policy or expose an unsafe operation through broad families.

Types

type AuthorizationMode

type AuthorizationMode string

const (
	ModeWindow    AuthorizationMode = "window"
	ModeExecution AuthorizationMode = "execution"
)

type DefaultPolicyEffect

type DefaultPolicyEffect string

DefaultPolicyEffect is the provider-owned baseline for generated policy.

const (
	DefaultEffectAllow   DefaultPolicyEffect = "allow"
	DefaultEffectRequest DefaultPolicyEffect = "request"
	DefaultEffectDeny    DefaultPolicyEffect = "deny"
)

type Descriptor

type Descriptor struct {
	Name                 string               `json:"name"`
	OperationRevision    int                  `json:"operation_revision"`
	Summary              string               `json:"summary,omitempty"`
	Disposition          string               `json:"disposition"`
	AuthorizationMode    AuthorizationMode    `json:"authorization_mode"`
	ExplicitOnly         bool                 `json:"explicit_only"`
	Sealed               bool                 `json:"sealed"`
	CredentialOutputKind *string              `json:"credential_output_kind,omitempty"`
	Internal             bool                 `json:"internal"`
	Implementation       ImplementationStatus `json:"implementation_status"`
	Risk                 Risk                 `json:"risk"`
	DefaultPolicyEffect  DefaultPolicyEffect  `json:"default_policy_effect,omitempty"`
	TargetKind           string               `json:"target_kind"`
	MaxUses              int                  `json:"max_uses"`
	RequestTTLSeconds    int                  `json:"request_ttl_seconds"`
	ApprovalTTLSeconds   int                  `json:"approval_ttl_seconds"`
	FamilyGlobAllowed    bool                 `json:"family_glob_allowed"`
	AgentFacing          bool                 `json:"agent_facing"`
	MCPTool              *string              `json:"mcp_tool"`
	CLICommand           *string              `json:"cli_command"`
	TargetSchema         string               `json:"target_schema,omitempty"`
	ArgumentSchema       string               `json:"argument_schema,omitempty"`
	ResultSchema         string               `json:"result_schema,omitempty"`
	CredentialKind       string               `json:"credential_kind,omitempty"`
	SealedInputPaths     []string             `json:"sealed_input_paths,omitempty"`
	UpstreamBindingIDs   []string             `json:"upstream_binding_ids,omitempty"`
	ExecutorKind         string               `json:"executor_kind,omitempty"`
	ReconcilerKind       string               `json:"reconciler_kind,omitempty"`
}

Descriptor is provider-owned registration metadata. It contains no credentials or requester-controlled values.

func AgentFacing

func AgentFacing(descriptors []Descriptor) []Descriptor

AgentFacing returns the descriptors exposed to authenticated agent clients.

func MatchCLICommand

func MatchCLICommand(descriptors []Descriptor, args []string) (Descriptor, int, bool)

MatchCLICommand matches the longest provider-owned descriptor command at the start of args.

type ImplementationStatus

type ImplementationStatus string

const (
	StatusImplemented       ImplementationStatus = "implemented"
	StatusProtocol          ImplementationStatus = "protocol"
	StatusGraphQL           ImplementationStatus = "graphql"
	StatusInternal          ImplementationStatus = "internal"
	StatusOperatorOnly      ImplementationStatus = "operator-only"
	StatusLocal             ImplementationStatus = "local"
	StatusDuplicate         ImplementationStatus = "duplicate"
	StatusBlockedCredential ImplementationStatus = "blocked-credential"
	StatusBlockedUpstream   ImplementationStatus = "blocked-upstream"
	// StatusCataloged means the typed operation is frozen and generated, but its
	// credential provider and upstream executor have not been enabled yet.
	StatusCataloged ImplementationStatus = "cataloged"
)

type InputSchemas

type InputSchemas func(Descriptor) (map[string]any, map[string]any, map[string]any)

InputSchemas supplies provider-owned target, public argument, and sealed argument schemas to shared descriptor-driven surfaces.

type Risk

type Risk string

const (
	RiskLow      Risk = "low"
	RiskMedium   Risk = "medium"
	RiskHigh     Risk = "high"
	RiskCritical Risk = "critical"
)

type SurfaceOptions

type SurfaceOptions struct {
	Descriptors            []Descriptor
	Schemas                InputSchemas
	AttributeNames         []string
	ToolDescription        func(Descriptor) string
	CredentialSlotPattern  string
	WindowSubmitsOperation bool
}

SurfaceOptions configures descriptor-driven CLI and MCP generation without embedding provider vocabulary in the shared package.

type ValidationOptions

type ValidationOptions struct {
	Provider                   string
	ExpectedCount              int
	MCPToolPrefix              string
	RequireDefaultPolicyEffect bool
}

ValidationOptions contains provider registration constraints without embedding provider vocabulary in the shared package.