Documentation
¶
Overview ¶
Package piglet provides piglet-based capability scoping for pig sessions.
D18: Stock Pig's generic `pig piglet` command and in-session capability scoping.
The package has two entry points:
- RunCommand: pre-session CLI (pig piglet list|show|validate|schema|add|remove)
- BuildExtension: in-session runtime scoping via extension.Extension
The extension reads a piglet YAML (from --piglet flag, PIG_PIGLET_PATH env, PIG_PIGLET_NAME env, or search paths), parses per-source tool scoping rules, and calls SetActiveTools to filter the tool set before the first agent turn.
Piglet is used by:
- managed runtimes (mounted YAML through PIG_PIGLET_PATH)
- local Pig invocations (--piglet flag or ~/.pig/piglets/<name>.yaml)
Piglet YAML schema types and parser.
A piglet is the complete agent definition: extensions with per-source capability scoping, MCP servers, skills, prompts, model config. The same YAML format is used locally (~/.pig/piglets/), on platform (ConfigMap from Agent CRD spec.piglet), and in independently published Piglet source.
Piglet is the agent-author scoping mechanism. A hosting platform may apply an additional administrative policy ceiling without rewriting the Piglet.
Index ¶
- Constants
- func ActiveAgentEnvironmentIdentity() string
- func ActiveByDefaultTools(p *Piglet) []string
- func ActiveSourceFromEnv() string
- func ActiveSourceIsPath(value string) bool
- func ActiveSourceValue(p *Piglet, baked bool) string
- func AgentToolScopeLine(p *Piglet, untrustedProject bool) string
- func AmbientPigletPath() string
- func Bake(p *Piglet, pigletDir string) ([]byte, error)
- func BuildExtensionWithPiglet(initial *Piglet) extension.Extension
- func BuildExtensionWithPigletTools(initial *Piglet, owner func(extension.ToolInfo) string) extension.Extension
- func BuildExtensionWithToolScope(initial *Piglet, scope *extension.ToolScope) extension.Extension
- func CheckRemoteAddable(path string) error
- func CompileToolScope(piglet *Piglet, owner func(extension.ToolInfo) string) *extension.ToolScope
- func DistributionOffline() bool
- func MCPScopeLine(p *Piglet) string
- func RenderLineage(w io.Writer, out *LineageOutput)
- func RenderTree(w io.Writer, roots []*TreeNode)
- func Resolve(nameOrPath string) (string, error)
- func ResolveWithTrust(nameOrPath string, trustOverride *bool) (string, error)
- func RunCommand(args []string, stdout, stderr io.Writer) int
- func SchemaJSON() []byte
- func ScopeTools(piglet *Piglet, allTools []ToolInfo) []string
- func SetRunningBinary(fn func() (name string, closed, ok bool))
- func ShadowedWorkspacePiglet(nameOrPath string, trustOverride *bool) string
- func StripBuildTags() []string
- func StripDeltaReport(name string, current *StripSpec) []string
- func SystemPigletsDir() string
- func ToolScopeNotice(p *Piglet, hidden []extension.HiddenTool) string
- func ToolScopeSummary(p *Piglet) string
- func ToolScopeTableMarkdown() string
- func ValidateAgainstSchema(yamlBytes []byte) error
- func ValidateRemoteSource(raw string) error
- type AgentEnvironment
- type AgentEnvironmentPolicy
- type AgentEnvironmentRuntimeOptions
- type AgentEnvironmentRuntimeResult
- type AgentMount
- type AgentPigRuntime
- type AgentSecretBinding
- type AgentSecretTarget
- type AgentWorkspace
- type BinaryLineage
- type BuildSpec
- type Discovery
- type EffectiveResolution
- type ExtendsSpec
- type ExtensionEntry
- type LineageEntry
- type LineageLink
- type LineageOutput
- type LineageReport
- type LinkChanges
- type ModelConfig
- type NPMBinaries
- type NPMSource
- type NPMSourceOptions
- type OverlayBase
- type Piglet
- func (p *Piglet) BakedSkill(name string) bool
- func (p *Piglet) EffectiveAgentEnvironment() *AgentEnvironment
- func (p *Piglet) FrontendDir() (string, error)
- func (p *Piglet) HasFrontend() bool
- func (p *Piglet) OverlayOf() (binary string, ok bool)
- func (p *Piglet) ResolutionIdentity() ([]LineageEntry, string, string)
- func (p *Piglet) SourcePath() string
- func (p *Piglet) Validate() error
- func (p *Piglet) ValidateAgentEnvironmentLaunch() error
- func (p *Piglet) ValidateAgentEnvironmentRuntime() error
- func (p *Piglet) WithholdsUntrustedContextFiles() bool
- type PigletInfo
- type PromptRef
- type ProvenanceCheck
- type RecordComponent
- type RecordInfo
- type ReleaseSpec
- type RemoveSpec
- type ResolveOptions
- type ResolvedAgentEnvironment
- type ResolvedExtension
- type ResolvedPackage
- type ResolvedSecrets
- type ResolvedSkill
- type RuntimeIO
- type SecretDeclaration
- type SecretSource
- type SetChange
- type SkillEntry
- type SlotMember
- type Slots
- type StripDelta
- type StripIDList
- type StripKeep
- type StripSpec
- func (s *StripSpec) BuildTags() []string
- func (s *StripSpec) HasFeature(id string) bool
- func (s *StripSpec) IsEmpty() bool
- func (s *StripSpec) KeepLists() []StripIDList
- func (s StripSpec) MarshalYAML() (any, error)
- func (s *StripSpec) Record() (undo func())
- func (s *StripSpec) StrippedIDs() []StrippedID
- type StrippedID
- type ToolInfo
- type TreeNode
Constants ¶
const ( ToolScopeTableStart = "<!-- tool-scope-table:start (generated by coding/piglet/scope_table.go; do not edit) -->" ToolScopeTableEnd = "<!-- tool-scope-table:end -->" )
ToolScopeTableStart and ToolScopeTableEnd bracket the table in the docs.
const ( StripKindTool = "tool" StripKindCommand = "command" StripKindExtension = "extension" StripKindAPI = "api" StripKindFeature = "feature" )
Strip kinds name the five strip lists in records and `pig piglet show`.
const ( // StripDispositionRuntime marks a built-in that stays compiled in and is // disabled when the Piglet runs. StripDispositionRuntime = "runtime" // StripDispositionBinary marks a built-in the Piglet Binary does not // link. Stock PiG running the Piglet disables it at runtime. StripDispositionBinary = "binary" )
Strip dispositions say how a Piglet Binary strips a built-in.
const ( ContextFilesAll = "all" ContextFilesTrustedOnly = "trusted-only" )
Context file modes a Piglet may set. ContextFilesAll is Pi's behaviour: every project context file loads. ContextFilesTrustedOnly withholds the project's context files until the project is trusted.
const ActiveSourceEnv = "PIG_ACTIVE_PIGLET_SOURCE"
ActiveSourceEnv is the variable a running session exports to the processes its tools start, so `pig status`, `pig diagnose` and `pig piglet show` run from the agent's shell can see the Piglet the session runs. The value is the Piglet source path, or the Piglet's name for a Piglet Binary, whose Piglet has no source file. The variable is informational: no run selects a Piglet from it.
pig additive (D209): the active Piglet is exported to tool subprocesses as PIG_ACTIVE_PIGLET_SOURCE.
const InspectCommand = "piglet"
InspectCommand is the name of the read-only /piglet command the in-session extension registers. Its strip ID is "/piglet" in the commands list (pig additive, D92).
const MCPAdapterExtensionName = extension.McpAdapterEntry
MCPAdapterExtensionName is the Piglet extension entry that governs every MCP tool.
const NPMKeyword = "pig-piglet"
NPMKeyword is the npm keyword that lists a package as a Piglet source. Catalogs find published Piglets by this keyword the way Pi's gallery finds Pi packages by `pi-package`.
Variables ¶
This section is empty.
Functions ¶
func ActiveAgentEnvironmentIdentity ¶
func ActiveAgentEnvironmentIdentity() string
ActiveAgentEnvironmentIdentity returns the already-verified active environment identity injected into the inner process, or empty for host execution. It never reads secret values.
func ActiveByDefaultTools ¶
ActiveByDefaultTools are the built-in tools a run with this Piglet activates before settings and `--tools` change the selection: Pi's default active tools that the root `tools` list keeps and the strip lists leave. The root `tools` list limits what can be active; it does not activate a tool, so `tools: [read, grep]` activates only read.
func ActiveSourceFromEnv ¶
func ActiveSourceFromEnv() string
ActiveSourceFromEnv returns the ActiveSourceEnv value of this process, or "".
func ActiveSourceIsPath ¶
ActiveSourceIsPath reports whether an ActiveSourceEnv value names a Piglet file, as opposed to the name of a Piglet Binary.
func ActiveSourceValue ¶
ActiveSourceValue returns the value of ActiveSourceEnv for p: its name when it is a Piglet Binary's baked Piglet (baked), else its source path, else its name. A nil p has no value.
func AgentToolScopeLine ¶
AgentToolScopeLine is the line the agent gets when a Piglet is active, so it knows what it can and cannot reach: the Piglet (and the Piglet Binary it overlays), the most its tool scope lets it reach, what the strip lists removed, and the trust of the project when it is untrusted, and where to read the details. A Piglet Binary has no docs section, so this line is all its agent learns.
func AmbientPigletPath ¶
func AmbientPigletPath() string
AmbientPigletPath is the Piglet file a container image bakes in at /opt/pig/piglet.yaml, or "" when there is none or the platform has no such location.
func Bake ¶
Bake returns the Piglet definition a Piglet Binary embeds for the effective Piglet p, whose source file is in pigletDir. The baked definition carries the agent shape (extensions, skills, MCP, scoping, discovery) so the Binary can assemble the intended agent. Prompt files and skills are inlined; release, build, slot, and package metadata and extension source origins are dropped because the runnable members come from the embedded cell manifest. The one build setting kept is build.closed (D202). Its digest is the Piglet digest a Binary's records and signed manifest name, so they vouch for it.
func BuildExtensionWithPiglet ¶
BuildExtensionWithPiglet returns an extension.Extension that applies Piglet-based tool scoping at runtime. The caller supplies the Piglet selected before extension loading. The extension applies tool scope on session_start and before_agent_start events. If the Piglet declares a systemPrompt, the extension returns it from before_agent_start so Pig core uses it as the session system prompt.
The returned Extension registers read-only /piglet inspection unless the process strips it (strip.commands: /piglet). Piglet selection/editing is deliberately not available in-session: a different composition is selected by a separate Pig invocation.
func BuildExtensionWithPigletTools ¶
func BuildExtensionWithPigletTools(initial *Piglet, owner func(extension.ToolInfo) string) extension.Extension
BuildExtensionWithPigletTools is BuildExtensionWithPiglet with the owner of extension-registered tools: owner names the Piglet extension entry whose `tools` allowlist scopes a tool, or "" when no loaded extension registered it.
func BuildExtensionWithToolScope ¶
BuildExtensionWithToolScope is BuildExtensionWithPigletTools with the compiled scope the Session's registry filter also uses, so the extension reports the tools that very scope removed.
func CheckRemoteAddable ¶
CheckRemoteAddable applies the checks `pig piglet add npm:<package>` makes to published Piglet source that need neither network nor materialized Packages. It guarantees that a source which passes can be registered from npm.
pig additive (D18): npm Piglet source publication.
func CompileToolScope ¶
CompileToolScope compiles a Piglet's tool scope into the form the Session's registry filter reads (extension.ToolFilter.WithScope; pig additive, D23). owner names the Piglet extension entry that registered an extension tool, or "" when no loaded extension did. The rules are documented on extension.ToolScope.
func DistributionOffline ¶
func DistributionOffline() bool
DistributionOffline reports whether PI_OFFLINE or PIG_OFFLINE forbids the network access that remote Piglet distribution commands need.
func MCPScopeLine ¶
MCPScopeLine says in one line what the Piglet does to MCP tools and why, or "" when it keeps all of them. It is the static counterpart of ToolScopeNotice: it needs no running MCP server.
func RenderLineage ¶
func RenderLineage(w io.Writer, out *LineageOutput)
RenderLineage writes the chain root first. Each link below the root lists what it adds (+), removes (-) and alters (~) against its base.
func RenderTree ¶
RenderTree draws roots with box-drawing characters. `*` marks the current Piglet, `[installed]` one with a built Binary, `(external)` a base outside the inventory.
func Resolve ¶
Resolve finds a piglet by name, checking the resolution order:
- Explicit path (already absolute or relative)
- PIG_PIGLET_PATH env var
- PIG_PIGLET_NAME env var → search paths
- Workspace: .pig/piglets/<name>.yaml, only when the project is trusted
- User: ~/.pig/piglets/<name>.yaml
- System: /etc/pig/piglets/<name>.yaml
The workspace is project config, so it follows project trust: a stored decision for the project, no prompt. Resolve reads that decision; ResolveWithTrust takes the run's --approve / --no-approve override ahead of it.
func ResolveWithTrust ¶
ResolveWithTrust is Resolve with a project trust override: nil defers to the stored decision for the working directory.
func RunCommand ¶
RunCommand handles `pig piglet <subcommand>`. Returns -1 if args do not match, 0 on success, and 1+ on error.
func SchemaJSON ¶
func SchemaJSON() []byte
SchemaJSON returns the published Piglet JSON Schema v1 bytes.
func ScopeTools ¶
ScopeTools returns the names of the registered tools the Piglet keeps, in registry order.
func SetRunningBinary ¶
SetRunningBinary lets `pig piglet show` name whether the Piglet Binary it runs in is closed (build.closed). The package that owns the baked Piglet cannot be imported from here, so the CLI hands the answer in.
pig additive (D202): `pig piglet show` on a Piglet Binary prints whether it is closed.
func ShadowedWorkspacePiglet ¶
ShadowedWorkspacePiglet returns the name the run selected when the project defines a Piglet of that name in its config directory and project trust withholds it, or "" when nothing is withheld. An explicit path and an empty selection are never shadowed.
func StripBuildTags ¶
func StripBuildTags() []string
StripBuildTags lists every build tag a Piglet Binary can be built with, sorted: one for each built-in extension, strippable API and compile-out feature in the generated ID table.
func StripDeltaReport ¶
StripDeltaReport returns the strip delta report for the Piglet against its newest Binary record, with current as the Piglet's strip spec resolved now (nil reads the modes from the record). It returns nil when PiG has built no Binary for the Piglet.
func SystemPigletsDir ¶
func SystemPigletsDir() string
SystemPigletsDir is the machine-wide Piglet directory, or "" where PiG has none. A rooted path without a volume is drive-relative on Windows (C:\etc\pig\piglets), a place any local user can create, so Windows has no ambient system Piglet directory.
func ToolScopeNotice ¶
func ToolScopeNotice(p *Piglet, hidden []extension.HiddenTool) string
ToolScopeNotice lists the tools the Piglet's scope removed from the registry, grouped by MCP server or owning extension, each group with its reason. It is "" when the scope removed nothing.
func ToolScopeSummary ¶
ToolScopeSummary is the one-line tool scope of a Piglet for the agent's context. It states the most the agent can reach: the root `tools` list is a ceiling over the default active tools, and the strip lists remove tools in this process, so the line leaves out stripped built-in tools and says no MCP tools when MCP is stripped. The agent line says "at most" for that reason.
func ToolScopeTableMarkdown ¶
func ToolScopeTableMarkdown() string
ToolScopeTableMarkdown renders the tool scope rule table, one row per case, from the code that scopes the registry.
func ValidateAgainstSchema ¶
ValidateAgainstSchema checks Piglet YAML against the published JSON Schema closed vocabulary. It is the schema half of the schema/parser agreement; Go parsing (ParseBytes) adds the semantic checks the vocabulary schema cannot express.
func ValidateRemoteSource ¶
ValidateRemoteSource checks that raw is an npm or Git source reference that carries no authentication material, so it can be published. Rejected references and parser diagnostics never enter its errors.
Types ¶
type AgentEnvironment ¶
type AgentEnvironment struct {
Image string `yaml:"image,omitempty"`
DevContainer string `yaml:"devContainer,omitempty"`
Source string `yaml:"source,omitempty"`
PigRuntime *AgentPigRuntime `yaml:"pigRuntime,omitempty"`
Policy *AgentEnvironmentPolicy `yaml:"policy,omitempty"`
Workspace *AgentWorkspace `yaml:"workspace,omitempty"`
Mounts []AgentMount `yaml:"mounts,omitempty"`
Secrets []AgentSecretBinding `yaml:"secrets,omitempty"`
}
AgentEnvironment is a required whole-agent runtime when present. Exactly one source form is set; runtime and policy defaults are projected without rewriting the authored Piglet.
type AgentEnvironmentPolicy ¶
type AgentEnvironmentPolicy struct {
Preset string `yaml:"preset,omitempty"`
}
type AgentEnvironmentRuntimeOptions ¶
type AgentEnvironmentRuntimeOptions struct {
Engine string
Workspace string
Args []string
PigVersion string
StateRoot string
UnsafeHost bool
Commands runtimeCommands
IO RuntimeIO
}
AgentEnvironmentRuntimeOptions are machine-local execution inputs. They are never serialized into a Piglet or included in its portable identity.
type AgentEnvironmentRuntimeResult ¶
AgentEnvironmentRuntimeResult tells the caller whether startup should continue in the current process or terminate with the child engine's status.
func RunAgentEnvironment ¶
func RunAgentEnvironment(ctx context.Context, p *Piglet, options AgentEnvironmentRuntimeOptions) (AgentEnvironmentRuntimeResult, error)
RunAgentEnvironment enters a supported required Piglet environment before model, session, extension, or tool initialization. The current slice supports direct-image Piglets in explicit image-runtime mode with standard policy. Every other environment form remains fail-closed.
type AgentMount ¶
type AgentMount struct {
Source string `yaml:"source"`
Target string `yaml:"target"`
ReadOnly bool `yaml:"readonly,omitempty"`
}
AgentMount is one additional host bind exposed to the environment. Extra mounts are an elevated-policy capability because each one widens the host surface the agent can read or write.
func (*AgentMount) UnmarshalYAML ¶
func (m *AgentMount) UnmarshalYAML(node *yaml.Node) error
type AgentPigRuntime ¶
type AgentSecretBinding ¶
type AgentSecretBinding struct {
SecretRef string `yaml:"secretRef"`
Target AgentSecretTarget `yaml:"target"`
}
AgentSecretBinding maps one logical secret to a child environment target.
type AgentSecretTarget ¶
type AgentSecretTarget struct {
Env string `yaml:"env,omitempty"`
}
AgentSecretTarget currently supports child environment injection. File targets wait for the environment runtime materialization slice.
type AgentWorkspace ¶
type AgentWorkspace struct {
Folder string `yaml:"folder,omitempty"` // container path; default image WorkingDir then /workspace
ReadOnly *bool `yaml:"readonly,omitempty"` // nil = policy default (minimal read-only, else read-write)
}
AgentWorkspace selects where the invocation workspace lands inside the environment. The host source stays a machine-local execution input (default the current directory), so it is intentionally not a Piglet field.
func (*AgentWorkspace) UnmarshalYAML ¶
func (w *AgentWorkspace) UnmarshalYAML(node *yaml.Node) error
type BinaryLineage ¶
type BinaryLineage struct {
Path string `json:"path"`
Name string `json:"name"`
Version string `json:"version,omitempty"`
Digest string `json:"digest"`
Source string `json:"sourceDigest"`
Signer string `json:"signer"`
Trusted bool `json:"trusted"`
// Verified is false when the signature check fails: the executable bytes changed after signing, the signer is revoked, or the trust policy rejects the signer. The identity above is then only what the unverified manifest claims.
Verified bool `json:"verified"`
Signature string `json:"signature"`
}
BinaryLineage is the lineage a signed Piglet Binary carries: the identity it records, not an extends chain (the record keeps digests, not the chain). pig additive (D170): `pig piglet lineage` reports a Binary from its signed manifest.
type BuildSpec ¶
type BuildSpec struct {
Targets []string `yaml:"targets,omitempty"`
OutputName string `yaml:"outputName,omitempty"`
ExtensionRealization string `yaml:"extensionRealization,omitempty"`
// Closed makes the Piglet Binary built from this Piglet run only its baked Piglet: it refuses a Piglet selected at
// launch (--piglet, PIG_PIGLET_PATH, PIG_PIGLET_NAME) and --system-prompt, and discovers no ambient extensions or
// skills. Default false: the Binary behaves as stock pig started with its Piglet. Like all of build it is authored on
// the Piglet that is built and is not inherited through extends.
//
// pig additive (D202): a Piglet Binary accepts overlay Piglets unless built closed.
Closed bool `yaml:"closed,omitempty"`
}
BuildSpec defines portable build defaults. Builder selection and verification policy remain execution inputs and are intentionally not serialized here. pig additive (D18): Piglets own Pig's additive artifact build defaults. BuildSpec carries portable build defaults only. Delivery tier, strictness, update endpoint, release version, builder, credentials, and verification are execution or publication inputs, not portable Piglet source.
type Discovery ¶
type Discovery struct {
Extensions []string `yaml:"extensions,omitempty"`
Skills []string `yaml:"skills,omitempty"`
}
Discovery selects ambient Resource scopes by kind. Explicit Piglet entries are independent of discovery. Nil and empty lists both mean no ambient Resources in an active Piglet.
type EffectiveResolution ¶
type EffectiveResolution struct {
Piglet *Piglet `json:"-"`
Lineage []LineageEntry `json:"lineage"`
SourceDigest string `json:"sourceDigest"`
EffectiveDigest string `json:"effectiveDigest"`
GraphDigest string `json:"graphDigest"`
}
EffectiveResolution is a source Piglet resolved through its exact base lineage. Piglet contains no release/build/extends/remove metadata.
func ResolveEffective ¶
func ResolveEffective(path string) (*EffectiveResolution, error)
ResolveEffective resolves with no workspace anchor. Piglets that require a workspace:-anchored field fail until the caller supplies one explicitly.
func ResolveEffectiveWithOptions ¶
func ResolveEffectiveWithOptions(path string, options ResolveOptions) (*EffectiveResolution, error)
ResolveEffectiveWithOptions resolves path's typed extends lineage and deterministic merge algebra. Each source's Piglet-owned local paths are anchored before merge, so inherited resources are never re-anchored to a child directory.
pig additive (D18): additive Piglet derivation and exact lineage.
type ExtendsSpec ¶
type ExtendsSpec struct {
Source string `yaml:"source,omitempty"`
Version string `yaml:"version,omitempty"`
AllowWiden bool `yaml:"allowWiden,omitempty"`
Remove *RemoveSpec `yaml:"remove,omitempty"`
}
ExtendsSpec selects one base Piglet source plus an optional author version constraint. Resolution pins the exact content digest in lineage. A block without a source extends the Piglet Binary that runs the Piglet as an overlay (D202), so it carries only remove and allowWiden.
type ExtensionEntry ¶
type ExtensionEntry struct {
Name string `yaml:"name"`
Origins []string `yaml:"origins,omitempty"`
Tools *[]string `yaml:"tools,omitempty"`
}
ExtensionEntry selects one extension and optionally limits its model tools. A nil Tools pointer means every registered tool; a non-nil empty slice means none.
func (*ExtensionEntry) UnmarshalYAML ¶
func (e *ExtensionEntry) UnmarshalYAML(node *yaml.Node) error
UnmarshalYAML handles the bare extension-name shorthand.
type LineageEntry ¶
type LineageEntry struct {
Source string `json:"source"`
Version string `json:"version,omitempty"`
Digest string `json:"digest"`
}
LineageEntry pins one source in an effective Piglet's inheritance chain.
type LineageLink ¶
type LineageLink struct {
Name string `json:"name"`
Source string `json:"source"`
Version string `json:"version,omitempty"`
Digest string `json:"digest"`
Changes *LinkChanges `json:"changes,omitempty"`
}
LineageLink is one Piglet in an inheritance chain: its identity and what it changes against the Piglet it extends. The root has no Changes. pig additive (D170): Piglet lineage diagnostics report the chain `extends` already resolves.
type LineageOutput ¶
type LineageOutput struct {
Kind string `json:"kind"`
Piglet string `json:"piglet"`
Chain []LineageLink `json:"chain"`
Binary *BinaryLineage `json:"binary,omitempty"`
Provenance *ProvenanceCheck `json:"provenance,omitempty"`
Advisories []string `json:"advisories"`
}
LineageOutput is the `pig piglet lineage` result. Chain is root first. Advisories lists advisories the chain inherits; stock Pig records none, so the list stays empty until a Piglet source supplies them.
func Lineage ¶
func Lineage(target, source, workspace string) (*LineageOutput, error)
Lineage reports target, a Piglet name or source path or a signed Piglet Binary. For a Binary, source (a name or path) supplies the extends chain and the Binary's recorded digests are checked against it. It reads local files.
type LineageReport ¶
type LineageReport struct {
Piglet string `json:"piglet"`
Source string `json:"source"`
Chain []LineageLink `json:"chain"`
}
LineageReport is the inheritance chain of one source Piglet, root first.
func SourceLineage ¶
func SourceLineage(path, workspace string) (*LineageReport, error)
SourceLineage reports the chain of the source Piglet at path with each link's change against its base. It reads local files only.
type LinkChanges ¶
type LinkChanges struct {
Extensions SetChange `json:"extensions"`
Packages SetChange `json:"packages"`
Skills SetChange `json:"skills"`
Tools SetChange `json:"tools"`
Permissions SetChange `json:"permissions"`
Slots SetChange `json:"slots"`
Strip SetChange `json:"strip"`
Settings SetChange `json:"settings"`
}
LinkChanges is the effective difference between a Piglet and its base: extensions, packages, skills, built-in tools, permissions (the agent environment), slots, strip lists and the remaining settings.
func (LinkChanges) Empty ¶
func (c LinkChanges) Empty() bool
Empty reports that the Piglet changes nothing against its base.
type ModelConfig ¶
type ModelConfig struct {
Provider string `yaml:"provider,omitempty"`
Name string `yaml:"name,omitempty"`
ContextWindow int `yaml:"contextWindow,omitempty"`
Thinking string `yaml:"thinking,omitempty"`
}
ModelConfig specifies the model to use.
type NPMBinaries ¶
NPMBinaries names the signed Piglet Binary release that matches a published npm source. Catalogs show `pig piglet pull <Ref>` next to the source install command.
type NPMSource ¶
type NPMSource struct {
// Dir is a new temporary directory. The caller removes it.
Dir string
Name string
Version string
// Packages maps each Package alias to its source in the published Piglet.
Packages map[string]string
// Files lists every file in Dir, slash-separated and sorted.
Files []string
Warnings []string
}
NPMSource is one generated, publishable npm package directory.
func BuildNPMSource ¶
func BuildNPMSource(options NPMSourceOptions) (source NPMSource, err error)
BuildNPMSource validates an authored Piglet and writes the npm package that publishes it into a new temporary directory.
The generated piglet.yaml is the authored file with every local Package replaced by the npm reference of that Package, because a remote Piglet source cannot take local paths. The generated package.json carries the Piglet's name and release.version, the `pig-piglet` keyword, and the `pig.piglet` path that `pig piglet add` reads. The authored files are not modified.
pig additive (D18): npm Piglet source publication.
type NPMSourceOptions ¶
type NPMSourceOptions struct {
// Path is the authored Piglet YAML file.
Path string
// Workspace anchors workspace-bound Piglet inputs during validation.
Workspace string
// NPMName overrides the published package name. The default is the name in a package.json beside the Piglet, then the Piglet's own name.
NPMName string
// PackageMap maps a Package alias to the npm reference that replaces its source.
PackageMap map[string]string
// Binaries is recorded in the generated package.json when the release has signed Binaries.
Binaries *NPMBinaries
}
NPMSourceOptions selects the authored Piglet and the publication choices that its YAML cannot express.
type OverlayBase ¶
type OverlayBase struct {
// Piglet is the Binary's baked Piglet. Resolution never modifies it. When the Binary has a frontend member compiled in,
// Slots.Frontend names it (the baked bytes carry no slots), so extends.remove.slots can start the Binary without it.
Piglet *Piglet
// Digest is the digest of the baked Piglet's bytes, the identity the Binary's record and signed manifest vouch for.
Digest string
}
OverlayBase is the Piglet a Piglet Binary that is not built closed bakes, offered as the implicit base of the Piglet a user selects at launch (--piglet, PIG_PIGLET_PATH, PIG_PIGLET_NAME).
pig additive (D202): a Piglet Binary can declare that it accepts overlay Piglets.
type Piglet ¶
type Piglet struct {
Name string `yaml:"name"`
Description string `yaml:"description,omitempty"`
Extends *ExtendsSpec `yaml:"extends,omitempty"`
BuiltinTools *[]string `yaml:"tools,omitempty"`
Packages map[string]string `yaml:"packages,omitempty"`
Extensions []ExtensionEntry `yaml:"extensions,omitempty"`
Skills []SkillEntry `yaml:"skills,omitempty"`
Discovery *Discovery `yaml:"discovery,omitempty"`
ContextFiles string `yaml:"contextFiles,omitempty"` // pig additive (D211): trusted-only withholds an untrusted project's context files.
SystemPrompt *PromptRef `yaml:"systemPrompt,omitempty"`
AgentEnv *AgentEnvironment `yaml:"agentEnv,omitempty"`
Model *ModelConfig `yaml:"model,omitempty"`
Slots *Slots `yaml:"slots,omitempty"`
Build *BuildSpec `yaml:"build,omitempty"`
Release *ReleaseSpec `yaml:"release,omitempty"`
Secrets []SecretDeclaration `yaml:"secrets,omitempty"`
Strip *StripSpec `yaml:"strip,omitempty"` // pig additive (D92): built-ins this Piglet disables at runtime.
// contains filtered or unexported fields
}
Piglet is the top-level piglet YAML structure.
func Clone ¶
Clone returns an independent Piglet value while preserving its resolved source anchors. Runtime caches and locks are intentionally reset.
func ParseBytes ¶
ParseBytes parses and validates piglet YAML from bytes. Unknown keys are rejected to catch typos and unsupported fields early.
func (*Piglet) BakedSkill ¶
BakedSkill reports whether the skill is one the Piglet Binary baked and the overlay left as it was: it has no file, so its location is the Binary's, not the overlay's. It is false for a Piglet that is no overlay.
func (*Piglet) EffectiveAgentEnvironment ¶
func (p *Piglet) EffectiveAgentEnvironment() *AgentEnvironment
EffectiveAgentEnvironment applies semantic defaults without mutating source.
func (*Piglet) FrontendDir ¶
FrontendDir returns the absolute directory of the frontend slot's member, or "" when the Piglet has no frontend member. An inherited member resolves against the Piglet file that names it; the directory must exist inside that file's directory. pig additive (D91): a Piglet frontend member draws the interactive mode.
func (*Piglet) HasFrontend ¶
HasFrontend reports whether the Piglet fills the frontend slot. pig additive (D91): a Piglet frontend member draws the interactive mode.
func (*Piglet) OverlayOf ¶
OverlayOf names the Piglet Binary this Piglet is an overlay of (D202), or reports false when it is not one. A Piglet Binary's baked Piglet is no overlay; one that resolved a Piglet selected at launch is.
func (*Piglet) ResolutionIdentity ¶
func (p *Piglet) ResolutionIdentity() ([]LineageEntry, string, string)
ResolutionIdentity returns copies of the exact lineage and effective/graph digests attached by ResolveEffective. Source-only Piglets return zero values.
func (*Piglet) SourcePath ¶
SourcePath returns the parsed Piglet source path when available.
func (*Piglet) ValidateAgentEnvironmentLaunch ¶
ValidateAgentEnvironmentLaunch reports whether the current runtime slice can launch this Piglet without inspecting machine-local engine availability.
func (*Piglet) ValidateAgentEnvironmentRuntime ¶
ValidateAgentEnvironmentRuntime blocks a Piglet Binary build until the builder can preserve and execute the required whole-process environment. Launch support is checked separately because runtime slices can land before portable Binary/Image execution.
func (*Piglet) WithholdsUntrustedContextFiles ¶
WithholdsUntrustedContextFiles reports whether the Piglet withholds an untrusted project's context files. A nil Piglet does not.
type PigletInfo ¶
type PigletInfo struct {
Name string
Description string
Path string
Location string // "workspace", "user", "system", or "binary"
Records []RecordInfo
}
PigletInfo describes discovered Piglet source and Binary facets.
func List ¶
func List() ([]PigletInfo, error)
List returns all discoverable Piglet rows, merging source and managed Piglet Binary records. Malformed state is an error. pig additive (D41): Piglet inventory includes Piglet Binary facets.
type ProvenanceCheck ¶
type ProvenanceCheck struct {
Source string `json:"source"`
SourceDigest string `json:"sourceDigest"`
PigletDigest string `json:"pigletDigest"`
Matches bool `json:"matches"`
//portlint:allow emptydrop PiG-only format with no Pi counterpart (Pi has no Piglets or runtime slot)
Mismatches []string `json:"mismatches,omitempty"`
}
ProvenanceCheck compares the Piglet digests a Binary's signed manifest records with those recomputed from a source Piglet. PigletDigest is the digest of the Piglet definition the source bakes into a Binary.
func CheckProvenance ¶
func CheckProvenance(manifest signature.Manifest, source, workspace string) (*ProvenanceCheck, error)
CheckProvenance recomputes the source digest of the Piglet named by source and the digest of the Piglet definition it bakes into a Binary, as the build does, and compares them with manifest. workspace anchors workspace: paths as the build's --workspace did (the build defaults to its working directory). A mismatch returns the check and an error naming each differing digest.
type RecordComponent ¶
RecordComponent is one executable component's realization and materialization as recorded in a managed Piglet resolution record's component plan.
type RecordInfo ¶
type RecordInfo struct {
Path string
ResolutionPath string
ArtifactPath string
PigletDigest string
ReleaseVersion string
Target string
ArtifactDigest string
VerificationOK bool
ComponentPlanDigest string
ResolutionDigest string
BinaryDigest string
CurrentPath string
Components []RecordComponent
// Strip lists the built-ins the Binary record says its Piglet strips.
Strip []StrippedID
// StripKeep lists the Binary's keep-mode strip lists and their kept IDs.
StripKeep []StripIDList
}
RecordInfo describes one managed Piglet Binary record/artifact facet.
type ReleaseSpec ¶
type ReleaseSpec struct {
Version string `yaml:"version,omitempty"`
}
ReleaseSpec carries Piglet release identity, separate from portable build defaults. release.version is the distributed artifact's SemVer.
type RemoveSpec ¶
type RemoveSpec struct {
Packages []string `yaml:"packages,omitempty"`
Extensions []string `yaml:"extensions,omitempty"`
Skills []string `yaml:"skills,omitempty"`
// Slots names inherited slots whose member is removed, so PiG's own
// part applies again.
// pig additive (D91): a Piglet frontend member draws the interactive mode.
Slots []string `yaml:"slots,omitempty"`
// Strip re-enables inherited strip entries. It widens the base, so it
// requires allowWiden.
// pig additive (D92): Piglet strip lists.
Strip *StripSpec `yaml:"strip,omitempty"`
}
RemoveSpec names inherited collection members removed before child replacement/addition.
type ResolveOptions ¶
type ResolveOptions struct {
Workspace string
// AllowInstallScripts lets the package manager run the lifecycle scripts of the npm and Git Packages the Piglet names. The zero value installs them with scripts disabled.
//
// pig additive (D194): Piglet resolution installs Packages without running lifecycle scripts unless the user opts in.
AllowInstallScripts bool
// Base, when set, is the Piglet the chain's root implicitly extends: a Piglet Binary's baked Piglet, offered as the base of an overlay selected at launch. The resolved Piglet keeps the base's name and cannot replace, remove or widen what the base baked.
//
// pig additive (D202): a Piglet Binary can declare that it accepts overlay Piglets.
Base *OverlayBase
}
ResolveOptions supplies machine-local anchors that are not portable Piglet identity.
type ResolvedAgentEnvironment ¶
ResolvedAgentEnvironment identifies the concrete image or Dev Container selected by a Piglet environment source.
func ResolveAgentEnvironment ¶
func ResolveAgentEnvironment(p *Piglet) (*ResolvedAgentEnvironment, error)
ResolveAgentEnvironment validates and materializes the optional environment. It does not start an engine or execute lifecycle commands.
type ResolvedExtension ¶
type ResolvedExtension struct {
Entry ExtensionEntry
Path string // Resolved filesystem path
Origin string // The first typed origin that resolved successfully.
}
ResolvedExtension is an extension with its origin resolved to a concrete path.
func ResolveExtensions ¶
func ResolveExtensions(p *Piglet) ([]ResolvedExtension, []error)
ResolveExtensions resolves all extension origins to concrete filesystem paths. pig additive (D18): Package and typed-source origins use the generic side-effect-free install materializer before member selection. Returns resolved extensions and any errors for unresolvable entries.
type ResolvedPackage ¶
func ResolvePackages ¶
func ResolvePackages(p *Piglet) ([]ResolvedPackage, error)
ResolvePackages materializes every declared Package without mutating Package settings and returns its canonical root for lock/record construction.
type ResolvedSecrets ¶
type ResolvedSecrets struct {
// contains filtered or unexported fields
}
ResolvedSecrets contains transient secret values for immediate consumers. It must never be serialized, logged, placed in records/sessions, or returned by inspection APIs.
func ResolveRequiredSecrets ¶
func ResolveRequiredSecrets(ctx context.Context, p *Piglet) (*ResolvedSecrets, error)
ResolveRequiredSecrets resolves every logical secret consumed by the agent environment. Unused declarations remain inspectable without requiring machine-local availability.
func (*ResolvedSecrets) AgentEnvironment ¶
func (r *ResolvedSecrets) AgentEnvironment(p *Piglet) (map[string]string, error)
AgentEnvironment returns child environment variables for declared bindings. Values are copied so callers may zero their map without mutating the resolver.
func (*ResolvedSecrets) Clear ¶
func (r *ResolvedSecrets) Clear()
Clear overwrites transient values and drops references after immediate use.
func (*ResolvedSecrets) RuntimeEnvironment ¶
func (r *ResolvedSecrets) RuntimeEnvironment() (map[string]string, error)
RuntimeEnvironment carries resolved logical values into a verified inner Pig process without exposing values on argv. Keys reveal no logical names.
type ResolvedSkill ¶
type ResolvedSkill struct {
Entry SkillEntry
Path string // Resolved filesystem path
Origin string // The first typed origin that resolved successfully.
}
ResolvedSkill is a skill with its origin resolved to a concrete path.
func ResolveSkills ¶
func ResolveSkills(p *Piglet) ([]ResolvedSkill, []error)
ResolveSkills resolves all skill origins to concrete filesystem paths.
type SecretDeclaration ¶
type SecretDeclaration struct {
Name string `yaml:"name"`
From SecretSource `yaml:"from"`
}
SecretDeclaration declares a logical secret name and exactly one machine- local source. Values never enter portable Piglet state.
type SecretSource ¶
type SecretSource struct {
Env string `yaml:"env,omitempty"`
File string `yaml:"file,omitempty"`
Ref string `yaml:"ref,omitempty"`
}
SecretSource is the closed env|file|ref source union.
type SetChange ¶
type SetChange struct {
//portlint:allow emptydrop PiG-only format with no Pi counterpart (Pi has no Piglets or runtime slot)
Added []string `json:"added,omitempty"`
//portlint:allow emptydrop PiG-only format with no Pi counterpart (Pi has no Piglets or runtime slot)
Removed []string `json:"removed,omitempty"`
//portlint:allow emptydrop PiG-only format with no Pi counterpart (Pi has no Piglets or runtime slot)
Changed []string `json:"changed,omitempty"`
}
SetChange lists the names a Piglet adds, removes and alters against its base.
type SkillEntry ¶
type SkillEntry struct {
Name string `yaml:"name"`
Origins []string `yaml:"origins,omitempty"` // Required unless Content is embedded.
Description string `yaml:"description,omitempty"`
Content string `yaml:"content,omitempty"`
}
SkillEntry represents a skill with an origin.
func (*SkillEntry) UnmarshalYAML ¶
func (s *SkillEntry) UnmarshalYAML(node *yaml.Node) error
UnmarshalYAML handles the bare skill-name shorthand.
type SlotMember ¶
type SlotMember struct {
// Member is the member's directory, relative to the Piglet file that
// names it.
Member string `yaml:"member"`
// contains filtered or unexported fields
}
SlotMember is the member that fills one slot.
type Slots ¶
type Slots struct {
// Frontend is the frontend member: a Go module whose root package
// exports func Frontend() frontend.Frontend. The native builder fuses
// it into the Binary.
Frontend *SlotMember `yaml:"frontend,omitempty"`
}
Slots names the members that replace a part of PiG. A child Piglet inherits each slot, replaces a slot by naming it, or removes one with extends.remove.slots. pig additive (D91): a Piglet frontend member draws the interactive mode.
type StripDelta ¶
type StripDelta struct {
// FromPigVersion is the version of the core that built the Binary.
FromPigVersion string
// ToPigVersion is the running core's version.
ToPigVersion string
// Added counts the IDs the running core's table adds.
Added int
// LeftOut names the added IDs a keep-mode list strips, as slot IDs.
LeftOut []string
// NowIncluded names the added IDs a deny-mode list leaves enabled.
NowIncluded []string
}
StripDelta is the change of the strip table since a Piglet's newest Binary.
func (StripDelta) Lines ¶
func (d StripDelta) Lines() []string
Lines renders the report: one header line, then the two lists when the table adds an ID.
type StripIDList ¶
StripIDList is one strip list's IDs: a keep-mode list's kept IDs, or the list's part of the generated strip table.
func StripTable ¶
func StripTable() []StripIDList
StripTable returns the running core's generated strip table, one entry per list in manifest order. A Binary record keeps it, so a later core can name the built-ins it adds.
func (StripIDList) Field ¶
func (l StripIDList) Field() string
Field names the list as in a Piglet's strip key: tools, commands, extensions, apis or features.
type StripKeep ¶
type StripKeep struct {
Tools *[]string `yaml:"tools,omitempty"`
Commands *[]string `yaml:"commands,omitempty"`
Extensions *[]string `yaml:"extensions,omitempty"`
APIs *[]string `yaml:"apis,omitempty"`
Features *[]string `yaml:"features,omitempty"`
}
StripKeep names the built-ins each keep-mode list keeps. A nil list is in deny mode; an empty list keeps nothing. It has no keep key of its own.
type StripSpec ¶
type StripSpec struct {
Tools []string `yaml:"tools,omitempty"`
Commands []string `yaml:"commands,omitempty"`
Extensions []string `yaml:"extensions,omitempty"`
APIs []string `yaml:"apis,omitempty"`
Features []string `yaml:"features,omitempty"`
Keep *StripKeep `yaml:"keep,omitempty"`
}
StripSpec names the built-ins a Piglet strips. Every entry is a stable ID from the generated strip ID table (strip_ids_generated.go): a built-in tool name, a slash command written with its leading slash, a built-in extension name, a model API, or a feature ID.
Each list is in deny mode (the list names what is stripped) or in keep mode (Keep names what stays; every other ID of that list in the table is stripped, including IDs a later core adds). One list is never in both modes in one Piglet file. Parsing expands keep mode against the running core's table, so a parsed or resolved spec also carries the stripped IDs of a keep-mode list in the deny field, and every consumer reads the deny fields alone.
func (*StripSpec) BuildTags ¶
BuildTags returns the sorted build tags that compile the stripped built-ins out of a Piglet Binary.
func (*StripSpec) HasFeature ¶
HasFeature reports whether the spec names the feature ID. The builder and manifest validation read a Piglet's spec with it; the running process asks pigstrip.Has, which Record fills.
func (*StripSpec) IsEmpty ¶
IsEmpty reports whether the spec strips nothing and keeps no list in keep mode. A nil spec is empty.
func (*StripSpec) KeepLists ¶
func (s *StripSpec) KeepLists() []StripIDList
KeepLists returns each keep-mode list with its kept IDs, in manifest order. A spec without keep mode returns nil.
func (StripSpec) MarshalYAML ¶
MarshalYAML writes the spec as a Piglet file states it: a keep-mode list writes its keep list and not its expansion, so a baked Piglet re-expands against its Binary's own table and parses again.
func (*StripSpec) Record ¶
func (s *StripSpec) Record() (undo func())
Record records every entry of the spec in pigstrip, the process's one strip state, as a Piglet Binary's OFF shims record the built-ins it compiled out. The returned function undoes the records this call added.
func (*StripSpec) StrippedIDs ¶
func (s *StripSpec) StrippedIDs() []StrippedID
StrippedIDs returns every stripped built-in in canonical order: tools, commands, extensions, APIs, then features, each sorted by ID, with the disposition a Piglet Binary gives it.
type StrippedID ¶
StrippedID is one stripped built-in.
func (StrippedID) SlotID ¶
func (id StrippedID) SlotID() string
SlotID names the stripped built-in by its manifest path, the strip list and the ID: tools.grep, commands./share, extensions.mcp, features.themes.
type ToolInfo ¶
type ToolInfo struct {
Name string
Source string
// Namespace is the tool's namespace name, `mcp__<server>` for a built-in MCP tool (extension.McpNamespace). Empty when the tool has none.
Namespace string
}
ToolInfo is the minimal metadata needed for Piglet tool scoping.
type TreeNode ¶
type TreeNode struct {
Name string `json:"name"`
Version string `json:"version,omitempty"`
Location string `json:"location,omitempty"`
Source string `json:"source,omitempty"`
Installed bool `json:"installed"`
Current bool `json:"current"`
External bool `json:"external,omitempty"`
Children []*TreeNode `json:"children"`
}
TreeNode is one Piglet in the extends tree. Installed means a built Piglet Binary is recorded for it; Current means the environment selects it (PIG_PIGLET_NAME or PIG_PIGLET_PATH). External marks a base that is named by an `extends` but is not in the inventory. pig additive (D170): `pig piglet tree` reports the inventory `pig piglet list` reads, arranged by `extends`.
Source Files
¶
- active_source.go
- bake.go
- container_path.go
- distribution.go
- extends.go
- lineage.go
- lineage_cli.go
- main.go
- monorepo_add.go
- npmsource.go
- origin.go
- origins.go
- overlay.go
- prune.go
- pull_cli.go
- resolve.go
- runtime.go
- schema.go
- scope.go
- scope_summary.go
- scope_table.go
- secrets.go
- signing_cli.go
- strip.go
- strip_delta.go
- tree_cli.go
- types.go
- update_cli.go
Directories
¶
| Path | Synopsis |
|---|---|
|
Package artifact defines executable Piglet component plans and artifact records.
|
Package artifact defines executable Piglet component plans and artifact records. |
|
internal
|
|
|
genstripids
command
Command genstripids writes internal/pigstrip/ids_generated.go, the table of stable IDs a Piglet strip list may name, and the matching ID enums of coding/piglet/piglet.schema.json.
|
Command genstripids writes internal/pigstrip/ids_generated.go, the table of stable IDs a Piglet strip list may name, and the matching ID enums of coding/piglet/piglet.schema.json. |
|
Package release verifies and installs signed Piglet Binary releases.
|
Package release verifies and installs signed Piglet Binary releases. |
|
Package signature signs and verifies Piglet Binaries.
|
Package signature signs and verifies Piglet Binaries. |