Builtin functions

Complete reference for all built-in functions available in Harn.

Output

Type conversion

Runtime shape validation

Function parameters with structural type annotations (shapes) are validated at runtime. If a dict or struct argument is missing a required field or has the wrong field type, a descriptive error is thrown before the function body executes.

fn greet(u: {name: string, age: int}) {
  println("${u.name} is ${u.age}")
}

greet({name: "Alice", age: 30})   // OK
greet({name: "Alice"})            // Error: parameter 'u': missing field 'age' (int)

See Error handling – Runtime shape validation errors for more details.

Result

Harn has a built-in Result type for representing success/failure values without exceptions. Ok and Err create Result.Ok and Result.Err enum variants respectively. When called on a non-Result value, unwrap and unwrap_or pass the value through unchanged.

Example:

let good = Ok(42)
let bad = Err("something went wrong")

println(is_ok(good))             // true
println(is_err(bad))             // true

println(unwrap(good))            // 42
println(unwrap_or(bad, 0))       // 0
println(unwrap_err(bad))         // something went wrong

JSON

Type mapping:

json_validate schema format

The schema is a plain Harn dict (not JSON Schema). Supported keys:

Example:

let schema = {
  type: "dict",
  required: ["name", "age"],
  properties: {
    name: {type: "string"},
    age: {type: "int"},
    tags: {type: "list", items: {type: "string"}}
  }
}
json_validate(data, schema)  // throws if invalid

json_extract

Extracts JSON from LLM responses that may contain markdown code fences or surrounding prose. Handles ```json ... ```, ``` ... ```, and bare JSON with surrounding text.

let response = llm_call("Return JSON with name and age")
let data = json_extract(response)         // parse, stripping fences
let name = json_extract(response, "name") // extract just one key

Math

Trigonometry

Logarithms and exponentials

Constants and utilities

Sets

Set methods (dot syntax)

Sets also support method syntax: my_set.union(other).

String functions

String methods (dot syntax)

These are called on string values with dot notation: "hello".uppercase().

List methods (dot syntax)

Path functions

File I/O

Environment and system

Regular expressions

regex_captures

Returns a list of dicts, one per match. Each dict contains:

• match – the full matched string
• groups – a list of positional capture group values (from (...))
• Named capture groups (from (?P<name>...)) appear as additional keys

let results = regex_captures("(\\w+)@(\\w+)", "alice@example bob@test")
// [
//   {match: "alice@example", groups: ["alice", "example"]},
//   {match: "bob@test", groups: ["bob", "test"]}
// ]

Named capture groups are added as top-level keys on each result dict:

let named = regex_captures("(?P<user>\\w+):(?P<role>\\w+)", "alice:admin")
// [{match: "alice:admin", groups: ["alice", "admin"], user: "alice", role: "admin"}]

Returns an empty list if there are no matches. Throws on invalid regex.

Encoding

Example:

let encoded = base64_encode("Hello, World!")
println(encoded)                  // SGVsbG8sIFdvcmxkIQ==
println(base64_decode(encoded))   // Hello, World!

Hashing

Example:

println(sha256("hello"))  // 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
println(md5("hello"))     // 5d41402abc4b2a76b9719d911017c592

Date/Time

Testing

HTTP

All HTTP functions return {status: int, headers: dict, body: string, ok: bool}. Options: timeout (ms), retries, backoff (ms), headers (dict), auth (string or {bearer: "token"} or {basic: {user, password}}), follow_redirects (bool), max_redirects (int), body (string). Throws on network errors.

Mock HTTP

For testing pipelines that make HTTP calls without hitting real servers.

http_mock("GET", "https://api.example.com/users", {
  status: 200,
  body: "{\"users\": [\"alice\"]}",
  headers: {}
})
let resp = http_get("https://api.example.com/users")
assert_eq(resp.status, 200)

Interactive input

Async and timing

Concurrency primitives

Channels

Atomics

Persistent store

The store is backed by .harn/store.json relative to the script’s directory. The file is created lazily on first store_set. In bridge mode, the host can override these builtins.

LLM

See LLM calls and agent loops for full documentation.

Provider configuration

LLM provider endpoints, model aliases, inference rules, and default parameters are configured via a TOML file. The VM searches for config in this order:

1. HARN_PROVIDERS_CONFIG env var (explicit path)
2. ~/.config/harn/providers.toml
3. Built-in defaults (Anthropic, OpenAI, OpenRouter, HuggingFace, Ollama)

See harn init to generate a default config file, or create one manually:

[providers.anthropic]
base_url = "https://api.anthropic.com/v1"
auth_style = "header"
auth_header = "x-api-key"
auth_env = "ANTHROPIC_API_KEY"
chat_endpoint = "/messages"

[aliases]
sonnet = { id = "claude-sonnet-4-20250514", provider = "anthropic" }

[[inference_rules]]
pattern = "claude-*"
provider = "anthropic"

[[tier_rules]]
pattern = "claude-*"
tier = "frontier"

[model_defaults."qwen/*"]
temperature = 0.3

Timers

Structured logging

Metadata

Project metadata store backed by .burin/metadata/ sharded JSON files. Supports hierarchical namespace resolution (child directories inherit from parents).

MCP (Model Context Protocol)

Connect to external tool servers using the Model Context Protocol. Supports stdio transport (spawns a child process).

Example:

let client = mcp_connect("npx", ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])
let tools = mcp_list_tools(client)
println(tools)

let result = mcp_call(client, "read_file", {"path": "/tmp/hello.txt"})
println(result)

mcp_disconnect(client)

Notes:

• mcp_call returns a string when the tool produces a single text block, a list of content dicts for multi-block results, or nil when empty.
• If the tool reports isError: true, mcp_call throws the error text.
• mcp_connect throws if the command cannot be spawned or the initialize handshake fails.

Auto-connecting MCP servers via harn.toml

Instead of calling mcp_connect manually, you can declare MCP servers in harn.toml. They will be connected automatically before the pipeline executes and made available through the global mcp dict.

Add a [[mcp]] entry for each server:

[[mcp]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

[[mcp]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

Each entry requires:

The connected clients are available as properties on the mcp global dict:

pipeline default() {
  let tools = mcp_list_tools(mcp.filesystem)
  println(tools)

  let result = mcp_call(mcp.github, "list_issues", {repo: "harn"})
  println(result)
}

If a server fails to connect, a warning is printed to stderr and that server is omitted from the mcp dict. Other servers still connect normally. The mcp global is only defined when at least one server connects successfully.

MCP Server Mode

Harn pipelines can expose tools, resources, resource templates, and prompts as an MCP server using harn mcp-serve. The CLI serves them over stdio using the MCP protocol, making them callable by Claude Desktop, Cursor, or any MCP client.

Tool annotations (MCP spec annotations field) can be passed in the tool_define config to describe tool behavior:

tools = tool_define(tools, "search", "Search files", {
  params: { query: "string" },
  handler: { args -> "results for " + args.query },
  annotations: {
    title: "File Search",
    readOnlyHint: true,
    destructiveHint: false
  }
})

Example (agent.harn):

pipeline main(task) {
  var tools = tool_registry()
  tools = tool_define(tools, "greet", "Greet someone", {
    params: { name: "string" },
    handler: { args -> "Hello, " + args.name + "!" }
  })
  mcp_tools(tools)

  mcp_resource({
    uri: "docs://readme",
    name: "README",
    text: "# My Agent\nA demo MCP server."
  })

  mcp_resource_template({
    uri_template: "config://{key}",
    name: "Config Values",
    handler: { args -> "value for " + args.key }
  })

  mcp_prompt({
    name: "review",
    description: "Code review prompt",
    arguments: [{ name: "code", required: true }],
    handler: { args -> "Please review:\n" + args.code }
  })
}

Run as an MCP server:

harn mcp-serve agent.harn

Configure in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "my-agent": {
      "command": "harn",
      "args": ["mcp-serve", "agent.harn"]
    }
  }
}

Notes:

• mcp_tools(registry) (or the alias mcp_serve) must be called to register tools.
• Resources, resource templates, and prompts are registered individually.
• All print/println output goes to stderr (stdout is the MCP transport).
• The server supports the 2024-11-05 MCP protocol version over stdio.
• Tool handlers receive arguments as a dict and should return a string result.
• Prompt handlers receive arguments as a dict and return a string (single user message) or a list of {role, content} dicts.
• Resource template handlers receive URI template variables as a dict and return the resource text.