mhl-language

mhl language

mhl is a declarative language for AI agent pipelines: agents, tools, memory, MCP servers, prompts, and the pipelines that wire them together. It reads like TypeScript, and that resemblance is where most bugs come from. Trust this file and the compiler over your priors.

The other mhl-* skills go deeper: mhl-workflows (steps, branching, resume), mhl-agents (agents, prompts, routers), mhl-tools (tools, native ops, memory, extensions), mhl-testing, mhl-serving. Every native op and value method is in references/stdlib.md.

The verification loop

mhl is the source of truth. Run this loop on every change:

1. mhl lint <file-or-dir> until it prints No problems found.
2. mhl test <file-or-dir> until it exits 0.
3. mhl run <file> --dry-run --input key=value to validate the input contract and see the step plan. It executes nothing.

A plain mhl run launches real agents and real side effects, so treat it as a deliberate action, not a syntax check.

When mhl is missing, ask before installing it (install.sh from github.com/mh-language/mhl-core-runtime), and state plainly that any .mh you hand over without it is unverified.

Lint is not complete. It misses the traps marked (lint silent) below, so a clean lint does not prove those. Cover them with a test.

File shape

A file is a flat list of declarations: import, agent, router, prompt, skill, schema, memory, tool, extension, pipeline, workflow, type, enum, test. Any of them can carry export. Statements live only inside a step, a tool method, a lambda body, or a describe block, so reference snippets showing a bare var x = 1 are excerpts of one of those.

// Comments are // only.
agent Writer {
    command: "echo"            // swap for a real CLI such as "claude"
    args: ["${prompt}"]
}

prompt Greeting(name: string) {
    "Write a greeting for ${name}."
}

tool Text {
    slug(value: string): string -> value.trim().to_lower().replace(" ", "-")
}

pipeline Main {
    description: "Writes a greeting and logs its slug."
    input name: string
    var reply = ""

    step Greet {
        reply = Writer.run(prompt: Greeting(name: name))
    }

    step Report {
        log(Text.slug(reply))
    }
}

test main {
    describe greets_by_name {
        var result = Main.run(inputs: {name: "Ada"})
        are_equal(result.state, "completed")
        are_equal(result.executed, ["Greet", "Report"])
        is_true(result.vars.reply.contains("Ada"))
    }
}