Participants

Overview

PCP defines three participants in a tightly-coupled architecture: System Intelligence, the compositor, and adapters. Unlike client-server protocols such as MCP, where a language model connects to external tools over HTTP or stdio, PCP participants share a single process space. There is no network boundary to cross, no serialization layer, no daemon standing between the intelligence layer and the desktop.

This co-location is not an implementation detail. It is the architectural foundation that makes PCP’s latency, fidelity, and audit guarantees possible. Every participant has a defined role, and each role maps directly to a structural boundary within the compositor binary.

graph TD
    subgraph Compositor Process
        SI["System Intelligence"]
        Core["PCP Core"]
    end
    subgraph Adapter Layer
        AT["AT-SPI2 Adapter"]
        NV["Native Interface"]
        PL["Platform APIs"]
        BR["Compatibility Bridge"]
    end
    Apps["Applications"]

    SI -->|"invoke capabilities"| Core
    Core -->|"read / enrich"| AT
    Core -->|"read / enrich"| NV
    Core -->|"read / enrich"| PL
    Core -->|"read / enrich"| BR
    AT --> Apps
    NV --> Apps
    PL --> Apps
    BR --> Apps

System Intelligence

System Intelligence is the reasoning layer embedded in the compositor. It perceives desktop state, forms intent, and exercises agency by invoking capabilities through PCP Core. SI is not an external agent connecting to the OS from the outside. It is a compositor subsystem, sharing the same event loop, heap, and lifecycle as the windowing system itself.

This distinction has practical consequences. An external agent must poll or subscribe to desktop state over some IPC channel. It receives serialized snapshots, interprets them, forms a plan, and sends commands back across the same channel. Each crossing costs latency and loses fidelity. SI skips all of that. It calls PCP Core methods directly, operates on shared data structures, and receives events as they fire on the compositor’s own event loop.

SI draws on whatever cognitive resource serves its intelligence. That might be a local model, a remote inference endpoint, or a hybrid pipeline. The protocol does not dictate the inference backend. What it dictates is that SI is the system identity. It speaks with the authority of the OS, not as a guest tool requesting permission. When SI invokes a capability, the invocation carries the same weight as a user-initiated action, complete with audit logging and permission enforcement.

Because SI runs in-process, operations that external agents achieve through multi-step RPC chains collapse into single function calls. Reading a text buffer, subscribing to focus changes, activating a menu item: these are direct trait-method invocations on compositor data, not serialized requests traveling through a socket. The intelligence layer responds at the speed of the desktop itself.

The Compositor

The compositor is the single authoritative source of desktop state. Built on Wayland and wlroots, it tracks every surface, application, input event, workspace layout, clipboard contents, and output configuration on the system. Nothing on the desktop exists outside the compositor’s knowledge. Every window geometry, every z-order change, every keyboard event passes through it.

This authority matters because it eliminates the need for discovery heuristics. External automation frameworks spend considerable effort figuring out what is on screen: polling accessibility trees, scraping pixels, guessing at element roles. PCP does none of that. The compositor already knows. PCP re-exports what the compositor tracks, enriched with accessibility metadata, to the intelligence layer through PCP Core.

The compositor maintains the following state:

Domain	What the compositor tracks
Wayland clients	Connected applications, their protocols and lifecycles
Surfaces	Geometry, bounds, z-order stacking, visibility, and state flags
Input events	Keyboard, pointer, touch, and gesture streams
Outputs	Display configuration, resolution, scale factor, and layout
Workspaces	Virtual desktop arrangement and switch state
Focus	Current keyboard and pointer focus targets
Clipboard	Selection ownership and transfer state

PCP enriches this compositor state with data from the accessibility layer. AT-SPI2 trees provide element roles, states, actions, text content, value ranges, selection boundaries, and caret positions. The result is a desktop model that combines the compositor’s structural authority with the accessibility layer’s semantic depth. SI receives this merged model through PCP Core and acts on it directly.

Adapters

