harness

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 10, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrInvalidOptions       = errors.New("invalid harness resolver options")
	ErrInvalidPath          = errors.New("invalid harness path")
	ErrNotDirectory         = errors.New("harness path is not a directory")
	ErrUnreadableLayer      = errors.New("unreadable harness layer")
	ErrInvalidInstruction   = errors.New("invalid agent instructions")
	ErrInvalidSkill         = errors.New("invalid agent skill")
	ErrInvalidAgent         = errors.New("invalid named agent")
	ErrInvalidEventHandler  = errors.New("invalid event handler")
	ErrInvalidHook          = errors.New("invalid hook configuration")
	ErrResourceLimit        = errors.New("harness resource limit exceeded")
	ErrSkillNotFound        = errors.New("skill not found")
	ErrAgentNotFound        = errors.New("agent not found")
	ErrEventHandlerNotFound = errors.New("event handler not found")

	// ErrUnsupportedHomeReference reports a "~user" path segment. Only the
	// running user's own home directory can be expanded.
	ErrUnsupportedHomeReference = errors.New(
		"named user home directory is not supported",
	)
)

Functions

This section is empty.

Types

type ActivatedSkill

type ActivatedSkill struct {
	Skill
	Content string
}

ActivatedSkill is the full content returned by the use_skill tool.

type Agent

type Agent struct {
	Name         string
	Description  string
	Source       string
	Instructions string
	AllowedTools []string
	Hash         string
}

Agent is one named child or root agent definition.

type EventHandler

type EventHandler struct {
	Type         string
	Agent        string
	Delivery     string
	Source       string
	Instructions string
	Hash         string
}

EventHandler is one layered instruction for a specific session event type.

type Hook

type Hook struct {
	Name        string       `json:"name"`
	Event       HookEvent    `json:"event"`
	Match       HookMatch    `json:"match,omitzero"`
	Actions     []HookAction `json:"actions"`
	Source      string       `json:"source"`
	Priority    int          `json:"priority"`
	ConfigLayer bool         `json:"configLayer"`
	Hash        string       `json:"hash"`
}

Hook is one ordered matcher group from a layered hooks.yaml document. ConfigLayer is true only for PEEN_CONFIG_DIR's hook document.

type HookAction

type HookAction struct {
	Name        string            `yaml:"name" json:"name,omitempty"`
	Type        HookActionType    `yaml:"type" json:"type"`
	When        HookMatch         `yaml:"when" json:"when,omitzero"`
	Command     string            `yaml:"command" json:"command,omitempty"`
	Args        []string          `yaml:"args" json:"args,omitempty"`
	Environment map[string]string `yaml:"environment" json:"environment,omitempty"` //nolint:lll // Immutable schema tags.
	//nolint:tagliatelle // YAML uses the public snake_case schema.
	WorkingDir string `yaml:"working_dir" json:"workingDir,omitempty"`
	//nolint:tagliatelle,lll // YAML uses the public snake_case schema.
	TimeoutSeconds int    `yaml:"timeout_seconds" json:"timeoutSeconds,omitempty"`
	Message        string `yaml:"message" json:"message,omitempty"`
	//nolint:tagliatelle // YAML uses the public snake_case schema.
	EventType string         `yaml:"event_type" json:"eventType,omitempty"`
	Summary   string         `yaml:"summary" json:"summary,omitempty"`
	Data      map[string]any `yaml:"data" json:"data,omitempty"`
	Delivery  string         `yaml:"delivery" json:"delivery,omitempty"`
	Reason    string         `yaml:"reason" json:"reason,omitempty"`
	//nolint:tagliatelle // YAML uses the public snake_case schema.
	OnFailure HookFailureMode `yaml:"on_failure" json:"onFailure,omitempty"`
}

HookAction is one ordered operation in a hook group. Command is an executable path or name, never shell source; Args are passed verbatim.

type HookActionType

type HookActionType string

HookActionType selects the work one hook action performs.

