> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nelieo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AppSummary: Tracked Application Status and Metadata

> Reference for the AppSummary object returned by GET /apps — probe status, confidence, runtime, and counts for each tracked application.

The `AppSummary` object is the entry type returned in the array from `GET /apps`. Rather than returning full state snapshots for every tracked application, NSP gives you a compact view of each one — enough to determine whether an application is ready for reads and writes, what runtime it uses, and where it currently is in its lifecycle. You use `AppSummary` to decide which applications to target and to pick the right `pid` or `app_id` before calling `GET /state` or `POST /action`.

<ResponseField name="pid" type="integer" required>
  The OS process ID of the tracked application. Valid for the lifetime of the current process instance. Because the OS recycles PIDs after a process exits, you should pair `pid` with `probe_status` to confirm the process is still live before using it in an `ActionRequest`.
</ResponseField>

<ResponseField name="app_id" type="string" required>
  A stable semantic identifier for the application that persists across process restarts. On first detection NSP derives a candidate ID from the process name and PID (for example `gmail-chrome-12847`), then promotes it to a content-hash-based identifier once the probe has confirmed the app's identity through the signature registry. You can use `app_id` as a durable reference — if Gmail restarts and gets a new PID, the `app_id` remains the same and NSP automatically associates the new process with it.
</ResponseField>

<ResponseField name="app_name" type="string" required>
  Human-readable display name assigned by the signature registry, for example `"Gmail"`, `"Mission Planner"`, or `"VS Code"`. Suitable for display and logging. For programmatic identity checks, always use `app_id`.
</ResponseField>

<ResponseField name="runtime" type="enum" required>
  The runtime environment detected for this application. One of `v8`, `jvm`, `clr`, `native`, or `unknown`. Determines which probe strategy NSP uses and the expected confidence ceiling for the app.
</ResponseField>

<ResponseField name="probe_status" type="enum" required>
  The current lifecycle state of the probe attached to this application. Use this to determine whether the app is ready to serve state and accept actions.

  | Value       | Description                                                            |
  | ----------- | ---------------------------------------------------------------------- |
  | `detecting` | PID found; runtime classification in progress                          |
  | `attaching` | Connecting to the runtime (CDP handshake, JVMTI attach, CLR inject)    |
  | `cold`      | First full state extraction running — can take 3–90 s on first contact |
  | `active`    | Fast poll loop running — state is fresh and actions are available      |
  | `error`     | Last probe attempt failed — daemon is retrying automatically           |
  | `detached`  | Process exited — state cleaned up, no actions available                |

  Only apps with `probe_status: "active"` are ready for action dispatch. Apps in `detecting`, `attaching`, or `cold` states will become active shortly; `error` states self-recover on the next retry cycle; `detached` apps require the process to restart.
</ResponseField>

<ResponseField name="confidence" type="float" required>
  The current probe quality score from `0.0` to `1.0` for this application, matching the semantics of `SubstrateState.confidence`. Use this alongside `probe_status` to decide whether the app is ready for writes:

  * `confidence >= 0.80` — safe for `reversible_write` actions
  * `confidence >= 0.95` — safe for `irreversible_write` actions (also requires `verify_expression`)
</ResponseField>

<ResponseField name="object_count" type="integer" required>
  The number of dot-notation state keys currently in the application's SSF objects map. A value of `0` while `probe_status` is `active` may indicate the probe is between cycles; a sustained `0` may indicate a labeling failure.
</ResponseField>

<ResponseField name="action_count" type="integer" required>
  The number of actions currently available in the application's schema. This may grow over time as the probe learns more of the app's action surface across sessions.
</ResponseField>

***

## Full JSON Example

```json theme={null}
{
  "pid": 12847,
  "app_id": "gmail-chrome-12847",
  "app_name": "Gmail",
  "runtime": "v8",
  "probe_status": "active",
  "confidence": 0.97,
  "object_count": 23,
  "action_count": 5
}
```

**Application still attaching:**

```json theme={null}
{
  "pid": 28341,
  "app_id": "mission-planner-28341",
  "app_name": "Mission Planner",
  "runtime": "clr",
  "probe_status": "cold",
  "confidence": 0.0,
  "object_count": 0,
  "action_count": 0
}
```

***

## `app_id` Stability

Unlike `pid`, which changes whenever the OS assigns a new process slot, `app_id` is designed to remain constant for the same logical application across restarts, updates, and machine reboots. NSP builds it in two stages:

1. **Bootstrap ID** — generated immediately on process detection using the exe name, runtime, and initial PID: `gmail-chrome-12847`. This appears in `AppSummary` during the first probe cycle.
2. **Stable ID** — once the signature registry confirms the app identity (typically within the first active poll cycle), NSP promotes the ID to a content-hash form derived from the app's name, runtime, and version fingerprint. This ID does not contain the PID and survives restarts.

You should persist the stable `app_id` in your agent's configuration and use it as your primary reference. When an app restarts, NSP automatically re-links the new PID to the same `app_id` so your stored reference remains valid.