Get Started

What is NILScript?

NILScript is the open standard for how AI agents operate real business systems — safely, in any language, against any backend. It is the contract between the agent that decides and the system that owns the truth.

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.

NILScript sits between them and makes every action proposed, previewed, approved, and auditable before anything irreversible occurs. Think of it as the USB-C of agent ↔ system operations: one protocol, any agent, any backend, no lock-in.

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?

NILScript is to business automation what MCP is to tool-calling: the neutral layer everyone builds on. 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.

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