The language, from literals to loops.

A program is a sequence of top-level declarations. Mark a declaration export to publish it, and import { ... } from "file.mh" to bring named declarations in from another file, optionally under a local alias. import is the only cross-file mechanism.

TWO-FILE EXAMPLE

export agent Echo {
    command: "echo"
    args: ["${prompt}"]
}

export prompt Greeting(name: string) {
    "Hello, ${name}!"
}

import {Echo, Greeting as Hello}
    from "shared.mh"

pipeline Welcome {
    input name: string
    step Run {
        log(Echo.run(
            prompt: Hello(name: name)
        ))
    }
}

MHL uses blocks, does not require semicolons, and allows object fields to be separated by commas or line breaks. Comments start with //.

LITERALS

var absent = null
var enabled = true
var attempts = 3
var temperature = 0.2
var timeout = 45s
var title = "feature audit"
var message = """
Multiline text with ${title}.
"""
var tags = ["security", "backend", 2026]
var job = {
    id: 42
    status: "pending"
    metadata: { priority: 1, owner: "platform" }
}

DECLARABLE TYPES

tool Catalog {
    first(items: {id: number, tags: string[]}[]): {id: number, tags: string[]} -> items[0]
}

pipeline Import {
    input records: {id: number, active: bool}[]
    step Count { log(records.size()) }
}

TYPE ALIASES

type Name = <type> names a type expression so a repeated or verbose shape is written once. An alias is only a spelling — it resolves to exactly the type its target denotes, adds no distinct type, and is usable anywhere a : type annotation is (inputs, parameters, returns, shape fields). Aliases may reference other aliases. A cycle, a duplicate name, an unknown target, or a name that shadows a builtin keyword is a static error (mhl lint).

type Slug      = string
type Ids       = string[]
type Violation = { code: string, severity: string }

tool Report {
    add(slug: Slug, issues: Violation[]): Ids -> issues.map((v) -> v.code)
}

VALUES AND REFERENCES

Every { … } object and [ … ] array is a value: assigning it, passing it to a lambda or tool, or nesting it in another object hands over an independent copy, so two names never share a structure one of them changes. When sharing is what you want, create a reference object with ref { … } — or ref (expr), from a copy of any object. Every name that holds it sees every change, and == compares identity (the same object), not fields.

var a = { x: 1 }
var b = a
b["x"] = 2              // a.x is still 1 — b is a copy

var counter = ref { n: 0 }
var alias = counter
alias["n"] = 1          // counter.n is 1 — one shared object
counter == alias        // true: same object
ref { n: 1 } == ref { n: 1 }   // false: two objects

obj with { field: value, ... } copies obj and overrides the listed fields on the copy, leaving obj itself untouched — "the same object, except for these fields", without rewriting every other field by hand.

var d = { titulo: "x", avisos: [], outro: 1 }
var d2 = d with { avisos: ["a"] }
// d.avisos is still [] — d2 is a copy with just avisos overridden
// d2.titulo and d2.outro are unchanged: "x" and 1

var chained = { a: 1 } with { b: 2 } with { c: 3 }   // { a: 1, b: 2, c: 3 }, applied left to right

ENUMS

enum Name { A, B, C } declares a closed set of named constants. A value is produced only by qualified access — Name.A — and at run time it is a distinct tagged value, not a string: Status.Draft == "Draft" is false, type_of(Status.Draft) is "enum", and "${Status.Draft}" / json.stringify render the bare variant (Draft). : Name is a type annotation like any other. A match over an enum value is checked for exhaustiveness by mhl lint.

enum Status { Draft, Published, Archived }

pipeline Publish {
    input status: Status
    step Decide {
        var note = match status {
            Status.Draft     -> "hold"
            Status.Published  -> "ship"
            Status.Archived   -> "skip"
        }
        log(note)
    }
}

PRACTICAL GRAMMAR

declaration  := [export] (import | agent | prompt | memory | tool | extension | pipeline | workflow | type | enum | test)
import       := "import" "{" name ["as" alias] {"," name ["as" alias]} "}" "from" string
              | "import" string                                 // whole-file form: merges every declaration, export or not
pipeline     := ["partial"] ["loop"] ("pipeline" | "workflow") identifier ["max" number] "{" {member} "}"
step         := ["entry"] "step" identifier ["timeout" duration] "{" {statement} "}"   // "entry" only valid, and required exactly once, inside a "partial" declaration
extension    := "extension" kind identifier "{" {property} "}"   // kind is "mcp", "a2a" (built in), or an installed adapter's kind
type-alias   := "type" identifier "=" type
enum         := "enum" identifier "{" [identifier {"," identifier}] "}"
variable     := "var" identifier "=" expression
constant     := "const" identifier "=" expression   // single-assignment; reassigning is an error
assignment   := lvalue ("=" | "+=") expression   // "+=" is sugar for `x = x + expr`
property     := identifier ":" expression                        // declaration-body properties are newline-separated, not comma-separated
call         := expression "(" [argument {"," argument}] ")"
array        := "[" [expression {"," expression}] "]"
object       := "{" [key ":" expression {","? key ":" expression}] "}"
parameters   := parameter {"," parameter}
parameter    := identifier [":" type] ["=" expression]   // default: used when a caller omits the argument
lambda       := "(" [parameters] ")" "->" (expression | block)
if-expr      := "if" "(" expression ")" expression "else" expression
match-expr   := "match" expression "{" {(pattern | "_") "->" expression} "}"   // pattern: Enum.Variant or a bool/number/string literal
optional     := expression "?." identifier      // null / non-object / missing-field safe
optional     := expression "?." "[" expression "]"  // same, with a dynamic key
coalesce     := expression "??" expression      // left unless it is null
with-expr    := expression "with" object        // copy of expression with object's fields overridden; chains left to right

