@ushiromiya/hoatzin-node

Node.js native bindings for Hoatzin embedding and agent-mode evaluation.

import { AgentEngine } from "@ushiromiya/hoatzin-node";

const engine = new AgentEngine();
const result = engine.eval("(do (println \"hello\") {:answer 42})");

console.log(result.output);
console.log(result.value);

Effect Handlers

Hoatzin effects stay effects at the language boundary. The Node binding installs default fallback handlers for console and random, and embedders can replace or extend those fallbacks with synchronous JavaScript handlers.

import { AgentEngine } from "@ushiromiya/hoatzin-node";

const engine = new AgentEngine();

engine.eval(`(def host (effect (ask [prompt])))`);

engine.registerEffect("host", (call) => {
  const prompt = call.args[0]?.string ?? "";
  return {
    value: {
      kind: "string",
      string: `answer:${prompt}`,
    },
  };
});

console.log(engine.eval(`(host/ask "door?")`).valueText);

Native handlers are fallback handlers: a Hoatzin with-handler for the same effect takes precedence. Handler arguments and return values use tagged HoatzinValue objects; exact integers cross the boundary as decimal strings to avoid JavaScript Number precision loss. JavaScript fallback handlers are resume-only in 0.1.0; use a Hoatzin with-handler when you need prompt-level abort semantics.

reset() clears Hoatzin runtime state and agent lineage. Registered JavaScript handlers are kept on the host side; built-in effect handlers are reinstalled immediately, and user-defined effect handlers are reattached after the effect is declared again.

Agent mode remains available through evalAgent and returns the same structured values plus revision lineage messages.