NSP Core Concepts: State, Actions, Probes, and Safety

NSP organizes everything around a single idea: every running application is a substrate — a live, addressable source of typed data that your agent can read and write in real time. Understanding the three components of the substrate model, and the safety guarantees built into the action system, is the foundation for building reliable agents with NSP.

The Substrate Model

The substrate model has three components that work together on every state capture.

State

A typed JSON snapshot of the application’s current data, normalized to the Substrate Schema Format (SSF). State is read on demand or streamed continuously via WebSocket.

Actions

Typed function signatures discovered from the runtime that your agent can invoke directly — no UI interaction, no pixel coordinates, no simulated keystrokes.

Schema

A persistent, versioned registry of discovered state structures and action mappings. The schema is stored in SQLite and survives daemon restarts, so cold-start times improve over time.

SubstrateState (SSF)

Every application’s state is represented as a SubstrateState object in the Substrate Schema Format (SSF). This is the core data structure that every NSP endpoint returns and every SDK method operates on.

{
  "capture_id": "0196f4a2-3b5c-7d00-8e1f-9a0b2c3d4e5f",
  "app_id": "gmail-chrome-12847",
  "app_name": "Gmail",
  "pid": 12847,
  "runtime": "v8",
  "schema_version": "1.4.2",
  "captured_at": "2026-07-20T13:00:00Z",
  "confidence": 0.97,
  "context": {
    "url": "https://mail.google.com/mail/u/0/#inbox",
    "view": "gmail_inbox",
    "window_title": "Inbox - Gmail"
  },
  "objects": {
    "inbox.unread_count": 47,
    "inbox.total_count": 1284,
    "inbox.emails[0].id": "msg_18821af3",
    "inbox.emails[0].from": "alice@example.com",
    "inbox.emails[0].subject": "Q3 Performance Report",
    "inbox.emails[0].is_read": false,
    "inbox.emails[0].has_attachments": true
  },
  "actions": { "...": "..." },
  "probe_metadata": {
    "capture_latency_ms": 28,
    "total_latency_ms": 51,
    "cache_hit": false,
    "dom_tier_used": true
  }
}

Key Fields

Field	Type	Description
`capture_id`	UUIDv7	Time-ordered unique ID for this capture
`app_id`	string	Stable identifier — survives process restarts
`app_name`	string	Human-readable name, e.g. `"Gmail"`
`pid`	integer	OS process ID at time of capture
`runtime`	enum	`v8` / `jvm` / `clr` / `unknown`
`confidence`	float	Probe quality score 0.0–1.0
`objects`	object	Dot-notation key-value state map
`actions`	object	Available action schemas
`probe_metadata`	object	Capture telemetry (latency, cache status)

Confidence Score

Every SubstrateState carries a confidence field between 0.0 and 1.0 that represents how certain the probe is in its semantic labels. NSP uses this score to gate which actions your agent is allowed to execute — preventing writes on partially-understood state.

Range	Meaning	Action Gating
`0.0 – 0.39`	Unknown / probe initializing	No actions allowed
`0.40 – 0.79`	Partial — some objects labeled	Read-only actions
`0.80 – 0.94`	Good — most objects labeled	`reversible_write` actions allowed
`0.95 – 1.00`	Excellent — full semantic coverage	All actions including `irreversible_write`

Once a probe has run through its warm-up cycle, you can expect these confidence baselines by runtime:

Runtime	Expected Confidence
V8 / JavaScript	`0.95 – 0.99`
JVM / Java	`0.93 – 0.97`
CLR / .NET	`0.93 – 0.97`

Action Schema

Every action available on a substrate is described by an ActionSchema that tells your agent exactly what the action does, what parameters it requires, and what safety tier it belongs to.

{
  "send_reply": {
    "signature": "fn(thread_id: string, body: string, cc?: string[]) -> bool",
    "reversibility": "irreversible_write",
    "description": "Send a reply to an email thread",
    "confidence": 0.99,
    "parameters": [
      {
        "name": "thread_id",
        "type_name": "string",
        "required": true,
        "description": "Thread ID from inbox.emails[N].thread_id"
      },
      {
        "name": "body",
        "type_name": "string",
        "required": true,
        "description": "Reply body text"
      },
      {
        "name": "cc",
        "type_name": "array",
        "required": false,
        "description": "Optional CC email addresses"
      }
    ]
  }
}

The signature field uses a simple function notation so LLM-based agents can parse it without additional tooling. The confidence on an action schema reflects how certain the probe is that the action binding is correct — distinct from the state-level confidence.