Expressions produce values. They compose inside variables, arguments, properties, conditions, returns, and string interpolation.

PRECEDENCE — LOWEST TO HIGHEST

var ready = retries < 3 && files.size() > 0
var label = if (ready) "ready" else "blocked"
var total = price * quantity + shipping
var dynamic = record[field_name]
var slice = numbers[1..^1] // index 1 through one before the end
var text = "${label}: ${total}"

// `?.` reads through null, a non-object, or a missing field without raising;
// `?.[key]` is the same with a dynamic key; `??` supplies a default only
// when the left side is null.
var target = metric?.target?.trim() ?? ""
var retries = config?.retries ?? 3       // 0 stays 0 — only null is replaced
var field  = record?.[name] ?? null      // no `is_object(record)` guard needed

MATCH

match is a multi-way branch in expression position. Arms are tried top to bottom; the first whose pattern is deep-equal to the subject (the same comparison == uses) wins, or the _ wildcard. A pattern is an Enum.Variant or a bool/number/string literal. A match over an enum or bool with no _ arm must cover every case — mhl lint flags a missing one; any other subject relies on a runtime error if nothing matches.

var tier = match http_status {
    200 -> "ok"
    404 -> "missing"
    _   -> "error"
}

VALUE METHODS

DETERMINISTIC SELECTION EXAMPLE

var passed_ids = [10]
var features = [
    {id: 20, status: "pending", priority: 2, depends_on: [10]},
    {id: 30, status: "pending", priority: 1, depends_on: [99]},
    {id: 40, status: "pending", priority: 3, depends_on: []}
]

var ready = features
    .filter((f) -> f.status == "pending")
    .filter((f) -> f.depends_on
        .filter((d) -> !passed_ids.contains(d))
        .is_empty())
    .sort_by((f) -> f.priority)

var next = ready.find((f) -> f.id == 20)

Statements perform actions inside a step, a tool method, a block lambda, or a test case.

tool Summary {
    count_valid(items: {valid: bool}[]): number {
        var count = 0
        for (var item in items) {
            if (item.valid) count = count + 1
        }
        return count
    }
}

pipeline SafeRead {
    step Read {
        try {
            var config = json.parse(fs.read("config.json"))
            log.info("mode:", config.mode)
        } catch (err) {
            log.warn("invalid configuration:", err)
        } finally {
            log.info("read completed")
        }
    }
}

if (flag) return
log.info("unreachable")   // parse error: read as `return log.info(...)`, not two statements

Declares an AI backend callable through .run(prompt: ...). The runtime supports local CLI processes and models served by Ollama.

CLI AGENT

agent Claude {
    engine: "cli/claude-code"
    command: "claude"
    args: [
        "-p", "${prompt}",
        "--output-format", "json",
        "--json-schema", "${schema}"
    ]
    retry: {
        max_attempts: 3
        delay: 2s
        retry_on: [500, 503, "timeout", "rate_limit"]
    }
    cache: { ttl: 10m, storage: "disk" }
    rate_limit: { requests_per_minute: 20, concurrency: 2 }
}

CLI AGENT — PROMPT VIA STDIN

// Codex CLI reads its prompt from stdin when the positional argument is
// "-" — keeping an unboundedly large prompt (e.g. concatenated source
// documents) entirely out of argv, which matters on Windows specifically
// (see the WINDOWS tip below). `--output-schema` still takes a file path
// per Codex's own CLI, not inline JSON — `stdin:` only removes the prompt
// from argv, not a schema a given backend requires as a file.
agent Codex {
    engine: "cli/codex"
    command: "codex"
    args: ["exec", "-"]
    stdin: "${prompt}"
}

// Claude Code CLI's `-p` argument is a fixed instruction, not the content
// itself — the large piece (a document, a wiki page) goes through `stdin:`
// as separate reference material `-p` refers to. See the PROMPT INJECTION
// tip below before writing that material as anything that reads like a
// command rather than data to summarize.
agent Claude {
    engine: "cli/claude-code"
    command: "claude"
    args: ["-p", "Summarize the document piped on stdin in exactly one sentence."]
    stdin: "${prompt}"
}

OLLAMA AGENT AND CALL

agent LocalCoder {
    engine: "ollama/qwen2.5-coder"
    endpoint: "http://localhost:11434"
    temperature: 0.1
    fallback: [
        agent {
            command: "echo"
            args: ["fallback: ${prompt}"]
        }
    ]
}

