Core Concepts: NSP State, Actions, and Runtime Probes

NSP exposes every running application through a unified data model built from three primitives: structured state, typed actions, and a schema that ties them together. Understanding these primitives is the key to writing reliable agents — it tells you exactly what data you can read, what operations you can call, and what safety guarantees you can rely on.

The Substrate Model

NSP treats every running application as a substrate — a live, addressable data source you can read from and write to in real time. The substrate model has three components.

State

A typed JSON snapshot of the application’s current data, normalized to the Substrate Schema Format (SSF) with stable dot-notation keys.

Actions

Typed function signatures discovered from the runtime that your agent can invoke directly — no UI interaction, no mouse clicks.

Schema

A persistent, versioned registry of discovered state structures and action mappings, stored on disk and reused automatically across daemon restarts.

SubstrateState (SSF)

Every application’s state is represented as a SubstrateState object — the core data structure that flows through every part of NSP. You get one of these back from GET /substrate/v1/state/{pid}.

{
  "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
  }
}

Field Reference

Field	Type	Description
`capture_id`	UUIDv7	Time-ordered unique ID for this specific capture
`app_id`	string	Stable identifier tied to the app — survives process restarts
`app_name`	string	Human-readable name, e.g. `"Gmail"`
`pid`	integer	OS process ID at the time of capture
`runtime`	enum	`v8` / `jvm` / `clr` / `native` / `unknown`
`schema_version`	semver string	Schema version in use; a version bump means key mappings changed
`confidence`	float	Probe quality score from 0.0 to 1.0
`context`	object	Current navigational context — URL, view name, window title
`objects`	object	Flat dot-notation key/value map of all readable app state
`actions`	object	Available action schemas keyed by action name
`probe_metadata`	object	Diagnostic fields: capture latency (ms), total latency, and cache hit status

Confidence Score

Every SubstrateState carries a confidence field between 0.0 and 1.0 that represents how certain the probe is in the semantic accuracy of its labels. The daemon uses this score as a safety gate before allowing action execution.

Range	Meaning	Action Gating
`0.0 – 0.39`	Unknown — probe is initializing or no schema matched	No actions allowed
`0.40 – 0.79`	Partial — some objects labeled, schema incomplete	Read-only actions only
`0.80 – 0.94`	Good — most objects labeled with high accuracy	`reversible_write` actions allowed
`0.95 – 1.00`	Excellent — full semantic coverage confirmed	All actions, including `irreversible_write`

Runtime confidence baselines tell you what to expect once a probe is warm:

Runtime	Typical Confidence Range
V8 / JavaScript	`0.95 – 0.99`
JVM / Java	`0.93 – 0.97`
CLR / .NET	`0.93 – 0.97`
Native C++	`0.40 – 0.75`

If you see confidence below the expected baseline for a V8 or JVM app, the probe is likely still in its cold-start phase. Wait a few seconds and re-poll — confidence climbs as the schema cache warms up.

Action Schema

Every action available on a substrate is described by an ActionSchema that tells your agent exactly what parameters to pass, what to expect back, and how risky the operation is.

