AppSummary: Tracked Application Overview from GET /apps

AppSummary is the lightweight model the daemon returns for each tracked application in response to GET /substrate/v1/apps. It gives you everything you need to decide whether an application is ready to act on: the current probe status, confidence score, object and action counts, and the application’s navigational context. Unlike SubstrateState, AppSummary does not include the full objects map or action schemas — it is designed to be inexpensive to scan across many running applications so your agent can quickly find the right target before calling GET /state/{pid}.

JSON Example

{
  "total": 2,
  "apps": [
    {
      "pid": 12847,
      "app_id": "gmail-chrome-12847",
      "app_name": "Gmail",
      "runtime": "v8",
      "runtime_name": "JavaScript (V8)",
      "probe_status": "active",
      "confidence": 0.97,
      "object_count": 23,
      "action_count": 5,
      "last_captured_at": "2026-07-20T13:00:00Z",
      "has_state": true,
      "current_view": "gmail_inbox",
      "current_url": "https://mail.google.com/mail/u/0/#inbox"
    },
    {
      "pid": 4521,
      "app_id": "mission-planner-4521",
      "app_name": "Mission Planner",
      "runtime": "clr",
      "runtime_name": ".NET CLR",
      "probe_status": "active",
      "confidence": 0.95,
      "object_count": 47,
      "action_count": 12,
      "last_captured_at": "2026-07-20T13:00:01Z",
      "has_state": true,
      "current_view": null,
      "current_url": null
    }
  ]
}

Fields

integer

required

The OS process ID of the tracked application. Use this as the {pid} path parameter for GET /state/{pid} or in the pid field of an ActionRequest. PIDs change when an application restarts — use app_id for stable references.

string

required

A stable semantic identifier that survives daemon restarts and process restarts. Format on first detection is {app-name}-{pid} (for example, "gmail-chrome-12847"), then promoted to a content-hash-based ID. Store this value in your agent instead of pid for long-lived sessions.

string

required

The human-readable display name assigned by the signature registry, such as "Gmail" or "Mission Planner".

string

required

The runtime substrate identifier. One of v8, jvm, clr, native, or unknown.

string

required

A human-readable label for the runtime, such as "JavaScript (V8)", ".NET CLR", or "JVM". Suitable for display in UIs or log messages.

string

required

The current lifecycle state of the probe attached to this application. See the probe status lifecycle section below for the full set of values and their transitions.

float (0.0–1.0)

required

The most recent probe quality score for this application. A value of 0.0 means no state has been captured yet. Values below 0.80 will prevent reversible_write actions; values below 0.95 will prevent irreversible_write actions.

integer

required

The number of semantic state keys currently in the application’s objects map. A value of 0 means the cold probe has not yet completed. Use this to quickly gauge how much state has been extracted before fetching the full SubstrateState.

integer

required

The number of typed actions currently available in the application’s actions map. A value of 0 means the schema registry has not yet assigned any actions to this application.

string (ISO 8601) | null

required

The UTC timestamp of the most recent state snapshot. null if no snapshot has been captured yet (cold probe still in progress). Monitor this value to detect stale state — if it has not advanced in more than a few seconds, the probe may be in an error state.

boolean

required

true if at least one successful state snapshot has been captured and is available in cache. false during the cold probe phase. Always check has_state before calling GET /state/{pid} — calling it while has_state is false returns 503 probe_not_ready.

string | null

The semantic view name from the most recent context.view in the SubstrateState, such as "gmail_inbox" or "gmail_compose". Populated for V8 apps where views are distinguishable via URL routing; null for CLR, JVM, and native apps.

string | null

The current URL from the most recent context.url, such as "https://mail.google.com/mail/u/0/#inbox". Populated for browser and Electron apps; null for all others.

Probe Status Lifecycle

The probe_status field tracks the probe through its full lifecycle from process detection to detachment. Understanding these states helps you decide when an application is ready to use.

Status	Description
`detecting`	The process scanner found the PID; runtime classification (V8 / JVM / CLR) is in progress.
`attaching`	The daemon is establishing a connection to the runtime — CDP WebSocket handshake, JVMTI attach, or CLR MMF injection.
`cold_probe`	The first full state extraction is running. This can take 3–90 seconds depending on the application size and runtime. `has_state` is `false` during this phase.
`active`	The fast poll loop is running and state is continuously updated. `has_state` is `true`. This is the only status at which actions can be dispatched.
`error`	The most recent probe attempt failed. The daemon will retry automatically. `has_state` may still be `true` if a previous successful snapshot is in cache.
`detached`	The process has exited. The cached state has been removed. The entry will disappear from `GET /apps` shortly after.

A typical transition sequence for a newly opened application looks like this:

detecting → attaching → cold_probe → active

If the probe fails during cold start, the sequence may be:

detecting → attaching → cold_probe → error → cold_probe → active

Once active, a transient probe failure moves to error and back to active on recovery without discarding cached state.

Endpoints

Data Models

JSON Example

Fields

Probe Status Lifecycle

​JSON Example

​Fields

​Probe Status Lifecycle

JSON Example

Fields

Probe Status Lifecycle