mirror of
https://github.com/anomalyco/hex.git
synced 2026-11-22 01:54:19 +08:00
* Rename voice-control to hex everywhere, without migrations The Cargo package and binary are now hex, every OS keeps its data in a hex folder, and VOICE_CONTROL_* variables are HEX_*. Hex is a fresh app: the macOS voice-control rename, its symlink, and the Windows and Linux beta settings imports are gone. The Windows installer gets a new AppId so it never takes over an old voice-control install's entry. * Format * Drop the Windows paste-last default only the beta import used
225 lines
11 KiB
Markdown
225 lines
11 KiB
Markdown
# Linux Plan
|
|
|
|
**Status:** Active validation and capability plan. The x86_64 X11 beta,
|
|
wlroots-compatible native Wayland path, and Nix packaging are implemented.
|
|
Physical desktop/input validation and a genuine signed update remain release
|
|
gates; automated checks alone do not establish those behaviors.
|
|
|
|
## The Supported Contract Is Narrow
|
|
|
|
The Linux beta keeps its contracts explicit:
|
|
|
|
| Area | Contract |
|
|
| --- | --- |
|
|
| Distribution | Signed user-local direct install, or Nix-owned package updates |
|
|
| Host | x86_64 Linux; Arch/i3 reference and NixOS packaging |
|
|
| Desktop | i3/X11 or compatible wlroots Wayland compositor |
|
|
| Audio | CPAL through ALSA, typically backed by PipeWire |
|
|
| Inference | Vulkan with CPU fallback |
|
|
| Shortcut | Configurable key-containing chord; default `Alt+Space` |
|
|
| Insertion | Clipboard plus Ctrl-V, with a Ctrl-Shift-V terminal setting |
|
|
| UI | One process: the Rune window on demand and a Rune overlay HUD (layer-shell on Wayland, override-redirect on X11); a StatusNotifierItem tray icon when a tray host exists |
|
|
|
|
The beta does not claim voice commands, application or browser context,
|
|
meetings, or universal Wayland support. Wayland needs `wl-copy`, `wtype`, and
|
|
compatible compositor protocols; shortcuts come from the GlobalShortcuts portal
|
|
or from the user's compositor keybindings running `hex` commands.
|
|
There is no hidden XWayland or privileged injection fallback. See
|
|
[`../linux.md`](../linux.md) and [`../nix.md`](../nix.md).
|
|
|
|
## What Is Implemented
|
|
|
|
- Global hold/release dictation, Escape cancellation, and double-tap lock.
|
|
- Configurable persisted shortcut binding.
|
|
- Local model installation and transcription.
|
|
- Automatic clipboard insertion with bounded settling. The transcript remains
|
|
on the clipboard; arbitrary previous formats are not restored.
|
|
- CLI microphone override.
|
|
- One Hex process per user (optionally under a systemd user unit) with the
|
|
Rune window on demand, CLI controls, owner-only Unix IPC, desktop launcher,
|
|
and autostart entry.
|
|
- One shortcut state machine fed by X11 grabs, the Wayland GlobalShortcuts
|
|
portal, or idempotent `hex dictation`, `hex voice-action`, and
|
|
`hex paste-last` commands for desktops without the portal; persistent
|
|
click-through recording/processing overlay.
|
|
- Visible listener controls, transactional shortcut edits, and explicit service
|
|
shutdown; closing Settings leaves the managed runtime running.
|
|
- Nix package and matching development shell, NixOS installation, optional
|
|
Home Manager user service, and evaluated session-readiness checks.
|
|
- XDG paths, diagnostics, and exclusive listener ownership.
|
|
- Signed user-local updates with bounded download, exact size and SHA-256
|
|
verification, atomic version activation, and restart handoff.
|
|
|
|
The update path is implemented but is not yet proven by a complete signed
|
|
cross-version update on the supported Arch/i3 host.
|
|
|
|
The release script publishes the direct installer as `install-linux.sh`. The
|
|
installer verifies the same signed feed and content-addressed artifact as the in-app
|
|
updater, creates the managed version layout, and installs XDG desktop and
|
|
autostart entries. An AUR package is the preferred future Arch-native channel;
|
|
pacman must own updates for that layout.
|
|
|
|
## Remaining Work Is Sequenced By Capability
|
|
|
|
### 1. Validate The Signed Update Path
|
|
|
|
Run a genuine update between two published stable versions on the supported
|
|
Arch/i3 host. Verify:
|
|
|
|
- manifest signature and monotonic-version enforcement;
|
|
- exact artifact size and SHA-256 validation;
|
|
- atomic activation and application restart;
|
|
- retained-version rollback;
|
|
- refusal to overwrite development, root, or package-manager installs;
|
|
- systemd service restart and window reopen without requiring a tray host.
|
|
|
|
This validation blocks calling the direct-install update channel proven.
|
|
|
|
### 2. Add X11 Commands And Context
|
|
|
|
Only begin this slice when command parity is a product priority. Add:
|
|
|
|
- Moonshine command recognition and wake/sleep behavior;
|
|
- X11 foreground application and title through EWMH;
|
|
- platform-appropriate command shortcuts and application launch;
|
|
- MPRIS pause/resume for players Hex actually paused;
|
|
- logind or XDG idle-sleep inhibition;
|
|
- visible context age and failure.
|
|
|
|
Keep browser-host commands unavailable until a real browser adapter provides
|
|
the active URL. Never infer a URL from a window title.
|
|
|
|
### 3. Add Manual PipeWire Meetings
|
|
|
|
Manual meeting recording precedes automatic detection. Capture two explicit
|
|
sources:
|
|
|
|
1. The selected or default microphone source.
|
|
2. The monitor of the selected or default output sink.
|
|
|
|
Each callback must provide source, presentation timestamp, monotonic arrival
|
|
timestamp, sample rate, and mono float samples. Reuse the existing bounded WAV
|
|
writers, live drafts, gap accounting, manifests, recovery, and atomic final
|
|
publication.
|
|
|
|
Handle route replacement, Bluetooth profile changes, clock alignment, queue
|
|
pressure, and Hex feedback appearing in the output monitor. Route loss must
|
|
produce a visible gap or failure rather than silent corruption.
|
|
|
|
### 4. Add Metadata-Only Meeting Offers
|
|
|
|
After manual capture is reliable, observe PipeWire registry nodes and active
|
|
links without recording samples. Normalize process and media metadata into the
|
|
existing meeting-candidate model. Detection remains offer-only and never starts
|
|
recording automatically.
|
|
|
|
### 5. Expand Wayland Only With Explicit Capabilities
|
|
|
|
The implemented beta takes shortcuts from the GlobalShortcuts portal, or from
|
|
`hex` commands the user binds in the compositor, plus compositor-provided
|
|
clipboard and virtual-keyboard protocols. It reads no input devices and grants
|
|
no permissions. Broader support requires a separate capability decision:
|
|
|
|
| Contract | Input and insertion behavior |
|
|
| --- | --- |
|
|
| Basic | Portal shortcut, native clipboard, limited context, manual paste where injection is unavailable |
|
|
| Appliance | Automatic insertion and broader shortcuts through an explicitly approved privileged helper |
|
|
|
|
Unprivileged Wayland does not guarantee arbitrary foreground insertion, global
|
|
activity observation, foreground application identity, or bare-modifier
|
|
shortcuts. Do not hide those limitations behind XWayland.
|
|
|
|
Do not add compositor-specific shortcut paths or raw input-device readers;
|
|
the portal and the `hex` commands are the one general contract. If appliance
|
|
parity is ever required, decide on an approved helper separately and do not
|
|
build a general-purpose root daemon.
|
|
|
|
### 6. Validate Distribution Channels Deliberately
|
|
|
|
The app-managed updater owns only the user-local direct-install layout. Nix owns
|
|
its packaged installation and optional user service; a future Arch package must
|
|
also leave updates to the package manager. Add architectures,
|
|
distros, or package formats one validated channel at a time.
|
|
|
|
## Preserve The Portable Core
|
|
|
|
Do not fork these modules by platform:
|
|
|
|
- audio capture, mono conversion, bounded delivery, and drop accounting;
|
|
- dictation pre-roll, growable capture, controls, and resampling;
|
|
- transcription models, inference, processing, ordering, and cancellation;
|
|
- command grammar and pure resolution;
|
|
- event schema and bounded projections;
|
|
- paste continuation and clipboard restoration state transitions;
|
|
- meeting manifests, locking, WAV writing, transcript publication, and
|
|
recovery.
|
|
|
|
Platform adapters own native handles, permissions, and cleanup. Do not create
|
|
one application-wide `Platform` trait.
|
|
|
|
## Add Seams Only With Real Implementations
|
|
|
|
| Work beginning | Introduce then | Do not introduce |
|
|
| --- | --- | --- |
|
|
| X11 commands | Target action executor | Automation plugin registry |
|
|
| Foreground context | Private provider behind `ContextMonitor` | Browser framework before a browser adapter |
|
|
| PipeWire meetings | Capture session emitting existing packet facts | Generic media graph |
|
|
| PipeWire detection | Metadata-only microphone activity source | Sample capture for detection |
|
|
| Native Wayland | Runtime X11/Wayland capability selection | XWayland presented as native support |
|
|
| Privileged parity | Minimal versioned helper protocol | General-purpose root daemon |
|
|
| Additional packaging | One concrete channel and ownership rule | Universal package abstraction |
|
|
|
|
## Validation
|
|
|
|
Automated checks remain:
|
|
|
|
```sh
|
|
cargo fmt --check
|
|
cargo test
|
|
cargo clippy --all-targets --all-features -- -D warnings
|
|
git diff --check
|
|
./scripts/test-install-linux-release.sh
|
|
nix flake check
|
|
```
|
|
|
|
Run behavior tests against real adapters rather than mocks that repeat
|
|
implementation assumptions.
|
|
|
|
| Capability | macOS | X11 target | Wayland target |
|
|
| --- | --- | --- | --- |
|
|
| Command microphone and wake/sleep | Required | Required when shipped | Required when shipped |
|
|
| Hold/release, lock, cancel | Required | Required | Required if advertised |
|
|
| Foreground paste | Required | Required | Required if advertised |
|
|
| Send (paste plus Return) | Required | Required when shipped | Required when shipped |
|
|
| Browser, terminal, editor, Electron insertion | Required | Required | Capability-dependent |
|
|
| Application context | Required | Required when shipped | Capability-dependent |
|
|
| Desktop window and settings | Required | Required | Required |
|
|
| Manual two-track meeting | Required in developer builds | Required when shipped | Required when shipped |
|
|
| Offer-only meeting detection | Required in developer builds | Required when shipped | Required when shipped |
|
|
| Shutdown and route-loss recovery | Required | Required | Required |
|
|
|
|
## Risks
|
|
|
|
| Risk | Severity | Mitigation |
|
|
| --- | --- | --- |
|
|
| Generic Wayland parity is not a stable contract | Critical | Publish one constrained contract |
|
|
| Native Wayland insertion is compositor-controlled | High | Validate `wl-copy`/`wtype` on compatible compositors; broader portal/libei or approved-helper support needs separate validation |
|
|
| Foreground and browser context lack universal APIs | High | EWMH first; add a real browser adapter later |
|
|
| PipeWire output monitoring includes Hex feedback | High | Suppress feedback or construct a filtered capture graph |
|
|
| PipeWire metadata varies by package format | Medium | Build identity rules from observed fixtures |
|
|
| Packaging multiplies native dependencies | Medium | Keep one distro and channel until validated |
|
|
|
|
## Recorded Decisions
|
|
|
|
- Target x86_64 Arch Linux rolling on i3/X11.
|
|
- Ship through a signed user-local direct-install channel.
|
|
- Require automatic insertion and a key-containing shortcut.
|
|
- Exclude meetings; scope native Wayland to compatible wlroots protocols rather
|
|
than claiming every compositor. Shortcuts use the GlobalShortcuts portal or
|
|
user-bound `hex` commands, never raw input devices.
|
|
- Keep package-manager and app-managed update ownership separate.
|
|
- Do not install a privileged helper for the X11 contract.
|
|
- Rebuild the proposals in [#28](https://github.com/anomalyco/hex/pull/28) and
|
|
[#29](https://github.com/anomalyco/hex/pull/29) with regression coverage for
|
|
input state, overlay ownership, helper I/O, settings restart, and Nix environments.
|