Documentation
¶
Overview ¶
Package agentcrd contains host-side helpers for managing the obol.org/Agent CRD: building a spec from CLI flags, seeding the per-agent skills dir + SOUL.md on the host (which becomes the data PVC inside the cluster), and thin wrappers around kubectl apply/get/delete. The in-cluster reconciler in internal/serviceoffercontroller is the source of truth for the resulting K8s primitives; this package is just the host-side seam.
Index ¶
- func BuildAgent(name string, opts AgentOptions) map[string]any
- func HostHomePath(cfg *config.Config, name string) string
- func HostLegacySoulPath(cfg *config.Config, name string) string
- func HostNoBundledSkillsMarkerPath(cfg *config.Config, name string) string
- func HostSkillsPath(cfg *config.Config, name string) string
- func HostSoulPath(cfg *config.Config, name string) string
- func ListPersistedManifests(cfg *config.Config) []string
- func ManifestPath(cfg *config.Config, name string) string
- func Namespace(name string) string
- func ParseSkills(csv string) ([]string, error)
- func PersistManifest(cfg *config.Config, name string, manifest map[string]any) error
- func RemoveManifest(cfg *config.Config, name string) error
- func ResumeAll(cfg *config.Config, u *ui.UI)
- func SeedHostFiles(cfg *config.Config, name string, skills []string, objective string, ...) (soulWritten bool, err error)
- func ValidateName(name string) error
- func WriteSoul(cfg *config.Config, name, objective string, overwrite bool) (bool, error)
- type AgentOptions
- type SeedOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildAgent ¶
func BuildAgent(name string, opts AgentOptions) map[string]any
BuildAgent assembles the unstructured Agent manifest for kubectl apply. The reconciler is responsible for filling status; we never write it from the CLI side.
func HostHomePath ¶
HostHomePath is where the agent's .hermes data lives on the host. The cluster mounts this into the Hermes pod via the data PVC; writing SOUL.md/skills here puts them inside the pod automatically.
func HostLegacySoulPath ¶
HostLegacySoulPath is the pre-profile seed path used before Hermes profile casing was aligned. It is read during migration only.
func HostNoBundledSkillsMarkerPath ¶
HostNoBundledSkillsMarkerPath returns the location of the `.no-bundled-skills` marker file inside the agent's Hermes profile. When this file exists, Hermes' installer, `hermes update`, and skill syncs skip seeding bundled skills.
Sub-agents only ever need the narrow, operator-chosen skill subset we layer in via OBOL_SKILLS_DIR; Hermes' ~80 bundled skills (apple-notes, spotify, github-pr-workflow, gif-search, Pokemon-player, …) just bloat the system prompt for an EVM-focused paid service. The marker is the official upstream-supported opt-out; see Hermes docs/user-guide/features/skills.
func HostSkillsPath ¶
HostSkillsPath is the per-agent skills dir. OBOL_SKILLS_DIR points here from inside the pod.
func HostSoulPath ¶
HostSoulPath is where the seeded Hermes identity file lives. Hermes reads uppercase SOUL.md from HERMES_HOME, so keep this path aligned with upstream Hermes profile semantics.
func ListPersistedManifests ¶
ListPersistedManifests returns the agent names with a recorded manifest.
func ManifestPath ¶
ManifestPath returns the host-side record path for an agent's CR manifest.
func Namespace ¶
Namespace returns the namespace for an agent of the given name. Single source of truth: keep callers from spreading "agent-" prefixes through the codebase.
func ParseSkills ¶
ParseSkills splits the CLI-style comma list and validates that every name matches the CRD's skill-name pattern. Empty strings between commas are dropped; nothing is fancy on purpose.
func PersistManifest ¶
PersistManifest writes the applied Agent CR manifest to the host store.
func RemoveManifest ¶
RemoveManifest deletes the host-side record (on `obol agent delete`). Missing file is a no-op.
func ResumeAll ¶
ResumeAll re-applies every recorded Agent CR (namespace first — the controller's namespace handling is part of the reconcile loop that only runs once the CR exists). Called during `obol stack up`, BEFORE sell-offer replay so agent-backed ServiceOffers find their Agent. Best-effort per agent: one corrupt record must not block the rest.
func SeedHostFiles ¶
func SeedHostFiles(cfg *config.Config, name string, skills []string, objective string, opts SeedOptions) (soulWritten bool, err error)
SeedHostFiles writes the chosen skill subset and seeds SOUL.md on the host data path. SOUL.md is only written when missing (or when OverwriteSoul is true).
CONTRACT — sub-agents-for-sale ONLY. This helper also writes the `.no-bundled-skills` marker (see writeNoBundledSkillsMarker), which makes Hermes skip its ~80 bundled skills and run with just the operator-chosen subset. That is correct for a narrow, EVM-focused paid service but WRONG for the stack-managed master agent, which keeps the full bundled set. The master (internal/hermes) seeds its own home via a separate path (it does not call this) and must NEVER be routed through SeedHostFiles, or it would silently lose its bundled skills. The reusable seed primitives this is built from (WriteSoul, embed.WriteSkillSubset) deliberately do NOT write the marker, so the objective-only update path — and any future master-side reuse — stays safe; locked by TestMarkerOnlyWrittenBySeedHostFiles.
Returns whether SOUL.md was written this call so callers can report the difference between "fresh agent" and "existing agent, skills resynced".
func ValidateName ¶
ValidateName reports whether the agent name is valid for both K8s resource naming and the obol.org/Agent CRD pattern.
Types ¶
type AgentOptions ¶
AgentOptions is the host-side projection of AgentSpec used by the CLI.
type SeedOptions ¶
type SeedOptions struct {
// OverwriteSoul forces a SOUL.md rewrite even if one already exists.
// Default false: agent-owned after first reconcile.
OverwriteSoul bool
// ExactSkills removes any previously seeded skill dirs not present in the
// requested set before copying the embedded skill subset.
ExactSkills bool
}
SeedOptions controls how host-side seed data is written.
Source Files