skills

Documentation

Overview

Package skill defines the Skill interface and SkillRegistry for OpenBotStack.

A Skill is a governed, declarative unit of capability. Unlike tools (low-level operations like HTTP calls or DB queries), Skills are governed compositions with explicit inputs, outputs, permissions, and constraints.

Skills are stateless descriptors. They do NOT execute anything. Execution is delegated to openbotstack-runtime.

Index

• Variables
• type HTTPRequest
• type HTTPResponse
• type HostAPI
  • func NewHostAPI() *HostAPI
  • func (h *HostAPI) HTTPFetch(ctx context.Context, req HTTPRequest) (*HTTPResponse, error)
  • func (h *HostAPI) KVDelete(ctx context.Context, key string) error
  • func (h *HostAPI) KVGet(ctx context.Context, key string) ([]byte, error)
  • func (h *HostAPI) KVSet(ctx context.Context, key string, value []byte) error
• type InMemoryRegistry
  • func NewInMemoryRegistry() *InMemoryRegistry
  • func (r *InMemoryRegistry) Get(id string) (Skill, error)
  • func (r *InMemoryRegistry) List() []string
  • func (r *InMemoryRegistry) ListByPermission(permissions []string) []Skill
  • func (r *InMemoryRegistry) Register(skill Skill) error
  • func (r *InMemoryRegistry) Validate() error
• type ResourceLimits
• type Skill
• type SkillManifest
  • func ParseManifest(data []byte) (*SkillManifest, error)
  • func (m *SkillManifest) Validate() error
• type SkillRegistry
• type WasmInput
• type WasmLoader
  • func NewWasmLoader() *WasmLoader
  • func (l *WasmLoader) Load(ctx context.Context, wasmBytes []byte) (WasmModule, error)
  • func (l *WasmLoader) LoadFromPath(ctx context.Context, path string) (WasmModule, error)
• type WasmModule
• type WasmOutput

Variables

var (
	// ErrSkillNotFound is returned when a skill ID is not registered.
	ErrSkillNotFound = errors.New("skill: not found")

	// ErrSkillAlreadyExists is returned when registering a duplicate skill ID.
	ErrSkillAlreadyExists = errors.New("skill: already exists")

	// ErrSkillInvalid is returned when a skill fails validation.
	ErrSkillInvalid = errors.New("skill: invalid")
)

var (
	// ErrKeyNotFound is returned when a KV key doesn't exist.
	ErrKeyNotFound = errors.New("skill: key not found")

	// ErrInvalidURL is returned when URL is empty or invalid.
	ErrInvalidURL = errors.New("skill: invalid URL")
)

var (
	// ErrWasmLoadFailed is returned when Wasm loading fails.
	ErrWasmLoadFailed = errors.New("skill: wasm load failed")

	// ErrWasmExecuteFailed is returned when Wasm execution fails.
	ErrWasmExecuteFailed = errors.New("skill: wasm execute failed")
)

Types

type HTTPRequest

type HTTPRequest struct {
	Method  string
	URL     string
	Headers map[string]string
	Body    []byte
}

HTTPRequest represents an HTTP request.

type HTTPResponse

type HTTPResponse struct {
	StatusCode int
	Headers    map[string]string
	Body       []byte
}

HTTPResponse contains the HTTP response.

type HostAPI

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

HostAPI provides the host APIs available to Wasm skills.

func NewHostAPI

func NewHostAPI() *HostAPI

NewHostAPI creates a new host API instance.

func (*HostAPI) HTTPFetch

func (h *HostAPI) HTTPFetch(ctx context.Context, req HTTPRequest) (*HTTPResponse, error)

HTTPFetch performs an HTTP request.

func (*HostAPI) KVDelete

func (h *HostAPI) KVDelete(ctx context.Context, key string) error

KVDelete removes a key.

func (*HostAPI) KVGet

func (h *HostAPI) KVGet(ctx context.Context, key string) ([]byte, error)

func (*HostAPI) KVSet

func (h *HostAPI) KVSet(ctx context.Context, key string, value []byte) error

KVSet stores a value by key.

type InMemoryRegistry

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

InMemoryRegistry is an in-memory implementation of SkillRegistry. It is safe for concurrent use.

func NewInMemoryRegistry

func NewInMemoryRegistry() *InMemoryRegistry

NewInMemoryRegistry creates a new empty InMemoryRegistry.

func (*InMemoryRegistry) Get

func (r *InMemoryRegistry) Get(id string) (Skill, error)

Get retrieves a skill by ID.

func (*InMemoryRegistry) List

func (r *InMemoryRegistry) List() []string

List returns all registered skill IDs.

func (*InMemoryRegistry) ListByPermission

func (r *InMemoryRegistry) ListByPermission(permissions []string) []Skill

