Documentation
¶
Index ¶
- Variables
- 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 Skill
- 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) ConfigRoot() string
- func (s Snapshot) EventHandler(eventType string) (EventHandler, error)
- func (s Snapshot) EventHandlers() []EventHandler
- func (s Snapshot) Hash() string
- func (s Snapshot) Hooks() []Hook
- func (s Snapshot) Instructions() []Instruction
- func (s Snapshot) Manifest() []ManifestEntry
- func (s Snapshot) PromptBlocks(rootAgent string, explicitSkillNames ...string) ([]PromptBlock, error)
- func (s Snapshot) Skills() []Skill
- func (s Snapshot) Warnings() []Warning
- func (s Snapshot) Workspace() string
- type SourceKind
- type Warning
Constants ¶
This section is empty.
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") 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 ¶
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 {
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
}
Instruction is one ordered, always-on harness instruction 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 ¶
NewResolver builds a resolver whose config root is always the first layer.
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) ConfigRoot ¶
func (Snapshot) EventHandler ¶
func (s Snapshot) EventHandler(eventType string) (EventHandler, error)
func (Snapshot) EventHandlers ¶
func (s Snapshot) EventHandlers() []EventHandler
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, explicitSkillNames ...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 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.