piglet

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 48 Imported by: 1

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

View Source
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.

View Source
const (
	StripKindTool      = "tool"
	StripKindCommand   = "command"
	StripKindExtension = "extension"
	StripKindAPI       = "api"
	StripKindFeature   = "feature"
)

Strip kinds name the five strip lists in records and `pig piglet show`.

View Source
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.

View Source
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.

View Source
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.

View 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).

View Source
const MCPAdapterExtensionName = extension.McpAdapterEntry

MCPAdapterExtensionName is the Piglet extension entry that governs every MCP tool.

View Source
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

func ActiveByDefaultTools(p *Piglet) []string

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

func ActiveSourceIsPath(value string) bool

ActiveSourceIsPath reports whether an ActiveSourceEnv value names a Piglet file, as opposed to the name of a Piglet Binary.

func ActiveSourceValue

func ActiveSourceValue(p *Piglet, baked bool) string

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

func AgentToolScopeLine(p *Piglet, untrustedProject bool) string

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

func Bake(p *Piglet, pigletDir string) ([]byte, error)

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

func BuildExtensionWithPiglet(initial *Piglet) extension.Extension

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

func BuildExtensionWithToolScope(initial *Piglet, scope *extension.ToolScope) extension.Extension

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

func CheckRemoteAddable(path string) error

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

func CompileToolScope(piglet *Piglet, owner func(extension.ToolInfo) string) *extension.ToolScope

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

func MCPScopeLine(p *Piglet) string

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

func RenderTree(w io.Writer, roots []*TreeNode)

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

func Resolve(nameOrPath string) (string, error)

Resolve finds a piglet by name, checking the resolution order:

  1. Explicit path (already absolute or relative)
  2. PIG_PIGLET_PATH env var
  3. PIG_PIGLET_NAME env var → search paths
  4. Workspace: .pig/piglets/<name>.yaml, only when the project is trusted
  5. User: ~/.pig/piglets/<name>.yaml
  6. 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

func ResolveWithTrust(nameOrPath string, trustOverride *bool) (string, error)

ResolveWithTrust is Resolve with a project trust override: nil defers to the stored decision for the working directory.

func RunCommand

func RunCommand(args []string, stdout, stderr io.Writer) int

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

func ScopeTools(piglet *Piglet, allTools []ToolInfo) []string

ScopeTools returns the names of the registered tools the Piglet keeps, in registry order.

func SetRunningBinary

func SetRunningBinary(fn func() (name string, closed, ok bool))

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

func ShadowedWorkspacePiglet(nameOrPath string, trustOverride *bool) string

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

func StripDeltaReport(name string, current *StripSpec) []string

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

func ToolScopeSummary(p *Piglet) string

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

func ValidateAgainstSchema(yamlBytes []byte) error

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

func ValidateRemoteSource(raw string) error

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

type AgentEnvironmentRuntimeResult struct {
	Continue bool
	Bypassed bool
	ExitCode int
}

AgentEnvironmentRuntimeResult tells the caller whether startup should continue in the current process or terminate with the child engine's status.

func RunAgentEnvironment

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 AgentPigRuntime struct {
	Mode    string `yaml:"mode,omitempty"`
	Version string `yaml:"version,omitempty"`
}

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

type NPMBinaries struct {
	Ref    string `json:"ref"`
	Signer string `json:"signer"`
}

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

func Clone(p *Piglet) *Piglet

Clone returns an independent Piglet value while preserving its resolved source anchors. Runtime caches and locks are intentionally reset.

func Parse

func Parse(path string) (*Piglet, error)

Parse reads and validates a piglet YAML file.

func ParseBytes

func ParseBytes(data []byte) (*Piglet, error)

ParseBytes parses and validates piglet YAML from bytes. Unknown keys are rejected to catch typos and unsupported fields early.

func (*Piglet) BakedSkill

func (p *Piglet) BakedSkill(name string) bool

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

func (p *Piglet) FrontendDir() (string, error)

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

func (p *Piglet) HasFrontend() bool

HasFrontend reports whether the Piglet fills the frontend slot. pig additive (D91): a Piglet frontend member draws the interactive mode.

func (*Piglet) OverlayOf

func (p *Piglet) OverlayOf() (binary string, ok bool)

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

func (p *Piglet) SourcePath() string

SourcePath returns the parsed Piglet source path when available.

func (*Piglet) Validate

func (p *Piglet) Validate() error

Validate checks the piglet for schema violations.

func (*Piglet) ValidateAgentEnvironmentLaunch

func (p *Piglet) ValidateAgentEnvironmentLaunch() error

ValidateAgentEnvironmentLaunch reports whether the current runtime slice can launch this Piglet without inspecting machine-local engine availability.

func (*Piglet) ValidateAgentEnvironmentRuntime

func (p *Piglet) ValidateAgentEnvironmentRuntime() error

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

func (p *Piglet) WithholdsUntrustedContextFiles() bool

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 PromptRef

type PromptRef struct {
	File string `yaml:"file,omitempty"`
	Text string `yaml:"text,omitempty"`
}

PromptRef is either a file path or inline text.

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

type RecordComponent struct {
	Kind            string
	Name            string
	Realization     string
	Materialization string
}

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

type ResolvedAgentEnvironment struct {
	Form  string
	Value string
}

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

type ResolvedPackage struct {
	Alias  string
	Source string
	Root   string
}

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 RuntimeIO

type RuntimeIO struct {
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
	TTY    bool
}

RuntimeIO supplies the streams inherited by the container engine.

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

type StripIDList struct {
	Kind string
	IDs  []string
}

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

func (s *StripSpec) BuildTags() []string

BuildTags returns the sorted build tags that compile the stripped built-ins out of a Piglet Binary.

func (*StripSpec) HasFeature

func (s *StripSpec) HasFeature(id string) bool

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

func (s *StripSpec) IsEmpty() bool

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

func (s StripSpec) MarshalYAML() (any, error)

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

type StrippedID struct {
	Kind        string
	ID          string
	Disposition string
}

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`.

func BuildTree

func BuildTree(inventory []PigletInfo, currentName, currentPath string) ([]*TreeNode, error)

BuildTree arranges the inventory by `extends`, offline: it reads the source files the inventory names. currentName and currentPath are the environment's selection.

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.

Jump to

Keyboard shortcuts

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