Documentation
¶
Index ¶
- Constants
- Variables
- func CoreAgentNames() []string
- func CoreSkillNames() []string
- func ParseDisabledCoreAgents(raw string) ([]string, error)
- func ParseDisabledCoreSkills(raw string) ([]string, error)
- func SkillReferences(text string) []string
- func ValidateCoreAgentReference(name string, disabled []string) error
- type ActivatedSkill
- type Agent
- type EventHandler
- type Hook
- type HookAction
- type HookActionType
- type HookEvent
- type HookFailureMode
- type HookInputMatch
- type HookMatch
- type Instruction
- type Limits
- type ManifestEntry
- type PromptBlock
- type Resolver
- type ResolverOption
- func WithCoreInstructionsDisabled(disabled bool) ResolverOption
- func WithDisabledCoreAgents(names []string) ResolverOption
- func WithDisabledCoreSkills(names []string) ResolverOption
- func WithMemoryLayers(layers []workspacefs.Reader) ResolverOption
- func WithWorkspaceFilesystem(filesystem workspacefs.Reader, virtual bool) ResolverOption
- type Skill
- type SkillDelivery
- type Snapshot
- func (s Snapshot) ActivateSkill(name string) (ActivatedSkill, error)
- func (s Snapshot) Agent(name string) (Agent, error)
- func (s Snapshot) Agents() []Agent
- func (s Snapshot) Checkpoint() (json.RawMessage, error)
- func (s Snapshot) ConfigRoot() string
- func (s Snapshot) EventHandler(eventType string) (EventHandler, error)
- func (s Snapshot) EventHandlers() []EventHandler
- func (s Snapshot) ExpandSkills(names []string, delivered map[string]struct{}) ([]SkillDelivery, error)
- func (s Snapshot) Hash() string
- func (s Snapshot) Hooks() []Hook
- func (s Snapshot) Instructions() []Instruction
- func (s Snapshot) Manifest() []ManifestEntry
- func (s Snapshot) MatchingRules(paths []string) []Instruction
- func (s Snapshot) PromptBlocks(rootAgent string) ([]PromptBlock, error)
- func (s Snapshot) Skills() []Skill
- func (s Snapshot) Warnings() []Warning
- func (s Snapshot) Workspace() string
- type SourceKind
- type UnknownSkillError
- type Warning
Constants ¶
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 ¶
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") 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 ParseDisabledCoreAgents ¶ added in v0.18.0
ParseDisabledCoreAgents reads a PEEN_DISABLED_CORE_AGENTS value with the same rules as ParseDisabledCoreSkills.
func ParseDisabledCoreSkills ¶ added in v0.18.0
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
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
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 ¶
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 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
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.
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 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 ¶
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) 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 (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) 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)
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 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.