Reversibility

Every action is classified into one of three reversibility tiers. This is a safety contract enforced by the daemon and the SDK — not an advisory label. The tier determines what confidence level is required before NSP will dispatch the action.

read — No state change

The action reads data without modifying anything in the application. There is no confidence gate for read actions — they are safe to call at any time, even during probe warm-up.Examples: get_thread, search, list_contacts, read_document

reversible_write — Undoable change

The action modifies application state, but the change can be undone by the user or by a subsequent action.Requires: confidence >= 0.80Examples: archive, label, move_to_folder, mark_read, star, create_draft

irreversible_write — Permanent change

The action causes a permanent side effect that cannot be undone — sending a message, making a purchase, deleting data permanently.Requires: confidence >= 0.95 AND verify=True with a verify_expressionExamples: send_reply, delete_permanently, purchase, submit_form, send_messageThe SDK automatically enforces the verification requirement. Calling an irreversible action without it raises an error:

# This raises NSPIrreversibleNotConfirmedError
await session.execute("send_reply", parameters={...}, verify=False)

# Correct — verify=True and a verify_expression are both required
await session.execute(
    "send_reply",
    parameters={...},
    verify=True,
    verify_expression="inbox.sent_count > 0",
)

Runtime Probes

NSP supports three managed runtimes, each using a purpose-built probe. From your agent’s perspective, all three produce the same SSF JSON — the differences are internal.

V8 / JavaScript

The V8 probe connects to any running Chrome or Electron process via the Chrome DevTools Protocol (CDP) on the remote debugging port you configure at launch. State extraction uses a two-tier approach:

ASO Fast-Path (primary) — Injects a lightweight JavaScript snippet that reads the application’s data model from the V8 heap directly. Returns in 5–50ms and is used for all normal poll cycles.
Heap Snapshot Fallback — When the ASO fast-path is unavailable, the probe takes a full V8 heap snapshot, parses its flat node/edge format, filters runtime internals, and normalizes the result to SSF. This path takes approximately 47 seconds and is only used during initial schema discovery.

Supported applications: Gmail, Slack, VS Code, Notion, GitHub Desktop, Salesforce, WhatsApp Desktop, Discord, Shopify, HubSpot, and any Electron-based app.

JVM / Java

The JVM probe uses the JVMTI (JVM Tool Interface) to attach to a running Java process without modifying it. It loads a native JVMTI agent via the standard AttachAPI, uses JNI reflection to enumerate classes and read live field values, then converts Java objects to SSF JSON using type metadata from class files. Supported applications: SAP ERP, Eclipse, IntelliJ IDEA, Jenkins, Elasticsearch, ArduPilot GCS (Java build).

CLR / .NET

The CLR probe uses a Memory-Mapped File (MMF) channel to communicate with a managed bootstrapper injected into the target process. It injects the bootstrapper DLL using the Windows CLR Hosting API, then the managed bridge walks the CLR heap using reflection-style APIs to read field values and method return values across the MMF channel. Supported applications: Mission Planner, WinForms and WPF apps, Visual Studio, Microsoft Office, and any .NET 4.x or .NET 6+ application.

Support for native C/C++ applications without a managed runtime is coming next month.

App Lifecycle

When you start an application, NSP moves it through a predictable lifecycle before your agent can read its state. Understanding this sequence helps you handle the initial warm-up period in your agent code.

App Starts
   │
   ▼
Process scanner detects process (PID, exe name, cmdline)
   │
   ▼
Runtime detector classifies: V8 / JVM / CLR
   │
   ▼
Signature registry matches known app → assigns app_id + app_name
   │
   ▼
Probe attaches (cold probe: 3–90s on first run for that app)
   │
   ▼
First SubstrateState cached (confidence 0.80+)
   │
   ▼
Fast poll loop (default 2s interval) — ASO fast-path (~50ms)
   │
   ▼
State change notifications broadcast to WebSocket subscribers
   │
   ▼
App exits → probe detached → state removed from cache

The cold probe time (3–90 seconds) only applies the first time NSP encounters a given application. After the schema is persisted to the registry, subsequent attachments are much faster.

State Object Keys

NSP uses dot-notation flat keys for all state objects rather than nested JSON. This design lets your agent reference any specific value with a single precise string, and makes it straightforward for LLM-based agents to construct key references from natural language.

# Instead of navigating nested JSON: state["inbox"]["emails"][0]["subject"]
session.get_str("inbox.emails[0].subject")

