capability

package
v3.0.16 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const ResponseRedactedValue = "[REDACTED]"

ResponseRedactedValue is the only wire value used to replace sensitive response data.

View Source 
const RiskPlanSchemaVersion = "redevplugin.capability.risk_plan.v1"

Variables

View Source 
var (
	ErrInvalidRegistration     = errors.New("capability registration is invalid")
	ErrRegistrationMissing     = errors.New("capability registration is missing")
	ErrInvalidExecutionBinding = errors.New("capability execution binding is invalid")
	ErrExecutionRevoked        = errors.New("capability execution is revoked")
	ErrInvalidExecutionFailure = errors.New("capability execution failure is invalid")
	ErrQuotaExceeded           = errors.New("capability execution quota exceeded")
)
View Source 
var ErrInvalidRiskPlan = errors.New("invalid capability risk plan")

Functions

func NormalizeRiskPlanData 

func NormalizeRiskPlanData(data any) (any, error)

func PrepareResponseData 

func PrepareResponseData(data any) (any, error)

PrepareResponseData creates and redacts the bounded JSON value that may leave an adapter boundary.

func ValidateExecutionBinding 

func ValidateExecutionBinding(binding ExecutionBinding) error

ValidateExecutionBinding validates the closed cross-language execution snapshot without invoking JSON marshalers or changing container ownership.

Types

type Adapter 

type Adapter interface {
	Invoke(ctx context.Context, req Invocation) (Result, error)
}

type BusinessError 

type BusinessError struct {
	CapabilityID       string         `json:"capability_id,omitempty"`
	CapabilityVersion  string         `json:"capability_version,omitempty"`
	DetailSchemaSHA256 string         `json:"detail_schema_sha256,omitempty"`
	Code               string         `json:"code"`
	Message            string         `json:"message"`
	Details            map[string]any `json:"details,omitempty"`
}

func NewBusinessError 

func NewBusinessError(code, message string, details map[string]any) (*BusinessError, error)

NewBusinessError validates details against the closed canonical JSON set and retains a recursively cloned value. Callers may mutate their input after the function returns. Integers must be represented as safe json.Number or float64 values because native integer types are outside the cross-language execution contract.

func (*BusinessError) Error 

func (e *BusinessError) Error() string

type ConfirmationEvidence 

type ConfirmationEvidence struct {
	Required       bool   `json:"required"`
	Confirmed      bool   `json:"confirmed"`
	ConfirmationID string `json:"confirmation_id,omitempty"`
	RequestSHA256  string `json:"request_sha256,omitempty"`
	PlanSHA256     string `json:"plan_sha256,omitempty"`
	TargetSHA256   string `json:"target_sha256,omitempty"`
}

type Effect 

type Effect string
const (
	EffectRead    Effect = "read"
	EffectWrite   Effect = "write"
	EffectExecute Effect = "execute"
	EffectDelete  Effect = "delete"
	EffectAdmin   Effect = "admin"
)

type ExecutionBinding 

type ExecutionBinding struct {
	InvocationID            string                  `json:"invocation_id"`
	AuditCorrelationID      string                  `json:"audit_correlation_id"`
	ExecutionID             string                  `json:"execution_id,omitempty"`
	PublisherID             string                  `json:"publisher_id"`
	PluginID                string                  `json:"plugin_id"`
	PluginInstanceID        string                  `json:"plugin_instance_id"`
	PluginVersion           string                  `json:"plugin_version"`
	ActiveFingerprint       string                  `json:"active_fingerprint"`
	SurfaceInstanceID       string                  `json:"surface_instance_id,omitempty"`
	OwnerSessionHash        string                  `json:"owner_session_hash,omitempty"`
	OwnerUserHash           string                  `json:"owner_user_hash,omitempty"`
	OwnerEnvHash            string                  `json:"owner_env_hash,omitempty"`
	SessionChannelIDHash    string                  `json:"session_channel_id_hash,omitempty"`
	BridgeChannelID         string                  `json:"bridge_channel_id,omitempty"`
	RouteKind               RouteKind               `json:"route_kind"`
	CapabilityID            string                  `json:"capability_id"`
	CapabilityVersion       string                  `json:"capability_version"`
	BindingID               string                  `json:"binding_id"`
	Contract                *capabilitycontract.Pin `json:"contract,omitempty"`
	Method                  string                  `json:"method"`
	TargetMethod            string                  `json:"target_method"`
	Effect                  Effect                  `json:"effect"`
	Execution               string                  `json:"execution"`
	Permissions             PermissionEvidence      `json:"permissions"`
	Confirmation            ConfirmationEvidence    `json:"confirmation"`
	Revision                RevisionEvidence        `json:"revision"`
	Quota                   QuotaGrant              `json:"quota"`
	Target                  TargetDescriptor        `json:"target"`
	TargetDescriptorSHA256  string                  `json:"target_descriptor_sha256"`
	StreamEventTypeName     string                  `json:"stream_event_type_name,omitempty"`
	StreamEventSchemaSHA256 string                  `json:"stream_event_schema_sha256,omitempty"`
}