ListByPermission returns skills the caller is allowed to use. A skill is included if the provided permissions set contains ALL of its RequiredPermissions.

func (*InMemoryRegistry) Register

func (r *InMemoryRegistry) Register(skill Skill) error

Register adds a skill to the registry.

func (*InMemoryRegistry) Validate

func (r *InMemoryRegistry) Validate() error

Validate checks all registered skills for consistency.

type ResourceLimits

type ResourceLimits struct {
	MaxMemoryMB int64 `yaml:"max_memory_mb,omitempty"`
	MaxCPUMs    int64 `yaml:"max_cpu_ms,omitempty"`
}

ResourceLimits defines execution resource constraints.

type Skill

type Skill interface {
	// ID returns the unique, stable identifier for this skills.
	// Format: "namespace/name" (e.g., "core/search", "custom/invoice-generator")
	ID() string

	// Name returns a human-readable display name.
	Name() string

	// Description returns a concise explanation of what this skill does.
	// This is used by the LLM for skill selection.
	Description() string

	// InputSchema returns the JSON Schema defining expected inputs.
	// Returns nil if the skill takes no inputs.
	InputSchema() *skills.JSONSchema

	// OutputSchema returns the JSON Schema defining expected outputs.
	// Returns nil if the skill produces no structured output.
	OutputSchema() *skills.JSONSchema

	// RequiredPermissions returns the permission strings this skill requires.
	// Empty slice means no special permissions required.
	RequiredPermissions() []string

	// Timeout returns the maximum allowed execution duration.
	Timeout() time.Duration

	// Validate checks if the skill definition is internally consistent.
	Validate() error
}

Skill defines a governed, declarative unit of capability.

A Skill is NOT a tool. Whereas tools are low-level operations (HTTP call, DB query), Skills are governed compositions of tools with explicit inputs, outputs, permissions, and constraints.

Skills are stateless descriptors. They do NOT execute anything. Execution is delegated to openbotstack-runtime.

type SkillManifest

type SkillManifest struct {
	ID          string         `yaml:"id"`
	Version     string         `yaml:"version"`
	Name        string         `yaml:"name,omitempty"`
	Description string         `yaml:"description,omitempty"`
	Requires    []string       `yaml:"requires,omitempty"`
	Permissions []string       `yaml:"permissions,omitempty"`
	Timeout     time.Duration  `yaml:"timeout,omitempty"`
	Resources   ResourceLimits `yaml:"resources,omitempty"`
}

SkillManifest defines a skill's metadata and requirements.

func ParseManifest

func ParseManifest(data []byte) (*SkillManifest, error)

ParseManifest parses a YAML manifest into a SkillManifest.

func (*SkillManifest) Validate

func (m *SkillManifest) Validate() error

Validate checks if the manifest is valid.

type SkillRegistry

type SkillRegistry interface {
	// Register adds a skill to the registry.
	// Returns error if skill with same ID already exists.
	// Thread-safe for concurrent reads after initial registration.
	Register(skill Skill) error

	// Get retrieves a skill by ID.
	// Returns (nil, ErrSkillNotFound) if not registered.
	Get(id string) (Skill, error)

	// List returns all registered skill IDs.
	// This is used for LLM context building.
	List() []string

	// ListByPermission returns skills the caller is allowed to use.
	// Filters based on provided permission set.
	ListByPermission(permissions []string) []Skill

	// Validate checks all registered skills for consistency.
	Validate() error
}

SkillRegistry manages the catalog of available skills.

The registry is a read-only view during request processing. Registration happens at startup or through admin operations, NEVER during agent execution.

type WasmInput

type WasmInput struct {
	Function string
	Args     map[string]interface{}
}

WasmInput represents input for Wasm execution.

type WasmLoader

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

WasmLoader loads Wasm modules from bytes or files.

func NewWasmLoader

func NewWasmLoader() *WasmLoader

NewWasmLoader creates a new Wasm loader.

func (*WasmLoader) Load

func (l *WasmLoader) Load(ctx context.Context, wasmBytes []byte) (WasmModule, error)

Load loads a Wasm module from bytes.

func (*WasmLoader) LoadFromPath

func (l *WasmLoader) LoadFromPath(ctx context.Context, path string) (WasmModule, error)

LoadFromPath loads a Wasm module from a file path.

type WasmModule

type WasmModule interface {
	// Execute runs a function in the Wasm module.
	Execute(ctx context.Context, input WasmInput) (*WasmOutput, error)

	// Close releases resources.
	Close() error

	// MemoryLimit returns the memory limit in bytes.
	MemoryLimit() int64
}

WasmModule represents a loaded Wasm skill module.

type WasmOutput

type WasmOutput struct {
	Result interface{}
	Logs   []string
}

WasmOutput represents output from Wasm execution.