Reference implementation of the Neander v1 runtime.

The Grotto runtime executes Neander programs as an embeddable TypeScript library on Node.js. Neander is a small, safe-by-construction language designed for AI agents to generate programs that implement API-calling logic for enterprise systems.

The name: The language name references the Neanderthal — whose first fossil was unearthed from a grotto, the place "where the Neanderthal lived" — so Grotto is where Neander programs live and run.

Programs are submitted as source text and executed in an isolated worker thread under strict, configurable resource budgets — compute, memory, duration, source size, and nesting depth among them. Every submission returns a structured response envelope describing the return value or the precise way it failed.

Status: Early release (v0.1.0) tracking a draft language spec (v1_draft). Public interfaces are unstable and may change without notice before 1.0. This is a security-critical runtime — correctness, immutability, and spec conformance take priority. Provided as is, without warranty (see LICENSE); evaluate and review it yourself before relying on it in production.

Features

• Embeddable library API for host applications.
• Isolated execution — each non-trivial submission runs in its own worker thread with a fresh import of the configured API Provider Modules, so one submission can never observe or influence another.
• Enforced budgets — compute ("Thalers"), memory, duration, per-call timeout, source size, nesting depth, repeat-loop limit, and an optional cap on concurrent executions.
• Structured envelopes — success, language reference, flaw, error, and abort results, with exact serialization of arbitrary-precision integers.

Requirements

• Node.js >= 22.13.0

Install

This package is not yet published to npm. To use it from source:

git clone https://github.com/newadventuresinit/grotto.git
cd grotto
npm install
npm run build

Quick Start

import { Runtime, stringifyEnvelope } from 'grotto1';

const runtime = await Runtime.start({
  config: {
    neanderVersion: 1,
    thalerBudget: 5000,
    memoryBudgetKb: 2048,
    maxDurationMs: 10_000,
    perCallTimeoutMs: 3000,
    maxProgramSizeBytes: 65_536,
    maxNestingDepth: 64,
    maxRepeatLimit: 1000,
    // Absolute paths to modules implementing ApiProviderModule.
    apiProviderModules: [],
  },
});

const envelope = await runtime.submitProgram('');
console.log(stringifyEnvelope(envelope));

Runtime.start() validates the configuration and every API Provider Module before returning a ready instance. submitProgram(source) returns a ResponseEnvelope. Use stringifyEnvelope to serialize an envelope to JSON when the result may contain arbitrary-precision integers.

Demo HTTP Server

The runtime package does not ship a public HTTP transport. A source-tree demo server is included for local trials and for the eval harness. After building:

npm start
# Grotto demo HTTP server listening on http://127.0.0.1:3000

Submit a program with an HTTP POST. An empty body returns the Reference Response (the Neander Reference document plus the active configuration):

curl -X POST --data '' http://127.0.0.1:3000/

The demo server (scripts/serve.mjs) starts the runtime with a sample configuration and no API Provider Modules. Edit it — or write your own embedding — to add providers and tune budgets. PORT and HOST are honored.

Security: the demo server has no authentication by design. Production network exposure is the embedding application's responsibility.

Project layout

Path	Contents
src/	Runtime source and co-located *.test.ts tests.
src/adapters/	Repository-local demo/eval HTTP harness.
src/worker/	Worker-thread interpreter pipeline (lexer, parser, interpreter, …).
src/e2e/	End-to-end suite, grown toward a Neander conformance test suite.
scripts/serve.mjs	Runnable demo HTTP server (npm start).
arch/	Architecture specification (arc42) and C4 model (Structurizr DSL).
design/	Technical design document, catalogs, and backlog.
reference/	The Neander Reference document served by the runtime.
eval/	Agent eval harness — can a cold-start agent discover the API and complete tasks against a live runtime? (see eval/README.md).

Development

npm run build          # tsc
npm test               # build, then run the test suite over dist/
npm run test:watch     # watch mode
npm run test:coverage  # c8 coverage over the full suite

Tests use node:test + node:assert/strict, are co-located with source as *.test.ts, and run against the compiled dist/ output. Coverage is a single unified c8 gate over all of src. See CLAUDE.md / AGENTS.md for contributor guidance and CONTRIBUTING.md for the workflow.

License

Apache License 2.0 © 2026 New Adventures in IT and contributors.