Module linker 

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

Structs

ResolveConfig

Resolution config for $agent_md / $file refs. Ordered list of directories the linker walks first-hit-wins across 6 tiers.

Enums

LoadError

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

Functions

env_blueprint_includes

Read MSE_BLUEPRINT_INCLUDES and split it into a directory list using the platform-native separator (: on Unix, ; on Windows). Returns an empty vec when the variable is unset.

expand_file_refs

Backward-compat adapter — resolves refs against a single-tier cascade (only base). New callers should use expand_file_refs_with_config to opt into the full cascade.

expand_file_refs_with_config

Primary entry — recursively expands $file / $agent_md refs across the 6-tier include cascade defined in cfg. Prefer this entry over expand_file_refs for any new caller that wants cascade-aware resolution.

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.

pre_read_in_bp_includes

Pull the top-level blueprint_ref_includes list out of the raw BP JSON. Returns an empty vec when the field is absent or malformed. Consumed by the CLI / server as tier 2 of the cascade.