var schema = """
{"type":"object","properties":{"summary":{"type":"string"}}}
"""
var raw = LocalCoder.run(
    prompt: "Summarize the change.",
    schema: schema
)
var result = json.parse(raw)

BEFORE / AFTER HOOKS

An agent is a single-shot CLI process — it cannot decide mid-generation to call a tool or an MCP server. before/after are how the pipeline does that calling on the agent's behalf: real values, fetched before the prompt exists, not a hope the model reads and acts on an instruction.

agent Reviewer {
    command: "claude"
    args: ["-p", "${prompt}"]

    before: () -> {
        return {
            issue: GitHub.call("get_issue", { number: 42 }),
            diff: execution.git_diff()
        }
    }
    after: () -> {
        log("review is ${result.size()} characters")
    }
}

var review = Reviewer.run(
    prompt: "Issue: ${issue}\nDiff: ${diff}\nWrite a review."
)

• A hook body is an ordinary expression scope: it calls declared tool/extension/agent names, native ops (http, cmd, …) and mem the same way a step does. Both hooks take no parameters — a leftover (mcp, tools) -> is an error.
• Reads the caller's variables; writes never come back. Like any lambda, a hook closes over the scope that issued the .run(...) call — a step's, or an intermediary tool method's — as a one-time snapshot, not a live view: the body sees each captured variable's value as it stood when the hook started, but a bare name = ... assignment inside the body is accepted with no error and simply never reaches the caller's real variable, at any call depth — even called directly from a step, with no tool in between. A hook's only way to actually hand data back is its own return value (below), or an external effect it performs itself (a tool/extension call, mem).
• before's returned object's fields become real "${...}" bindings available to that call's prompt:/schema: arguments — the one channel a hook has for handing structured data back to its caller.
• after runs once, against whichever leg — the primary agent or a successful fallback — produced the final response, with it bound in the body as result. Its return MUST be a string or nothing: a non-null string replaces the response, no return (or an explicit null) passes it through unchanged, and any other type — an object included — raises "<Agent>.after must return a string (or nothing), got <type>". Unlike before, after cannot hand back structured data through its return value.

SKILLS

A skill (§08) is a reusable instruction package loaded from a Markdown file. skills: on the agent is an allow-list; run(skills: [...]) selects a subset of it, in call order; system_prompt is the only place that selection actually reaches the outgoing request.

skill CodeReview from "code-review.md"
skill SecurityReview from "security-review.md"

agent Reviewer {
    command: "claude"
    args: ["-p", "${prompt}"]
    skills: [CodeReview, SecurityReview]

    system_prompt: (skills, prompt) -> {
        var instructions = ""
        for (var s in skills) {
            instructions = instructions + "## " + s.frontmatter.name + "\n" + s.content + "\n\n"
        }
        return instructions + prompt
    }
}

var review = Reviewer.run(
    skills: [CodeReview, SecurityReview],
    prompt: "Review this diff."
)

• A call that never writes skills: at all never invokes system_prompt — the request sent is exactly what prompt: resolves to, identical to an agent with no skills feature in play, even on an agent that declares both skills: and system_prompt.
• system_prompt's first parameter is a list of {name, frontmatter, content} objects, one per selected skill, in call order. name is the skill's MHL declaration identifier — the same string nameof(CodeReview) resolves to, so a hook can compare by identity (s.name == nameof(CodeReview)) instead of a free-floating string. frontmatter is the parsed frontmatter block (frontmatter.name/frontmatter["name"] both work); content is the Markdown body with the frontmatter stripped out.
• Selecting a skill the agent didn't permit, repeating one, or naming one that isn't declared all fail before any model call — in both mhl lint and mhl run.
• Retry and fallback reuse the exact same already-composed prompt: system_prompt runs once, before the primary attempt, never per retry and never again for a fallback leg.

Declares a decision layer over a set of already-declared agents and exposes two methods: .delegate(prompt: ...), that picks which one should handle a given prompt and runs it — the same call shape as agent.run(...), with routing built in — and .select(prompt: ...), that resolves the same decision without running the chosen agent, for a caller that needs to know the answer first. The LLM decision call is optional: a router that declares only select is a purely deterministic router.

HYBRID DECISION

agent Billing {
    command: "claude" args: ["-p", "${prompt}"]
    description: "Handles invoices, billing questions, and refunds"
}
agent Support {
    command: "claude" args: ["-p", "${prompt}"]
    description: "Handles account access and technical issues"
}
agent Judge { engine: "cli/claude-code" command: "claude" args: ["-p", "${prompt}"] }

router Frontdesk {
    agents: [Billing, Support]

    // Tried first: a deterministic hook over the prompt text. A match
    // skips the LLM decision call entirely. nameof(Billing) — not the
    // string literal "Billing" — so a typo here is caught by mhl lint.
    select: (prompt) -> {
        if (prompt.contains("invoice")) { return nameof(Billing) }
        if (prompt.contains("refund")) { return nameof(Billing) }
        return null
    }

    // Used only when select is absent or returns nothing that names a
    // declared agent: Judge is an ordinary, independently declared agent
    // — nothing about its call configuration is duplicated on the
    // router — sent one "pick one of these agents" decision call built
    // from the prompt already passed to .delegate(...).
    decider: Judge
}

