Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs: supersede RFC 2447 with SDK-owned runtime RFC (#2550)

Francesco Bonacci8ff43009a721
diff --git a/libs/cua-driver/docs/sdk-first-runtime-north-star.md b/libs/cua-driver/docs/sdk-first-runtime-north-star.md
new file mode 100644
index 0000000000..ceb781bb39
--- /dev/null
+++ b/libs/cua-driver/docs/sdk-first-runtime-north-star.md
@@ -0,0 +1,465 @@
+# Cua Driver SDK-First Runtime North Star
+
+**Status:** Draft for architecture discussion
+
+**Direction:** Make the typed SDK and its owned native runtime the product
+boundary. Keep daemon and server topologies as optional adapters.
+
+**RFC:** [RFC 2549](../../../rfcs/2549-cua-driver-sdk-owned-runtime.md)
+
+**Supersedes:** [RFC 2447](../../../rfcs/2447-cua-driver-native-core-and-mcp-adapter.md)
+
+**Related:**
+[permission adapters and session modes](permission-adapters-and-session-modes-plan.md),
+[#2385](https://github.com/trycua/cua/issues/2385), and
+[#2437](https://github.com/trycua/cua/issues/2437).
+
+## Decision at a glance
+
+Cua Driver is a stateful native runtime exposed through typed SDKs. An
+application creates the runtime, uses it, and shuts it down. MCP, HTTP, a
+private worker, and a long-lived daemon can expose that runtime when a consumer
+needs a transport or process boundary.
+
+The daemon remains supported, but it stops defining the application contract.
+The migration preserves the released CLI, MCP, Rust, Python, and TypeScript
+interfaces. Runtime ownership may change behind them only after compatibility
+and behavior-parity gates pass.
+
+The runtime and public SDK stay transport-free. gRPC, MCP, HTTP, local sockets,
+and environment forwarding carry generated Driver envelopes outside the core.
+
+```mermaid
+flowchart TB
+ subgraph Consumers["Applications and adapters"]
+ APP["Native application"]
+ PYAPP["Python application"]
+ TSAPP["TypeScript application"]
+ MCP["MCP stdio adapter"]
+ HTTP["HTTP adapter"]
+ CLI["CLI"]
+ end
+
+ subgraph Contract["Public product boundary"]
+ SDK["Typed CuaDriver SDK"]
+ end
+
+ subgraph Runtime["Owned runtime"]
+ AUTH["Authorization coordinator"]
+ SESSIONS["Sessions and browser bindings"]
+ UI["Cursor, capture, and recording"]
+ CORE["Native platform core"]
+ end
+
+ APP --> SDK
+ PYAPP --> SDK
+ TSAPP --> SDK
+ MCP --> SDK
+ HTTP --> SDK
+ CLI --> SDK
+
+ SDK --> AUTH
+ AUTH --> SESSIONS
+ AUTH --> UI
+ SESSIONS --> CORE
+ UI --> CORE
+```
+
+## One contract, several topologies
+
+The topology changes ownership and isolation. It does not change tool
+semantics, authorization, results, or generated SDK types.
+
+```mermaid
+flowchart LR
+ subgraph Direct["Default: direct SDK"]
+ DAPP["Host application"]
+ DSDK["CuaDriver object"]
+ DRUNTIME["In-process runtime"]
+ DAPP --> DSDK --> DRUNTIME
+ end
+
+ subgraph Worker["Optional: private worker"]
+ WAPP["Host application"]
+ WSDK["CuaDriver object"]
+ CHANNEL["Inherited private channel"]
+ WRUNTIME["Supervised worker runtime"]
+ WAPP --> WSDK --> CHANNEL --> WRUNTIME
+ end
+
+ subgraph Service["Optional: explicit service"]
+ CLIENTS["External clients"]
+ ADAPTER["gRPC, MCP, HTTP, or daemon adapter"]
+ SRUNTIME["Service-owned runtime"]
+ CLIENTS --> ADAPTER --> SRUNTIME
+ end
+```
+
+| Need | Preferred topology |
+| --- | --- |
+| One application owns automation | Direct SDK |
+| The host wants native crash containment | Private supervised worker |
+| An MCP client owns one stdio process on Windows or Linux | MCP adapter with its own runtime |
+| Standalone installed MCP runs on macOS | CuaDriver.app-owned service runtime |
+| Several external clients must share state | Explicit service or daemon |
+| CuaDriver.app must own a stable macOS permission identity | App-owned runtime or child |
+| Short-lived scripts need persistent shared state | Explicit service or daemon |
+
+## Daemonless still means stateful
+
+The runtime owns state until its SDK object shuts down. Removing the required
+daemon does not turn tools into independent stateless functions.
+
+```mermaid
+stateDiagram-v2
+ [*] --> Created: CuaDriver.create(options)
+ Created --> Running: initialize native runtime
+ Running --> Running: sessions, actions, capture, grants
+ Running --> Draining: shutdown()
+ Draining --> Stopped: finish admitted work and cleanup
+ Stopped --> [*]
+
+ Running --> Stopped: host or worker exits
+```
+
+The runtime owns:
+
+- session and browser-binding state;
+- the runtime authorization ceiling and immutable session authorization
+ contexts;
+- bounded manifests and their session bindings;
+- consent grants, indicators, and revocation;
+- cursor overlays where the topology provides a main-thread owner, plus
+ capture and recording;
+- platform threads and event loops;
+- cleanup for shutdown, expiry, and host death.
+
+## Compatibility is a hard constraint
+
+The architecture is not permission to disrupt current users. The CLI keeps its
+commands, defaults, flags, socket behavior, platform identity, exit codes, and
+machine-readable output. The SDKs keep `create`, `connect`, typed operation
+names, package exports, result envelopes, structured errors, and lifecycle
+behavior.
+
+Private-worker options and new runtime configuration are additive. Changing a
+released interface or an observably different default requires a separate
+compatibility decision and the appropriate semantic-versioning release.
+Browser-use improvements can continue shipping on the current daemon-backed
+CLI while the SDK-owned refactor proceeds behind these gates.
+
+## macOS TCC ownership
+
+TCC needs a stable responsible process. It does not require a global socket
+daemon.
+
+```mermaid
+flowchart TB
+ subgraph Embedded["Host-owned identity"]
+ HOST["Signed Host.app<br/>owns TCC grants"]
+ INPROC["In-process Cua runtime"]
+ CHILD["Private child runtime"]
+ HOST -->|"same process"| INPROC
+ HOST -->|"direct spawn keeps responsibility chain"| CHILD
+ end
+
+ subgraph Standalone["Cua-owned identity"]
+ CUAAPP["Signed CuaDriver.app<br/>owns TCC grants"]
+ CUARUNTIME["App-owned runtime or child"]
+ CUAAPP --> CUARUNTIME
+ end
+
+ subgraph Avoid["Unsupported ownership"]
+ RANDOM["Unrelated launcher"]
+ GLOBAL["Discoverable global daemon"]
+ RANDOM -->|"identity or responsibility is ambiguous"| GLOBAL
+ end
+```
+
+The host must load the runtime directly or spawn its private worker without
+breaking the macOS responsibility chain. CuaDriver.app can own the identity for
+standalone use. LaunchServices handoffs remain outside the supported embedding
+contract, but standalone installed MCP may use LaunchServices to reach
+CuaDriver.app and preserve its stable TCC identity.
+
+Direct permission checks are read-only. The embedding host owns permission UX
+and any restart required after Accessibility or Screen Recording grants
+change.
+
+## Permission modes belong to sessions below a runtime ceiling
+
+The trusted host chooses an immutable authorization ceiling when it creates a
+runtime. It then creates immutable session contexts beneath that ceiling before
+actions begin. Effective authority is the intersection of the runtime ceiling,
+the session context, managed policy, and user policy. A session can narrow but
+never widen the ceiling.
+
+Released callers that do not use a trusted host session API inherit a
+compatibility session with today's daemon or runtime behavior. This preserves
+the current CLI and SDK contract while the permission model becomes portable
+across direct, worker, and service topologies.
+
+```mermaid
+flowchart LR
+ HOST["Trusted host"]
+ CEILING["Runtime authorization ceiling"]
+ RUNTIME["CuaDriver runtime"]
+ SESSION["Immutable session authorization"]
+ BINDING["Bound action surface or<br/>authenticated connection"]
+ MODEL["Model or automation caller"]
+ TOOLS["Authorized tool execution"]
+
+ HOST -->|"constructs"| CEILING
+ CEILING --> RUNTIME
+ HOST -->|"creates before actions"| SESSION
+ RUNTIME --> SESSION
+ SESSION --> BINDING
+ MODEL --> BINDING --> TOOLS
+
+ MODEL -.->|"cannot create, select, or widen"| SESSION
+ BINDING -.->|"public session IDs are not authority"| CEILING
+```
+
+An unrestricted session suppresses Cua approval prompts only. Managed policy,
+user policy, hard invariants, TCC, resource ownership, revocation, and cleanup
+still apply. Its explicit acknowledgement must come from trusted host
+construction, not an agent-visible request.
+
+## Mixed trust uses authenticated sessions or separate processes
+
+A gateway may host several authorization modes beneath one runtime ceiling
+only when trusted host code creates the sessions and each action is bound to
+the corresponding authenticated connection or in-process action surface.
+
+```mermaid
+flowchart TB
+ GATEWAY["Trusted gateway"]
+ CEILING["Runtime authorization ceiling"]
+
+ subgraph RUNTIME["One runtime generation"]
+ STANDARD["Session A<br/>standard"]
+ BOUNDED["Session B<br/>bounded manifest"]
+ UNRESTRICTED["Session C<br/>unrestricted acknowledgement"]
+ end
+
+ A["Bound action surface A"]
+ B["Authenticated connection B"]
+ C["Authenticated connection C"]
+
+ GATEWAY -->|"constructs"| CEILING
+ CEILING --> STANDARD --> A
+ CEILING --> BOUNDED --> B
+ CEILING --> UNRESTRICTED --> C
+```
+
+The model receives only the action surface already bound to its effective
+context. It never receives the host-only session factory, mode setter,
+connection proof, or serialized authority value. Public session IDs remain
+lifecycle labels and cannot select permission modes.
+
+If a topology cannot provide a trusted binding, it exposes the compatibility
+session or uses a separate runtime-owner process per mode. Multiple in-process
+runtimes are a possible later optimization after every process-global facility
+has been isolated; they are not a security boundary against arbitrary host
+code.
+
+## Generated SDK direction
+
+The generated SDKs carry one typed contract into each supported language.
+Transports consume this contract instead of defining a second one.
+
+```mermaid
+flowchart LR
+ CORE["Private native core"]
+ ABI["Versioned C ABI"]
+ RUST["Safe Rust SDK"]
+ UNIFFI["Generated UniFFI bridge"]
+ PY["Python SDK"]
+ TS["TypeScript SDK"]
+
+ RUSTAPP["Rust applications and adapters"]
+ PYAPP["Python applications and adapters"]
+ TSAPP["TypeScript applications and adapters"]
+
+ CORE --> ABI --> RUST
+ RUST --> UNIFFI
+ UNIFFI --> PY
+ UNIFFI --> TS
+
+ RUST --> RUSTAPP
+ PY --> PYAPP
+ TS --> TSAPP
+```
+
+MCP stdio can create and own `CuaDriver` directly on Windows, Linux, and
+embedded macOS paths. Standalone installed macOS MCP keeps the signed
+CuaDriver.app service identity by default. It does not add a second proxy layer
+unless the deployment asks for service ownership or shared state.
+
+Remote applications use the same generated SDK through an internal remote
+connection backend. The backend exchanges generated Driver envelopes through a
+minimal authenticated channel. gRPC may implement that channel, but it does not
+become the native core, public SDK contract, or a second tool vocabulary.
+
+## Explicit single-runtime ownership follows portable authorization
+
+The current implementation still has process-global authorization and platform
+state. First, canonical dispatch receives a portable effective session context.
+Then one direct runtime per process becomes explicit and generation-scoped
+authorization and resource ownership move behind that runtime. Complete
+same-process multi-runtime isolation is later work.
+
+```mermaid
+flowchart LR
+ subgraph Today
+ GLOBALS["Process globals<br/>permission mode, manifest, hooks"]
+ CLIENTA["Runtime object A"]
+ CLIENTB["Runtime object B"]
+ CLIENTA --> GLOBALS
+ CLIENTB --> GLOBALS
+ end
+
+ subgraph FirstMilestone["First milestone"]
+ PA["Process A<br/>one runtime"]
+ COMPAT["Compatibility session<br/>current behavior"]
+ PB["Process B<br/>one runtime"]
+ SA["Authenticated session A"]
+ SB["Authenticated session B"]
+ FA["Process A facilities"]
+ FB["Process B facilities"]
+ PA --> COMPAT
+ PB --> SA
+ PB --> SB
+ PA --> FA
+ PB --> FB
+ end
+
+ GLOBALS -->|"make ownership explicit"| PA
+ GLOBALS -->|"isolate by process"| PB
+```
+
+State that must become runtime-owned includes:
+
+- runtime authorization ceiling and unrestricted acknowledgement;
+- immutable session contexts, bounded manifests, and policy views;
+- trusted session creation and authenticated action bindings;
+- consent provider and grant broker;
+- session registry and teardown hooks;
+- browser bindings and resource ownership;
+- mutable platform callbacks that currently assume one runtime.
+
+Shared process facilities must be read-only, synchronized, or represented by
+an explicit process coordinator. A second direct runtime returns a structured
+conflict until those facilities can no longer merge authority.
+
+## Migration path
+
+```mermaid
+flowchart LR
+ P0["1. Canonical authorization<br/>at runtime dispatch"]
+ P1["2. Portable session<br/>authorization"]
+ P2["3. Trusted session<br/>creation and binding"]
+ P3["4. Runtime ownership<br/>and single-runtime guard"]
+ P4["5. Make direct SDK<br/>the documented default"]
+ P5["6. Platform-aware<br/>MCP ownership"]
+ P6["7. Add private worker<br/>for isolation"]
+ P7["8. Authenticate service mode<br/>and measure compatibility use"]
+
+ P0 --> P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7
+```
+
+### Current work under this direction
+
+- PR #2542 remains necessary. Every topology needs canonical authorization at
+ runtime dispatch and an honest enforcement-adapter inventory.
+- PR #2545 is the portable session-authorization foundation. Keep its effective
+ authorization, mode-ceiling, expiry, and revocation concepts; route current
+ callers through one compatibility context; and move daemon-specific
+ registries behind the runtime boundary.
+- Trusted mixed modes ship only after a host-only session factory and an
+ authenticated action binding pass substitution, replay, expiry, revocation,
+ generation, and reconnect tests.
+- Issue #2437 is narrowed, not replaced. Its session model becomes
+ topology-independent, while separate runtime-owner processes remain the safe
+ fallback for topologies without a protected binding.
+- Issue #2385 remains topology-independent. Each sensitive capability still
+ needs a scoped enforcement adapter before Cua can claim active protection.
+
+## Invariants
+
+These are target-state requirements. The compatibility daemon must meet the
+service-authentication invariant before it is presented as a mixed-trust
+service.
+
+1. The typed SDK is the only application contract.
+2. Direct SDK, worker, MCP, HTTP, and daemon paths produce the same behavior.
+3. Each runtime receives an immutable authorization ceiling at construction.
+4. Each action resolves an immutable session context that can narrow but never
+ widen the runtime ceiling.
+5. No public tool, session ID, metadata field, environment value controlled by
+ the caller, or reconnect request can create, select, or widen authority.
+6. Released callers inherit a compatibility session with unchanged behavior.
+7. Runtime and session shutdown revoke the resources they own.
+8. A private worker dies with its host and exposes no reusable public endpoint.
+9. macOS permission status names the responsible signed application.
+10. Unrestricted mode changes prompt behavior but does not bypass policy or OS
+ security.
+11. One direct runtime is allowed per process until shared facilities pass a
+ separate isolation gate.
+12. Browser and CDP bindings do not migrate between sessions or runtime
+ generations.
+13. Every service endpoint authenticates its peer; endpoint location is not
+ identity.
+14. Released CLI, MCP, and SDK interfaces remain compatible across topology
+ changes.
+15. gRPC and other remote protocols remain adapters outside the native runtime
+ and typed application contract.
+16. The daemon remains available only where a service topology earns its
+ operational cost.
+
+## Exit criteria
+
+The SDK-first architecture is ready to become the default when:
+
+- direct Rust, Python, and TypeScript SDK tests exercise the same typed
+ operations and error contract;
+- CLI help, subcommand, flag, exit-code, JSON, and MCP-schema fixtures remain
+ compatible;
+- Python and TypeScript export and signature snapshots remain compatible with
+ the previous supported release;
+- representative applications written against the previous supported SDK
+ release run without source changes;
+- released calls inherit a compatibility session with unchanged authorization
+ behavior;
+- a second direct runtime returns a structured conflict;
+- a session cannot exceed its runtime ceiling or exchange grants, manifests,
+ browser bindings, or handles with another session;
+- model-visible values cannot create or select a session authorization
+ context;
+- direct, worker, service, and remote actions resolve the context bound by
+ their trusted host or authenticated connection;
+- substitution, replay, duplicate binding, cross-generation use, expiry,
+ revocation, and reconnect-without-reauthorization fail before dispatch;
+- topologies without a trusted binding use the compatibility session or
+ separate runtime-owner processes per mode;
+- Windows and Linux MCP stdio can own a runtime without opening a daemon
+ socket;
+- shutdown, host death, cancellation, and in-flight side effects have tested
+ outcomes;
+- macOS tests prove embedded host-owned and standalone CuaDriver.app-owned TCC
+ attribution;
+- private-worker tests prove parent-liveness cleanup and generation isolation;
+- direct macOS overlays use a certified main-thread adapter or report
+ structured unavailability;
+- local and remote service endpoints reject unauthenticated peers;
+- browser bindings, recordings, overlays, and grants remain generation-scoped;
+- compatibility telemetry shows which consumers still need `connect()` and the
+ long-lived daemon.
+
+## Open decisions
+
+- Which platform services can safely remain process-global?
+- Does the private worker use the stable C ABI directly or a narrow inherited
+ control channel above the SDK?
+- How long should `CuaDriver.connect()` remain a supported compatibility path?
+- Which existing daemon administrative tools need typed SDK replacements?
diff --git a/rfcs/2447-cua-driver-native-core-and-mcp-adapter.md b/rfcs/2447-cua-driver-native-core-and-mcp-adapter.md
index 32399cb5db..9b126f715d 100644
--- a/rfcs/2447-cua-driver-native-core-and-mcp-adapter.md
+++ b/rfcs/2447-cua-driver-native-core-and-mcp-adapter.md
@@ -5,19 +5,23 @@ authors:
- Cua maintainers
- "@r33drichards"
created: 2026-07-22
-last_updated: 2026-07-22
-status: review
+last_updated: 2026-07-24
+status: superseded
discussion: https://github.com/trycua/cua/issues/2447
implementation:
- https://github.com/trycua/cua/pull/2461
- https://github.com/trycua/cua/pull/2467
- https://github.com/trycua/cua/pull/2468
supersedes:
-superseded_by:
+superseded_by: 2549
---
# RFC 2447: CUA Driver: Native Core and MCP Adapter
+> **Superseded by [RFC 2549](2549-cua-driver-sdk-owned-runtime.md).**
+> RFC 2549 carries forward the typed-contract and native-ABI decisions while
+> replacing the runtime-ownership and process-topology guidance.
+
## Summary
CUA Driver has one public, typed SDK contract above a native core. The native
diff --git a/rfcs/2549-cua-driver-sdk-owned-runtime.md b/rfcs/2549-cua-driver-sdk-owned-runtime.md
new file mode 100644
index 0000000000..b08ab19c30
--- /dev/null
+++ b/rfcs/2549-cua-driver-sdk-owned-runtime.md
@@ -0,0 +1,1300 @@
+---
+rfc: 2549
+title: "Cua Driver: SDK-Owned Runtime and Optional Services"
+authors:
+ - Cua maintainers
+created: 2026-07-24
+last_updated: 2026-07-24
+status: review
+discussion: https://github.com/trycua/cua/issues/2549
+rfc_pr: https://github.com/trycua/cua/pull/2550
+implementation:
+supersedes: 2447
+superseded_by:
+---
+
+# RFC 2549: Cua Driver: SDK-Owned Runtime and Optional Services
+
+## Summary
+
+Cua Driver will make the typed `CuaDriver` SDK and its owned native runtime the
+default application boundary. Applications create a stateful runtime, use it,
+and shut it down without first starting or connecting to a shared daemon.
+
+MCP, HTTP, private workers, and long-lived daemons remain supported as adapters
+for deployments that need a protocol or process boundary. They consume the same
+typed SDK and preserve the same behavior. A daemon becomes an explicit service
+choice instead of a prerequisite for every integration.
+
+The native runtime and public typed contract remain transport-free. gRPC,
+HTTP, MCP, local sockets, and environment-specific forwarding are adapters
+around a generated Driver connection, not dependencies of the core.
+
+Authorization moves from process-global configuration into a runtime ceiling
+and immutable session contexts. Trusted host code selects the ceiling when it
+constructs the runtime and selects each session context before actions begin.
+Agent-visible requests, public session IDs, and transport metadata cannot
+select or widen that authority. Calls using released interfaces inherit a
+compatibility session with the runtime's current behavior.
+
+The first milestone supports one direct runtime per process. A second
+`CuaDriver::create` call returns a structured conflict until process-global
+facilities have been isolated. A runtime may host different session modes only
+when a trusted host creates them and every action is bound to the corresponding
+authenticated connection. Otherwise, gateways use separate private workers or
+service processes.
+
+Standalone `cua-driver mcp` on macOS remains owned by the signed
+CuaDriver.app service so it keeps a stable TCC identity. Embedded macOS hosts
+may own the runtime directly. Windows and Linux MCP processes may own their
+runtimes directly.
+
+This RFC supersedes
+[RFC 2447](2447-cua-driver-native-core-and-mcp-adapter.md). It carries forward
+RFC 2447's typed SDK, generated bindings, native core, versioned C ABI, and
+downstream transport model. It replaces RFC 2447's runtime-ownership and
+daemon-topology guidance with the narrower decisions below.
+
+### Supersession scope
+
+The following RFC 2447 decisions remain normative through this RFC:
+
+- the typed `CuaDriver` SDK is the public application contract;
+- Rust, Python, and TypeScript expose generated forms of that contract;
+- the native core remains private behind the SDK and versioned C ABI;
+- MCP, HTTP, CLI, and daemon surfaces are downstream adapters;
+- adapters cannot bypass canonical authorization or invent a second tool
+ contract.
+
+This RFC replaces RFC 2447 where it was underspecified or coupled unrelated
+questions:
+
+- runtime ownership defaults to the application SDK rather than a daemon;
+- one direct runtime per process is the initial concurrency contract;
+- permission modes belong to immutable sessions below a runtime ceiling;
+- mixed modes require trusted creation and authenticated action binding, with
+ separate runtime-owner processes as the safe fallback;
+- MCP ownership depends on platform identity, including the macOS standalone
+ exception;
+- private workers and authenticated services are explicit optional
+ topologies;
+- platform facilities, lifecycle failure, and service authentication have
+ acceptance gates.
+
+## Motivation
+
+Cua Driver adopted a daemon for sound operational reasons:
+
+- the process owned long-lived sessions and desktop resources;
+- the installed macOS application gave TCC a stable responsible identity;
+- MCP, CLI, and SDK clients could share one runtime;
+- native failures stayed outside client processes.
+
+The daemon later became both the runtime owner and the public integration
+boundary. That coupling now creates costs:
+
+- applications must manage a process, socket, readiness, reconnects, and
+ generation changes before making a typed call;
+- the daemon and each client can carry different versions of the contract;
+- embedded hosts need extra lifecycle code to preserve their macOS
+ responsibility chain;
+- MCP often needs a stdio proxy in front of a socket daemon;
+- shared-daemon permission modes require authenticated session delegation;
+- SDK methods still inherit assumptions from the client-server topology.
+
+RFC 2447 established a different contract direction. The native core sits below
+a typed SDK, and MCP and HTTP consume that SDK. The first implementation now
+supports `CuaDriver::create`, which constructs the runtime in the importing
+process without starting an executable or opening a socket.
+
+The architecture should follow that contract. Runtime ownership belongs to the
+SDK object by default. Service processes remain available when a deployment
+needs them.
+
+## Goals
+
+- Make direct SDK creation the documented default for Rust, Python, and
+ TypeScript applications.
+- Preserve the released CLI commands, defaults, flags, socket behavior, exit
+ codes, and machine-readable output throughout the migration.
+- Preserve the released Rust, Python, and TypeScript SDK constructors, typed
+ methods, package exports, result envelopes, and error contracts.
+- Keep sessions, browser bindings, grants, capture, overlays, and cleanup
+ stateful for the lifetime of the runtime.
+- Give each runtime an immutable authorization ceiling and each session an
+ immutable effective authorization context selected by trusted host code.
+- Let a trusted gateway run different permission modes through authenticated,
+ connection-bound sessions or separate runtime-owner processes without a
+ model-visible mode selector.
+- Let MCP stdio own a runtime directly where platform identity permits it,
+ without requiring a second daemon and socket proxy.
+- Provide a private supervised-worker topology for hosts that want process
+ isolation.
+- Keep an explicit daemon or service topology for shared external clients and
+ compatibility.
+- Preserve one typed contract and one authorization path across every topology.
+- Keep the native runtime and public SDK contract independent of gRPC, HTTP,
+ MCP, local sockets, and environment-specific forwarding.
+- Allow authenticated remote clients through generated Driver envelopes and a
+ transport adapter without creating a second desktop-control contract.
+- Preserve stable macOS TCC ownership for host-owned and Cua-owned
+ applications.
+
+## Non-goals
+
+- Make desktop operations stateless.
+- Remove daemon support in this RFC.
+- Deprecate `CuaDriver.connect()` before usage and migration data exist.
+- Change the default CLI or standalone MCP topology as a prerequisite for
+ shipping browser-use improvements.
+- Rename or remove a released SDK method, constructor, option, result field, or
+ package export.
+- Support multiple direct runtimes in one process in the first milestone.
+- Treat two runtime objects in one process as a security boundary against
+ arbitrary code in that process.
+- Let a model create, select, or upgrade a runtime or session permission mode.
+- Treat a public session ID, tool argument, MCP metadata field, or reconnect
+ token as authority.
+- Replace the versioned C ABI or generated SDK bindings from RFC 2447.
+- Make gRPC, MCP, HTTP, or the current daemon framing the native core or public
+ SDK contract.
+- Define every future protected-consent adapter tracked by
+ [#2385](https://github.com/trycua/cua/issues/2385).
+- Change macOS TCC, Windows interactive-session, or Linux display security
+ rules.
+
+## Terminology
+
+**Native core**
+: The private platform implementation that performs desktop and browser work.
+
+**Typed SDK**
+: The public `CuaDriver` application contract exposed through Rust and
+generated language bindings.
+
+**Runtime**
+: A stateful native instance owned by a `CuaDriver` SDK object. It owns
+authorization, sessions, grants, bindings, overlays, capture, recording, and
+cleanup.
+
+**Direct runtime**
+: A runtime loaded into the application process through
+`CuaDriver.create(options)`.
+
+**Private worker**
+: A host-supervised child process that owns one runtime and communicates
+through a private inherited channel. It does not expose a reusable system
+endpoint.
+
+**Service runtime**
+: A runtime owned by a daemon, MCP server, HTTP server, or another process that
+intentionally serves external clients.
+
+**Adapter**
+: A component that maps another interface, such as MCP or HTTP, to the typed
+SDK.
+
+**Remote Driver connection**
+: An internal SDK backend that exchanges generated, versioned Driver envelopes
+through an authenticated asynchronous channel. gRPC may implement that channel,
+but the runtime does not depend on gRPC.
+
+**Runtime authorization ceiling**
+: The immutable maximum modes, unrestricted acknowledgement, policy bindings,
+and resource constraints a runtime may host.
+
+**Session authorization**
+: The immutable effective mode, optional bounded manifest, policy bindings,
+grants, expiry, runtime generation, and authenticated connection binding for
+one session. It can narrow but never widen the runtime ceiling.
+
+**Compatibility session**
+: The process-owned session context inherited by released CLI, MCP, daemon, and
+SDK calls that do not use a trusted host session API. It preserves current
+behavior while session authorization is introduced.
+
+## Current state
+
+### The typed SDK already owns a native runtime
+
+[`CuaDriver::create`](../libs/cua-driver/rust/crates/cua-driver-sdk/src/lib.rs)
+constructs `NativeAbiDriver` in the importing process. It launches no driver
+executable and opens no daemon socket.
+
+The same SDK retains
+[`CuaDriver::connect`](../libs/cua-driver/rust/crates/cua-driver-sdk/src/lib.rs)
+as a compatibility client for the installed daemon. Both paths expose the same
+typed methods.
+
+### Transport adapters sit above the SDK
+
+[RFC 2447](2447-cua-driver-native-core-and-mcp-adapter.md) defines the SDK as
+the application contract. MCP, HTTP, and CLIs consume the SDK. They do not
+define peer contracts to the core.
+
+```mermaid
+flowchart LR
+ CORE["Private native core"]
+ ABI["Versioned C ABI"]
+ SDK["Typed CuaDriver SDK"]
+ APPS["Applications"]
+ MCP["MCP adapter"]
+ HTTP["HTTP adapter"]
+ CLI["CLI"]
+
+ CORE --> ABI --> SDK
+ SDK --> APPS
+ SDK --> MCP
+ SDK --> HTTP
+ SDK --> CLI
+```
+
+### The daemon still owns compatibility and embedding paths
+
+`EmbeddedCuaDriverHost` starts a private daemon, waits for its socket, exposes
+SDK and MCP connection details, and owns shutdown. This path preserves a signed
+host application's macOS responsibility chain when it needs an external MCP
+endpoint or process separation.
+
+The preferred application path in
+[the embedding guide](../libs/cua-driver/rust/Skills/cua-driver/EMBEDDING.md)
+is already direct SDK creation.
+
+### Some state remains process-global
+
+Permission mode, managed and user policy, bounded manifests, consent-provider
+identity, session authorization, session registries and end hooks, capture
+scopes, recording and screenshot hooks, replay state, CDP port claims, browser
+download gates, the macOS cursor overlay, and the shared ABI executor still
+assume one process-wide runtime. Some setters also use first-writer-wins
+behavior and silently ignore later configuration.
+
+Two `CuaDriver` objects therefore cannot yet carry independent authorization
+or resource ownership reliably inside one process. The first direct-runtime
+milestone makes that constraint explicit instead of treating same-process
+multi-runtime isolation as a prerequisite.
+
+### Permission work reflects the shared-daemon topology
+
+Issue [#2437](https://github.com/trycua/cua/issues/2437) proposes trusted
+per-session modes in a shared daemon. The draft implementation in
+[PR #2545](https://github.com/trycua/cua/pull/2545) introduces daemon ceilings,
+connection-bound authorization contexts, leases, expiry, and revocation.
+
+The `SessionModeCeiling` and `EffectiveAuthorizationContext` concepts are
+portable beyond the daemon. The current implementation exposes only a
+process-owned compatibility context and keeps delegated mixed modes disabled
+until actions arrive on an authenticated connection. This RFC carries that
+portable model forward while keeping separate runtime-owner processes as the
+fallback when a trusted binding is unavailable.
+
+## Proposal
+
+### 1. Make the SDK-owned runtime the default
+
+Applications create one runtime through the typed SDK:
+
+```text
+host application
+ |
+ v
+CuaDriver.create(options)
+ |
+ v
+stateful native runtime
+```
+
+The runtime remains active until the host calls `shutdown()` and destroys the
+SDK object. It admits work, owns resources, evicts idle sessions, drains
+admitted calls during shutdown, and releases platform state.
+
+The SDK must not start a global daemon as a hidden side effect of `create`.
+Only one direct runtime may exist in a process during the first milestone.
+Additional creation attempts return a structured `runtime_already_exists`
+conflict. Supporting multiple direct runtimes later requires a separate
+isolation gate and evidence.
+
+### 2. Support three explicit execution topologies
+
+```mermaid
+flowchart LR
+ subgraph Direct["Direct SDK, default"]
+ DAPP["Host application"]
+ DSDK["CuaDriver object"]
+ DRT["In-process runtime"]
+ DAPP --> DSDK --> DRT
+ end
+
+ subgraph Worker["Private worker, optional"]
+ WAPP["Host application"]
+ WSDK["CuaDriver object"]
+ CH["Inherited private channel"]
+ WRT["Child runtime"]
+ WAPP --> WSDK --> CH --> WRT
+ end
+
+ subgraph Service["Service, explicit"]
+ CLIENTS["External clients"]
+ SERVER["gRPC, MCP, HTTP, or daemon adapter"]
+ SRT["Service-owned runtime"]
+ CLIENTS --> SERVER --> SRT
+ end
+```
+
+#### Direct SDK
+
+Direct SDK is the default for an application that owns its automation
+lifecycle. It has no driver socket, daemon discovery, or reconnect protocol.
+
+#### Private worker
+
+Private worker gives one host a process boundary without creating a shared
+service. The host starts the worker directly, supplies only an inherited
+channel or handle, and owns its lifetime.
+
+The worker must:
+
+- bind to one host generation;
+- terminate or revoke its resources when the host channel closes;
+- expose no discoverable endpoint advertised as private;
+- reject reconnect and reattachment after its original host channel closes;
+- return structured completion state for actions interrupted by worker death;
+- preserve the host's macOS responsibility chain when embedding requires it.
+
+#### Service
+
+Service mode supports external clients that intentionally share one runtime or
+need a network or socket endpoint. `cua-driver serve` and
+`CuaDriver.connect()` remain supported during migration.
+
+Service mode must authenticate every connection, state its lifecycle and
+sharing contract, and verify the connecting OS principal. It cannot become the
+implicit fallback when direct runtime creation fails.
+
+### 3. Keep one contract across topologies
+
+Every topology calls the same typed SDK operations and canonical runtime
+authorization coordinator.
+
+```mermaid
+flowchart TB
+ RUST["Rust application"]
+ PY["Python application"]
+ TS["TypeScript application"]
+ MCP["MCP adapter"]
+ HTTP["HTTP adapter"]
+ REMOTE["Generated remote Driver adapter"]
+ SERVICE["Daemon compatibility adapter"]
+
+ SDK["Typed CuaDriver contract"]
+ AUTH["Canonical runtime authorization"]
+ TOOLS["Native tool registry"]
+
+ RUST --> SDK
+ PY --> SDK
+ TS --> SDK
+ MCP --> SDK
+ HTTP --> SDK
+ REMOTE --> SDK
+ SERVICE --> SDK
+ SDK --> AUTH --> TOOLS
+```
+
+An adapter may reject an invalid request before calling the SDK. It cannot
+authorize a request that the runtime denies, invent a second tool schema, or
+call private core operations.
+
+#### Keep remote transport below the typed SDK
+
+Remote clients use the same generated SDK methods as local clients. Internally,
+the SDK may select an embedded, local-daemon, or remote connection backend. The
+remote backend exchanges generated, versioned Driver request and result
+envelopes over a minimal asynchronous channel with deadlines, cancellation,
+request identity, capability negotiation, and structured transport errors.
+
+The channel carries opaque Driver envelopes. It does not expose one hand-written
+method per tool. gRPC, a Fleet channel, an HTTP/2 stream, or another
+environment-specific route may implement the channel without entering the
+native core or changing the public desktop-control contract.
+
+The service-side adapter authenticates the remote principal, validates the
+generated envelope, applies lifecycle controls, and invokes the same typed SDK.
+Remote protocol generation and exhaustive dispatch remain coordinated with
+[the environment-convergence proposal](https://github.com/trycua/cua/pull/2513).
+They are not prerequisites for the local browser release or the first
+SDK-owned-runtime milestone.
+
+### 4. Move authority into runtime ceilings and session contexts
+
+Each runtime owns an immutable authorization ceiling created before it accepts
+actions. Each admitted session owns an immutable effective authorization
+context:
+
+```text
+RuntimeAuthorizationCeiling
+ allowed_permission_modes
+ unrestricted_acknowledged
+ managed_policy_view
+ user_policy_view
+ protected_consent_provider
+ runtime_generation
+
+SessionAuthorization
+ effective_permission_mode
+ optional_bounded_manifest
+ immutable_policy_bindings
+ approval_and_revocation_state
+ absolute_and_idle_expiry
+ runtime_generation
+ authenticated_principal_and_connection_binding
+```
+
+The exact public types remain an implementation decision, but the contract is
+fixed:
+
+- trusted host code supplies the runtime ceiling at construction;
+- trusted host code creates a session context before exposing its action
+ surface;
+- effective session authority is the intersection of the runtime ceiling,
+ session configuration, managed policy, and user policy;
+- a session can narrow but never widen its runtime ceiling;
+- constructor and trusted session options are authoritative;
+- compatibility environment variables apply only when the corresponding
+ constructor option is absent;
+- contradictory constructor and environment configuration fails closed;
+- the runtime validates it before registering tools;
+- runtime and session configurations cannot widen after construction;
+- agent-visible calls cannot create, replace, or select an authorization
+ context;
+- a public session ID remains a lifecycle label rather than an authority
+ bearer;
+- unrestricted requires a separate launch-time acknowledgement;
+- managed and user policy denials still apply;
+- session teardown revokes its grants and bindings;
+- runtime teardown revokes every session owned by that generation.
+
+Released callers that do not use a trusted host session API receive a
+process-owned compatibility session. Its effective mode and policy match the
+existing daemon or runtime configuration, so introducing this model does not
+change current CLI or SDK behavior.
+
+Process-global read-only data may remain shared. In the first milestone,
+mutable state that carries authority or resource ownership belongs to the one
+direct runtime or an explicit process coordinator. Later same-process
+multi-runtime support must first move or coordinate every relevant facility.
+
+```mermaid
+flowchart LR
+ subgraph Current["Current process assumptions"]
+ GLOBAL["Process-global mode, manifest, hooks"]
+ A1["Runtime A"] --> GLOBAL
+ B1["Runtime B"] --> GLOBAL
+ end
+
+ subgraph FirstMilestone["First milestone"]
+ P1["Process A<br/>one runtime"]
+ C1["Compatibility session<br/>inherits current mode"]
+ P2["Process B<br/>one runtime"]
+ S1["Authenticated session A"]
+ S2["Authenticated session B"]
+ F1["Process A facilities"]
+ F2["Process B facilities"]
+ P1 --> C1
+ P2 --> S1
+ P2 --> S2
+ P1 --> F1
+ P2 --> F2
+ end
+
+ GLOBAL -->|"make ownership explicit"| P1
+ GLOBAL -->|"isolate by process"| P2
+```
+
+### 5. Bind permission modes to trusted sessions
+
+A trusted gateway may create separate immutable session contexts beneath one
+runtime ceiling:
+
+```mermaid
+flowchart TB
+ HOST["Trusted gateway"]
+ CEILING["Runtime authorization ceiling"]
+
+ subgraph Runtime["One runtime generation"]
+ STANDARD["Session A<br/>standard"]
+ BOUNDED["Session B<br/>bounded manifest"]
+ UNRESTRICTED["Session C<br/>unrestricted acknowledgement"]
+ end
+
+ CA["Authenticated action connection A"]
+ CB["Authenticated action connection B"]
+ CC["Authenticated action connection C"]
+
+ HOST -->|"constructs"| CEILING
+ CEILING --> STANDARD
+ CEILING --> BOUNDED
+ CEILING --> UNRESTRICTED
+ STANDARD --> CA
+ BOUNDED --> CB
+ UNRESTRICTED --> CC
+```
+
+The trusted host receives a host-only session factory. The agent receives only
+the typed action surface already bound to one effective context. It does not
+receive the session factory, mode setter, connection proof, or serialized
+authority value.
+
+The binding mechanism depends on topology:
+
+- a direct SDK host creates the context before handing a session object to
+ untrusted automation;
+- a private worker binds the context to its inherited host channel;
+- a daemon or service binds the context to an authenticated accepted
+ connection;
+- a remote Driver adapter binds it to the authenticated remote principal and
+ connection generation.
+
+If a topology cannot provide that binding, it exposes only the compatibility
+session or uses one runtime-owner process per mode. It must not accept a
+model-supplied mode or use a public session ID as proof.
+
+Multiple runtime objects in one process remain a later performance
+optimization. Sessionized authority does not require them and does not turn
+same-process objects into a security boundary.
+
+### 6. Let MCP own or connect to a runtime according to platform identity
+
+On Windows and Linux, and for embedded macOS hosts that deliberately accept
+the host application's TCC attribution, the MCP stdio flow is:
+
+```text
+agent host starts cua-driver mcp
+ |
+ v
+MCP process creates CuaDriver runtime
+ |
+ v
+MCP requests call typed SDK methods
+ |
+ v
+stdin EOF triggers runtime shutdown
+```
+
+This flow uses one long-lived process. It keeps state for the MCP connection
+without starting `cua-driver serve` and proxying requests through a socket.
+
+Standalone installed `cua-driver mcp` on macOS is the exception. It connects
+to a runtime owned by the signed CuaDriver.app service so Accessibility and
+Screen Recording grants remain attributed to a stable application identity.
+An explicit direct option is supported for callers that deliberately want the
+MCP process or embedding host to own TCC attribution.
+
+An explicit connection option continues to support an existing service:
+
+```text
+cua-driver mcp --connect <service endpoint>
+```
+
+The final CLI spelling will follow the repository's CLI review process.
+
+### 7. Preserve platform ownership
+
+#### macOS
+
+TCC evaluates the responsible signed application:
+
+```mermaid
+flowchart TB
+ subgraph HostOwned["Embedded application"]
+ HOSTAPP["Signed Host.app<br/>owns TCC grants"]
+ DIRECT["Direct runtime"]
+ CHILD["Directly spawned private worker"]
+ HOSTAPP -->|"same process"| DIRECT
+ HOSTAPP -->|"responsibility inheritance"| CHILD
+ end
+
+ subgraph CuaOwned["Standalone application"]
+ CUAAPP["Signed CuaDriver.app<br/>owns TCC grants"]
+ CUART["App-owned runtime or child"]
+ CUAAPP --> CUART
+ end
+```
+
+Direct SDK creation performs TCC checks as the importing application. A private
+worker spawned directly by the host remains inside the host's responsibility
+chain. Standalone Cua use continues to rely on the signed CuaDriver.app
+identity.
+
+An embedded host must not use LaunchServices to start its private worker or
+silently launch an unrelated global daemon. The installed standalone MCP path
+may use LaunchServices to reach CuaDriver.app because preserving that stable
+responsible identity is the purpose of the service topology.
+
+Changing Accessibility or Screen Recording grants may require restarting the
+responsible host application. In direct mode, `check_permissions` reports
+state without trying to transfer ownership or perform hidden relaunches. The
+embedding host owns its permission-request UX and restart flow.
+
+#### Windows
+
+The runtime must execute in the interactive user's session. A service in
+Session 0 cannot own desktop input or capture and must fail before accepting
+actions. A direct runtime inherits the host process integrity level. A private
+worker inherits or is started inside the host's interactive session.
+
+Elevated or `uiAccess` input requires the signed Cua-owned UIAccess worker. Its
+named pipe is a service surface, not a private inherited channel, and must
+authenticate the connecting principal.
+
+#### Linux
+
+The runtime must bind to the intended display, compositor, and user session.
+Service mode may own a dedicated display environment. Direct and worker modes
+inherit an application-provided environment and must report the resolved
+desktop scope.
+
+On Wayland, XDG portal grants may be scoped to a runtime or session and may
+prompt again after restart. A long-lived service may amortize those prompts,
+but direct mode must report the actual portal scope rather than implying that
+grants survive runtime replacement.
+
+### 8. Define lifecycle and failure behavior
+
+```mermaid
+stateDiagram-v2
+ [*] --> Created: create(options)
+ Created --> Running: initialization succeeds
+ Created --> Stopped: configuration fails
+ Running --> Draining: shutdown()
+ Running --> Stopped: host or worker dies
+ Draining --> Stopped: admitted work resolves
+ Stopped --> [*]
+```
+
+The runtime must:
+
+- reject new calls after shutdown begins;
+- wait for already admitted calls before orderly shutdown returns;
+- revoke grants, indicators, bindings, and session authority;
+- finalize or report partial recordings and file outputs;
+- report whether an interrupted action completed, failed before its side
+ effect, or has unknown completion;
+- keep generation-scoped handles invalid after restart;
+- require new browser preparation and profile binding after restart; browser
+ and CDP bindings never migrate between runtime generations.
+
+### 9. Handle shared platform facilities explicitly
+
+Some resources may be unique per process or desktop:
+
+- cursor overlay ownership;
+- display capture streams;
+- keyboard and pointer injection backends;
+- platform callbacks registered through global APIs;
+- browser endpoint ownership;
+- recording encoders and session-end hooks.
+
+The implementation must classify each facility as:
+
+1. runtime-owned;
+2. immutable and safe to share;
+3. coordinated by an explicit process owner;
+4. unsupported across concurrent in-process runtimes.
+
+Concurrent use must return a structured conflict or apply a documented
+coordination rule. It cannot merge grants or bindings implicitly.
+
+The macOS cursor overlay is a process-coordinated AppKit facility that requires
+an owning main thread. A direct runtime exposes the overlay only when the host
+installs a certified main-thread UI adapter. Otherwise cursor-overlay methods
+return a structured `facility_unavailable` error without asserting or
+silently moving AppKit work to an unsafe thread. Private-worker and service
+topologies own a suitable event loop and provide the full overlay.
+
+A certified adapter is a documented SDK contract that schedules overlay work
+on the host's AppKit main thread and passes the platform overlay test matrix.
+Certification describes tested conformance, not a new signing authority.
+
+Cross-process competition for desktop-wide resources is OS-arbitrated or
+reported as a structured conflict. General cross-process scheduling is outside
+this RFC. Visible indicators and status affordances must still identify their
+owning runtime and remain revocable.
+
+### 10. Keep the daemon as an explicit product surface
+
+The daemon remains appropriate when:
+
+- several external clients must share one runtime;
+- a remote transport is required;
+- the deployment needs a stable Cua-owned process identity;
+- short-lived clients need state that outlives them;
+- native crash isolation is required and a private worker does not fit.
+
+Service documentation must identify:
+
+- who starts and stops the service;
+- which users or processes can connect;
+- whether clients share sessions and resources;
+- which authorization configuration the service owns;
+- what survives a client disconnect;
+- how version compatibility is negotiated.
+
+Every local service endpoint must combine restrictive filesystem or named-pipe
+permissions with same-user peer authentication. Unix endpoints verify peer
+credentials such as `getpeereid` or `SO_PEERCRED`; Windows named pipes verify
+the client token and use a restrictive ACL. A remote endpoint requires an
+explicit authenticated principal and transport security. Endpoint location or
+same-machine reachability alone is not authentication.
+
+The daemon remains a compatibility surface during migration. It may be
+presented as a mixed-trust service only after the authentication acceptance
+tests in this RFC pass.
+
+### 11. Treat compatibility as a release gate
+
+The runtime topology is an implementation choice behind existing public
+contracts. Migrating ownership must not force current CLI, MCP, Python,
+TypeScript, or Rust users to change how they invoke Cua Driver.
+
+The following CLI behavior remains stable until a separate reviewed proposal
+changes it:
+
+- bare `cua-driver` and `cua-driver mcp` invocation behavior;
+- existing subcommand names, flags, environment variables, and socket
+ selection;
+- default standalone macOS ownership through CuaDriver.app;
+- documented exit codes, JSON fields, MCP schemas, and error categories;
+- current session, shutdown, reconnect, and compatibility-daemon behavior.
+
+The following SDK behavior remains stable:
+
+- `CuaDriver.create(options)` and `CuaDriver.connect(socket_path)`;
+- released typed operation names and language-idiomatic projections;
+- package-root exports and generated binding names;
+- result envelopes, structured error categories, lifecycle, and cancellation;
+- compatibility with applications written against the previous supported
+ package release.
+
+New runtime options and worker constructors must be additive. A backend may
+change only after contract and behavior parity tests pass. Removing or
+renaming a released surface, changing a default topology with observable
+effects, or deprecating `connect()` requires a separate compatibility decision
+and the appropriate semantic-versioning release.
+
+Browser-use improvements may ship on the current CLI and daemon topology before
+the later phases of this RFC. The architecture migration cannot become a
+prerequisite for an otherwise compatible browser release.
+
+## Public API direction
+
+The final generated names require an API review. The conceptual surface is:
+
+```rust
+let driver = CuaDriver::create(RuntimeOptions {
+ authorization,
+ // Other runtime-owned options.
+})?;
+
+let isolated = CuaDriver::create_worker(WorkerOptions {
+ authorization,
+ // Worker lifecycle and packaging options.
+})?;
+
+let service_client = CuaDriver::connect(ServiceConnection {
+ endpoint,
+})?;
+```
+
+Each language binding must expose the same lifecycle and typed operations.
+Language wrappers may add idiomatic resource-management helpers, such as
+Python async context managers or TypeScript disposal helpers, without changing
+the underlying contract.
+
+`create_worker` is a proposed capability, not a commitment to this exact
+method name.
+
+Until a later multi-runtime isolation gate passes, `create` permits one direct
+runtime per process. Hosts that need another mode or trust domain use
+`create_worker` or an authenticated service process.
+
+The existing `create` and `connect` constructors remain public with their
+released signatures. The conceptual options above may add fields or helpers;
+they do not authorize replacing those constructors.
+
+## Alternatives considered
+
+### Keep the shared daemon as the default
+
+This preserves current deployment behavior and concentrates resource ownership
+in one process. It also keeps socket lifecycle, version negotiation, reconnect
+rules, and shared authorization in the common path for applications that do
+not need them.
+
+The generated SDK and direct runtime would remain secondary clients. That
+conflicts with RFC 2447's dependency direction.
+
+### Keep permission modes daemon-wide
+
+This is the lowest-change option for the current CLI. It cannot give an
+embedding gateway different immutable modes without starting one daemon per
+mode, and it makes permission semantics depend on process topology.
+
+This RFC instead adopts a portable runtime-ceiling and session-context model.
+Released callers inherit one compatibility context, preserving daemon-wide
+behavior until a trusted host uses the session API.
+
+### Trust public session IDs to select permission modes
+
+This would be easy to expose through MCP or the current daemon protocol. It is
+not selected because an agent can copy, substitute, replay, or invent public
+identifiers. A mode becomes effective only through a host-only factory and an
+authenticated action binding. Separate runtime-owner processes remain the safe
+fallback when that binding does not exist.
+
+### Remove all daemon and worker support
+
+A direct-only SDK would have the smallest topology. It would remove supported
+use cases for shared external clients, stable service identity, state that
+outlives short-lived callers, and process crash containment.
+
+This RFC keeps those topologies as explicit choices.
+
+### Make each action stateless
+
+Desktop automation depends on session scope, browser bindings, element
+generations, grants, recording state, and cleanup. Reconstructing that state
+for every action would weaken identity checks and increase startup cost.
+
+The proposal keeps a stateful runtime.
+
+### Keep separate hand-written contracts for SDK and transports
+
+Independent contracts can evolve at different speeds, but they invite schema,
+error, authorization, and lifecycle drift. RFC 2447 already chose one typed
+contract with generated language bindings.
+
+This RFC keeps that decision.
+
+### Make gRPC the native core contract
+
+gRPC provides useful framing, streaming, deadlines, and generated service
+stubs. Making it the core or public application contract would couple local
+embedded use to a network transport and let gRPC service evolution shape the
+desktop API.
+
+This RFC keeps gRPC as one optional carrier for generated Driver envelopes.
+The public contract remains the typed `CuaDriver` SDK.
+
+## Compatibility and migration
+
+Migration is additive until a separate deprecation decision.
+
+### Compatibility lock
+
+Before changing a default backend or process owner, capture the released CLI,
+MCP, Rust, Python, and TypeScript surfaces as compatibility fixtures. Each
+phase must run those fixtures against both the old and proposed topology.
+
+An internal ownership change is blocked when it changes a command line,
+constructor, package export, tool schema, result envelope, structured error,
+exit code, lifecycle outcome, or default platform identity without a separate
+public decision.
+
+The generated remote-connection work in
+[PR #2513](https://github.com/trycua/cua/pull/2513) is complementary. It may add
+an internal remote backend and authenticated service adapter, but it cannot
+replace local `create()` or `connect()`, introduce a second tool vocabulary, or
+make gRPC a core dependency.
+
+### Phase 0: Canonical authorization
+
+Land authorization at the runtime dispatch boundary so direct SDK, daemon,
+MCP, HTTP, CLI, and raw-socket paths cannot bypass it. Publish an honest
+inventory of active and metadata-only enforcement adapters.
+
+[PR #2542](https://github.com/trycua/cua/pull/2542) is the current candidate for
+this phase.
+
+Phase 0 changes the authorization enforcement point, not the public CLI or SDK
+signatures.
+
+### Phase 1: Portable session authorization foundation
+
+Land the runtime ceiling, effective session context, expiry, revocation, and
+context-aware dispatch model. Route released calls through a process-owned
+compatibility session with unchanged behavior.
+
+[PR #2545](https://github.com/trycua/cua/pull/2545) is the current foundation
+candidate. Its `SessionModeCeiling` and `EffectiveAuthorizationContext` types
+are retained, while daemon-specific registries become runtime-owned.
+
+Delegated mixed modes remain unavailable in a topology that lacks an
+authenticated action binding. This phase may ship before the larger runtime
+topology refactor and does not change the current CLI or SDK surface.
+
+### Phase 2: Trusted session creation and binding
+
+Add a host-only session factory that returns an action surface already bound to
+one immutable effective context. Direct hosts bind in-process, workers bind to
+their inherited channel, and services bind to an authenticated accepted
+connection.
+
+Released calls continue to inherit the compatibility session. A public session
+ID, MCP argument, environment value supplied by the agent, or reconnect token
+cannot select a context.
+
+**Gate:** mixed-mode support is advertised only for certified topologies whose
+host factory and action binding pass substitution, replay, expiry, revocation,
+and reconnect tests. Other topologies remain compatible and daemon-wide.
+
+### Phase 3: Runtime ownership and a single-runtime guard
+
+Make constructor authorization authoritative, define compatibility
+environment-variable precedence, and return a structured conflict on a second
+direct runtime in the same process. Move consent-provider ownership, grants,
+session registries, and generation-scoped bindings behind the runtime
+boundary.
+
+Publish the full process-global facility inventory. Do not wait for complete
+same-process multi-runtime isolation before shipping the direct default.
+
+### Phase 4: Direct SDK default
+
+Make `CuaDriver.create()` the primary path in Rust, Python, and TypeScript
+documentation and examples. Keep `connect()` documented as service mode.
+
+Package and version the native library with the generated SDKs on every
+supported platform.
+
+### Phase 5: Platform-aware MCP ownership
+
+Make MCP stdio own its runtime on Windows, Linux, and embedded macOS paths.
+Keep standalone installed macOS MCP connected to the signed CuaDriver.app
+service by default. Preserve explicit direct and service connection modes.
+
+### Phase 6: Private worker
+
+Add the supervised-worker topology with parent-liveness cleanup, private
+channel inheritance, generation binding, no reattachment, and
+platform-specific packaging.
+
+### Phase 7: Service authentication and cleanup
+
+Authenticate local peers and remote principals, then document the daemon as
+service mode. Measure remaining `connect()` and daemon usage before proposing
+any deprecation.
+
+### Later: Same-process multi-runtime isolation
+
+Only pursue multiple direct runtimes in one process when a measured use case
+justifies the extra coordination. This later phase must isolate or coordinate
+every process-global facility and pass the corresponding contention tests.
+
+```mermaid
+flowchart LR
+ P0["Canonical authorization"]
+ P1["Portable session<br/>authorization"]
+ P2["Trusted session<br/>creation and binding"]
+ P3["Runtime ownership<br/>single-runtime guard"]
+ P4["Direct SDK default"]
+ P5["Platform-aware MCP"]
+ P6["Private worker"]
+ P7["Authenticated service"]
+
+ P0 --> P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7
+```
+
+### Rollback
+
+Each phase keeps service mode available. A release may switch the documented
+default back to the daemon while preserving the typed SDK if direct runtime
+behavior fails a platform gate.
+
+Rollback must not restore an authorization bypass or migrate authority from a
+runtime into caller-controlled metadata.
+
+## Security, privacy, and telemetry
+
+### Threat model
+
+The caller may be an agent influenced by untrusted content. It can choose tool
+names and arguments exposed through its adapter. It cannot be trusted to choose
+its permission mode, approve a protected action, or provide a truthful session
+identity.
+
+Trusted host code owns runtime construction. If an agent can execute arbitrary
+code inside that trusted host process, the in-process authorization boundary
+does not contain it. Such deployments need a private worker, service identity,
+VM, or another external isolation boundary.
+
+### Authorization
+
+- The runtime ceiling is immutable after construction.
+- Each session authorization context is immutable after trusted creation.
+- Effective authority is the intersection of runtime ceiling, session context,
+ managed policy, and user policy.
+- A session can narrow but never widen its runtime ceiling.
+- Unrestricted requires explicit acknowledgement outside agent-visible tool
+ calls.
+- Managed policy, user policy, hard invariants, OS permissions, and resource
+ ownership apply in every mode.
+- Session IDs remain lifecycle labels. They do not carry authority.
+- Serialized bearer values cannot select a session context or upgrade a
+ runtime.
+- Actions bind to the session context selected by a trusted in-process host,
+ inherited worker channel, or authenticated service connection.
+- Adapters cannot mint or satisfy protected consent.
+- Grants bind to one session and runtime generation and revoke on either
+ teardown.
+
+### Process isolation
+
+The first milestone permits one direct runtime per process. Authenticated
+session bindings may carry different modes beneath that runtime's ceiling.
+Topologies without such a binding run different modes or trust domains in
+separate runtime-owner processes. This separation does not protect against a
+host that can arbitrarily control or inspect all of those processes.
+
+Private workers and services add process separation. Their channels must use
+OS identity and inherited-handle rules appropriate to the platform. Private
+workers accept only their original inherited host channel. Services
+authenticate every connection as described above.
+
+### Privacy
+
+Telemetry may report:
+
+- execution topology;
+- SDK and runtime versions;
+- runtime generation;
+- permission mode;
+- policy and manifest hashes;
+- counts of active sessions or grants;
+- structured refusal and lifecycle codes.
+
+Telemetry must not contain:
+
+- screenshots or accessibility trees;
+- typed text or clipboard contents;
+- cookies, browser storage, or page content;
+- local file contents or raw paths when a digest or class is sufficient;
+- protected-consent responses;
+- serializable authority values.
+
+### Protected consent
+
+Issue [#2385](https://github.com/trycua/cua/issues/2385) continues to govern
+which capability groups have active protected-consent adapters. Moving a
+capability into an SDK-owned runtime does not promote its enforcement state.
+The consent provider and grant broker become runtime-owned, but the protected
+host surface remains outside the agent-visible request channel.
+
+## Implementation plan
+
+### Slice A: Preserve canonical authorization
+
+- Land the `ToolRegistry::invoke` or enclosing runtime authorization
+ chokepoint.
+- Keep direct and service paths on that chokepoint.
+- Test aliases, raw routes, generated SDK calls, and daemon adapters.
+
+### Slice B: Land portable session authorization
+
+- Add immutable runtime-ceiling and effective-session-context types.
+- Pass an effective session context to the authorization coordinator.
+- Route released callers through one process-owned compatibility context.
+- Bind expiry, revocation, bounded manifests, and grants to that context.
+- Preserve `EffectiveAuthorizationContext` and `SessionModeCeiling` from
+ PR #2545 while keeping them independent of daemon protocol types.
+- Keep mixed-mode delegation disabled until a trusted session factory and
+ authenticated action binding exist.
+
+### Slice C: Add trusted session creation and binding
+
+- Expose a host-only session factory outside the agent tool registry.
+- Return an action surface already bound to one immutable context.
+- Bind direct sessions in-process, worker sessions to inherited channels, and
+ service sessions to authenticated accepted connections.
+- Reject mode escalation, public-ID substitution, replay, duplicate binding,
+ cross-generation use, expiry, and reconnect without reauthorization.
+- Keep released CLI and SDK calls on the compatibility context.
+
+### Slice D: Introduce runtime configuration
+
+- Remove process-global permission mode and bounded manifest lookups.
+- Pass runtime ceiling and session context through `DriverRuntime`.
+- Reject contradictory unrestricted acknowledgement.
+- Make constructor options authoritative, use compatibility environment
+ variables only for absent options, and fail on contradictory values.
+- Keep compatibility constructors mapped to one process-owned runtime config.
+
+### Slice E: Make single-runtime ownership explicit
+
+- Inventory mutable singletons and global callbacks.
+- Add a process-wide guard that permits one direct `DriverRuntime`.
+- Move generation-scoped authorization and resource ownership into
+ `DriverRuntime`.
+- Add an explicit coordinator for facilities that are unique per process.
+- Return structured conflicts for a second direct runtime and unsupported
+ facility use.
+- Defer complete same-process multi-runtime isolation until a consumer requires
+ it.
+
+### Slice F: Prove generated SDK parity
+
+- Regenerate Rust, Python, and TypeScript surfaces from one contract.
+- Test create, invoke, cancellation, shutdown, error mapping, and destruction.
+- Verify native library provenance in released packages.
+
+### Slice G: Simplify MCP
+
+- Let MCP stdio create a runtime directly on Windows, Linux, and embedded
+ macOS paths.
+- Keep installed standalone macOS MCP on the CuaDriver.app service identity.
+- Preserve explicit service connection mode.
+- Verify EOF cleanup and interrupted-action reporting.
+
+### Slice H: Add private workers
+
+- Define the narrow host-worker protocol.
+- Bind worker generation and authority at spawn.
+- Implement parent-liveness shutdown.
+- Reject reconnect and reattachment.
+- Prove TCC responsibility inheritance on macOS.
+- Prove interactive-session placement on Windows.
+- Prove display binding and cleanup on Linux.
+
+### Slice I: Complete service session binding
+
+- Move the configured-session registry from process-global state into the
+ service-owned runtime.
+- Connect the portable context model to an authenticated host-control and
+ action channel.
+- Keep host leases and connection proofs opaque, non-serializable, and bound to
+ one runtime generation.
+- Advertise mixed-mode service support only after the authenticated binding
+ passes the session authorization test matrix.
+
+### Slice J: Authenticate service endpoints
+
+- Verify Unix-domain-socket peers with same-user credentials in addition to
+ restrictive filesystem permissions.
+- Apply restrictive Windows named-pipe ACLs and verify client tokens.
+- Require explicit authenticated principals and transport security for remote
+ endpoints.
+- Treat the signed Windows UIAccess worker pipe as a service endpoint.
+- Test denial before runtime actions, session lookup, or delegated authority.
+
+## Test and acceptance plan
+
+The RFC is implemented when all of the following evidence passes.
+
+### Contract parity
+
+- Rust, Python, and TypeScript expose the same typed operations and lifecycle.
+- Direct, private-worker, MCP, HTTP, and daemon paths produce compatible
+ results and structured errors.
+- A generated remote Driver path produces compatible typed results without
+ exposing its transport through the public operation contract.
+- Generated contract and symbol checks pass on macOS, Windows, and Linux.
+- CLI help, subcommand, flag, exit-code, JSON, and MCP-schema fixtures remain
+ unchanged unless an independently reviewed compatibility change says
+ otherwise.
+- Python and TypeScript package-export and signature snapshots remain
+ compatible with the previous supported release.
+- Representative applications written against the previous supported Rust,
+ Python, and TypeScript packages run against the new release without source
+ changes.
+
+### Authorization
+
+- A second direct runtime in one process fails with a structured conflict.
+- Constructor options override absent compatibility defaults, and
+ contradictory explicit sources fail closed.
+- Released calls inherit a compatibility session with unchanged behavior.
+- A session context cannot exceed its runtime ceiling.
+- Sessions cannot exchange grants, manifests, browser bindings, or resource
+ handles.
+- An agent-visible request cannot create, select, or widen runtime or session
+ authority.
+- Public session IDs, MCP metadata, connection labels, and reconnect tokens
+ cannot select an effective context.
+- Direct, worker, service, and remote actions resolve the context bound by
+ their trusted host or authenticated connection.
+- Substitution, replay, duplicate binding, cross-generation use, expiry, and
+ revoked contexts fail before platform dispatch.
+- Unrestricted cannot start without trusted construction-time
+ acknowledgement.
+- Managed and user policy denials remain effective in unrestricted mode.
+- Session teardown invalidates its grants and bindings.
+- Runtime restart invalidates every prior-generation context, grant, and
+ binding.
+
+### Lifecycle
+
+- Concurrent shutdown calls are idempotent.
+- Shutdown rejects new work and drains admitted work.
+- Host death terminates a private worker and revokes its resources.
+- A dead or disconnected worker cannot be reattached.
+- Connection loss revokes or expires its session contexts according to the
+ declared lifecycle; reconnect cannot silently recover authority.
+- Interrupted actions report known or unknown completion honestly.
+- Idle sessions and recordings are reclaimed by their owning runtime.
+
+### Platform behavior
+
+- macOS direct mode reports the signed host application's TCC attribution.
+- macOS private-worker mode stays in the host's responsibility chain.
+- Standalone macOS MCP reports the signed CuaDriver.app identity.
+- Direct macOS permission checks are read-only and document host restart
+ requirements after grant changes.
+- Direct macOS cursor overlays either use a certified main-thread host adapter
+ or return `facility_unavailable`; worker and service paths provide the full
+ overlay.
+- Windows tests execute at the expected integrity level in an interactive user
+ session and reject Session 0.
+- The Windows UIAccess worker authenticates its named-pipe client.
+- Linux tests prove the intended display, compositor, and Wayland portal scope.
+
+### Resource isolation
+
+- Concurrent cross-process overlays, capture streams, recording, input, and
+ browser bindings either remain isolated, are OS-arbitrated, or return a
+ documented conflict.
+- Session end in one runtime-owner process cannot tear down resources owned by
+ another.
+- Worker or runtime failure cannot leave an unowned visible indicator or live
+ capture.
+- Browser profiles and CDP bindings never migrate across runtime generations.
+
+### Compatibility
+
+- Existing service clients continue to work through `connect()`.
+- Existing CLI and standalone MCP workflows retain their commands, defaults,
+ platform identity, and observable lifecycle.
+- Existing Rust, Python, and TypeScript callers retain their constructors,
+ typed methods, exports, result envelopes, and structured error categories.
+- Existing callers that do not use the host-only session factory inherit the
+ compatibility session without source changes.
+- Local service endpoints reject peers that fail same-user credential checks.
+- Remote service endpoints reject unauthenticated principals.
+- Service and direct versions negotiate or refuse incompatibility before
+ actions run.
+- Rollback to service-default documentation requires no data migration.
+
+## Unresolved questions
+
+- Which current platform callbacks can become runtime-owned, and which require
+ one process coordinator?
+- Should the private worker protocol call the stable C ABI directly or carry a
+ narrow SDK operation protocol?
+- Which daemon administrative tools still need typed SDK replacements?
+- What usage threshold and support window should precede a future
+ `CuaDriver.connect()` deprecation RFC?
+- Which authenticated host-control and action connection should first certify
+ mixed permission modes in a shared service?
+
+## Decision record
+
+RFC 2549 supersedes RFC 2447 while preserving its typed-contract and native-ABI
+decisions. Final disposition remains pending RFC discussion.