Documentation
¶
Overview ¶
init.go — scaffolding for new pod definitions.
`konareef pod init <name>` creates a minimal pod directory containing a pod.toml that validates against the v0.1 schema, a placeholder system prompt template, and an author-facing README. The generated tree is the fastest possible path from "I want to build a pod" to "I have something `konareef pod validate` accepts."
parse.go — typed-struct decoding for pod.toml documents.
Parse is intentionally permissive: it only catches TOML syntax errors. Missing required fields show up as zero values; conditional constraints (directive.task XOR template, wallet.reuse when strategy=reuse) are the schema's job and surface only via Validate or ParseAndValidate.
Callers that want both typed access AND schema-validation should use ParseAndValidate, which combines the two operations and gives a single place to handle each failure mode.
types.go — typed Go structs that mirror pod.toml v0.1.
These are the canonical client-side representation of a pod definition. Optional sections are pointers so callers can distinguish "absent" from "set to zero value" (matters for spawn-time decisions like whether to apply default budgets vs. explicit zeros).
The struct tags drive BurntSushi/toml decoding via Parse(). The schema validation happens separately in Validate() against the canonical JSON Schema; these types are not the schema's source of truth.
Package pod provides parsing and validation of konareef pod.toml files.
The canonical JSON Schema lives in the reef-core repo at priv/pod/spec_v0_1.schema.json; a vendored copy is embedded here so `konareef pod validate` runs offline without a reef-core round-trip. reef-core remains the authoritative parser at spawn time — local validation is a dev-time UX convenience, not a trust boundary.
Public surface:
- Issue: a single validation problem with a structured path
- Validate(podTOML): validate raw TOML bytes
- ValidateFile(path): read and validate a file
Index ¶
- func Init(opts InitOptions) ([]string, error)
- func ParseAndValidate(podTOML []byte) (Spec, []Issue, error)
- type Budget
- type Context
- type ContextMemory
- type ContextPrompt
- type ContextSkill
- type ContextTool
- type Deliverable
- type Dependencies
- type Directive
- type GPU
- type Hardware
- type Hooks
- type Identity
- type InitOptions
- type Input
- type Inputs
- type Issue
- type Marketplace
- type Model
- type Output
- type Predicate
- type Runtime
- type Spec
- type Wallet
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Init ¶
func Init(opts InitOptions) ([]string, error)
Init scaffolds a new pod directory according to opts. Returns the list of files written (in deterministic order) on success, or a descriptive error if the name is invalid, the directory already exists, or any filesystem write fails.
The function is atomic-on-success in the sense that the destination directory is checked for existence up front: a partial scaffold can still leave files behind if a write fails midway, but the pre-flight check ensures Init never overwrites an existing pod tree.
func ParseAndValidate ¶
ParseAndValidate decodes podTOML into a Spec AND validates the original bytes against the embedded v0.1 schema. Returns the parsed Spec, any schema issues (empty when valid), and a non-nil error only when the TOML is malformed or the embedded schema fails to compile.
The parsed Spec is returned even when issues is non-empty — the caller can choose to surface a partial typed view alongside the issue list.
Typical usage in spawn-flow callers:
spec, issues, err := pod.ParseAndValidate(podTOML)
if err != nil {
// malformed TOML or programmer error in the embedded schema
}
if len(issues) > 0 {
// render issues to user; refuse to spawn
}
// spec is well-formed AND validated; proceed.
Types ¶
type Budget ¶
type Budget struct {
MaxSats int `toml:"max_sats,omitempty"`
PerCallCapSats int `toml:"per_call_cap_sats,omitempty"`
DailyCapSats int `toml:"daily_cap_sats,omitempty"`
}
Budget is the [budget] table — sat-denominated spend caps.
type Context ¶
type Context struct {
Memory []ContextMemory `toml:"memory,omitempty"`
Skills []ContextSkill `toml:"skills,omitempty"`
Tools []ContextTool `toml:"tools,omitempty"`
Prompts []ContextPrompt `toml:"prompts,omitempty"`
}
Context is the context table — pre-loaded memory, skills, tools, and prompts injected before the directive fires.
type ContextMemory ¶
type ContextMemory struct {
Kind string `toml:"kind"`
Snapshot string `toml:"snapshot,omitempty"`
Path string `toml:"path,omitempty"`
URL string `toml:"url,omitempty"`
Content string `toml:"content,omitempty"`
}
ContextMemory is one [[context.memory]] entry.
type ContextPrompt ¶
ContextPrompt is one [[context.prompts]] entry.
type ContextSkill ¶
type ContextSkill struct {
Source string `toml:"source"`
Version string `toml:"version,omitempty"`
}
ContextSkill is one [[context.skills]] entry.
type ContextTool ¶
type ContextTool struct {
Source string `toml:"source"`
Config map[string]interface{} `toml:"config,omitempty"`
}
ContextTool is one [[context.tools]] entry.
type Deliverable ¶
type Deliverable struct {
Path string `toml:"path"`
Description string `toml:"description,omitempty"`
Optional bool `toml:"optional,omitempty"`
}
Deliverable is one [[output.deliverables]] entry.
type Dependencies ¶
type Dependencies struct {
System []string `toml:"system,omitempty"`
Runtime []string `toml:"runtime,omitempty"`
Secrets []string `toml:"secrets,omitempty"`
}
Dependencies is the [dependencies] table — system, runtime, and secret requirements resolved at spawn time. Secrets are *names only*; values come from reef-core's vault.
type Directive ¶
type Directive struct {
Task string `toml:"task,omitempty"`
Template string `toml:"template,omitempty"`
MaxIterations int `toml:"max_iterations,omitempty"`
ToolsAllowed []string `toml:"tools_allowed,omitempty"`
ToolsDenied []string `toml:"tools_denied,omitempty"`
}
Directive is the [directive] table — the mission. Exactly one of Task or Template must be set; this is enforced by the schema.
type GPU ¶
type GPU struct {
Kind string `toml:"kind"`
Count int `toml:"count"`
VRAMGiB int `toml:"vram_gib"`
Model string `toml:"model,omitempty"`
}
GPU is the [hardware.gpu] sub-table.
type Hardware ¶
type Hardware struct {
CPUCores int `toml:"cpu_cores,omitempty"`
Memory string `toml:"memory,omitempty"`
Disk string `toml:"disk,omitempty"`
GPU *GPU `toml:"gpu,omitempty"`
}
Hardware is the [hardware] table — minimum resource requirements.
type Hooks ¶
type Hooks struct {
PreSpawn string `toml:"pre_spawn,omitempty"`
PostSpawn string `toml:"post_spawn,omitempty"`
OnSuccess string `toml:"on_success,omitempty"`
OnFailure string `toml:"on_failure,omitempty"`
}
Hooks is the [hooks] table — escape-hatch shell scripts at lifecycle points. Marketplace audits should flag any pod that uses these.
type Identity ¶
type Identity struct {
Name string `toml:"name"`
Version string `toml:"version"`
Authors []string `toml:"authors,omitempty"`
License string `toml:"license,omitempty"`
Description string `toml:"description,omitempty"`
Homepage string `toml:"homepage,omitempty"`
Tags []string `toml:"tags,omitempty"`
// LineageID is the 16-byte cross-session salt-lookup key, encoded
// as a 32-character lowercase hex string. Set once at genesis by
// `konareef pod init`. Type-C pods may ignore it; Type-D pods
// require it to resolve lineage-scoped salt material.
LineageID string `toml:"lineage_id,omitempty"`
}
Identity is the pod table — author-facing metadata.
type InitOptions ¶
type InitOptions struct {
// Name is the pod identifier — must match the v0.1 schema identifier
// pattern. Required.
Name string
// Dir is the output directory. Defaults to "./<Name>" when empty.
Dir string
// Runtime is the runtime kind written into [runtime].kind. Defaults
// to "lobster" when empty.
Runtime string
// Model is "<provider>/<name>" written into [model]. Defaults to
// "anthropic/claude-sonnet-4-5" when empty. If no "/" is present
// the entire string is treated as the model name and the provider
// defaults to "anthropic".
Model string
}
InitOptions controls pod scaffolding. All fields except Name have sensible defaults applied by Init when left empty.
type Input ¶
type Input struct {
Type string `toml:"type"`
Required bool `toml:"required,omitempty"`
Description string `toml:"description,omitempty"`
}
Input is one [inputs.<name>] descriptor. v0.1 exposes only the fields callers need for prompt rendering and required-input enforcement; type- specific constraints (default, min, max, pattern, values) are validated at the schema layer and not surfaced through this struct yet.
type Inputs ¶
Inputs is the [inputs] table — typed parameters callers pass at spawn. Maps the input name to its definition.
type Issue ¶
Issue describes a single validation problem.
Path is a dotted path into the pod.toml document with bracket notation for array indices, e.g. "context.skills[0].source". An empty Path means the issue applies to the whole document (e.g. a missing top-level key).
Message is a human-readable description of what went wrong.
func Validate ¶
Validate parses podTOML as a pod.toml document and checks the result against the embedded v0.1 schema.
It returns a slice of Issues (empty when the document is valid) and a non-nil error only when:
- podTOML is not parseable as TOML, or
- the embedded schema itself fails to compile (a build/programmer bug).
Schema-validation failures are returned as Issues, not as errors, so callers can render them as a list to the user rather than aborting.
func ValidateFile ¶
ValidateFile reads the file at path and validates it. The path argument is included in any I/O error returned for context.
type Marketplace ¶
type Marketplace struct {
Listed bool `toml:"listed,omitempty"`
PriceModel string `toml:"price_model,omitempty"`
PriceSats int `toml:"price_sats,omitempty"`
PreviewURL string `toml:"preview_url,omitempty"`
Icon string `toml:"icon,omitempty"`
Screenshots []string `toml:"screenshots,omitempty"`
Categories []string `toml:"categories,omitempty"`
}
Marketplace is the [marketplace] table — discovery + commerce metadata.
type Model ¶
type Model struct {
Provider string `toml:"provider"`
Name string `toml:"name"`
MaxTokens int `toml:"max_tokens,omitempty"`
Temperature *float64 `toml:"temperature,omitempty"`
ProviderOpts map[string]interface{} `toml:"provider_opts,omitempty"`
}
Model is the [model] table — selects the LLM driving the runtime. Temperature is a pointer because 0.0 is a valid explicit value distinct from "not set".
type Output ¶
type Output struct {
Format string `toml:"format,omitempty"`
Success []Predicate `toml:"success,omitempty"`
Failure []Predicate `toml:"failure,omitempty"`
Deliverables []Deliverable `toml:"deliverables,omitempty"`
}
Output is the [output] table — success/failure predicates and deliverables. Used by reef-core to decide when a pod is "done".
type Predicate ¶
type Predicate struct {
Kind string `toml:"kind"`
Path string `toml:"path,omitempty"`
Count int `toml:"count,omitempty"`
Pattern string `toml:"pattern,omitempty"`
Value int `toml:"value,omitempty"`
Tool string `toml:"tool,omitempty"`
Script string `toml:"script,omitempty"`
}
Predicate is one [[output.success]] or [[output.failure]] entry. Kind discriminates which other fields are meaningful (e.g., kind="file_exists" requires Path; kind="min_words" requires Path+Count; kind="timeout_seconds" requires Value).
type Spec ¶
type Spec struct {
PodSpecVersion string `toml:"pod_spec_version"`
Pod Identity `toml:"pod"`
Runtime Runtime `toml:"runtime"`
Model *Model `toml:"model,omitempty"`
Hardware *Hardware `toml:"hardware,omitempty"`
Dependencies *Dependencies `toml:"dependencies,omitempty"`
Context *Context `toml:"context,omitempty"`
Inputs Inputs `toml:"inputs,omitempty"`
Directive *Directive `toml:"directive,omitempty"`
Output *Output `toml:"output,omitempty"`
Budget *Budget `toml:"budget,omitempty"`
Wallet *Wallet `toml:"wallet,omitempty"`
Hooks *Hooks `toml:"hooks,omitempty"`
Marketplace *Marketplace `toml:"marketplace,omitempty"`
}
Spec is the top-level pod.toml document.