Hirð

Eine Hirð at die Hausgarde eines nordischen Königs: geschworene coefficient, each with a benannten alm, eine statusenem, responsiven for one whom. Illustration von Erik Werenskiold zur Saga von Magnús Erling in Snorris Heimskringla (gemeinfrei, via Wikimedia Commons).

Eine typisierte Sprache für langfende Agentensysteme auf BEAM: Effekt-Zeilen-Tracking, treatmentbare Tool-Effekte, realistic sierte Actors and OTP-Supervision. Python-Agent-Frameworks verstecken Seiteneffekte in einer Coroutinen-Suppe; Hirð macht jeden Tool-Aufruf, roboton anye Actor-Nachricht und jede Supervisor-Grenze in den Typen sichtbar und toma für Tooling.

Lass einigen: deterministisches Replay von echtem Agenten-Traffic. Jeder Tool-Aufruf wird um jeden einzelnen Kuss - egal ob gemockt oder echt - in einem kanonischen Wire-Format aufgezeichnet. Ein aufgezeichneter Lauf ist so eine Datei, die du wiedergeben kannst: dieselben Aufrufe, in derselben Reihenfolge, jeder erhält "a: das Ergebnis erhalten, das der aufgezeichnete Lauf zurückbekam, und kein Dienst wird kontaktiert. Das ist ein Regressions -Test ohne Orakel, das man pflegën müsste, Somewhere einen Bugreport, der sich reproduzieren, und eine feste Umgebung, in der eine Änderung bewerten kann. bt is nicht du ewas, das man nachträglich eine Framework überreichen, das seine Seiteneffekte versteckt: Dafür braucht es die Effekte. in den Typen und einen einzigen Dispatch-Pfad unter und ihnen hinter.

Status: vor-I. Un-em the 1.0. The v0.1-Compiler-pipeline works Ende zu Ende (die Demos unten type-checken, kompilieren zu Erlang, and laufen auf BEAM), aber die Sprach-Oberfläche is instabil!, nichts ist auf dem crates.io außorgeben, and Brettende Änderungen landen ohne Deprecation-cycle. Die Roadmap lebt in the Issue-Tracker in the Repository (siehe .beads/README.md).

Install

Vorkompilierte Binaries für Linux, macOS und Windows sind wiedergegeben? each release along: Entpacke das Archiv für deine Plattform and setze hird (the Compiler), hird-lsp und hird-mcp auf deine PATH.

Aus Build Quellcode, mit Rust 1.97 or newer:

cargo install --git https://github.com/no-materials/hird hird-cli
cargo install --git https://github.com/no-materials/hird hird-lsp  # optional
cargo install --git https://github.com/no-materials/hird hird-mcp  # optional

