NSP Architecture: How State Extraction Really Works

The NSP daemon is a single process that runs on the host machine and does four things: it watches for new applications, attaches language-specific probes to them, normalizes their state into structured JSON, and serves that state to your agent over a local HTTP and WebSocket API. This page explains what each of those layers does and how a request travels through the system — so you can reason about latency, debug unexpected behavior, and build agents that use the API efficiently.

System Overview

The diagram below shows the full architecture from your agent’s perspective. Your agent only ever talks to the Agent API layer at the top. Everything beneath it is managed by the daemon.

┌─────────────────────────────────────────────────────────────────────────────┐
│  AI AGENT  (Python, TypeScript, Claude, GPT, custom LLM loop)               │
│  GET /substrate/v1/state/{pid}   POST /substrate/v1/action                  │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │ HTTP / WebSocket   localhost:7842
┌──────────────────────────────────▼──────────────────────────────────────────┐
│  Agent API  (REST + WebSocket server)                                        │
│  ┌────────────────┐  ┌─────────────────┐  ┌──────────────────────────────┐  │
│  │ Auth Middleware│  │ Rate Limiter    │  │ ActionDispatcher             │  │
│  │ X-Substrate-Key│  │ StateQuery 100/s│  │ V8 / CLR / JVM / OS         │  │
│  └────────────────┘  │ ActionExec 10/s │  └──────────────────────────────┘  │
│                       └─────────────────┘                                   │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
┌──────────────────────────────────▼──────────────────────────────────────────┐
│  Process Watcher  (Process lifecycle orchestrator)                           │
│  ┌─────────────────┐  ┌───────────────────┐  ┌────────────────────────────┐ │
│  │ ProcessScanner  │  │ RuntimeDetector   │  │ ProbeLifecycle             │ │
│  │ sysinfo poll    │  │ V8 / JVM / CLR    │  │ spawn / poll / cache       │ │
│  │ every 500ms     │  │ classification    │  │ broadcast StateChange      │ │
│  └─────────────────┘  └───────────────────┘  └────────────────────────────┘ │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │ per-runtime probe calls
┌──────────────────────────────────▼──────────────────────────────────────────┐
│  RUNTIME PROBES                                                              │
│  ┌──────────────┐          ┌──────────────┐          ┌──────────────┐       │
│  │  V8 Probe    │          │  JVM Probe   │          │  CLR Probe   │       │
│  │  CDP / ASO   │          │  JVMTI + JNI │          │ MMF+Reflect  │       │
│  └──────┬───────┘          └──────┬───────┘          └──────┬───────┘       │
└─────────┼─────────────────────────┼─────────────────────────┼───────────────┘
          │                         │                         │
          ▼                         ▼                         ▼
     Chrome/Electron             Java/JVM                 .NET/CLR
     (port 9222+)                (JVMTI)                (MMF bridge)

Native C/C++ process probing is scheduled for release next month. All other layers shown above are available today.

The Four Layers

Each layer has a clearly defined responsibility. Your agent interacts only with the Agent API — the other three layers are transparent.

Agent API

A hardened REST and WebSocket server running on localhost:7842. It handles authentication via the X-Substrate-Key header, enforces rate limits (100 req/s for state reads, 10 req/s for action execution), validates action safety, dispatches actions to the correct runtime, and runs post-action verification. This is the only layer your agent code calls directly.

Process Watcher

Polls all running OS processes every 500ms. When it detects a new process, the runtime detector classifies it as V8, JVM, CLR, or unknown by inspecting the process name, command-line arguments, and loaded modules. Once classified, the probe lifecycle manager spawns a probe task, runs a fast poll loop every 2 seconds, and caches the latest state in memory for instant retrieval.

Runtime Probes

Three language-specific probes extract live semantic state from running processes. The V8 probe connects via Chrome DevTools Protocol (CDP). The JVM probe loads a JVMTI agent and uses JNI reflection. The CLR probe injects a managed bootstrapper via the Windows CLR Hosting API and communicates over a Memory-Mapped File channel. All three normalize their output to the same SSF JSON format.

Semantic Engine