const (
	HookActionCommand   HookActionType = "command"
	HookActionInject    HookActionType = "inject"
	HookActionEmitEvent HookActionType = "emit_event"
	HookActionDeny      HookActionType = "deny"
)

type HookEvent

type HookEvent string

HookEvent identifies a lifecycle point configured in .agents/hooks.yaml.

const (
	HookEventPreUserMessage  HookEvent = "pre_user_message"
	HookEventPostUserMessage HookEvent = "post_user_message"
	HookEventSessionStart    HookEvent = "session_start"
	HookEventTurnStart       HookEvent = "turn_start"
	HookEventTurnStop        HookEvent = "turn_stop"
	HookEventTurnCancelled   HookEvent = "turn_cancelled"
	HookEventPreCompact      HookEvent = "pre_compact"
	HookEventPostCompact     HookEvent = "post_compact"
	HookEventPreToolUse      HookEvent = "pre_tool_use"
	HookEventPostToolUse     HookEvent = "post_tool_use"
	HookEventToolUseFailure  HookEvent = "tool_use_failure"

	HookEventPreReadFile          HookEvent = "pre_read_file"
	HookEventPostReadFile         HookEvent = "post_read_file"
	HookEventReadFileFailure      HookEvent = "read_file_failure"
	HookEventPreListFiles         HookEvent = "pre_list_files"
	HookEventPostListFiles        HookEvent = "post_list_files"
	HookEventListFilesFailure     HookEvent = "list_files_failure"
	HookEventPreSearchText        HookEvent = "pre_search_text"
	HookEventPostSearchText       HookEvent = "post_search_text"
	HookEventSearchTextFailure    HookEvent = "search_text_failure"
	HookEventPreWriteFile         HookEvent = "pre_write_file"
	HookEventPostWriteFile        HookEvent = "post_write_file"
	HookEventWriteFileFailure     HookEvent = "write_file_failure"
	HookEventPreEditFile          HookEvent = "pre_edit_file"
	HookEventPostEditFile         HookEvent = "post_edit_file"
	HookEventEditFileFailure      HookEvent = "edit_file_failure"
	HookEventPreApplyPatch        HookEvent = "pre_apply_patch"
	HookEventPostApplyPatch       HookEvent = "post_apply_patch"
	HookEventApplyPatchFailed     HookEvent = "apply_patch_failure"
	HookEventPreMovePath          HookEvent = "pre_move_path"
	HookEventPostMovePath         HookEvent = "post_move_path"
	HookEventMovePathFailure      HookEvent = "move_path_failure"
	HookEventPreRemovePath        HookEvent = "pre_remove_path"
	HookEventPostRemovePath       HookEvent = "post_remove_path"
	HookEventRemovePathFailed     HookEvent = "remove_path_failure"
	HookEventPreMakeDirectory     HookEvent = "pre_make_directory"
	HookEventPostMakeDirectory    HookEvent = "post_make_directory"
	HookEventMakeDirectoryFailure HookEvent = "make_directory_failure"
)

type HookFailureMode

type HookFailureMode string

HookFailureMode controls what a failed action does. The zero value leaves the phase-specific runtime default in effect.

const (
	HookFailureDeny     HookFailureMode = "deny"
	HookFailureContinue HookFailureMode = "continue"
)

type HookInputMatch

type HookInputMatch struct {
	Exists *bool  `yaml:"exists" json:"exists,omitempty"`
	Equals any    `yaml:"equals" json:"equals,omitempty"`
	Regex  string `yaml:"regex" json:"regex,omitempty"`
}

HookInputMatch matches one JSON Pointer in a tool or lifecycle payload. Equals keeps the YAML value's type, so true and "true" never compare equal.

type HookMatch

type HookMatch struct {
	Tool       string                    `yaml:"tool" json:"tool,omitempty"`
	Path       string                    `yaml:"path" json:"path,omitempty"`
	Extensions []string                  `yaml:"extensions" json:"extensions,omitempty"` //nolint:lll // Immutable schema tags.
	Root       string                    `yaml:"root" json:"root,omitempty"`
	Input      map[string]HookInputMatch `yaml:"input" json:"input,omitempty"`
}