var reply = Frontdesk.delegate(prompt: "My invoice is wrong.")

PURELY DETERMINISTIC — NO LLM CALL AT ALL

router Frontdesk {
    agents: [Billing, Support]

    // No decider declared at all: there is no decision call to cascade
    // to, so select alone must be exhaustive.
    select: (prompt) -> {
        if (prompt.contains("invoice")) { return nameof(Billing) }
        return nameof(Support)
    }
}

A named template with parameters. A prompt renders to a string and can be passed to an agent or composed into another prompt.

INLINE AND COMPOSED

prompt Role() {
    "You are a software security reviewer."
}

prompt Review(role: prompt, file: string, code: string) {
    """
    ${role}

    Review ${file}. Return concrete risks and a minimal fix.

    ${code}
    """
}

var request = Review(
    role: Role(),
    file: "auth.go",
    code: fs.read("auth.go")
)

MARKDOWN BODY

# Review of ${file}

## Criteria
- correctness
- security
- compatibility

## Code
${code}

prompt Review(
    file: string,
    code: string
) from "review.prompt.md"

var rendered = Review(
    file: "main.go",
    code: fs.read("main.go")
)

• Prompt arguments are named: Review(file: "x", code: source).
• Missing, extra, or unknown placeholders fail instead of producing incomplete text.
• A parameter may declare a default — prompt Review(file: string, lang: string = "en") — used when the caller omits that named argument. Because prompt binding is by name, defaulted parameters may appear in any position, and a default expression is evaluated in the caller's scope (it cannot reference a sibling parameter).
• Use \${NAME} in external Markdown when a placeholder must remain literal.

FRONTMATTER (FILE-SOURCED ONLY)

---
version: 2
---
# Review of ${file}
${code}

prompt Review(file: string, code: string) from "review.prompt.md"

log(Review.frontmatter.version)     // 2
log(Review.frontmatter["version"])  // 2 — same value, dynamic key

A from "..." file may optionally open with a flat ----delimited frontmatter block — the same shape a skill's SKILL.md uses, but with no required keys, since it carries no runtime meaning of its own here. It is stripped out of the rendered body and reachable as PromptName.frontmatter, an ordinary object. A file with no such block behaves exactly as before this existed — frontmatter is simply an empty object. An inline prompt Name() { "..." } body never has frontmatter.

Declares a reusable instruction package loaded from a Markdown file with frontmatter — the mhl counterpart of Claude's Agent Skills. Always file-sourced; there is no inline skill Name { ... } form. Consumed through an agent's skills: allow-list and system_prompt hook — see §05 agent · SKILLS.

---
name: code-review
description: Review a diff for correctness issues
---
Look for null dereferences and off-by-one errors.

export skill CodeReview from "code-review.md"

• Importable and exportable like any other named declaration: export skill CodeReview from "...", import {CodeReview} from "skills.mh".
• A missing file, a frontmatter block with no name/description, or a file over the size limit all fail at import resolution — before mhl run ever reaches a step that uses the skill.
• Nothing in a skill's Markdown is ever executed. Any effect an agent needs still goes through a before hook calling a declared tool/extension — a skill is instructions only.

Declares a JSON Schema file an agent's structured output must follow. Used as a value, the name is an object with the file's JSON text and its absolute path — the two shapes agent CLIs take a schema in (claude --json-schema '<json>' inline, codex --output-schema <file> by path).

export schema Brief from "schemas/brief.schema.json"

import { Brief } from "schemas.mh"

var inline = Claude.run(prompt: p, schema: Brief.content)
var by_file = Codex.run(prompt: p, schema: Brief.path)

• The value is a plain object {content: string, path: string}: it passes wherever a parameter of that shape is expected, and a local var of the same name shadows it.
• A missing file, invalid JSON, a document that is not a JSON object, or a file over 1 MiB fails at import resolution — reported by mhl lint and before mhl run reaches any step.
• Importable, exportable, and valid in nameof(Brief) like any other named declaration.
• The checkpoint digest covers the schema's content, not its path: editing the schema invalidates --resume, moving the project does not.

memory declares a named store. mem creates a pipeline-scoped persistent variable, ideal for a loop pipeline stop condition.

NAMED MEMORY

memory Session {
    type: "json"
    path: ".mhl/session.json"
}

memory Audit {
    type: "append_log"
    path: ".mhl/audit.log"
}

Session.set("attempt", 1)
Session.set({status: "running", owner: "platform"})
var attempt = Session.get("attempt", 0)
Session.remove("owner")
Audit.append("pipeline started")

PERSISTENT PIPELINE VARIABLE

loop pipeline Poll {
    mem attempts = 0
    mem status = "pending"

    repeat: {
        stop_when: status == "done"
        max_iterations: 10
    }

    step Check {
        attempts = attempts + 1
        status = if (attempts >= 3) "done" else "pending"
        log.info("attempt", attempts, status)
    }
}

• mem name = value uses get-or-init semantics: the initializer runs only when no value exists.
• The value survives between iterations and is visible to repeat.stop_when.
• name.reset() deletes the persisted value; the next access initializes it again.