{
  "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 confidence on an action schema reflects how reliably NSP can invoke it — separate from the state-level confidence. Both must meet their respective thresholds before execution proceeds.

Reversibility

Every action is classified into one of three reversibility tiers. This is a safety contract enforced at the daemon and SDK level, not a suggestion or annotation.

read — No state change

The action reads data without modifying any application state. There is no confidence gate for read actions — they are safe to call at any confidence level.Examples: get_thread, search, list_contacts, read_document, get_calendar_events

# No restrictions — callable at any confidence
results = await session.execute("search", parameters={"query": "Q3 report"})

reversible_write — Undoable change

The action modifies application state in a way that can be undone. The daemon requires confidence >= 0.80 before dispatching.Examples: archive, label, move_to_folder, mark_read, star, create_draft

# Allowed when confidence >= 0.80
result = await session.execute(
    "archive",
    parameters={"email_id": "msg_18821af3"},
)

irreversible_write — Permanent change

The action causes a permanent side effect that cannot be undone. The daemon requires confidence >= 0.95 and the SDK requires verify=True with a verify_expression. Calling execute without these raises NSPIrreversibleNotConfirmedError.Examples: send_reply, delete_permanently, purchase, submit_form, send_message

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

# Correct — provide verify=True and a verify_expression
result = await session.execute(
    "send_reply",
    parameters={
        "thread_id": "thread_abc123",
        "body": "Thanks, I'll review this shortly.",
    },
    verify=True,
    verify_expression="inbox.emails[0].is_read == true",
)

After executing the action, NSP waits 200 ms, then polls the app state up to 10 times — evaluating your verify_expression each cycle — before returning. The response includes a verification object with the outcome, which changed fields were observed, and the total latency.

Runtime Probes

Each runtime family uses a fundamentally different technical method to reach the application’s internal state. Understanding which probe applies to your target app helps you predict accuracy, cold-start time, and confidence baselines.

V8 / JavaScript

The V8 probe connects to Chrome or any Electron app via the Chrome DevTools Protocol (CDP) remote debugging port (enabled with --remote-debugging-port=9222). It uses a fast-path state extraction method that returns in 5–50 ms during normal operation. On first encounter with a new app, NSP falls back to a full heap snapshot to build the schema — this takes up to ~47 seconds but runs only once. All subsequent reads use the fast path against the cached schema. Covered apps: Gmail, Slack, VS Code, Notion, GitHub Desktop, Salesforce, WhatsApp Desktop, Discord, Shopify, HubSpot, and any Electron-based application.

JVM / Java

The JVM probe attaches to a running Java process without requiring a restart, reads live object fields using the JVM’s native instrumentation interface, and converts Java objects to SSF JSON using class type metadata. No code changes to the target application are needed. Covered apps: SAP ERP, Eclipse, IntelliJ IDEA, Jenkins, Elasticsearch, ArduPilot GCS (Java build).

CLR / .NET

The CLR probe injects a managed bootstrapper into the target .NET process and reads field values and method return values from the CLR heap, communicating results back to the daemon over an inter-process channel. No changes to the target application are required. Covered apps: Mission Planner, WinForms apps, WPF apps, Visual Studio, Microsoft Office (Excel, Word, PowerPoint), and any .NET 4.x or .NET 6+ desktop app.

Native / C++

The native probe reads raw process memory from compiled binaries that carry no semantic metadata. NSP layers a Visual-Memory Grounding pass on top — correlating memory regions with a local vision model to produce human-readable semantic labels. Covered apps: Bloomberg Terminal, Photoshop, AutoCAD, Chrome internals (C++ layer). Expect confidence in the 0.40–0.75 range rather than the high-nineties seen for managed runtimes.

App Lifecycle

An app moves through a well-defined state machine from the moment NSP detects its process to the moment it exits. Understanding this lifecycle helps you reason about cold-start delays, poll frequency, and WebSocket event timing.

App Starts
   │
   ▼
Daemon detects new process (PID, exe name, command line)
   │
   ▼
Runtime classified: V8 / JVM / CLR / Native
   │
   ▼
Known app matched → app_id and app_name assigned
   │
   ▼
Probe attaches (cold start: 3–90 s on first encounter)
   │
   ▼
First SubstrateState cached (confidence 0.80+)
   │
   ▼
Fast poll loop (default 2 s interval, ~50 ms per read)
   │
   ▼
State change notifications broadcast to WebSocket subscribers
   │
   ▼
App exits → probe detached → state removed from cache

The cold probe delay (3–90 seconds) only occurs the first time NSP encounters an app. On every subsequent start, the daemon reuses the cached schema from disk and reaches an active probe state in under a second.

State Object Keys

NSP stores all state values in a flat dot-notation map rather than nested JSON. This design means your agent can reference any specific value with a single deterministic string — no recursive traversal, no path ambiguity.

# Access a nested value with a single key
subject = session.get_str("inbox.emails[0].subject")

# Query all keys under a prefix
inbox_keys = session.state.keys_with_prefix("inbox.")

Keys are stable across poll cycles for a given app and schema version. If inbox.emails[0].subject resolves to the email subject today, it resolves to the email subject on every subsequent read until the schema version changes. When schema_version increments (a semver bump in the SubstrateState), re-validate any hardcoded key references in your agent.

Get Started

The Daemon

Runtime Probes

Security

Guides

The Substrate Model

State

Actions

Schema

SubstrateState (SSF)

Field Reference

Confidence Score

Action Schema

Reversibility

Runtime Probes

V8 / JavaScript

JVM / Java

CLR / .NET

Native / C++

App Lifecycle

State Object Keys

​The Substrate Model

State

Actions

Schema

​SubstrateState (SSF)

​Field Reference

​Confidence Score

​Action Schema

​Reversibility

​Runtime Probes

​V8 / JavaScript

​JVM / Java

​CLR / .NET

​Native / C++

​App Lifecycle

​State Object Keys

The Substrate Model

SubstrateState (SSF)

Field Reference

Confidence Score

Action Schema

Reversibility

Runtime Probes

V8 / JavaScript

JVM / Java

CLR / .NET

Native / C++

App Lifecycle

State Object Keys