fragments

Documentation

Overview

Package fragments provides a template system for reusable prompt fragments and recipes. It supports variable substitution, bash command execution, and markdown-based template processing for automating routine tasks.

Index

• func LoadCompactPrompt(ctx context.Context) (string, error)
• type ArgumentMeta
• type Config
• type Fragment
• type HookConfig
• type Metadata
• type Option
  • func WithAdditionalDirs(dirs ...string) Option
  • func WithDefaultDirs() Option
  • func WithFragmentDirs(dirs ...string) Option
• type Processor
  • func NewFragmentProcessor(opts ...Option) (*Processor, error)
  • func (fp *Processor) GetFragmentMetadata(fragmentName string) (*Fragment, error)
  • func (fp *Processor) ListFragmentsWithMetadata() ([]*Fragment, error)
  • func (fp *Processor) LoadFragment(ctx context.Context, config *Config) (*Fragment, error)

Functions

func LoadCompactPrompt

func LoadCompactPrompt(ctx context.Context) (string, error)

LoadCompactPrompt loads the compact recipe and returns just the prompt content. This allows CompactContext() to reuse the same prompt as manual compaction.

Types

type ArgumentMeta

type ArgumentMeta struct {
	Description string `yaml:"description,omitempty"`
	Default     string `yaml:"default,omitempty"`
}

ArgumentMeta defines metadata for a fragment argument

type Config

type Config struct {
	FragmentName string
	Arguments    map[string]string
}

Config holds configuration for fragment processing

type Fragment

type Fragment struct {
	ID       string
	Metadata Metadata
	Content  string
	Path     string
}

Fragment represents a fragment with its metadata and content

type HookConfig

type HookConfig struct {
	Handler string `yaml:"handler"`        // Built-in handler name (e.g., "swap_context")
	Once    bool   `yaml:"once,omitempty"` // If true, only execute on the first turn
}

HookConfig defines configuration for a recipe hook

type Metadata

type Metadata struct {
	Name            string                  `yaml:"name,omitempty"`
	Description     string                  `yaml:"description,omitempty"`
	AllowedTools    []string                `yaml:"allowed_tools,omitempty"`
	AllowedCommands []string                `yaml:"allowed_commands,omitempty"`
	Arguments       map[string]ArgumentMeta `yaml:"arguments,omitempty"` // Argument definitions with descriptions
	Hooks           map[string]HookConfig   `yaml:"hooks,omitempty"`     // Lifecycle hooks -> handler config
	Workflow        bool                    `yaml:"workflow,omitempty"`  // If true, this fragment can be used as a subagent workflow
	Profile         string                  `yaml:"profile,omitempty"`   // Profile name to use for workflow execution
}

Metadata represents YAML frontmatter in fragment files

type Option

type Option func(*Processor) error

Option is a function that configures a FragmentProcessor

func WithAdditionalDirs

func WithAdditionalDirs(dirs ...string) Option

WithAdditionalDirs adds additional fragment directories to the current ones If no directories are currently set, it starts with defaults first If dirs is empty, this is a no-op

func WithDefaultDirs

func WithDefaultDirs() Option

WithDefaultDirs resets to default fragment directories

func WithFragmentDirs

func WithFragmentDirs(dirs ...string) Option

WithFragmentDirs sets custom fragment directories

type Processor

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

Processor handles fragment loading and rendering

func NewFragmentProcessor

func NewFragmentProcessor(opts ...Option) (*Processor, error)

NewFragmentProcessor creates a new fragment processor with optional configuration

func (*Processor) GetFragmentMetadata

func (fp *Processor) GetFragmentMetadata(fragmentName string) (*Fragment, error)

GetFragmentMetadata retrieves a fragment's metadata and raw content without processing templates or executing bash commands. This is useful for listing and inspecting fragments without side effects.

func (*Processor) ListFragmentsWithMetadata

func (fp *Processor) ListFragmentsWithMetadata() ([]*Fragment, error)

ListFragmentsWithMetadata returns all available fragments from configured directories and built-in recipes, including their parsed metadata and content. Fragments are deduplicated with precedence given to user directories over built-ins.

func (*Processor) LoadFragment

func (fp *Processor) LoadFragment(ctx context.Context, config *Config) (*Fragment, error)

LoadFragment loads and processes a fragment template by name, applying variable substitution and executing any embedded bash commands. It returns the parsed fragment with its metadata and rendered content.