Computer module

Computer access using cmux-cua 0.7.1, pinned to commit e0f738807dbff2f35fe67d7fbcc99c7082cffc23 with the private alwith-cmux-host-v2 contract on macOS ARM64, Windows x64 and Linux x64. macOS uses the Codex profile; Windows and Linux use the native window profile. The TypeScript entry composes MCP descriptors from native authority without storing conversations. Its stable attachment descriptor is independent of Driver readiness and application execution authority. New, resumed and forked threads receive the same discoverable tool contract; the application grant is checked only when a computer tool executes.

The Rust host owns one embedded Driver child and a private transport. Its logical lease key is chosen by the consumer: U uses one application lease shared by every conversation. Individual thread cancellation or window hiding does not revoke this lease. Disabling computer use stops the child and revokes every native execution connection while leaving MCP discovery available. Hosts must shut down on application exit and connection loss. Launch directly from the signed application for macOS permission attribution.

macOS uses a Unix socket and requires Accessibility and Screen Recording. Windows uses authenticated local named pipes; Linux uses a private Unix socket and requires an interactive desktop session. Actual capture and accessibility evidence gate readiness on every platform. Linux window preview uses X11/XWayland; native Wayland window previews depend on compositor support and may be unavailable. Permission covers the local desktop, not an application allowlist. Elevated Windows apps may require OS privileges the ordinary driver does not have. No UIAccess helper is installed.

./artifacts supplies pinned download URLs or package-relative bundled paths, with SHA-256 digests. Apple Silicon macOS uses the archive in artifacts/ with cmux Codex profile and embedded-host patch; Windows/Linux use the same patched source with their native backend. All driver archives are bundled and checksum-pinned. Resolve bundled paths relative to the ./artifacts module and verify the archive before extracting it. Stage the executable, distribute licenses/, and sign it with the application. Patch sources and the rebuild script live in this repository under driver-patches/ and are excluded from the npm package. The MCP proxy uses an explicit embedded endpoint and cannot start a standalone daemon after revocation.

Run bun run test, bun run build, and bun run test:rust in this directory.

The gateway binds an MCP connection token to the returned session ID. It serializes tool access with a FIFO lease held until Runtime turn completion. Cancellation drains an outstanding native action before handoff; transport failure requires the host to stop the Driver before releasing native execution ownership. Consumers must forward Runtime run-state snapshots, including sessions awaiting input. Codex may restart an MCP process with its existing session descriptor. The gateway drains any dispatched action and closes the previous transport before accepting the replacement, which must discover its tools again. Transport failures and unknown action outcomes require explicit host recovery; actions are never replayed.

proxy/stdio.mjs runs with Bun and bridges MCP over authenticated loopback TCP. Stage it as an application resource. The preview independently captures the owned window as a bounded JPEG without changing the Driver's grounding cache. Consumers scope subscriptions to visible windows and discard stale target revisions. Frames are ephemeral and are not a video recording or conversation storage.

Startup verifies the driver's screenshot and accessibility-tree path against a visible host window before publishing a connection. Keep a host window open during recovery. Tool replies have a 150-second deadline (the driver's maximum 120-second tool budget plus transport headroom); protocol discovery has a 20-second deadline. Notifications do not extend these deadlines. A timed-out action has an unknown outcome: stop the Driver before resetting the gateway, reconnect, and observe rather than replaying it. Driver stderr and content-free tool timing records are kept in bounded in-memory buffers for the current application session only. Raw stderr may contain driver error details; it is never automatically persisted or uploaded.

On Windows/Linux, the gateway declares its host-owned Driver session before each session-bound tool call. Driver start_session is idempotent while active and explicitly revives an ended session, so a long-lived MCP connection cannot remain stuck on a tombstone. A failed declaration prevents the requested tool from being dispatched. User tool failures are returned unchanged and are never replayed. Application reconnection replaces the Driver generation and its execution connections while retaining MCP attachment identity.

On macOS, the agent receives the ten app-oriented cmux tools unchanged. Observe with get_app_state, use its grounded indices or coordinates, then refresh after layout changes, modal transitions, or errors. Actions report dispatch only. The cmux MCP proxy owns connection lifecycle; no per-action start_session call is injected. Host readiness/focus calls use a separate authenticated native endpoint and never expand the public MCP catalog. The cursor feed is read only for the current gateway owner and never enters the action request queue.

Every platform uses separate socket and host credentials, private state paths, forced MCP proxy routing, and a parent-lifetime pipe. Metadata validates the exact version, contract, profile, PID and host identity. Host-only operations are limited to readiness and focus and do not become agent tools. Embedded Windows daemons use the default local pipe ACL, reject remote clients and do not start a UIAccess worker. Embedded mode never exposes the optional unauthenticated HTTP transport. Legacy .cua-theme files are not applied; the driver uses its own native cursor.

Before packaging, build all three driver candidates using driver-patches/build.ts on their native OS and verify driver-patches/verify.ts. Only completed builds appear in src/artifacts.lock.json; a missing target fails staging and blocks packaging, with no fallback to another driver. The candidate workflow builds and tests without publishing. Unit tests and cross-compilation do not replace real Windows/Linux desktop capture, input and permission-revocation verification.

Tauri plugin

alwith-computer owns the host, gateway, fault recovery and preview:

.plugin(alwith_computer::init(Config { development_directory, proxy: Some(proxy), observer: Some(observer), ..Default::default() }))

Grant alwith-computer:default (or the settings, session and preview sets) to the windows that show computer UI, and call commands through @alwith/module-computer/commands. The application forwards Runtime run states with Computer::sync_running, calls Computer::release when Runtime or Codex exits, awaits Computer::shutdown in its exit sequence and calls Computer::kill_on_exit last.

Conversation-independent MCP attachments

The application grant defaults to disabled. Every conversation can attach the same computer MCP contract while execution is disabled. Attachment identity lasts for the MCP conversation attachment; Driver generations and their private credentials are internal to the native gateway. Opening, replaying, or sending a conversation must not wait for computer permission checks or Driver readiness.

The gateway answers discovery without a running control daemon. macOS uses the Driver's permission-free Codex bootstrap registry; Windows x64 and Linux x64 use its pure dump-docs --type mcp registry export. Tool names, descriptions, schemas, and action annotations come from that executable rather than application copies. Metadata discovery neither captures the desktop nor starts a control daemon.

Only computer calls acquire desktop ownership, check the current application grant and system permissions, and open an execution transport for the current Driver. Disabling access revokes execution admission before stopping every native Driver connection. Reconnection replaces those internal transports and credentials without closing the agent-facing MCP attachment. Failed calls return MCP tool errors; they do not fail conversation admission or replay. Unknown action outcomes are never replayed. A new observation is required after recovery.