Adapters are the translation layers between PCP Core and the application ecosystem. Each adapter type knows how to extract semantic data from a specific class of application surface. Together they form a progressive-fidelity stack: deeper integration yields richer semantic access, but basic control is always available.

graph LR
    subgraph PCP Core
        direction TB
        Core["Desktop Model"]
    end

    subgraph Adapter Stack
        direction TB
        AT["AT-SPI2 Adapter"]
        NV["Native Interface"]
        PL["Platform APIs"]
        BR["Compatibility Bridge"]
    end

    subgraph Applications
        direction TB
        GTK["GTK / Qt / Electron"]
        T1["Tier 1 Native"]
        HW["Hardware Surfaces"]
        LEG["Legacy Windows"]
    end

    Core --> AT --> GTK
    Core --> NV --> T1
    Core --> PL --> HW
    Core --> BR --> LEG

AT-SPI2 Adapter

The AT-SPI2 adapter bridges the Linux accessibility tree into the PCP desktop model. GTK, Qt, Electron, and Firefox applications all expose their widget hierarchies through AT-SPI2. This adapter walks those trees, extracts element roles and states, reads text content and caret positions, and surfaces action sets for each accessible node. Most Linux desktop applications fall into this category, making the AT-SPI2 adapter the primary semantic bridge for the majority of installed software.

Native Server Interface

Tier 1 applications that ship signed capability manifests communicate through the native server interface. These apps bypass accessibility-tree bridging entirely. Instead, they register structured capability handlers that the compositor invokes directly. The native interface provides the highest fidelity: SI can read and write application data, invoke domain-specific operations, and receive typed results. The quickstart guide covers building Tier 1 applications in detail.

Platform APIs

Hardware surfaces, clipboard access, notification systems, and other platform-level resources are exposed through the platform adapter. These are not application-specific. They represent OS-level capabilities that any agent might need: reading the clipboard, posting a notification, or querying display geometry. The platform adapter gives SI access to these resources without requiring application cooperation.

Compatibility Bridges

Legacy applications that predate modern accessibility frameworks pose a harder problem. The compatibility bridge translates older interfaces, such as MSAA and UI Automation, into the PCP data model. This translation is necessarily lossy. Element roles get mapped to the closest PCP equivalent, text extraction falls back to bounding-box heuristics, and interaction collapses to input simulation. The bridge ensures that even legacy applications remain controllable, albeit at reduced fidelity compared to native or AT-SPI2-integrated apps.

In-Process Communication

All communication between SI and PCP Core happens through direct language-level trait calls. They share the same address space, the same heap, and the same event loop. There is no serialization step, no IPC mechanism, no Unix socket, and no message bus for internal operations.

This design choice has concrete implications. When PCP Core builds the desktop model from compositor state and accessibility-tree data, it does not serialize that model into bytes and ship it across a process boundary. SI receives a reference to the live data structure. Element trees are traversed through zero-copy views. State changes propagate through the compositor’s own event dispatch, not through polling loops or change notifications over a socket.

The contrast with IPC-based architectures is sharp. An external agent framework connecting over DBus or HTTP must serialize every request, transmit it, deserialize it on the other side, compute a result, serialize that, transmit it back, and deserialize the response. For a single capability invocation, that is a minimum of four serialization steps and two network crossings. For a voice command that requires reading text content, updating a selection, and confirming the result, the round-trip overhead compounds rapidly.

PCP eliminates that overhead entirely. Operations that would require multiple IPC round-trips in an external architecture collapse into single function calls. This matters for latency-sensitive work: voice commands that need sub-100ms response, real-time manipulation of text selections, continuous tracking of focus and input state. The intelligence layer operates on desktop state at the same speed the compositor itself does.

Shared memory does not stop at element trees. Event subscriptions, capability invocation results, audit log entries, and session metadata all pass through direct references rather than serialized copies. Type safety is enforced at compile time through Rust’s type system, not at runtime through schema validation of wire-format messages. If a capability handler returns the wrong type, the compiler catches it. No runtime deserialization error, no schema mismatch, no fallback code path.