# Use prefix queries to fetch a whole section of state
inbox = session.state.keys_with_prefix("inbox.")

Keys are stable across poll cycles — the same key will always refer to the same semantic concept for a given app and schema version. If the underlying application updates and the schema changes, NSP increments the schema_version field so your agent can detect and adapt to the change.

Python SDK Reference

The Python SDK (pip install nelieo-nsp) provides typed, async-friendly wrappers around all daemon endpoints. The two primary classes are NSPClient and Session.

NSPClient

NSPClient is the top-level entry point. Use it as an async context manager so the underlying HTTP connection is properly closed on exit.

import nelieo_nsp as nsp

async with nsp.NSPClient(base_url="http://localhost:7842", api_key="...") as client:
    # Check daemon health
    ok = await client.ping()

    # List all currently tracked applications
    apps = await client.list_apps()

    # Fetch the full SubstrateState for a specific PID
    state = await client.get_state(pid=12847)

    # Attach to an app by name and get a Session
    session = await client.attach("Gmail")

Method	Signature	Description
`ping`	`() -> bool`	Returns `True` if the daemon is reachable and healthy
`list_apps`	`() -> list[AppInfo]`	Returns all apps currently tracked by the daemon
`get_state`	`(pid: int) -> SubstrateState`	Fetches the latest cached state for the given PID
`attach`	`(app_name: str) -> Session`	Finds the running app by name and returns a live Session

Session

A Session is a live handle to one tracked application. It caches the most recently fetched SubstrateState and provides typed helpers for reading values and executing actions.

# Typed state accessors
unread: int   = session.get_int("inbox.unread_count")
subject: str  = session.get_str("inbox.emails[0].subject")

# Execute an action
result = await session.execute(
    "archive",
    parameters={"email_id": "msg_18821af3"},
)

# Pull a fresh state snapshot from the daemon
await session.refresh()

# Stream state changes via WebSocket
async for event in session.watch():
    print(event.changed_fields)

Method	Signature	Description
`get_str`	`(key: str) -> str`	Read a string value from the current state snapshot
`get_int`	`(key: int) -> int`	Read an integer value from the current state snapshot
`execute`	`(action: str, parameters: dict, verify: bool, verify_expression: str) -> ActionResult`	Execute an action on the attached application
`refresh`	`() -> None`	Force a fresh state snapshot from the daemon
`watch`	`() -> AsyncIterator[StateChangeEvent]`	Stream live state change events over WebSocket

CLI Reference

The axon-daemon.exe binary includes a built-in CLI for managing the daemon process and its Windows Service registration.

# Start the daemon in the foreground (development mode)
axon-daemon.exe run

# Install and register as a Windows Service
axon-daemon.exe install

# Remove the Windows Service registration
axon-daemon.exe uninstall

# Start the already-installed Windows Service
axon-daemon.exe start

# Stop the running Windows Service
axon-daemon.exe stop

# Print the daemon's current status (version, uptime, tracked processes)
axon-daemon.exe status

# Generate a new API key and print it to stdout
axon-daemon.exe keygen

Command	Description
`run`	Start the daemon directly in the terminal (foreground, no service)
`install`	Register `axon-daemon.exe` as a Windows Service that auto-starts on login
`uninstall`	Remove the Windows Service registration
`start`	Start the Windows Service (after `install`)
`stop`	Stop the running Windows Service
`status`	Print version, uptime, port, and number of tracked processes
`keygen`	Generate a new random API key for use with `X-Substrate-Key` authentication

Get Started

The Daemon

Runtime Probes

Security

Guides

The Substrate Model

State

Actions

Schema

SubstrateState (SSF)

Key Fields

Confidence Score

Action Schema

Reversibility

Runtime Probes

V8 / JavaScript

JVM / Java

CLR / .NET

App Lifecycle

State Object Keys

Python SDK Reference

NSPClient

Session

CLI Reference

​The Substrate Model

State

Actions

Schema

​SubstrateState (SSF)

​Key Fields

​Confidence Score

​Action Schema

​Reversibility

​Runtime Probes

​V8 / JavaScript

​JVM / Java

​CLR / .NET

​App Lifecycle

​State Object Keys

​Python SDK Reference

​NSPClient

​Session

​CLI Reference

The Substrate Model

SubstrateState (SSF)

Key Fields

Confidence Score

Action Schema

Reversibility

Runtime Probes

V8 / JavaScript

JVM / Java

CLR / .NET

App Lifecycle

State Object Keys

Python SDK Reference

NSPClient

Session

CLI Reference