Deep Inspection

Overview

Deep inspection is the PCP diagnostic surface for understanding what the system knows at runtime. It exposes capability schemas, invocation statistics, data-model snapshots, and invocation history. All inspection methods require AuthLevel::Privileged with AuthPrincipal::Admin. There is no way to access them without elevated credentials.

These tools exist for two audiences: System Intelligence (which uses them internally for self-monitoring and recovery) and developers debugging capability registration, target resolution, or execution pipeline behavior.

Inspection Methods

inspection.capability.query

Returns detailed metadata for a single capability or a filtered list across all registered capabilities.

Parameters:

{
  "method": "inspection.capability.query",
  "params": {
    "capability_id": "editor.org.xfce.mousepad.read",
    "include_stats": true
  }
}

Response includes:

• Full capability schema (parameter types, return types, supported actions)
• Invocation count since registration
• Average latency (P50, P99)
• Last invocation record: timestamp, caller identity, parameters, result, duration
• Registration source: static detection, manifest declaration, or adapter inference
• Current capability state: Active, Stale, Degraded, or Unregistered

When capability_id is omitted, the response returns all capabilities for a given app or across the entire system, with optional filtering by domain, tier, or state.

inspection.state.snapshot

Returns a point-in-time snapshot of an app’s Tier 1 data model. This is the authoritative view of what the compositor believes the app’s internal state to be, as reported by the native server interface.

Parameters:

{
  "method": "inspection.state.snapshot",
  "params": {
    "app_id": "org.example.editor",
    "scope": "full"
  }
}

Tier 1 only. Calling this on a Tier 2 or Tier 3 app returns a NotTier1 error (-32099). The snapshot includes the full element tree, all registered capability handlers, and the current session context for the app.

Use this when debugging why a capability invocation produced unexpected results. The snapshot shows exactly what the compositor had to work with at the time of the call.

inspection.history.query

Returns recent invocation history for a specific app or capability. Data comes from the learning runtime’s HistoryStore at ~/.local/share/portal/learning/history.jsonl.

Parameters:

{
  "method": "inspection.history.query",
  "params": {
    "app_id": "org.example.editor",
    "capability_id": "editor.org.example.editor.format",
    "since": "2026-07-20T00:00:00Z",
    "limit": 50
  }
}

Response includes:

• List of invocation records, newest first
• Each record: timestamp, intent source, parameters, result (success/failure), error code (if failed), duration in milliseconds
• Aggregate statistics: total invocations, success rate, average latency

This is the same data that the learning runtime uses for adaptive behavior and crash recovery. Querying it through the inspection API gives developers a read-only view without touching the learning runtime’s internal state directly.

CLI Tools

The portal pcp CLI exposes a set of diagnostic subcommands that wrap the inspection methods. All require AuthPrincipal::Admin.

Capability Inspector

portal pcp inspect capability --app org.example.editor
portal pcp inspect capability --id editor.org.example.editor.read --stats

Dumps capability schemas, registration metadata, and optional invocation statistics. Supports filtering by app ID, domain, tier, or state.

Intent Tester

portal pcp test intent "open mail in thunderbird" --dry-run
portal pcp test intent "format bold" --target org.example.editor --verbose

Runs an intent through the execution pipeline in dry-run mode (no actual execution) or with verbose logging. Shows target resolution output, permission check results, and the action that would be performed. Useful for debugging why an intent resolves to the wrong app or why a permission check fails.

Tree Viewer

portal pcp inspect tree --app org.example.editor
portal pcp inspect tree --surface 0x42 --depth 5

Dumps the accessibility element tree for a running app or specific surface. Shows element IDs, roles, names, states, and bounding boxes. Mirrors what the AT-SPI2 adapter sees.

Manifest Validator

portal pcp validate manifest /path/to/manifest.json
portal pcp validate manifest --app org.example.editor --check-signature

Validates a capability manifest against the PCP schema. Checks required fields, types, capability ID format, and optionally verifies the Ed25519 signature against trusted keys.

Audit Log Viewer

portal pcp audit show --domain app --since "2026-07-20" --limit 100
portal pcp audit search --action delete --app org.example.editor

Reads the append-only audit trail at /var/log/portal/audit-*.jsonl. Supports filtering by domain, action class, app, time range, and result (success/failure). Each entry includes the full intent, permission decision, and execution outcome.

Intent Sandbox

portal pcp sandbox intent "delete all files" --app org.example.editor

Runs an intent in a sandboxed environment that logs every step of the execution pipeline without performing any real actions. Shows what capabilities would be invoked, what permissions would be checked, and what the final state change would be. Use this to verify that a capability handler behaves correctly without side effects.

Security Requirements

Every inspection method and CLI tool requires AuthLevel::Privileged. The compositor checks the caller’s AuthPrincipal before processing any inspection request. There is no way to downgrade or bypass this requirement.

Inspection results are not cached. Each query hits the live system state. This means inspection calls have the same latency characteristics as regular PCP operations and are subject to the same rate limiting rules.