func CloneExecutionBinding 

func CloneExecutionBinding(binding ExecutionBinding) (ExecutionBinding, error)

CloneExecutionBinding returns an independently owned execution snapshot.

func (ExecutionBinding) Identity 

func (b ExecutionBinding) Identity() PluginIdentity

func (ExecutionBinding) OwnerScope 

func (b ExecutionBinding) OwnerScope() ExecutionOwnerScope

func (ExecutionBinding) Surface 

func (b ExecutionBinding) Surface() SurfaceScope

type ExecutionCanceler 

type ExecutionCanceler interface {
	CancelExecution(ctx context.Context, req ExecutionCancellation) error
}

type ExecutionCancellation 

type ExecutionCancellation struct {
	Execution   ExecutionContext `json:"execution"`
	ExecutionID string           `json:"execution_id"`
	Reason      string           `json:"reason,omitempty"`
	RequestedAt time.Time        `json:"requested_at"`
}

type ExecutionContext 

type ExecutionContext struct {
	ExecutionBinding
	Events ExecutionSink `json:"-"`
}

type ExecutionFailureCode 

type ExecutionFailureCode string
const (
	ExecutionFailureAdapterFailed   ExecutionFailureCode = "adapter_failed"
	ExecutionFailureContractInvalid ExecutionFailureCode = "contract_invalid"
	ExecutionFailurePlatformFailed  ExecutionFailureCode = "platform_failed"
	ExecutionFailureQuotaExceeded   ExecutionFailureCode = "quota_exceeded"
	ExecutionFailureRuntimeFailed   ExecutionFailureCode = "runtime_failed"

	ExecutionFailureMessage = "execution failed"
)

func (ExecutionFailureCode) Valid 

func (c ExecutionFailureCode) Valid() bool

type ExecutionOwnerScope 

type ExecutionOwnerScope struct {
	OwnerSessionHash     string
	OwnerUserHash        string
	OwnerEnvHash         string
	SessionChannelIDHash string
}

ExecutionOwnerScope is the exact short-lived session boundary for an operation or stream. Persistent resource ownership uses sessionctx.ResourceScope.

func (ExecutionOwnerScope) Normalized 

func (s ExecutionOwnerScope) Normalized() ExecutionOwnerScope

func (ExecutionOwnerScope) Valid 

func (s ExecutionOwnerScope) Valid() bool

type ExecutionSink 

type ExecutionSink interface {
	ID() string
	ReportProgress(ctx context.Context, progress OperationProgress) error
	Append(ctx context.Context, event any) error
	Complete(ctx context.Context) error
	Close(ctx context.Context) error
	Cancel(ctx context.Context, reason string) error
	Fail(ctx context.Context, code ExecutionFailureCode, cause error) error
	CancelRequested() <-chan struct{}
}

type Invocation 

type Invocation struct {
	Execution ExecutionContext `json:"execution"`
	Arguments map[string]any   `json:"arguments,omitempty"`
}

type OperationProgress 

type OperationProgress struct {
	Revision       uint64  `json:"revision"`
	Phase          string  `json:"phase"`
	CompletedUnits *uint64 `json:"completed_units,omitempty"`
	TotalUnits     *uint64 `json:"total_units,omitempty"`
	Unit           string  `json:"unit,omitempty"`
}

OperationProgress is a host-neutral progress snapshot. Phase identifiers are plugin-defined and must be localized by the plugin; the platform never persists host-authored display text.

type PermissionEvidence 

type PermissionEvidence struct {
	Required []string `json:"required"`
	Granted  []string `json:"granted"`
}

type PluginIdentity 

type PluginIdentity struct {
	PublisherID       string `json:"publisher_id"`
	PluginID          string `json:"plugin_id"`
	PluginInstanceID  string `json:"plugin_instance_id"`
	PluginVersion     string `json:"plugin_version"`
	ActiveFingerprint string `json:"active_fingerprint"`
}

type QuotaGrant 

type QuotaGrant struct {
	MaxConcurrent  int       `json:"max_concurrent,omitempty"`
	MaxDurationMS  int       `json:"max_duration_ms,omitempty"`
	MaxStreamBytes int64     `json:"max_stream_bytes,omitempty"`
	ExpiresAt      time.Time `json:"expires_at,omitempty"`
}

type Registration 

type Registration struct {
	Contract        capabilitycontract.KnownContract
	TargetProjector TargetProjector
	Adapter         Adapter
}

type Registry 

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

func NewRegistry 

func NewRegistry() *Registry

func (*Registry) AddContract 

func (r *Registry) AddContract(contract capabilitycontract.KnownContract) error

