NILScript

Give an AI agent real power over your systems — and take on zero risk doing it.

NIL (the Network Intent Layer) is the neutral standard for how agents act in real backends:
every write is previewed, approved, fully traced, and one-click reversible — and an agent can only
touch what your backend actually exposes. Hallucinations can't write. OpenAPI for agent-actions.

Why · The numbers · Quickstart · Commands · How it works · Build an adapter · Status

Benchmarks — the numbers

A safety layer is only worth something if the numbers move. We took the
InjecAgent prompt-injection suite (ACL Findings 2024) —
a poisoned tool response tries to hijack the agent into an unauthorized write — and ran every case
twice: the agent calling tools directly (raw), and the same agent routed through NIL
(gated). Same model, same attacks. Only the gate differs.

Read that again. Across 4,216 attacks, on two different models, under both the standard and the
reinforced injection setting, the number of unauthorized writes that reached the backend through NIL
was zero — and it cost nothing: every legitimate task still completed. Raw agents were hijacked
into a real write on up to 1 in 22 cases; NIL committed none of them.

That gap isn't a better prompt or a smarter model — it's structural. A write physically cannot
commit without a previewed propose → approve → commit, and the agent can only name verbs the backend
exposes. Change the model and the raw hijack rate moves; the NIL column stays 0.

Honesty matters as much as the numbers: this harness uses a single-step decision (not InjecAgent's
two-step ReAct), so the raw rates here (0–4.46%) sit below the paper's 24% GPT-4 baseline and are
harness-specific — the comparable, defensible claim is the NIL → 0, always reported next to
100% benign success (never the safety number alone). Full method + the other three axes
(task-success, conformance, performance): docs/benchmarking-plan.md ·
reproduce: bench/.

The one-paragraph version

A raw agent with API keys is a loaded gun: one hijacked prompt, one hallucinated call, and it writes
something irreversible to your production system. NIL puts a thin, neutral layer between the agent and
the backend. The agent can only propose; nothing happens to your data until a proposal is
approved; every effect is traced and carries a reversal handle; and the agent can only name
operations your backend has actually declared — anything else is refused, not faked. You build the
adapter once, and any NIL-speaking agent works against it.

See it in action

A ~10s walkthrough of the Reference Playground: an agent chats to a live backend and you watch a write
go propose → approve → commit → rollback in a real trace — nothing touches the data until you say so.

https://github.com/user-attachments/assets/21ecd97b-5914-4618-b7ca-5f80d0a76467

Prefer to run it yourself? pip install nilscript[demo] && nilscript demo.

Why this exists

New in 0.3.0

• Discovery handshake — every adapter exposes GET /nil/v0.1/describe returning its skeleton: {nil, system, verbs, targets:{name:{exists, fields[]}}}. SDK handshake(transport) connects any client uniformly: reachable → conformant → provisioned.
• PROPOSE preflight — a verb whose native target isn't provisioned is refused at PROPOSE (UPSTREAM_UNAVAILABLE), not failed after COMMIT.
• Generic resource.* family (resource-v1) — create / read / update / delete over any target the skeleton exposes, no per-entity verb authoring. read is a QUERY; writes ride PROPOSE→COMMIT.
• Synthesized reversibility — generic writes reverse with zero per-verb mapping: create→delete, update→restore before-image, delete→recreate, all via the standard ROLLBACK, keyed to the real record id.
• Identifier resolution — update/delete accept a real id or a human identifier (code/name/…), resolved server-side.
• STATUS.result — a COMMIT returns the SSOT result: entity{type,id,url} + ssot{system,read_after_write} + a compensation handle.
• Reference Playground — pip install nilscript[demo] && nilscript demo: chat to a live backend, watch propose→approve→commit→rollback in a real trace.

Quickstart

# 0.3.0 is on PyPI:
pip install "nilscript[cli]"

nilscript verbs                                  # the verb catalog from the standard
nilscript scaffold-shim --name my-nil-adapter    # a bootable shim skeleton for any backend
cd my-nil-adapter && pip install -e ".[dev]" && pytest   # red until you fill 3 files (by design)

Three files become yours — system.py (the one place I/O happens), translate.py (verb ⇄ native),
compensation.py (reversibility). Everything else is generated and identical across adapters.
Or just see it: nilscript demo boots the Playground. Full walkthrough:
docs/contributing-an-adapter.md.

