harness

package
v0.40.0 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// CorePrefix addresses a core skill or agent, the ones embedded in the
	// binary. A custom skill or agent name never contains ":", so the prefix
	// cannot collide with a name from a layer.
	CorePrefix = "core:"

	// DisableAllCore selects every core skill or agent in a disable list.
	DisableAllCore = "all"

	// NoRootAgent is the root agent of a blank agent: no agent instructions
	// and every tool. It is not lowercase kebab case, so no agent file can
	// take the name.
	NoRootAgent = "(none)"
)

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")
	// ErrPromptBudgetExceeded reports a system prompt, assembled from the
	// harness, that is over the deployment's share of the context window.
	ErrPromptBudgetExceeded = errors.New("system prompt over its token budget")
	ErrSkillNotFound        = errors.New("skill not found")
	ErrSkillContentTooLarge = errors.New("skill content too large")
	ErrAgentNotFound        = errors.New("agent not found")
	ErrEventHandlerNotFound = errors.New("event handler not found")
	ErrUnknownCoreName      = errors.New("unknown core name")

	// 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

func CoreAgentNames added in v0.18.0

func CoreAgentNames() []string

CoreAgentNames lists the core agents, without the core prefix, in sorted order.

func CoreSkillNames added in v0.18.0

func CoreSkillNames() []string

CoreSkillNames lists the core skills, without the core prefix, in sorted order.

func DeleteLearnedFile added in v0.37.0

func DeleteLearnedFile(
	directories LearnedDirectories,
	reference LearnedFileReference,
) error

DeleteLearnedFile removes a learned rule's file or a learned skill's directory.

func ParseDisabledCoreAgents added in v0.18.0

func ParseDisabledCoreAgents(raw string) ([]string, error)

ParseDisabledCoreAgents reads a PEEN_DISABLED_CORE_AGENTS value with the same rules as ParseDisabledCoreSkills.

func ParseDisabledCoreSkills added in v0.18.0

func ParseDisabledCoreSkills(raw string) ([]string, error)

ParseDisabledCoreSkills reads a PEEN_DISABLED_CORE_SKILLS value: core skill names without the core prefix, separated by commas, or "all". Whitespace around an entry is ignored, as are empty entries. The result is sorted and free of duplicates.

func SkillReferences added in v0.18.0

func SkillReferences(text string) []string

SkillReferences finds standalone :skill-name references in a user message or in a skill body. A reference is exact, not semantic: it starts the text or follows whitespace, and it ends at a normal token boundary. A core skill is written :core:skill-name, and only that exact prefix may carry a colon. Each name appears once, in the order of its first reference.

func ValidateCoreAgentReference added in v0.18.0

func ValidateCoreAgentReference(name string, disabled []string) error

ValidateCoreAgentReference checks the part of an agent reference that needs no filesystem: a core: reference must name an existing core agent that is not disabled. Any other reference passes, because a plain name may be a custom agent only a layer knows about.

Types

type ActivatedSkill

type ActivatedSkill struct {
	Skill
	Content string
}

