Capabilities and references

A capability is a described operation, not an invitation to improvise arbitrary code. Its descriptor defines the command identity, input and output schemas, required permissions, risk, timeouts and execution semantics.

Discovery does not authorize execution

computerctl --json capabilities list
computerctl commands describe ui.invoke

A listed capability may still be unavailable in the current environment or denied by policy. Registering a driver or an MCP upstream does not enable all of its operations for every session.

References identify specific objects

Discovery can return an opaque reference for an application, window or control. It carries session and lifecycle context rather than asking the caller to repeat an operating-system identifier.

References are short-lived. Provider generations and backend fingerprints protect against known stale objects being silently replaced by newly created ones. A reference from another session is not a transferable permission token.

Ambiguity should stay visible

A query can return several candidates. A mutating operation must not silently choose one because its label seems close enough. Ranked search can help discovery; it must not substitute for explicit target resolution.

Catalogue revisions matter

A provider can change its catalogue. The runtime binds an invocation to the selected descriptor and provenance. Old pagination or descriptor state should fail rather than retarget an operation after a refresh.

A useful client sequence

Discover the relevant operation. Inspect its schema and risk. Resolve a current target when the operation needs one. Submit structured arguments. Handle denial, ambiguity, stale references and uncertain mutation outcomes explicitly; none of them justify a more privileged fallback.

Source: architecture and reference semantics, reviewed 22 September 2026.