Command tour

nilscript is the toolkit for building and verifying adapters from the standard.

Connect an agent (MCP)

nilscript mcp is one generic MCP server: any MCP-compatible agent connects once and drives any
NIL adapter through governed propose→approve→commit→rollback — and the using-nilscript skill
travels with it (an MCP prompt + resource), so the agent learns the discipline on connect.

pip install "nilscript[mcp]"
nilscript mcp --adapter-url http://127.0.0.1:8099   # point Claude Desktop / Cursor at it (stdio)
# remote (e.g. nilscript.org): uvicorn nilscript.mcp.app:app  →  https://<host>/mcp

The agent gets nil_describe / nil_propose / nil_commit / nil_query / nil_status / nil_rollback
plus a propose_<verb> per exposed verb (the tool list is the skeleton — a hallucinated verb
isn't even on the menu). Only nil_commit writes, and only an approved proposal commits.
Full steps (Claude Desktop config + remote connector): docs/connect-claude.md.

How it works

NIL separates the neutral intent layer from backend reality. An agent speaks NIL to a thin
edge; the edge translates to native calls; every write is two-step.

flowchart LR
    A[Agent / Speaker] -- NIL envelope --> E[Edge<br/>6 endpoints]
    E --> T[translate.py<br/>verb ⇄ native]
    T --> S[system.py<br/>the only I/O]
    S --> B[(Your backend)]
    M[requirements-manifest.json<br/>discovered once] -. pre-fills .-> E
    subgraph Safe write
      P[PROPOSE<br/>no side effects] --> C[APPROVE] --> X[COMMIT<br/>executes] --> R[ROLLBACK<br/>previews reversal]
    end

The two layers:

The ecosystem

Architecture & contribution: adapter-ecosystem-strategy.md ·
contributing-an-adapter.md.

Install

pip install nilscript          # the standard only (JSON + docs) — zero runtime deps
pip install nilscript[cli]     # + the adapter toolkit (scaffold-shim, scan, manifest)
pip install nilscript[sdk]     # + the Python SDK (httpx, pydantic)
pip install nilscript[demo]    # + the reference Playground (FastAPI + LiteLLM)

The standard is language-neutral JSON: a Go/TypeScript/Rust implementer reads the schemas in
src/nilscript/nil/ and src/nilscript/dsl/ directly — no per-language package reserved (the
OpenAPI / JSON-Schema model).

Where it stands

• ✅ 0.3.0 — describe handshake, generic resource.* CRUD, synthesized reversibility, ROLLBACK.
• ✅ 180 kernel tests green; pocketbase adapter 17/17 conformance; cross-repo parity gate in CI.
• ✅ Safety proven on a published benchmark — InjecAgent, 4,216 evals, unauthorized writes via NIL = 0% (see the numbers).
• ✅ Live proof — a real customer + invoice into a live ERPNext, from the standard alone; the reference Playground drives a live PocketBase end-to-end.
• 🚧 Young open standard — not yet battle-tested at merchant scale. We lead with the proof, not traction claims.
• 🚧 PyPI publish staged; install from source for 0.3.0 until it lands.

Paper & citation

NIL is described in a published paper — Unexpressible, Not Filtered: A Structural Framework for
Governing AI-Agent Actions — the Network Intent Layer (ElBasheir A. M. Elkhider, 2026),
archived on Zenodo with a permanent DOI: 10.5281/zenodo.20774491.

If you use or reference NIL, please cite it:

@misc{elkhider2026nil,
  title  = {Unexpressible, Not Filtered: A Structural Framework for Governing AI-Agent Actions --- the Network Intent Layer},
  author = {Elkhider, ElBasheir A. M.},
  year   = {2026},
  doi    = {10.5281/zenodo.20774491},
  url    = {https://doi.org/10.5281/zenodo.20774491}
}

Contributing & community

• Change the standard: CONTRIBUTING.md · GOVERNANCE.md (the spec is extracted from running code).
• Build an adapter: docs/contributing-an-adapter.md → open an Adapter submission issue.
• Security: SECURITY.md (90-day coordinated disclosure). Conduct: CODE_OF_CONDUCT.md.

License

Dual-licensed by artifact class: CC BY 4.0 for specification text, Apache 2.0 for schemas,
conformance vectors, and SDK code. See LICENSE.