ActivatedSkill is the full content returned by the useSkill 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.
	WorkingDir  string            `yaml:"workingDir" json:"workingDir,omitempty"`   //nolint:lll // Immutable schema tags.
	Timeout     string            `yaml:"timeout" json:"timeout,omitempty"`
	Message     string            `yaml:"message" json:"message,omitempty"`
	MessageFile string            `yaml:"messageFile" json:"messageFile,omitempty"` //nolint:lll // Immutable schema tags.
	EventType   string            `yaml:"eventType" 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"`
	OnFailure   HookFailureMode   `yaml:"onFailure" 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. Timeout is a Go duration string such as "30s" bounding one command action; empty takes the runner's default.

func (HookAction) CommandTimeout added in v0.18.0

func (a HookAction) CommandTimeout() (time.Duration, error)

CommandTimeout parses Timeout as a Go duration. Empty returns zero, which means the runner's default. A set value must be a positive duration.

type HookActionType

type HookActionType string

HookActionType selects the work one hook action performs.

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

type HookEvent

type HookEvent string

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

const (
	HookEventPreUserMessage  HookEvent = "preUserMessage"
	HookEventPostUserMessage HookEvent = "postUserMessage"
	HookEventSessionStart    HookEvent = "sessionStart"
	HookEventTurnStart       HookEvent = "turnStart"
	HookEventTurnStop        HookEvent = "turnStop"
	HookEventTurnCancelled   HookEvent = "turnCancelled"
	HookEventPreCompact      HookEvent = "preCompact"
	HookEventPostCompact     HookEvent = "postCompact"
	HookEventPreToolUse      HookEvent = "preToolUse"
	HookEventPostToolUse     HookEvent = "postToolUse"
	HookEventToolUseFailure  HookEvent = "toolUseFailure"

	HookEventPreReadFile          HookEvent = "preReadFile"
	HookEventPostReadFile         HookEvent = "postReadFile"
	HookEventReadFileFailure      HookEvent = "readFileFailure"
	HookEventPreListFiles         HookEvent = "preListFiles"
	HookEventPostListFiles        HookEvent = "postListFiles"
	HookEventListFilesFailure     HookEvent = "listFilesFailure"
	HookEventPreSearchText        HookEvent = "preSearchText"
	HookEventPostSearchText       HookEvent = "postSearchText"
	HookEventSearchTextFailure    HookEvent = "searchTextFailure"
	HookEventPreWriteFile         HookEvent = "preWriteFile"
	HookEventPostWriteFile        HookEvent = "postWriteFile"
	HookEventWriteFileFailure     HookEvent = "writeFileFailure"
	HookEventPreEditFile          HookEvent = "preEditFile"
	HookEventPostEditFile         HookEvent = "postEditFile"
	HookEventEditFileFailure      HookEvent = "editFileFailure"
	HookEventPreApplyPatch        HookEvent = "preApplyPatch"
	HookEventPostApplyPatch       HookEvent = "postApplyPatch"
	HookEventApplyPatchFailed     HookEvent = "applyPatchFailure"
	HookEventPreMovePath          HookEvent = "preMovePath"
	HookEventPostMovePath         HookEvent = "postMovePath"
	HookEventMovePathFailure      HookEvent = "movePathFailure"
	HookEventPreRemovePath        HookEvent = "preRemovePath"
	HookEventPostRemovePath       HookEvent = "postRemovePath"
	HookEventRemovePathFailed     HookEvent = "removePathFailure"
	HookEventPreMakeDirectory     HookEvent = "preMakeDirectory"
	HookEventPostMakeDirectory    HookEvent = "postMakeDirectory"
	HookEventMakeDirectoryFailure HookEvent = "makeDirectoryFailure"
)

func HookEvents added in v0.19.0

func HookEvents() []HookEvent

HookEvents lists every hook event a hooks.yaml document may name.

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 {
	Kind     SourceKind
	Source   string
	Priority int
	Content  string
	Hash     string

	// Scope is the directory, relative to the workspace, that a nested
	// AGENTS.md covers. It is empty for every file outside the workspace
	// tree and for the workspace's own AGENTS.md.
	Scope string

	// Name is a rule's file name without the .md extension.
	Name string
	// Paths are a rule's glob patterns from its frontmatter. A rule with
	// paths stays out of the system prompt and reaches the model when a file
	// tool touches a matching file. Content never holds the frontmatter.
	Paths []string
	// Base is the directory a scoped rule's patterns are relative to: the
	// directory holding the rule's .agents or .claude directory, or the
	// resolved directory for a rule from the configuration directory.
	Base string
}

Instruction is one ordered, always-on harness instruction block.

func (Instruction) IsScoped added in v0.35.0

func (i Instruction) IsScoped() bool

IsScoped reports whether the instruction is a rule that loads only for matching files.

type LearnedDirectories added in v0.37.0

type LearnedDirectories struct {
	// Workspace is the session's workspace root. Its learned files are under
	// .agents/learned.
	Workspace string
	// Global is the global learned directory itself, or empty when the
	// deployment has none.
	Global string
}

LearnedDirectories are the two places learned files live for one session.

type LearnedFile added in v0.37.0

type LearnedFile struct {
	LearnedFileReference

	Path       string
	SizeBytes  int64
	ModifiedAt time.Time
	// AlwaysLoaded is true for a rule without a scope, which is part of every
	// system prompt.
	AlwaysLoaded    bool
	EstimatedTokens int
}

LearnedFile is one learned rule, or one learned skill's SKILL.md.

func ListLearnedFiles added in v0.37.0

func ListLearnedFiles(
	directories LearnedDirectories,
	estimate TokenEstimator,
) ([]LearnedFile, error)

ListLearnedFiles lists the learned rules and skills in both directories, workspace first, each sorted by kind and name. A missing directory lists nothing, and symbolic links are skipped as the resolver skips them.

func ReadLearnedFile added in v0.37.0

func ReadLearnedFile(
	directories LearnedDirectories,
	reference LearnedFileReference,
	estimate TokenEstimator,
) (LearnedFile, string, error)

ReadLearnedFile returns one learned file and its content. A reference that names nothing, or a path that leaves its learned directory through a symbolic link, is commerr.ErrNotFound.

type LearnedFileReference added in v0.37.0

type LearnedFileReference struct {
	Scope LearnedScope
	Kind  LearnedKind
	// Name is a rule's path under rules/ without .md, slash-separated, or a
	// skill's directory name.
	Name string
}

LearnedFileReference names one learned rule or skill.

type LearnedKind added in v0.37.0

type LearnedKind string

LearnedKind says whether a learned file is a rule or a skill.

const (
	LearnedKindRule  LearnedKind = "rule"
	LearnedKindSkill LearnedKind = "skill"
)

type LearnedScope added in v0.37.0

type LearnedScope string

LearnedScope says which learned directory a learned file lives in.

const (
	// LearnedScopeWorkspace is a workspace's own .agents/learned.
	LearnedScopeWorkspace LearnedScope = "workspace"
	// LearnedScopeGlobal is the global learned directory every session reads.
	LearnedScopeGlobal LearnedScope = "global"
)

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,
	options ...ResolverOption,
) (Resolver, error)

NewResolver builds a resolver whose config root is always the first layer. Options may remove core skills and agents from every snapshot it builds.

func (Resolver) CheckRootAgent added in v0.18.0

func (r Resolver) CheckRootAgent(name string) error

CheckRootAgent verifies at startup the root agent failures that no workspace can fix: a core: name that is unknown or disabled. Any plain name passes, because a workspace may define it. It resolves per turn and fails then if no layer has it.

func (Resolver) Resolve

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

Resolve rebuilds the harness snapshot for the selected workspace.

func (Resolver) ResolveDirectory added in v0.23.0

func (r Resolver) ResolveDirectory(directory string) (Snapshot, error)

ResolveDirectory reads the current directory and its ancestors, without loading definitions from descendants the agent has not entered.

type ResolverOption added in v0.18.0

type ResolverOption func(*resolverSettings)

ResolverOption adjusts how a Resolver builds its snapshots.

func WithCoreInstructionsDisabled added in v0.35.0

func WithCoreInstructionsDisabled(disabled bool) ResolverOption

WithCoreInstructionsDisabled leaves Peen's embedded AGENTS.md out of every snapshot when disabled is true, so only the configured layers give the agent instructions.

func WithDisabledCoreAgents added in v0.18.0

func WithDisabledCoreAgents(names []string) ResolverOption

WithDisabledCoreAgents removes the named core agents, given without the core prefix, from every snapshot. NewResolver rejects a name no core agent has.

func WithDisabledCoreSkills added in v0.18.0

func WithDisabledCoreSkills(names []string) ResolverOption

WithDisabledCoreSkills removes the named core skills, given without the core prefix, from every snapshot. NewResolver rejects a name no core skill has.

func WithLearnedDirectory added in v0.36.0

func WithLearnedDirectory(directory string) ResolverOption

WithLearnedDirectory reads the global learned directory right after the config layer, so the rules and skills an agent saved there reach every session. A missing directory is not an error.

func WithMemoryLayers added in v0.22.0

func WithMemoryLayers(layers []workspacefs.Reader) ResolverOption

WithMemoryLayers adds immutable layers after disk and workspace discovery.

func WithWorkspaceFilesystem added in v0.22.0

func WithWorkspaceFilesystem(
	filesystem workspacefs.Reader,
	virtual bool,
) ResolverOption

WithWorkspaceFilesystem confines workspace discovery to a virtual root. The trusted configuration directory is still read from the host.

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 SkillDelivery added in v0.18.0

type SkillDelivery struct {
	Skill ActivatedSkill

	// Referenced is true when another skill's body named this skill, rather
	// than the caller.
	Referenced bool

	// AlreadyDelivered marks a skill the caller named that the conversation
	// already holds. Only a note is due, not a second copy.
	AlreadyDelivered bool
}

SkillDelivery is one skill reaching a conversation through ExpandSkills.

type Snapshot

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

Snapshot is an immutable result of resolving one workspace.

func RestoreCheckpoint added in v0.25.0

func RestoreCheckpoint(encoded json.RawMessage) (Snapshot, error)

RestoreCheckpoint validates saved state and never consults the filesystem.

func (Snapshot) ActivateSkill

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

ActivateSkill resolves a skill by name. A plain name finds the custom skill first and the core skill second. A name with the core prefix finds only the core skill.

func (Snapshot) Agent

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

Agent resolves an agent by name with the same rules as ActivateSkill. NoRootAgent resolves to an agent with no instructions and no tool limit.

func (Snapshot) Agents

func (s Snapshot) Agents() []Agent

func (Snapshot) Checkpoint added in v0.25.0

func (s Snapshot) Checkpoint() (json.RawMessage, error)

Checkpoint retains resolved content without reading its source files again.

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) ExpandSkills added in v0.18.0

func (s Snapshot) ExpandSkills(
	names []string,
	delivered map[string]struct{},
) ([]SkillDelivery, error)

ExpandSkills resolves the skills a caller named and every skill their bodies reference, depth first in reference order. Each skill appears once.

delivered holds the resolved names (as ActivatedSkill.Name reports them) the conversation already has. It is read, never changed; the caller records what it delivers. A named skill in delivered comes back marked AlreadyDelivered and its references are not followed. A referenced skill in delivered is left out. A skill named twice in one call, including by a plain and a core spelling of one name, is delivered once.

An unknown name the caller gave fails the call with ErrSkillNotFound. An unknown reference inside a skill body is skipped; the resolver already reported it as a warning. Delivered content over the harness file size limit fails with ErrSkillContentTooLarge.

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) MatchingRules added in v0.35.0

func (s Snapshot) MatchingRules(paths []string) []Instruction

MatchingRules returns the scoped rules whose patterns match at least one of paths, in prompt order. Each path is made relative to the rule's base, and a path outside the base matches nothing.

func (Snapshot) PromptBlocks

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

func (Snapshot) Skills

func (s Snapshot) Skills() []Skill

func (Snapshot) Warnings added in v0.13.0

func (s Snapshot) Warnings() []Warning

Warnings returns invalid optional sources Peen ignored while resolving this snapshot. The returned slice is safe for callers to modify.

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"
	SourceKindRule         SourceKind = "rule"
	SourceKindSkill        SourceKind = "skill"
	SourceKindAgent        SourceKind = "agent"
	SourceKindEventHandler SourceKind = "event-handler"
	SourceKindHook         SourceKind = "hook"
)

type TokenEstimator added in v0.37.0

type TokenEstimator func(text string) (int, error)

TokenEstimator estimates the tokens in a text.

type UnknownSkillError added in v0.18.0

type UnknownSkillError struct {
	Message string
}

UnknownSkillError reports a :name that matches no skill. Message is written for the person who typed the name: it holds no source location, and it travels unchanged across the worker socket and into the WebSocket failure.

func NewUnknownSkillError added in v0.18.0

func NewUnknownSkillError(name string, available []string) *UnknownSkillError

NewUnknownSkillError names the unknown reference and lists the skills that exist, cutting a long list to maxListedSkills names and a count.

func (*UnknownSkillError) Error added in v0.18.0

func (e *UnknownSkillError) Error() string

func (*UnknownSkillError) Is added in v0.18.0

func (e *UnknownSkillError) Is(target error) bool

Is makes the error match ErrSkillNotFound.

type Warning added in v0.13.0

type Warning struct {
	Kind   SourceKind `json:"kind"`
	Source string     `json:"source"`
	Reason string     `json:"reason"`
}

Warning reports one optional harness source Peen ignored after it failed validation. The remaining valid sources still form the active snapshot.

Jump to

Keyboard shortcuts

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