openhuman/docs/src-tauri/README.md

Tauri shell documentation (app/src-tauri/)

This folder is the desktop host for OpenHuman: Tauri v2 + WebView, IPC commands, window management, and bridging to the openhuman Rust sidecar (core JSON-RPC). It does not duplicate the full domain stack — that lives in the repo-root Rust crate (openhuman_core, src/bin/openhuman.rs).

Quick reference

Document	Description
Architecture	Modules, core process, sidecar staging
IPC commands	invoke commands registered in lib.rs
Core bridge	core_process, core_rpc, daemon helpers

Responsibilities

1. Web UI — Load the Vite build from app/dist (or dev server on port 1420).
2. IPC — Expose a small, explicit set of Tauri commands (see 02-commands.md).
3. Core lifecycle — Ensure the openhuman binary is running (child process and/or service) and proxy JSON-RPC via core_rpc_relay.
4. AI prompts on disk — Resolve bundled src/openhuman/agent/prompts from resources / dev cwd for ai_get_config / write_ai_config_file.
5. Window + tray — Desktop window behavior and system tray (see lib.rs).

Building the sidecar

app/package.json core:stage runs scripts/stage-core-sidecar.mjs, which cargo build --bin openhuman at the repo root and copies the binary into app/src-tauri/binaries/ for Tauri externalBin.

Stuck process recovery

Normal app quit runs teardown from RunEvent::ExitRequested: child webviews are closed before CEF shutdown, the embedded core's cancellation token is triggered, and the final process sweep sends SIGTERM to direct children before escalating holdouts with SIGKILL after a short grace period. Sweep summaries are logged as [app] sweep: term=N kill=M total=K; any nonzero kill count is a warning and means a child ignored graceful shutdown.

On macOS, hard exits such as Force Quit, SIGKILL, or a renderer crash can skip normal teardown. The next launch runs startup recovery before CEF cache preflight: it lists OpenHuman processes whose executable path belongs to the launching .app/Contents, skips the current process, sends SIGTERM, waits briefly, then sends SIGKILL to stragglers that still match the same pid and command. These events use the [startup-recovery] log prefix.

Startup recovery intentionally skips when OPENHUMAN_CORE_REUSE_EXISTING=1 is set so manual CLI-core reuse still works. It also skips when the CEF SingletonLock is held by a live process, letting the normal second-instance path fail without killing the already-running app.

For diagnostics, the Tauri command process_diagnostics_list_owned returns the currently owned process list used by startup recovery, or an error if process enumeration fails. The macOS implementation is bundle-scoped; Linux and Windows currently return an empty list.

Related

• Full stack narrative: ../ARCHITECTURE.md
• Frontend: ../src/README.md