HookMatch selects hook actions by their structured invocation context. Every populated field is required to match.

type Instruction

type Instruction struct {
	Source   string
	Priority int
	Content  string
	Hash     string
}

Instruction is one ordered AGENTS.md block.

type Limits

type Limits struct {
	MaxFiles             int
	MaxInstructions      int
	MaxSkills            int
	MaxAgents            int
	MaxEventHandlers     int
	MaxHooks             int
	MaxDirectoryEntries  int
	MaxFileBytes         int64
	MaxTotalContextBytes int64
}

Limits bounds filesystem-derived harness context. Zero fields use defaults.

func DefaultLimits

func DefaultLimits() Limits

DefaultLimits returns the bounds a zero Limits resolves to. Wiring code needs them to keep a separate bound consistent with the file bound rather than restating the number and letting the two drift.

type ManifestEntry

type ManifestEntry struct {
	Kind     SourceKind `json:"kind"`
	Name     string     `json:"name"`
	Source   string     `json:"source"`
	Priority int        `json:"priority"`
	Hash     string     `json:"hash"`
}

ManifestEntry describes one resolved source without exposing mutable state.

type PromptBlock

type PromptBlock struct {
	Kind    SourceKind
	Name    string
	Source  string
	Content string
	Hash    string
}

PromptBlock is an ordered, provenance-carrying context fragment.

type Resolver

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

Resolver discovers the layered harness context for one workspace at a time.

func NewResolver

func NewResolver(configRoot string, limits Limits) (Resolver, error)

NewResolver builds a resolver whose config root is always the first layer.

func (Resolver) Resolve

func (r Resolver) Resolve(workspace string) (Snapshot, error)

Resolve rebuilds the harness snapshot for the selected workspace.

type Skill

type Skill struct {
	Name          string
	Description   string
	Source        string
	Directory     string
	Hash          string
	Metadata      map[string]any
	Homepage      string
	Permissions   map[string]any
	UserInvocable bool
	License       string
	Compatibility string
	AllowedTools  string
}

Skill is the catalogue entry exposed before a skill is activated.

type Snapshot

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

Snapshot is an immutable result of resolving one workspace.

func (Snapshot) ActivateSkill

func (s Snapshot) ActivateSkill(name string) (ActivatedSkill, error)

func (Snapshot) Agent

func (s Snapshot) Agent(name string) (Agent, error)

func (Snapshot) Agents

func (s Snapshot) Agents() []Agent

func (Snapshot) ConfigRoot

func (s Snapshot) ConfigRoot() string

func (Snapshot) EventHandler

func (s Snapshot) EventHandler(eventType string) (EventHandler, error)

func (Snapshot) EventHandlers

func (s Snapshot) EventHandlers() []EventHandler

func (Snapshot) Hash

func (s Snapshot) Hash() string

func (Snapshot) Hooks

func (s Snapshot) Hooks() []Hook

Hooks returns every additive hook group in layer and file order.

func (Snapshot) Instructions

func (s Snapshot) Instructions() []Instruction

func (Snapshot) Manifest

func (s Snapshot) Manifest() []ManifestEntry

func (Snapshot) PromptBlocks

func (s Snapshot) PromptBlocks(rootAgent string) ([]PromptBlock, error)

func (Snapshot) Skills

func (s Snapshot) Skills() []Skill

func (Snapshot) Workspace

func (s Snapshot) Workspace() string

type SourceKind

type SourceKind string

SourceKind identifies one type of discovered harness file.

const (
	SourceKindInstruction  SourceKind = "instruction"
	SourceKindSkill        SourceKind = "skill"
	SourceKindAgent        SourceKind = "agent"
	SourceKindEventHandler SourceKind = "event-handler"
	SourceKindHook         SourceKind = "hook"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL