Documentation
¶
Overview ¶
Package agentprofile loads immutable, declarative Coding subagent profiles. It owns discovery and validation only; Runtime compiles profiles against the current capability and approval policy before any profile can execute.
Index ¶
- Constants
- Variables
- type Audience
- type CapabilityMode
- type Definition
- type Delivery
- type Diagnostic
- type Entry
- type EntryStatus
- type ExecutionLimits
- type HookSelection
- type Kind
- type Limits
- type MCPSelection
- type Options
- type OutputContract
- type OutputFormat
- type Registry
- type Scope
- type Selector
- type SelectorKind
- type SkillSelection
- type ToolSelection
- type Visibility
Constants ¶
const ( // SchemaV1Alpha1 is the only custom profile frontmatter schema accepted by // this release. SchemaV1Alpha1 = "pips.agent/v1alpha1" )
Variables ¶
var ( // ErrInvalid reports malformed profile options or profile data. ErrInvalid = errors.New("coding agent profile: invalid") // ErrLimitExceeded reports bounded profile discovery or content exhaustion. ErrLimitExceeded = errors.New("coding agent profile: limit exceeded") // ErrInsecure reports an unsafe user-owned profile root. ErrInsecure = errors.New("coding agent profile: insecure root") )
Functions ¶
This section is empty.
Types ¶
type Audience ¶
type Audience string
Audience identifies the caller whose visible profiles are requested.
type CapabilityMode ¶ added in v0.1.9
type CapabilityMode string
CapabilityMode selects which tool classes an agent type may use. It is a property of the type, never a spawn argument, and it narrows the Runtime's delegable catalog rather than granting anything by itself.
const ( // CapabilityReadOnly keeps read, search, history, question, and Skill tools. CapabilityReadOnly CapabilityMode = "read-only" // CapabilityReadWrite adds file editing to the read-only set. CapabilityReadWrite CapabilityMode = "read-write" // CapabilityExecute adds shell execution to the read-only set. CapabilityExecute CapabilityMode = "execute" // CapabilityAll keeps every delegable tool. CapabilityAll CapabilityMode = "all" )
func ParseCapabilityMode ¶ added in v0.1.9
func ParseCapabilityMode(value string) (CapabilityMode, bool)
ParseCapabilityMode accepts the canonical spelling and the tolerated input aliases. It reports false for an unknown value.
type Definition ¶
type Definition struct {
ID string
Kind Kind
Scope Scope
Source string
Digest string
Schema string
Name string
Description string
Instructions string
Model string
// CapabilityMode narrows the tool kinds this type may use. It applies only
// when Tools.Allow is empty; an explicit allowlist already names its tools.
CapabilityMode CapabilityMode
Visibility Visibility
Delivery []Delivery
Limits ExecutionLimits
Tools ToolSelection
Skills SkillSelection
MCP MCPSelection
Hooks HookSelection
Output OutputContract
}
Definition is one fully parsed immutable-by-convention profile snapshot. Source never contains an absolute local filesystem path.
func BuiltinDefinitions ¶
func BuiltinDefinitions() []Definition
BuiltinDefinitions returns the program-owned compatibility identities. Their prompt and optional structured output contract are rendered by the subagent package when the unified dispatcher compiles one into an execution plan.
The toolsets mirror the source built-ins: general-purpose keeps the full delegable catalog, while explore, plan, and review are read-only. review is a pips extension.
func ParseOneShot ¶
func ParseOneShot(id string, data []byte, limits Limits) (Definition, error)
ParseOneShot validates an explicit, non-persisted definition using exactly the same strict Markdown/YAML contract as a discovered profile. The caller supplies the bounded canonical ID because a one-shot has no file stem. This function performs no filesystem or network I/O.
func (Definition) Clone ¶
func (d Definition) Clone() Definition
Clone returns a detached definition snapshot.
type Diagnostic ¶
Diagnostic is a bounded, content-free loading decision. Source, Winner, and Suppressed use safe provenance strings rather than absolute filesystem paths.
type Entry ¶
type Entry struct {
ID string
Kind Kind
Scope Scope
Source string
Digest string
Status EntryStatus
SuppressedBy string
Definition Definition
Diagnostics []Diagnostic
}
Entry preserves valid suppressed and invalid discovery records for Library diagnostics without exposing profile body content.
type EntryStatus ¶
type EntryStatus string
EntryStatus describes whether a discovered profile is active or retained for diagnostics only.
const ( // EntryAvailable is the winning active profile for its canonical ID. EntryAvailable EntryStatus = "available" // EntrySuppressed is a valid lower-precedence profile. EntrySuppressed EntryStatus = "suppressed" // EntryInvalid is an invalid or reserved-ID profile that cannot dispatch. EntryInvalid EntryStatus = "invalid" )
type ExecutionLimits ¶
ExecutionLimits are requested upper bounds. Zero means inherit the Runtime ceiling; profile compilation may only narrow that ceiling.
type HookSelection ¶
type HookSelection struct {
Private []string
}
HookSelection names exact trusted Agent-private lifecycle hooks.
type Kind ¶
type Kind string
Kind identifies whether a profile is supplied by Pips or declarative input.
const ( // KindBuiltin identifies a program-owned compatibility profile. KindBuiltin Kind = "builtin" // KindCustom identifies a profile loaded from a user or trusted project root. KindCustom Kind = "custom" // KindEphemeral identifies a validated one-shot profile. It is reserved for // the explicit one-shot path and is not discovered from roots. KindEphemeral Kind = "ephemeral" )
type Limits ¶
type Limits struct {
MaxEntries int
MaxDefinitions int
MaxDepth int
MaxPathBytes int
MaxDefinitionBytes int64
MaxTotalDefinitionBytes int64
MaxFrontMatterBytes int
MaxBodyBytes int
MaxIDBytes int
MaxNameBytes int
MaxDescriptionBytes int
MaxModelBytes int
MaxSelectors int
MaxSkills int
MaxSchemaBytes int
MaxSchemaDepth int
MaxSchemaNodes int
MaxSchemaProperties int
}
Limits bound profile discovery, parsing, and declarative payloads before a profile reaches a Runtime generation.
func DefaultLimits ¶
func DefaultLimits() Limits
DefaultLimits returns conservative local bounds for declarative profiles.
type MCPSelection ¶
type MCPSelection struct {
Private []string
}
MCPSelection names exact configured Agent-private MCP servers. It does not select any tool by itself; Tools remains the capability authority surface.
type OutputContract ¶
type OutputContract struct {
Format OutputFormat
Schema json.RawMessage
}
OutputContract is the declarative final-result contract. Schema contains canonical JSON bytes rather than YAML nodes so callers never retain mutable parser state.
type OutputFormat ¶
type OutputFormat string
OutputFormat identifies the local final-result contract for a custom profile.
const ( // OutputText accepts a bounded UTF-8 final response. OutputText OutputFormat = "text" // OutputJSONSchema validates a bounded JSON final response locally. OutputJSONSchema OutputFormat = "json_schema" )
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is an immutable loading snapshot. It intentionally has no model, Tool, or credential dependency, so parsing a profile cannot grant authority.
func Load ¶
Load discovers custom definitions from safe roots, merges them with reserved builtin identities, and returns one detached immutable registry snapshot. Project roots are never inspected until ProjectTrusted is true.
func (Registry) Diagnostics ¶
func (r Registry) Diagnostics() []Diagnostic
Diagnostics returns deterministic loading diagnostics.
func (Registry) List ¶
func (r Registry) List() []Definition
List returns active definitions in canonical ID order.
func (Registry) Lookup ¶
func (r Registry) Lookup(id string) (Definition, bool)
Lookup returns the active profile for id.
func (Registry) VisibleFor ¶
func (r Registry) VisibleFor(audience Audience) []Definition
VisibleFor returns active profiles visible to the selected caller.
type Scope ¶
type Scope string
Scope identifies the safe source boundary that supplied a profile.
const ( // ScopeBuiltin is a program-owned compatibility profile. ScopeBuiltin Scope = "builtin" ScopeUserShared Scope = "user:shared" // ScopeUserPips is the private ~/.pips/agents root. ScopeUserPips Scope = "user:pips" ScopeProjectShared Scope = "project:shared" // ScopeProjectPips is the trusted .pips/agents root. ScopeProjectPips Scope = "project:pips" // ScopeEphemeral identifies an explicitly submitted one-shot definition. // It is never discovered from disk or written by profile parsing. ScopeEphemeral Scope = "ephemeral" )
type Selector ¶
type Selector struct {
Kind SelectorKind
Value string
}
Selector is a parsed profile capability request. It is not an authority grant: Runtime intersects it with its active delegable catalog.
type SelectorKind ¶
type SelectorKind string
SelectorKind identifies the exact catalog dimension selected by a profile.
const ( // SelectorTool selects one exact Tool wire name. SelectorTool SelectorKind = "tool" // SelectorSource selects Tools from one catalog source identity. SelectorSource SelectorKind = "source" // SelectorTag selects Tools carrying one Runtime-owned catalog tag. SelectorTag SelectorKind = "tag" )
type SkillSelection ¶
SkillSelection constrains the immutable Skill snapshot selected at dispatch.
type ToolSelection ¶
ToolSelection constrains the Runtime-owned delegable Tool catalog.
type Visibility ¶
Visibility controls which caller can discover a profile. A profile may still be unavailable at dispatch when its current runtime requirements are unmet.
func (Visibility) VisibleFor ¶
func (v Visibility) VisibleFor(audience Audience) bool
VisibleFor reports whether the requested caller may discover a profile.