func (*Registry) Register 

func (r *Registry) Register(registration Registration) error

func (*Registry) RequireContract 

func (r *Registry) RequireContract(pin capabilitycontract.Pin) (capabilitycontract.KnownContract, error)

func (*Registry) Resolve 

func (r *Registry) Resolve(pin capabilitycontract.Pin) (Registration, error)

type Result 

type Result struct {
	Data any `json:"data,omitempty"`
}

type RevisionEvidence 

type RevisionEvidence struct {
	PolicyRevision     uint64 `json:"policy_revision"`
	ManagementRevision uint64 `json:"management_revision"`
	RevokeEpoch        uint64 `json:"revoke_epoch"`
}

type RiskFlag 

type RiskFlag struct {
	ID                   string       `json:"id"`
	Severity             RiskSeverity `json:"severity"`
	Summary              string       `json:"summary"`
	Description          string       `json:"description,omitempty"`
	RequiresConfirmation bool         `json:"requires_confirmation,omitempty"`
	RequiresAdmin        bool         `json:"requires_admin,omitempty"`
	DataLossRisk         bool         `json:"data_loss_risk,omitempty"`
	Destructive          bool         `json:"destructive,omitempty"`
}

type RiskPlan 

type RiskPlan struct {
	SchemaVersion        string         `json:"schema_version"`
	CapabilityID         string         `json:"capability_id,omitempty"`
	BindingID            string         `json:"binding_id,omitempty"`
	Method               string         `json:"method,omitempty"`
	TargetMethod         string         `json:"target_method,omitempty"`
	Action               string         `json:"action,omitempty"`
	Effect               Effect         `json:"effect,omitempty"`
	ResourceRef          string         `json:"resource_ref,omitempty"`
	ResourceDisplayName  string         `json:"resource_display_name,omitempty"`
	Summary              string         `json:"summary"`
	RiskFlags            []RiskFlag     `json:"risk_flags"`
	RequiresConfirmation bool           `json:"requires_confirmation,omitempty"`
	RequiresAdmin        bool           `json:"requires_admin,omitempty"`
	DataLossRisk         bool           `json:"data_loss_risk,omitempty"`
	Destructive          bool           `json:"destructive,omitempty"`
	DenyReason           string         `json:"deny_reason,omitempty"`
	Details              map[string]any `json:"details,omitempty"`
}

func NewRiskPlan 

func NewRiskPlan(inv Invocation, summary string) RiskPlan

func NormalizeRiskPlan 

func NormalizeRiskPlan(plan RiskPlan) (RiskPlan, error)

type RiskSeverity 

type RiskSeverity string
const (
	RiskSeverityInfo     RiskSeverity = "info"
	RiskSeverityLow      RiskSeverity = "low"
	RiskSeverityMedium   RiskSeverity = "medium"
	RiskSeverityHigh     RiskSeverity = "high"
	RiskSeverityCritical RiskSeverity = "critical"
)

type RouteKind 

type RouteKind string
const (
	RouteCapability RouteKind = "capability"
	RouteWorker     RouteKind = "worker"
	RouteCoreAction RouteKind = "core_action"
)

type StreamContract 

type StreamContract struct {
	EventTypeName string
	EventSchema   map[string]any
}

type SurfaceScope 

type SurfaceScope struct {
	SurfaceInstanceID    string `json:"surface_instance_id,omitempty"`
	OwnerSessionHash     string `json:"owner_session_hash,omitempty"`
	OwnerUserHash        string `json:"owner_user_hash,omitempty"`
	OwnerEnvHash         string `json:"owner_env_hash,omitempty"`
	SessionChannelIDHash string `json:"session_channel_id_hash,omitempty"`
	BridgeChannelID      string `json:"bridge_channel_id,omitempty"`
}

type TargetDescriptor 

type TargetDescriptor struct {
	Kind   string         `json:"kind"`
	Fields map[string]any `json:"fields"`
}

func CloneTargetDescriptor 

func CloneTargetDescriptor(target TargetDescriptor) (TargetDescriptor, error)

CloneTargetDescriptor validates and recursively clones target fields.

type TargetProjector 

type TargetProjector interface {
	ProjectTarget(ctx context.Context, req TargetResolutionRequest) (TargetDescriptor, error)
}

type TargetResolutionRequest 

type TargetResolutionRequest struct {
	Identity          PluginIdentity         `json:"identity"`
	Surface           SurfaceScope           `json:"surface"`
	CapabilityID      string                 `json:"capability_id"`
	CapabilityVersion string                 `json:"capability_version"`
	BindingID         string                 `json:"binding_id"`
	Contract          capabilitycontract.Pin `json:"contract"`
	Method            string                 `json:"method"`
	TargetMethod      string                 `json:"target_method"`
	TargetInput       map[string]any         `json:"target_input"`
}

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.