Module loader 

Blueprint loader (Phase B). Loads a Blueprint from a JSON / YAML file and recursively expands the internal {"$file": "..."} refs.

File-ref expansion

Anywhere inside the JSON value, this form is replaced by the referenced file’s contents as a raw string. Paths are resolved relative to the Blueprint file’s directory:

{ "$file": "prompts/system-writer.md" }

Typical uses:

• Externalising a large prompt out of a flow Step.in: {"op":"lit","value":{"$file":"prompts/x.md"}}.
• Externalising any field inside AgentDef.spec (system_prompt, args, etc.).
• Externalising per-agent or global hints.

Agent-md ref expansion (structured ref)

Specialised ref that expands an agent.md (frontmatter + body) into an AgentDef object:

{
  "agents": [
    { "$agent_md": "agents/domain-researcher.md" }
  ]
}

Where $file returns a raw string, $agent_md runs the file through agent_md_loader::parse and returns a fully-populated AgentDef JSON object with profile.system_prompt, meta, spec, and so on already filled in. Path hygiene matches $file: absolute paths and .. are rejected.

Enums

LoadError

Everything that can go wrong while loading and $file/$agent_md expanding a Blueprint from disk.

Functions

expand_file_refs

default_kind is the fallback used when a $agent_md has no sibling kind — it should already be resolved by upper layers of the four-layer cascade. Callers resolve the BP top-level default_agent_kind and any CLI override before calling this function and pass in the literal kind.

load_blueprint_from_path

Load a Blueprint from a file path. Detects JSON vs. YAML by extension, recursively expands $file refs, and parses the result into a typed Blueprint.

pre_read_default_agent_kind

Pull default_agent_kind out of the raw BP JSON top level. Falls back to the schema’s Default impl (Operator) if the key is missing or its type does not match. This is the first stage of resolving the default kind used inside expand_file_refs when a $agent_md has no sibling kind override.