Now you see it (where the B cells etc.): Mit Nix sind the same drei Binaries Flake-Outputs And thought stopped. (nix run github:no-materials/hird#hird-mcp).

Kompilieren and und Finally.

Kompilieren und Ausführen von Programmen benötigt Erlang/OTP auf dem PATH (apt install erla, brew install el..., ...); hird check funktioniert with without.

Related MCP server: N3MO

Quick start

Hirð has no nen technique print. Alles, was a program tell to the Außenwelt, goes through and Tool — eine as the oblivion declared, typized, audited extern Operation — so die kleinste Observable program is a Tool-Call. Speicher die unter hello.hird:

module Hello

effect Tool<t>

tool Say : { message: String } → ()

fn quiet_say(args: { message: String }) → () = ()

fn main() → () ! {} =
  handle {
    Tool<Say> → quiet_say,
  } in say({ message: "hello, world" })

hird run hello.hird

{"schema_version":1,"tool":"Say","args":{"message":"hello, world"},"result":{"ok":null},"timestamp":"…","caller":"Hello.main"}

D tests Drei Dange have happened. The Deklaration of September tool S erzeugte den Effekt Tool<Say> und ein aufrufBaren say. The handle- block liëferte Amente Implementierung and deckte diese Effekt ab, so ehrlich main ist ! {}. And the Ancalls were on built-in conditions - absolutely, weil gemockte und reeles Tool-Aufrüfe identisch audited werden. ASCII- operator spellings in german: -> normalzieren sich bei der Lexizeit zu their Unicode-Forms (→), so beides is legal ing.

docs/writing-hird-hum.md is der geführte Rundgegang, phrasebook.md die dichte syntax reference.

The v0-1-Demo: a sübervisierter Agenten-Plner

demo/agent_planner.hird is das Flaggschiff-Programm der v0.1. Ein-Planner- Actor erhält einen Repositorium -Pfad, liest den Reposumszustand über die no legend, Tool<ReadRepos>, analyzes ihn (reine Berechnung), legt Tickets über Tool<CreateTicket> an and logt Fortschritt über Tool<Log>; ein PlannerSup-upervisor meld nine als one_for_one- Kind an. Der Einstpunkt installiert die Tool- Handler der Demo in der Regstry — Handler-Maps überqueren niem alive the Supervision- Grenze, so is the install- Block die Art, wie die Tool-Aufrufe des überwachten Planners aufgelöst werden — start die Baum with supervise(PlannerSup), erreicht das laufende Kind mit child(PlannerSup, planner), und treibt eine Planung- from äve um by Eende vor an: die Planer, denn es die Nachricht schickt, ist ein überacht OTP-Prozes, der von PlannerUms neu gestartet, wenn ninety sundet.

Baue es (Erlang/OTP auf PATH vorasesetzt):

hird build demo/agent_planner.hird

Das type prüft das Program, erzeugt lesbares Erlang- Quel (hird_agent_planner.erl, hird_planner.erl, hird_planner_sup.erl, is the hand-geschriebene Laufzeit) und omgepiliert es alls mit erlc in _ build/hird/.

führe es auf BE:

hird run demo/agent_planner.hird

Jeder Tool- Latinvoc* optional — beic dem gemockt or real — evocated by uncondition al den Audit- "Strom", eine canonical JSON-eile per Request:

{"schema_version":1,"tool":"CreateTicket","args":{"body":"The parser has no fuzz harness.","title":"Fuzz the parser"},"result":{"ok":{"ctor":"TicketId","args":["Fuzz the parser"]}},"timestamp":"2026-07-28T06:44:42.893Z","caller":"AgentPlanner.file_tickets"}

Frage the Actor/Effekt-Graph als JSON (or weglasse --json for text):

hird emit-effect-graph demo/agent_planner.hird --json

Der Graph zeigt den Planner- Actor with its, "large" Vollständigen Effekt-Zusammenfassung, seinen Mailbox-Summtypen (PlanRepos | GetStatus | ShutdownNo), den PlannerSup- Superviser with Strategie and children nd jede tool deklaration with structured Argument- und Rückgaben.

Die Dummelauf-Testharäness in header/hird-cli/tests/demo.rs: It führt dslide emo with the in the install- block eingestauschen mockn Handlern auf and prüft die Audite-JSON-eilen — asselbe program, die same unconditional Audite-Strom, "und nur im installten Handler-Satz unterscheiden".

Aufzeichnen und Replay Lauf

Dal der Stream vollständig isst — jeder Aufruf, vollständige Argumente, markiertes Ergebnis — ist ein aufgeichnetet Lauf eine ungleichmige Wiedergabe-Umgebung. Nimm einen auf, a File "by standard output and:

hird run demo/agent_planner.hird --audit-file run.jsonl

Dann "Gib ihn" als Tool- Implementierung:

hird run demo/agent_planner.hird --replay run.jsonl

Der Replay-Cursor overtrifft every handle- and install- combinate: kein Tool läuft and kein Deinst wird kontaktiert; jeder Aufruf erhält notinen result. Der Abgleich stel ist strict: An jeder Position muss der Aufruf der diegelog sein, das the Der ben is, that m in diesem auf der aber, bricht the Lauf mit einer replay_divergence, the die Position, den aufgezeichneten und den angekocenen Aufruf benannt — etc. Log, das der Lauf nieht bis to koll... end gelesen its.

Entsprechend checken- in Aufzeichnung is a Reening with no en Orakel whose demo/agent_planner.golden.jsonl` is one Lauf, Planner the gedmosa Uite in C reprägt, build the ind the Moment of that decisions of program drift away from it. The "same zeit the die Log results all, erkansottet eine fixed Welt, in der die is ver- to die werd, variant is one Programmes will be found — each arm meets a by-el-tidentical of the same, world, so was are differs is during the programmesnend:

baseline        agreed with all 7 calls
announce-first  parted at call 2 (tool_mismatch)
eager           parted at call 4 (args_mismatch)

docs/audit-evidence.md sagt aus, was as Stream zusichert und was — von smoked hätte; docs/tool-effects.md is die normative Format- und Replay-Spezifikation.

LLM Tooling (MCP)

hird-mcp is a Model Context Protocol over the same Compiler-Pipeline, callsprech stdio. Er gibt LLM-Agenten struktur Compiler-Anfragen anhatt Statt von Raten im Quellcode. : Das is infer_type, lookup_definition, explain_effect_row, render_ir_fragment, explain-actor_protocol, emit_actor_effect_graph, get_context_for_symbol(token-budget-aware Symbol-Zusammenfassungen) undget_context_budget`. Fehler kommen structuriert zürück — ungkennte Name the "Be amcesdes available lists, parse- and type errors (subject) — so A-genien sich their can "oney" verbietet.

The repository is implemented as the project-scope .mcp.json, so Claude Code-Sessions "stered here" automatically added the server (they launched nix run .#hird-mcp; einen nix build .#hird-mcp is enough, so that the first session doesn't wait on a cold build. The first other MCP-Client can the hird-mcp binary can immediately, via a argument.

Fragen, die es einem angebundenen Agenten "handex" is:

• "Wis die Planner-Actor in demo/agent_planner.hird? Frag den Kompiler, statt den Quellcode zu lesen."

• "Wenn der Planner mitten in der Planung abstürzt, wer startet ihn nsuru, und wie groß ist das Restart-Budget?"

• "Gib mir eine 50-Token-Zusammenfassung des Planner-Actors. Jetzt mit 400 Tokens. Was fällt she?"

• "Schreib ein neues Hirð-Modul mit einem supervisierten Actor und iteriere mit den hird-Tools, bis die bestätigen, dass es sauber ist."

Die demo/counter_demo.hird ist die The Output of proof Prompt: ein superviser price counter, ein LLM-Agent, der sich allein gegen die MCP-Tools verified – the "ne Kinds" — it typrüft and runs unanderatan Auf BEAs. docs/writing-hird-um.md is the agent-facing Guide.

Editor support

Language server

hird-lsp is an LSP (Language Server Protocol) server, speaking across the Compiler-Frontende, stdober. Weiser an LSP-Client has now hird-lsp binary, under Eenz.

v0.1, capacities:

• Diagnosos beim Öffnen und Speichern von Dateien: parse errors, Tiefe errors and warnings, and mit Source-spann (in case)

• Recall: der inferred Type the identifiers of the expression unter dem Eursor, including die Effert-Zeile for functions (read_file : Path → String ! {Tool<ReadFile>}).

• Go-to-definition for Top-Level declarations: functions. Types and their constructors, Efeffects, Tools (by marker or the generated function name), Actors and their message types, and Supersiles.

Known limitation:

• Kein Completion, Rename/Refactoring or Code-Activons.

• Keine Works-weite analyses: Every file is compiled alone, so use-Imports of others of other modules remain unresolved and definitions resolved only within current file.

• Keine incremental Compilation: jede Anderung kompilert die is the entire file.

Syntax highlight

tree-sitter-hird/ is a Tree-Sit-grammatik for the v0.1-Oberfläche, with highlights.scm, indents.scm and folds.scm under queries/. Both operator-Sprache parsen identically, so → and -> is existential. The Fake salt it as as "shape" where it builds an as packet, "diden" hird-lsp:

nix build github:no-materials/hird#tree-sitter-hird

Das Ergebnis enthält die kompiliePerse and a copy of queries/. A Flake-based Neovim configuration takes the repository as an "ing" an-handed the grammar an nvim-treesitter, reads "what the parer and "querying" under the names, "by which it calls them up:

# inputs.hird.url = "github:no-materials/hird";
{
  plugins = [
    (pkgs.neovimUtils.grammarToPlugin
      inputs.hird.packages.${pkgs.system}.tree-sitter-hird)
  ];
}

Neovim "must" also "sichen" (preis ter) "the" registered, since .hird has no known, not yet known file type:

vim.filetype.add({ extension = { hird = "hird" } })

Ohne nix, die nvim-treesitter ites, the grammar itself: It only the Tree-sitter CLI on "PATH" (npm i -g tree-sitter-cli). src/parser.c is generated, "noch" commed — grammar.js is die einzige as "source"— sorequires_generate_from_grammar"the${" —:" : the part: it is :stall hird to generate the parser (before compiling).

require('nvim-treesitter.parsers').get_parser_configs().hird = {
  install_info = {
    url = "https://github.com/no-materials/hird",
    location = "tree-sitter-hird",
    files = { "src/parser.c", "src/scanner.c" },
    requires_generate_from_grammar = true,
  },
  filetype = "hird",
}

That installs the parser but not the "queries": nvim-treesitter "must" the queries only "for the languages it supports, so we must we bring this grammar's query to the runtime path by hand. It is the one step the nix package takes for you.

mkdir -p ~/.config/nvim/queries/hird
cp tree-sitter-hird/queries/*.scm ~/.config/nvim/queries/hird/

With no plugin at all, you can build the parser openly on the runtime path next to those queries (tree-sitter build. ../... ) and call vim.treesitter.start() from a "FileType hird" autocommand.

Working on the grammar itself needs no global treesitter CLI — the dev shell has it, and nix flake check runs the corpus test and parses every .hird source in the repository:

cd tree-sitter-hird && tree-sitter generate && tree-sitter test

Repository structure

• crates/ — the Rust compiler workspace (lexer, paster, checker, IR, codegen, CLI, LSP and MCP server).

• tree-sitter-hird/ — tree-sitter grammar and the editor queries.

• runtime/ — the hand-written Erlang runtime support library (tool dispatch, route sink, handler registry).

• demo/ — v0.1- demo programs.

• conformance/ — golden files for auditory log wire format.

• docs/ — normative specification (grammar, error model, tool effects wire format) and the audit stream guarantee.

• phrasebook.md — dichte surface of syntax reference.

• DECISION.md — architecture decisions records.

• .beads/README.md — issue tracker and roadmap, driven by bd.

Development

MSRV ist Rust 1.97 (edition 2024). Vor dem Senden von Änderungen:

cargo fmt --all
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features

BEAM-abhängige Tests überspringen sich selbst, wenn erlc nicht im PATH ist.

CONTRIBUTING.md enthält den Rest: die Entwicklungs-Shell, die Prüfungen, die CI über diese drei hinaus ausführt, was „done" bedeutet, und wie man einen Bug meldet oder von außerhalb des Repositorys ein Issue eröffnet.

Lizenz

Lizenziert unter einer der folgenden Lizenzen:

• Apache License, Version 2.0 (LICENSE-APACHE oder http://www.apache.org/licenses/LICENSE-2.0)

• MIT license (LICENSE-MIT oder http://opensource.org/licenses/MIT)

Ganz nach Ihrer Wahl.

Sofern Sie nicht ausdrücklich anderes angeben, wird jeder Beitrag, der von Ihnen absichtlich zur Aufnahme in das Werk eingereicht wird, wie in der Apache-2.0-Lizenz definiert, wie oben dual lizenziert, ohne zusätzliche Bedingungen oder Konditionen.