Agent surface

C+ applications can expose a live native interface to an agent through the same semantic surface on every supported UI backend. The agent can describe the interface, act on exposed controls, and observe semantic events. The application chooses which nodes exist in that surface and supplies the grant that bounds each caller.

This is an optional application capability. A Facet application that never imports facet_agent links none of the agent stack.

Stack

agent_core owns policy and protocol-neutral behavior. A platform backend walks its live native or Facet tree and implements the backend vtable. agent_mcp serializes that vtable for an external caller; agent_inapp calls the same vtable directly.

inspector is separate. It is a developer tool for inspecting and editing the Facet tree; ordinary agent actions drive the interface a person can use and do not imply structural editing power.

Describe, act, observe

• Describe. describe_ui returns the curated, exposed tree by default. The opt-in full mode includes structural nodes, class names, and frames for diagnostics, but does not bypass exposure or value authorization. Backends re-walk the live interface before operations, so newly mounted controls can appear in the next snapshot. Developer keys and list-item keys provide stable identities across rebuilds.
• Act. Backend verbs include click, text entry, navigation or scrolling, hit testing, caret movement, and platform-supported menu actions. Every verb is checked against exposure, the widget's affordance ceiling, and the caller's grant before native I/O occurs. Text writes carry a base version; a stale write returns VersionConflict instead of replacing newer text.
• Observe. Semantic events use curated verbs and optional node, verb, and role filters. Subscriber queues are bounded; UiChanged coalesces and an overflow drops the oldest event rather than blocking the emitter.

Capability grants

Authorization is a capability set, not one allow/deny bit. An external policy has the shape fn(Request) -> Grant; an in-process session carries a Grant directly. The seven capabilities are:

The convenience grants are nothing(), reader(), operator(), protected_reader(), and protected_operator(). None includes either Private bit or cap_edit_tree; those must be added deliberately.

A Request identifies the InApp or External channel and carries the MCP client name, method, and an opaque token. The client name is useful for a legible consent prompt but is not a credential. Token verification and grant construction belong to application policy; agent_jwt provides the JWT-shaped middleware layer.

Sensitivity and exposure

Sensitivity is declared on content and inherited by descendants, with the strictest tier winning:

Tiers keep a node's existence and developer-authored name visible while withholding its value. Exclusion removes a subtree from the agent view. These checks are separate from whether a control is enabled, observe-only, wired to a handler, or otherwise actionable.

Facet integration

Enable the optional integration before App::run, and register the MCP endpoint before startup:

import "facet_agent/agent" as agent;
import "facet_runtime/runtime" as runtime;

fn run() -> i32 {
    agent::enable();
    runtime::agent_mcp("myapp");

    let app = runtime::App::new("myapp");
    app.window("main", Home::boxed);
    let _run = app.run("main");
    return 0;
}

facet_agent/consent supplies the common non-blocking policy: an unknown MCP client's first request is refused while the application presents a prompt; the client retries after the user decides. Applications can instead install any fn(Request) -> Grant policy with facet_agent::set_policy.

The runtime derives the listening address from the application id and process id. macOS and Linux expose a user-only Unix socket plus loopback HTTP; Windows, iOS, and Android use loopback HTTP. The application prints the selected endpoint and records its discovery information for launchers.