Get Started

What is NILScript?

NILScript is a server-side governed-action contract for AI agents: the agent proposes intent, a deterministic kernel is the only component that commits, and an action a backend never declared is unexpressible rather than filtered. It is the governed action layer that tool-integration standards leave undefined.

Overview

Agents can already talk to anything. They cannot yet act on the systems that run a business — the ones that move money, inventory, invoices, and orders — without risking the exact thing those systems exist to protect: the truth of what happened.

MCP and OpenAPI standardize what an agent can reach. NIL governs what an agent can author: the agent only proposes intent against operations a backend has declared, a deterministic kernel is the only component that commits a write, and the result is read back. NIL composes with those standards; it does not replace them. Think of it as USB for systems, with governance: one adapter per backend, and any agent can then operate it without being trusted.

Intent, not implementation

An agent describes what it wants to happen. The system decides how, and whether, it happens. NILScript is the shape of that conversation.

A standard, not a product

NILScript follows the MCP model, not the n8n model. The schemas, the profiles, the conformance suite, the docs, and a runnable reference are open. Any language can implement it; any vendor can conform to it; nobody needs permission. The spec is extracted from running code — never invented in a committee.

The business lives above the standard, in production runtimes and vertical intelligence. NILScript is stewarded by the Wosool project, which keeps its production engine closed and contributes the standard openly.

What we ask everyone to agree on

An agent acting on a business should propose, not execute.
A human (or a policy acting for one) should see a true preview before committing.
Authority should be scoped, budgeted, and revocable by default.
“Ask, don’t guess” should be a protocol outcome, not a prompt-engineering hope.
Every action should be idempotent and auditable as a property of the wire.
A consequential action should be reversible by governed compensation where it can be, and refused honestly where it cannot.

What can NILScript enable?

Where MCP and OpenAPI standardize what an agent can reach, NILScript governs what an agent can author: the governed action layer those standards leave undefined. With one conformant integration, an agent can:

Operate any conformant backend — commerce, ERP, billing, scheduling — through a single verb catalog instead of N bespoke APIs.
Propose changes that are previewed from system facts before they run, so a hallucinated amount or identifier never reaches the ledger.
Route high-stakes actions through tiered human approval with a full, append-only audit trail.

Two layers, one neutral spec

NILScript is two layers and a neutral spec — not a product, not a SaaS, not a framework you adopt wholesale. Any language can read it; any vendor can conform to it.

NIL — the wire protocol

NIL (Network Intent Layer) is a constrained protocol for agent ↔ system communication — the “USB port for software.” It defines a small, closed set of performatives:

Performative	Meaning
`PROPOSE`	An agent proposes an action. No side effects.
`PROPOSAL`	The system answers with a preview — or a refusal.
`COMMIT`	Execute an approved proposal, with an idempotency guarantee.
`QUERY`	Read business truth, fresh. Never cached, never remembered.
`STATUS`	Poll the outcome of a parked or running action.
`EVENT`	The backend pushes the real result back, signed.
`ROLLBACK`	Request a governed reversal, answered by a compensation preview.
`DECIDE`	The owner approves — out of band, on a separate credential.

The orchestration DSL

Above the wire, the NILScript DSL is the language an agent writes: a declarative JSON graph (a DAG) of typed nodes. A static validator admits or rejects the whole plan before any side effect, then a durable runtime executes it node by node — surviving restarts, retries, and human approval gates.

plan.nil.json

{
  "wosool": "0.1",
  "workspace": "ws_demo",
  "locale": "ar",
  "entry": "step_1",
  "pipeline": [
    { "id": "step_1", "type": "query", "verb": "commerce.product",
      "args": { "sku": "TSHIRT-01" }, "next": "step_2" },
    { "id": "step_2", "type": "condition",
      "expression": "$.step_1.output.stock < 10",
      "on_true": "step_3", "on_false": "step_4" },
    { "id": "step_3", "type": "action", "skill": "product",
      "verb": "commerce.create_purchase_order",
      "args": { "sku": "TSHIRT-01", "qty": "100" }, "next": "step_4" }
  ]
}

Safe by construction

The DSL is deliberately incomplete: no unbounded loops, no file access, no eval, no user-defined functions. It expresses any automation a merchant can describe in words — and nothing else. The ceiling is the safety guarantee.

Generation → Validation → Runtime

NILScript separates three concerns that chat collapses into one:

Generation. An LLM compiles natural-language intent into a NILScript DSL program. It produces text; it executes nothing.
Validation. A static validator admits or rejects the whole program before any side effect — schema, references, acyclicity, grant scope, types.
Durable runtime. A workflow engine interprets the graph node by node, driving NIL on each edge and surviving crashes, retries, and approval gates.

The core inversion: the part that is creative is not allowed to act, and the part that acts is not creative.

The SEQRD-PC kernel

Read as a mnemonic, the kernel is SEQRD-PC — STATUS · EVENT · QUERY · ROLLBACK · DECIDE · PROPOSE · COMMIT. Every legal exchange on the wire is one of these, and only these — which is exactly what makes the protocol auditable.

Why is it safe?

NILScript moves AI interaction from stateless chat to durable orchestration. Safety is structural, not a policy bolted on after the fact:

Default-deny grants. A speaker can only do what its grant explicitly lists. An unknown verb is a security boundary, not a feature request.
Hallucinations die at the server. Previews are rendered from facts the system resolves, never from values the agent supplied.
Tiered approval. LOW executes immediately, MEDIUM notifies, HIGH parks for approval, CRITICAL adds a cooling delay.
Idempotency + append-only audit. A retried commit replays the original outcome; every sentence is bound to its grant, policy version, actor, preview, and result.

The unauthorized-write rate is zero by construction within the threat model, confirmed on a live backend, not a small number reached by tuning. The guarantee holds while NIL is the sole effect path. On the kernel API path the kernel performs the confirmation and read-back; on the MCP path that confirmation currently rests on the adapter envelope, gated at admission, and kernel-side re-verification per request is future work.

Refusals are answers, not errors

When an agent is ambiguous, the system refuses with up to eight candidates and asks the human to choose. Ask, don’t guess.

Bounded reversibility

Every effect declares whether and how it can be undone, so a failed program is walked back through governed compensation rather than left half-applied:

REVERSIBLE — a clean inverse exists (create ↔ delete).
COMPENSABLE — no inverse, but an offsetting forward action (record_payment → process_refund).
IRREVERSIBLE — no reversal exists; a ROLLBACK is refused honestly. The default for any unmarked verb.

Get started

Install the standard — schemas, docs, and CLI — with zero runtime dependencies:

shell

pip install nilscript            # standard: schemas, docs, CLI — zero deps
pip install "nilscript[sdk]"     # adds the typed Python client (httpx + pydantic)
npm install nilscript            # spec + JSON Schemas for the JS/TS ecosystem