Converts raw runtime data — V8 heap nodes, JVMTI field lists, CLR type trees — into human-readable dot-notation state keys and versioned action schemas. Discovered schemas are persisted to SQLite so that subsequent attachments to the same application skip the discovery phase and reach full confidence much faster.

API Endpoints

The Agent API exposes nine endpoints. All endpoints except /health require the X-Substrate-Key header when authentication is enabled.

Method	Path	Description
`GET`	`/health`	Liveness probe — no authentication required
`GET`	`/substrate/v1/apps`	List all tracked apps and their probe status
`GET`	`/substrate/v1/state/{pid}`	Fetch full SubstrateState for a process
`GET`	`/substrate/v1/schema/{pid}`	Fetch the action schema for a process
`POST`	`/substrate/v1/action`	Execute an action on a tracked app
`GET`	`/substrate/v1/watch/{pid}`	WebSocket stream of state change events
`GET`	`/substrate/v1/diff/{pid}`	Fetch a state diff since the last capture
`POST`	`/substrate/v1/verify`	Run a standalone state verification expression
`POST`	`/substrate/v1/learn/{pid}`	Submit learning feedback to improve schema accuracy

Request Lifecycle — GET /state/

When your agent calls GET /substrate/v1/state/{pid}, the request travels through the following stages. The typical total latency is 1–5ms for a cached state read or 50–200ms when requesting a fresh snapshot.

Agent → GET /substrate/v1/state/12847
          │
          ▼
    [Auth] X-Substrate-Key verified
          │
          ▼
    [Rate Limit] StateQuery bucket checked (100 req/s)
          │
          ▼
    state_handler(pid=12847)
          │
          ├─ Lookup latest cached SubstrateState by PID
          │
          ├─ If fresh=true: force an immediate snapshot
          │     └─ Wakes the fast poll loop, waits for result
          │
          ▼
    StateResponse { SubstrateState } → JSON 200

Omit ?fresh=true for the fastest possible response — the cached state is updated every 2 seconds by default and is sufficient for most agent loops. Use fresh=true only when you need the absolute latest state immediately after an action.

Request Lifecycle — POST /action

Action execution passes through an additional safety validation stage before dispatch. The full flow ensures that irreversible actions are never executed on low-confidence state and that the result is verified before your agent moves on.

Agent → POST /substrate/v1/action { action: "send_reply", parameters: {...} }
          │
          ▼
    [Auth + Rate Limit: ActionExec 10 req/s]
          │
          ▼
    Safety validation
          ├─ Is reversibility == irreversible_write? → verify_expression required
          ├─ Is action name heuristically dangerous (delete/destroy/purge)? → verify_expression required
          └─ Is current confidence sufficient for this reversibility tier?
          │
          ▼
    ActionDispatcher routes to the correct runtime
          ├─ V8 app  → Runtime.evaluate via CDP WebSocket
          ├─ CLR app → MMF command to managed bridge
          └─ JVM app → JVMTI method invocation
          │
          ▼
    [if verify_expression set] StateVerifier polls
          ├─ Wait 200ms for application to settle
          ├─ Poll state up to 10 cycles (verify_timeout_ms / 500ms each)
          ├─ Evaluate verify_expression against updated state
          └─ Return VerificationOutcome { passed, changed_fields, ... }
          │
          ▼
    ActionResponse { success, latency_ms, verification, state_delta } → JSON 200

The safety validation step runs before any dispatch occurs. If your agent submits an irreversible action without a verify_expression, the request is rejected at this stage with a 400 error — the action is never sent to the application.

Get Started

The Daemon

Runtime Probes

Security

Guides

System Overview

The Four Layers

Agent API

Process Watcher

Runtime Probes

Semantic Engine

API Endpoints

Request Lifecycle — GET /state/

Request Lifecycle — POST /action

​System Overview

​The Four Layers

Agent API

Process Watcher

Runtime Probes

Semantic Engine

​API Endpoints

​Request Lifecycle — GET /state/

​Request Lifecycle — POST /action

System Overview

The Four Layers

API Endpoints

Request Lifecycle — GET /state/

Request Lifecycle — POST /action