A tool creates a small, reusable API over native operations. Declare const or var in the tool body for values shared by its methods during a call. Methods take positional arguments, may declare types, and use either an expression body (name(p): T -> expression) or a statement block (name(p): T { ... }). The -> is needed only before an expression; before a block it is optional, since the { already opens the body.

tool Project {
    const test_timeout = 2m
    var directory = "."
    read(path: string): string -> fs.read(path)

    test(package: string): {stdout: string, stderr: string, exit_code: number} ->
        cmd.exec(["go", "test", package], timeout: test_timeout)

    changed_go_files(): string[] {
        var paths = fs.list(directory)
        return paths.filter((path) -> path.ends_with(".go"))
    }
}

var source = Project.read("main.go")
var result = Project.test("./...")
if (result.exit_code != 0) fail(result.stderr)

AVAILABLE OPERATIONS

var result = cmd.exec(["git", "status", "--short"], timeout: 30s)
var response = http.post(
    url: "https://api.example.com/jobs",
    headers: {"Authorization": "Bearer " + env("API_TOKEN")},
    body: {status: "ready"}
)
var jobs = http.get(
    url: "https://api.example.com/jobs",
    query: {"state": "ready", "limit": "50"},
    tls: {cert: "client.pem", key: "client.key"},   // mutual TLS
    proxy: "http://corp-proxy:3128"                  // else HTTP(S)_PROXY is used
)
if (jobs.ok) fs.write("result.json", json.stringify(jobs.json))
http.download("https://api.example.com/artifacts/build.zip", "build.zip")
dir.create("artifacts/reports")                 // idempotent; creates parents
var entries = dir.list("artifacts")             // immediate, sorted paths
dir.clear("artifacts/adr")                      // exists and is empty afterwards
if (dir.exists("artifacts/reports")) dir.delete("artifacts/reports") // empty only
var expires_at = time.add(time.now(), 7d)

dir is the directory-specific companion to fs. dir.create(path) has mkdir -p semantics and succeeds when the directory already exists. dir.exists(path) returns true only for a directory (an existing file returns false). dir.list(path) returns immediate entries as joined paths in filename order. dir.delete(path) removes only an empty directory and raises for a file, missing path, or non-empty directory; it never recursively deletes contents. dir.clear(path) is the one recursive primitive, for regenerating a whole collection: afterwards path exists and is empty — created when absent, everything inside removed when present (a symlink inside is removed itself, never followed). It refuses an empty path, a filesystem root, the working directory or one of its ancestors, and a symlinked path.

var legacy = fs.read("export.csv", encoding: "windows-1252") // decoded to UTF-8
var notes  = fs.read("notes.txt", "auto")                     // BOM / UTF-8 / Windows-1252
fs.write("report.csv", rendered, encoding: "utf-8-bom")      // Excel-friendly
var out = cmd.exec(["tool.exe"], encoding: "ibm850")          // legacy console code page

Strings are always UTF-8 inside mhl. fs.read/fs.write/fs.append and cmd.exec/cmd.exec_all take an optional encoding that transcodes at the boundary: "utf-8" (strict), "utf-8-bom", "utf-16"/"utf-16le"/"utf-16be", "latin1", "windows-1252", any WHATWG or IANA charset name, and — for reading only — "auto". Without it, bytes pass through untouched; read a legacy file with its real encoding before handing it to an agent's stdin:, since strict CLIs reject non-UTF-8 input. See the specification for the exact rules.

time.parse/time.format's layout accepts either a raw Go reference-time layout ("2006-01-02") or the friendlier yyyy/MM/dd/HH/mm/ss tokens (e.g. time.format(dt, "dd/MM/yyyy")) — case matters where a unit would otherwise be ambiguous: MM is always month, mm is always minute; HH is always 24-hour, hh is always 12-hour.

var target = input.repo_dir                       // some checkout, not this one

if (git.status(dir: target).exit_code != 0) fail("${target} is not a git repository")

var diff = git.diff("HEAD", dir: target)
if (!diff.is_empty()) {
    git.add(["src/", ":(exclude).harness"], dir: target)
    var committed = git.commit("chore: sync generated files", dir: target)
    if (committed.exit_code != 0) fail(committed.stderr)
}
var sha = git.rev_parse("HEAD", dir: target)      // short hash, e.g. "0661a80"
var recent = git.log(5, dir: target)             // --oneline text, newest first

git operations run git in the interpreter's working directory — or in a dir: argument when given (every git.* op accepts one; it maps to git -C <dir>), so a pipeline can act on a checkout other than its own. status, add and commit return the same inspectable {stdout, stderr, exit_code} shape as cmd.exec — a non-zero exit is a value to check, not a raised error — while diff, log and rev_parse return plain text and fail closed, raising on a bad ref. add requires at least one path, commit a non-empty message, log a positive count, and rev_parse a non-empty ref; each is validated before git is invoked. commit's message is passed as its own argument, never shell-quoted, so spaces survive intact; diff takes an optional target ref, and status/commit an optional trailing paths filter.

log.info("running as", os.user(), "on", os.hostname())
var cache_dir = fs.join(os.home_dir(), ".cache", "myapp")
dir.create(cache_dir)
if (os.platform() == "windows") { /* ... */ }

extension <kind> <Name> { ...props } declares a use of a runtime capability provider. The core sees only a kind, a name, and a property bag; the adapter registered for that kind validates the properties and defines the methods you call on <Name>. Two kinds ship built in — mcp and a2a, detailed below. Any other kind resolves through an installed external adapter.

Several adapters of one kind — from "<id>"

When more than one installed adapter serves the same kind, pick one per declaration by its manifest id. The kind stays the contract (properties and methods); the id picks the implementation. Without from, a kind served by two installed adapters fails as ambiguous, and mhl extension doctor notes every such kind.

extension data Cache from "mhl.data.redis"    { url: env("REDIS_URL") }
extension data Db    from "mhl.data.postgres" { dsn: env("DATABASE_URL") }

Declares a Model Context Protocol server connection. Configuration supports stdio or HTTP transports and secure environment references. Call it with Server.call("toolName", { ... }), discover its catalog with Server.list_tools(), or inspect it with Server.discover().

extension mcp LocalFiles {
    transport: "stdio"
    command: "npx"
    args: [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "."
    ]
}

extension mcp IssueTracker {
    transport: "http"
    url: "https://mcp.example.com"
    headers: {
        "Authorization":
            "Bearer " + env("MCP_TOKEN")
    }
}

var result = IssueTracker.call("search_issues", { query: "is:open" })
var catalog = IssueTracker.list_tools()
var info = IssueTracker.discover()

• transport: "stdio" uses command and args; each call spawns a fresh process.
• transport: "http" uses url and headers; each call is a fresh, independent request.
• env("NAME") resolves a credential only when needed and keeps it out of source.
• .call(toolName, arguments) issues a JSON-RPC tools/call; .list_tools() issues tools/list; .discover() issues server/discover (supported versions/capabilities/identity), or, against a handshake server, returns the initialize result's identity instead.
• protocol: selects the wire protocol: "auto" (default), "2026-07-28" (stateless only), "2025-11-25" or "2025-06-18" (standard handshake, advertising that revision). Any other value is a build-time error.
• In "auto" mode the stateless 2026-07-28 form is tried first; if the server rejects it with a protocol-incompatibility error (JSON-RPC -32602/-32600, or HTTP 400) the call is retried over the standard initialize / notifications/initialized handshake (advertising 2025-11-25, _meta dropped, Mcp-Session-Id threaded through), letting the server negotiate the version down. If both fail, the error names both attempts.
• On http, .call(...) first checks the target tool's schema for x-mcp-header-annotated arguments (top-level, string/integer/boolean only) and mirrors any present into Mcp-Param-{Name} headers — best-effort: if the schema can't be fetched, the call proceeds without them.
• A server response with resultType: "input_required" (Multi Round-Trip Requests — the server wants elicitation/sampling input) is rejected with a clear error; this client cannot gather and resubmit that input.

Declares a stateless connection to a remote agent that speaks the Agent2Agent (A2A) protocol, revision 0.2.x: JSON-RPC 2.0 over HTTP(S) with header-based auth. Send it a message with Agent.send("..."), read its published capabilities with Agent.agent_card(), and poll or abort a running task with Agent.get_task(id) / Agent.cancel(id).

extension a2a Translator {
    url: "https://translator.example.com/a2a"
    headers: {
        "Authorization":
            "Bearer " + env("A2A_TOKEN")
    }
    poll_interval: 1s     // optional, default 1s
    poll_timeout: 120s    // optional, default 120s
}

var reply = Translator.send("Translate 'hello' to French")
log(reply.text)                       // -> "bonjour"

var card = Translator.agent_card()    // /.well-known/agent-card.json
var again = Translator.send("and to German?", context: reply.context_id)

var status = Translator.get_task(reply.task_id)
var stopped = Translator.cancel(reply.task_id)

• url is the remote agent's JSON-RPC endpoint; headers carry auth, with env("NAME") resolving a credential only when needed and keeping it out of source.
• .send(message, context?) issues message/send with the string as a single text part. If the reply is a Task that is not yet in a terminal state, it polls tasks/get every poll_interval until the task finishes or poll_timeout elapses. context: sets contextId for a follow-up turn.
• The result is a normalized object: a message is {kind: "message", text, parts, message_id, context_id}; a task is {kind: "task", task_id, context_id, state, text, artifacts, history, status}. text is the concatenation of every text part — a convenience; the raw parts/artifacts are still there.
• .agent_card() GETs <origin>/.well-known/agent-card.json. .get_task(id, history_length?) issues tasks/get; .cancel(id) issues tasks/cancel.
• A task that stops in input-required or auth-required is rejected with a clear error — mhl's A2A client cannot gather and resubmit that input.

The executable unit. Inputs arrive through the CLI, pipeline variables are shared across steps, and steps run in declared order. pipeline keeps that order — goto is a lint error. workflow is the same in every other way but allows goto <step>, forward or backward, so its steps form an explicitly branching state machine. Either takes the loop prefix.

RECOVERABLE WORKFLOW

workflow Release {
    input environment: string
    var approved = false

    // No `checkpoint` block needed — per-step checkpointing is on by
    // default, so `--resume` already works. Add one only to tune it:
    //   checkpoint: { ttl: 30d }        // keep abandoned state longer
    //   checkpoint: { enabled: false }  // opt out entirely

    step Validate {
        var result = cmd.exec(["go", "test", "./..."], timeout: 2m)
        if (result.exit_code != 0) fail(result.stderr)
        approved = true
    }

    step Publish {
        if (!approved) goto Validate       // backward jump — needs `workflow`
        log.info("publishing to", environment)
    }
}

STATIC STEP DISPATCH

step Gate {
    if (!approved) pause("review " + artifact)
    goto match artifact {
        "brief" -> BriefCommit
        "adr"   -> AdrCommit
        _ -> fail("unknown artifact: " + artifact)
    }
}

goto match evaluates artifact once and selects the first matching arm. To reuse that table, declare route Generate(artifact: string) { ... } in the workflow and call it with goto Generate(artifact) from any step. A route has one typed parameter and static step destinations; mhl lint checks its name, arity, patterns, and targets. It transfers control directly rather than returning a string. Expression nameof(BriefGenerate) cannot name a workflow step because that builtin checks top-level declarations. On --resume, a paused gate runs again with updated inputs and selects the route then. See sample/syntax/pipeline_vs_workflow/goto_match_artifact_review.mh.

SPLITTING ACROSS FILES

A large workflow — many artifact types, each its own Generate/Commit pair — can outgrow one file. partial splits the declaration, not the pipeline: every fragment sharing a name and the same pipeline/workflow keyword is combined into one declaration before it ever runs, exactly like C#'s partial class. A fragment is pulled in with the bare, brace-less form of import — import "file.mh" — which merges every declaration in that file, not just named/exported ones; that's what lets a fragment join without itself being exported. Because steps and pipeline-scoped vars are looked up by name, a goto in one fragment reaches a step declared in another with no extra wiring.

import "discovery.brief.mh"

partial workflow Discovery {
    var pending_data = null

    entry step Dispatch {
        goto BriefGenerate
    }
}

partial workflow Discovery {
    step BriefGenerate {
        pending_data = { title: "brief" }
        log(pending_data)
    }
}

Because a pipeline otherwise starts at its first physically declared step, and "first" stops meaning anything once steps arrive from more than one file, a partial declaration must mark its real starting point explicitly: exactly one step, anywhere among its fragments, carries the entry keyword — entry step Dispatch { ... } above. entry is rejected outside a partial declaration, where the first step is unambiguous already.

// shared/artifacts/artifact_commit.mh — one tool, reused from every
// workflow's own *Commit step; only the trailing goto stays there.
export tool ArtifactCommit {
    finish(project_id: string, relative: string, title: string, body: string, data: any, tokens_in: number, tokens_out: number): any -> {
        var rendered = PageShell(title: title, body: body, meta: ArtifactMeta.line(time.format(time.now(), "yyyy-MM-dd HH:mm"), "artifacts/" + relative, tokens_in, tokens_out))
        ArtifactData.write(project_id, relative, data)
        fs.write(Paths.artifact(project_id, relative), rendered)
        return { path: "artifacts/" + relative }
    }
}

// Each workflow's own Commit step shrinks to the one thing that's actually
// specific to it (which body renderer, which title) plus its goto:
step BriefCommit {
    discovery_result = ArtifactCommit.finish(project_id, "brief.html", "Brief", ArtifactBody.brief(pending_data), pending_data, tokens_in, tokens_out)
    goto Done
}

READING THE PREVIOUS RUN'S STATE

pipeline BuildCounter {
    context: {
        source: "latest"     // or "session:<id>"; default "latest"
        require: false        // true = fail the run when no prior state exists
    }

    var build = 1

    step Report {
        log.info("session ${context.session_id}, resumed=${context.resumed}")
        if (context.vars.keys().contains("build")) {
            build = context.vars["build"] + 1
        }
    }
}

EXPLICIT RESULT PROJECTION

workflow PublishRelease {
    input environment: string
    var artifact_url  = ""
    var internal_token = ""

    output: {
        url:         artifact_url,          // rename / pick
        environment: environment,           // any expression over the final state
    }

    step Ship {
        artifact_url  = "https://releases.example.com/" + environment
        internal_token = resolve_token()    // stays internal — not in `output:`
    }
}

TYPED SIGNATURE

type Finding      = { file: string, message: string }
type ReviewInput  = { diff: string, base?: string }
type ReviewOutput = { approved: bool, findings: Finding[], summary: string }

workflow ReviewPullRequest(req: ReviewInput): ReviewOutput {
    var findings = []
    var summary  = ""

    step Review {
        var base = req.base ?? "main"            // optional field → null when omitted
        var review = json.parse(Reviewer.run(prompt: "Review against ${base}:\n${req.diff}"))
        findings = review.findings
        summary  = review.summary
    }

    output: {                                    // required alongside a result type
        approved: findings.size() == 0
        findings: findings
        summary:  summary
    }
}

A pipeline/workflow (and its loop form — loop workflow Refine(req: In): Out max 3 { ... }) may declare a signature in the same name(param): Type shape a tool method uses. Both halves are optional and independent; a declaration with neither behaves exactly as before.

LIFECYCLE HOOKS

Five optional body properties observe a run without taking part in it — a lambda of exactly one parameter, called for its side effects (log, mem, a declared tool/extension); its return value is ignored, and returning anything other than nothing at all is a runtime error. Each parameter is bound to one of three builtin, globally declared types — SessionContext, StepContext, FailureContext — the same vocabulary a string/number/bool annotation already resolves through, so session./step./failure. is a real, navigable member access: an editor lists that type's fields the moment you type the dot, with no annotation required (mhl lambdas stay unannotated everywhere else too). The parameter's name is whatever you write — session below is just a convention, not a keyword.

workflow Discovery {
    session_start: (session) -> {
        log("start " + session.session_id + " resumed=" + json.stringify(session.resumed))
    }
    session_end: (session) -> {
        log("end broke=" + json.stringify(session.broke))
    }
    step_start: (step) -> { log("-> " + step.step) }
    step_end:   (step) -> { log("<- " + step.step + " error=" + json.stringify(step.error)) }
    stop_failure: (failure) -> {
        log("FAILED " + failure.step + ": " + failure.error + " (" + failure.reason + ")")
    }

    step Dispatch {
        // Add workflow operations here.
    }
}

LOOP WITH AN EXPLICIT STOP

loop pipeline PollBuild {
    mem status = "pending"
    mem checks = 0

    repeat: {
        stop_when: status == "passed"
        max_iterations: 20
    }

    step Check {
        checks = checks + 1
        var response = http.post(
            url: "https://ci.example.com/status",
            body: {attempt: checks}
        )
        status = json.parse(response.body).status
        if (status == "failed") break "build failed"
    }
}

CONCURRENT SUB-AGENTS IN A STEP

pipeline Review {
    input diff: string
    input changed_files: string[]

    spawn: { max_concurrency: 4 }   // run-wide ceiling; default 4

    step Analyze {
        spawn rev   = Reviewer.run(prompt: "review:\n${diff}")
        spawn tests = Tester.run(prompt: "run the tests for:\n${diff}")
        spawn sec   = Security.run(prompt: "security pass:\n${diff}")

        wait rev, tests, sec timeout: 90s        // wait-all, fail-fast
        // wait any rev, tests, sec              // first success, cancels the rest
        // wait 2 of rev, tests, sec             // first N successes (quorum)
        // wait rev, tests on_error: "collect"   // never fails the step; read .ok / .error

        log(rev.result)
        if (!tests.ok) log("tests failed: ${tests.error}")
    }

    step FanOut {
        // one spawn per element: `item` is bound while each call's arguments
        // are built, so every prompt differs. `reviews` is an array of task
        // handles — `wait` joins it as a group; it indexes and iterates.
        spawn reviews = Reviewer.run(prompt: "review file ${item}") for item in changed_files
        wait reviews timeout: 90s                // or `wait any reviews` / `wait 2 of reviews`
        for (var r in reviews) log("${r.status}: ${r.result}")
    }
}

CONCURRENT STEPS (BARRIER)

pipeline Enrichment {
    input topic: string

    var docs   = ""
    var issues = ""

    parallel Gather timeout 2m {      // both steps run at once; barrier caps at 2m
        step FetchDocs timeout 45s { docs = Docs.run(prompt: "summarize ${topic}") }
        step FetchIssues           { issues = Issues.run(prompt: "open issues for ${topic}") }
    }

    step Merge {                      // runs only after BOTH branches finish
        log("docs   => ${docs}")
        log("issues => ${issues}")
    }
}

MHL files can be self-verifying examples. Each describe receives a fresh environment and uses the same statement syntax as a step.

tool Normalize {
    slug(text: string): string ->
        text.trim().to_lower().replace(" ", "_")
}

test normalize_examples {
    describe basic_slug {
        are_equal(Normalize.slug(" Feature Title "), "feature_title")
    }

    describe array_selection {
        var values = [1, 2, 3, 4]
        var even = values.filter((n) -> n % 2 == 0)
        are_equal(even, [2, 4])
        is_true(even.contains(4))
        is_false(even.contains(3))
    }

    describe future_behavior {
        incomplete("waiting for implementation")
    }
}

RUNNING A WORKFLOW FROM A TEST

Inside a describe block only, Name.run(inputs?: object) — where Name is a declared pipeline/workflow — runs its steps to completion (or to a break/pause/failure) in an isolated, throwaway sandbox and returns the outcome as an object instead of raising, so a test can assert on a workflow expected to fail exactly as easily as one expected to complete.

pipeline GuardedRetry {
    step Implement {
        var attempts = 4
        if (attempts > 3) break "too many attempts"
    }
    step Handoff { var done = true }
}

test guarded_retry_test {
    describe stops_after_too_many_attempts {
        var result = GuardedRetry.run()
        is_true(result.ok)
        are_equal(result.state, "broke")
        are_equal(result.break_reason, "too many attempts")
        are_equal(result.executed, ["Implement"])
    }
}

The mhl binary handles execution, tests, static analysis, and editor integration.

OPERATIONAL CHECKLIST