Skip to content
This repository was archived by the owner on Nov 8, 2026. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
e8a4bcb
bench: add scripts/bench_host.py (time-to-first / time-to-final)
Oct 29, 2026
96e1e65
host: stream partial results, route by scope/minQuery, forward action…
Oct 29, 2026
d6434fa
frontend: merge streamed results without jumping selection; tiered ra…
Oct 29, 2026
d329496
files: background chunked index, substring candidates, top-k heap
Oct 29, 2026
095da06
menus: cache-first AT-SPI search with worker-thread walks
Oct 29, 2026
b01ef74
run: mark Run: row as fallback; id carries the query
Oct 29, 2026
3f5e5ad
apps: rescan .desktop dirs in the background; refresh on warm
Oct 29, 2026
807a652
host: frecency history boosts recently chosen results
Oct 29, 2026
3aff304
omarchy: full native menu parity via omarchy-menu summon, guards, con…
Oct 29, 2026
6d5a1ed
system: key-bound Omarchy controls with sources; power/update moved t…
Oct 29, 2026
6f395e9
defaults: Omarchy default apps, TUIs and web apps as bound to keys; w…
Oct 29, 2026
6c6d844
run: conservative PATH discovery (scandir only, confirm-gated fallbac…
Oct 29, 2026
e56ff98
run: cite foot's package source
Oct 29, 2026
37f0394
release: 0.10.0 — changelog, roadmap, provider protocol docs, scopes
Oct 29, 2026
c89ebda
shell: fix duplicate textFormat in ActionPanel (palette failed to loa…
Oct 29, 2026
d53f0a8
shell: keep previous results while a query streams; no blank or stale…
Oct 29, 2026
911196e
ranking: rank file rows below command matches unless the query has fi…
Oct 29, 2026
3702f82
shell: Esc on a confirmation card returns straight to the results list
Oct 29, 2026
2ff8cd6
tests: make the three timing tests tolerant of slow machines
Oct 29, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 104 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,110 @@ Release numbers come from the root manifest.json. This changelog starts with

## [Unreleased]

## [0.10.0]

Native-session verification on Omarchy is still pending for everything
below: it is covered by Python/Node tests and a synthetic host benchmark only,
not yet exercised in the real Quickshell overlay on Hyprland.

### Speed
- The host streams merged results as soon as the first provider answers
(`partial`, `final`, `pending`, `failed`), then follow-ups under the same
query id. Late providers still update the final view.
- Manifest routing hints `minQuery`/`scopedOnly`, plus more scope prefixes
(`om:`/`menu:`, `s:`, `w:`, `m:`, `p:`, `run:`, `web:`).
- `op:warm` when the overlay opens: files, menus, apps, omarchy and run
pre-load caches. Frontend debounce went from 80 ms to 30 ms.
- Files: background chunked index (no per-entry stat), partial cold replies,
substring candidates with top-k selection; stat only for shown rows.
- Menus (AT-SPI): cache-first with stale-while-revalidate, walks on a
worker thread with a 1.2 s budget; stdin never blocks. Without gi or the
accessibility bus it answers [] instead of crashing.
- Apps: .desktop rescans happen in the background.
- Benchmark (`scripts/bench_host.py`, 60k-file synthetic home): warm
median 105 ms → 7 ms, cold "notes" 571 ms with no file rows → first rows
77 ms and files at 351 ms, typing "con…config" ~100 ms → 11–23 ms. With a
1.5 s straggler provider: first rows 502 ms → 14 ms. The final/unresolved
marker now arrives at 600 ms (merge deadline raised from 500 ms).

### Search quality
- Ranking tiers: exact > prefix > word boundary > substring > subsequence,
stable ties. `fallback` rows (`Run:` and PATH commands) always rank last.
- Selection follows the same result while rows stream in; updates wait
while an action panel or confirmation is open.
- Frecency: chosen results get a bounded `recent` boost within their tier
(`$XDG_STATE_HOME/pallet/history.json`, 14-day half-life, 400 entries,
`PALLET_HISTORY=0` disables; `Run:` commands are never recorded).

### Foundations
- Confirmation sheets are bound to the exact result id and query.
- Provider failures/timeouts are shown in the footer; action failures
(provider `executed:false`, host-launched argv that fails to spawn) flash
in the footer and raise an `omarchy-notification-send` notification.
- `launch` actions are spawned by the host (argv, no shell) so a missing
command is reported.
- Conservative PATH discovery in the run provider: directory listing only,
never executes candidates; exact name, or prefix with `run:`; confirm-gated.

### Omarchy parity and actions
- omarchy provider: every entry of Omarchy's own menu
(`default/omarchy/omarchy-menu.jsonc` plus the user overlay), run through
`omarchy-menu summon <id>`. `when`/`disabled` guards are evaluated in the
background like the native menu. Hidden rows stay hidden, installed rows
are marked, and unknown guards open the parent menu. Destructive and
system-state entries (power, remove, reset, security, DNS, updates,
installs) require confirmation. Shell panels (Network, Bluetooth, Audio,
Power, Display, Calendar, World Clock, Tailscale, Weather) are included.
- system provider: key-bound controls Omarchy does not list in its menu,
covering volume, mic, output and media-source switching, media keys,
brightness, keyboard backlight, Bluetooth power, notifications, window
helpers (Close All Windows confirms), time/battery and the agent picker.
Power and update rows moved to the omarchy provider (no duplicates). The
hibernation probe at import time was removed.
- New defaults provider (`web:`): Omarchy's default apps, TUIs and web apps
as its keys launch them (private browser, tmux/herdr terminals, cliamp,
btop, Signal, 1Password, Spotify, lazydocker when present, ChatGPT, Grok,
HEY Calendar/New Email, New X Post). Also web-app searches
(`youtube …`, `maps …`, `chatgpt …`, `grok …`, `google …`) with the text
percent-encoded into one URL argument.
- Every provider README lists the Omarchy source file for each command.

### Changed
- The system provider no longer offers Lock/Suspend/Reboot/Shutdown/Update.
The omarchy provider now provides them through the native menu.
- Files "open in editor" prefers `omarchy-launch-editor`; "terminal here"
uses `xdg-terminal-exec --dir=`.

### Fixed (Omarchy VM smoke test)
- Typing no longer flickers or shows stale rows. While a query is in
flight the previous answer is re-ranked locally against the new text
(also when editing backwards or across a scope prefix that still
matches); the list is only blanked for an empty query. Streamed partial
messages keep the previous rows of providers that have not answered yet,
so the 600 ms final message no longer reshuffles the list; the final
message is authoritative. The re-rank now uses the query text that was
sent for an answer, not the input text at the moment the reply landed.
Replies for old query ids are still dropped.
- Ranking: without file intent (`/`, `~`, `.`), file and folder rows sit in
their own band below every command row that matches at substring tier or
better (still above weak subsequence matches; their own tier order is kept
inside the band). "config" now lists Omarchy's Config, Update Config and
Update Config: … rows before ~/.config/ghostty/config, and "theme" lists
the Theme menu row before ~/.local/state/omarchy/current/theme. An
exact-named file no longer gets a bonus over an exact-named command.
- Esc on a confirmation card (for example Shutdown) cancels it and returns
straight to the results list instead of to the Actions panel; a second
Esc closes the overlay.
- Timing tests no longer fail on slow machines (TCG VM): `tests/timing.py`
scales time limits by `PALLET_TEST_TIME_SCALE` or a factor calibrated
from Python start-up time (never below 1). The menus no-accessibility test
keeps the provider's stdin open until it replies (closing it first lost
the walk worker's answer whenever hyprctl reported a focused window); the
guard-timeout test uses a scaled budget and a guard that always outlives
it; the streaming test warms the host up first and checks the first emit
against the slow provider's reply (fast row only, not final, `slow`
pending, earlier than the slow reply) as well as a scaled 0.3 s bound.

## [0.9.1]

### Fixed
Expand Down
13 changes: 13 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,10 @@ python3 scripts/check_release.py
python3 -m unittest discover -s tests -v
```

Timing tests scale their time limits on slow machines (calibrated from
Python start-up time); force a factor with `PALLET_TEST_TIME_SCALE=5` on a
TCG VM or loaded CI runner.

Host smoke test (does not execute result actions):

```sh
Expand All @@ -60,6 +64,15 @@ Use prefixes when you want one provider focused instead of mixed search:
- `files:invoice` or `f:invoice` — files only
- `obsidian:todo` or `o:todo` — Obsidian actions only
- `apps:zen` or `a:zen` — applications only
- `omarchy:theme`, `om:theme` or `menu:theme` — the native Omarchy menu (every entry) and shell panels
- `system:mute` or `s:mute` — volume, media, brightness, notifications, window helpers
- `web:lofi` (also `default:`) — Omarchy's default apps and web apps; text searches every web app
- `windows:`/`w:`, `menus:`/`m:`, `plugins:`/`p:` — open windows, the focused app's menus, plugins
- `run:pyth` — PATH commands starting with the text, plus `Run: pyth`

Mixed search remains the default; scopes are additive, not required. A few
leading words also pick a web app without a scope: `youtube lofi`,
`maps coffee`, `chatgpt …`, `grok …`, `google …`.

Mixed search remains the default; scopes are additive, not required.

Expand Down
50 changes: 45 additions & 5 deletions docs/PROVIDERS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,39 @@ A provider is a subprocess speaking newline-delimited JSON over stdio. It is nev
{"name": "apps", "exec": ["python3", "providers/apps/provider.py"], "capabilities": ["search"]}
```

Optional routing hints:

- `minQuery` — skip unscoped queries shorter than this many characters
(files and run use 3, menus and defaults 2). Scoped queries always reach the
provider, even when empty.
- `scopedOnly: true` — only answer when the query is explicitly scoped.

## Messages

Host to provider: `{"id":"q1","op":"search","query":"fire"}` · `{"id":"q2","op":"cancel","target":"q1"}` · `{"id":"a1","op":"execute","action":{...}}`.
Host to provider: `{"id":"q1","op":"search","query":"fire","scope":""}` · `{"id":"q2","op":"cancel","target":"q1"}` · `{"id":"a1","op":"execute","action":{...}}` · `{"id":"","op":"warm"}`.

Provider to host: `{"id":"q1","results":[...]}` · `{"id":"q1","results":[...],"partial":true}` · `{"id":"q1","cancelled":true}` · `{"id":"a1","executed":false,"error":"why"}`.

- `query` is the bare text with any scope prefix removed; `scope` is the
provider name when the user scoped the query (`f:`, `web:`, ...), else `""`.
- `partial: true` streams what is ready now; send the complete list later
under the same id without `partial`. Each reply replaces the provider's
earlier rows for that query.
- `warm` is sent when the overlay opens: pre-load caches, reply nothing.
Unknown ops must be ignored.
- `executed: false` with an `error` string is shown to the user (footer and
an `omarchy-notification-send` notification).

Provider to host: `{"id":"q1","results":[...]}` · `{"id":"a1","executed":true}`.
The host tags merged results with their provider name; custom actions route only back to that owning provider.
It streams cumulative merged snapshots to the client with `final`, `pending`
(still answering), `failed` (dead/unavailable), `unresolved` (on the final
snapshot: providers that did not answer by the deadline) plus `scope` and
`bare`. Rows arriving shortly after the deadline are still merged in.

Client to host (besides `search`/`cancel`/`execute`/`warm`):
`{"id":"l1","op":"launch","argv":[...]}` (the host spawns argv detached and
replies `executed`/`error`), and `{"op":"record","provider":"apps","result":"apps:x","title":"X"}`
(frecency history; see below).

## Result metadata

Expand All @@ -23,10 +50,23 @@ The host tags merged results with their provider name; custom actions route only
- `fallbackIcon`, `fallbackColor` — optional glyph/color used only when every icon candidate misses.
- `score` — advisory 0..1; blended with the frontend fuzzy score.
- `provider` — set by the host during merge.
- `id` — stable per result and unique per query meaning (for example `run:<query>`);
selection follows it while rows stream in, and a confirmation sheet is bound
to it plus the exact query.
- `fallback: true` — always ranked after every non-fallback row (the `Run:` row
and PATH command rows). The `run` provider is always treated as fallback.
- `recent` — set by the host, 0..1, from frecency history
(`$XDG_STATE_HOME/pallet/history.json`; `PALLET_HISTORY=0` disables it;
`run` rows are never recorded). It only reorders rows within the same match
tier (exact > prefix > word > substring > subsequence).
- Rows from the `files` provider rank below every other row that matches at
substring tier or better unless the query has file intent (`/`, `~` or
`.`), so an exact-named Omarchy, system or app row beats an equally named
file or folder.

## Action types

- `launch` — argv array, executed directly by the frontend, no shell
- `launch` — argv array, spawned detached by the host, no shell; a spawn failure is reported back
- `copy` — put text on the clipboard (frontend)
- `open` — path or url via xdg-open (frontend)
- `custom` — provider-defined payload sent back to the owning provider
Expand All @@ -37,10 +77,10 @@ The host tags merged results with their provider name; custom actions route only
{
"type": "launch",
"title": "Update Omarchy",
"argv": ["foot", "--", "omarchy", "update"],
"argv": ["omarchy-menu", "summon", "update.omarchy"],
"danger": "confirm",
"tone": "positive",
"confirmation": {"title": "Update Omarchy?", "detail": "Runs the official Omarchy update in a terminal."}
"confirmation": {"title": "Update Omarchy?", "detail": "Runs Omarchy's own menu action (omarchy-menu summon update.omarchy)."}
}
```

Expand Down
36 changes: 27 additions & 9 deletions docs/ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,31 @@ Implemented in 0.9.0, native-session verification still required:
- [x] Refresh on later searches, including in-place edits and removed entries.
- [x] Isolated regression tests; no installed programs launched during discovery.

Next foundation patches:
- [ ] Reject stale responses by query ID in the frontend, including edits,
clearing, dismissing, reopening, and changing scope.
- [ ] Preserve confirmations only for the exact selected result/query.
- [ ] Show provider failures/timeouts and propagate action failures.
- [ ] Ensure command suggestions cannot outrank meaningful local matches.
- [ ] Conservative exact/prefix PATH command discovery and user-saved TUI
profiles; never execute candidate binaries to discover capabilities.
Foundation patches (0.9.1–0.10.0; tests only, native-session verification
still pending):
- [x] Reject stale responses by query ID in the frontend, including edits,
clearing, dismissing, reopening, and changing scope (0.9.1).
- [x] Preserve confirmations only for the exact selected result/query.
- [x] Show provider failures/timeouts and propagate action failures
(provider `executed:false` and host launch failures).
- [x] Ensure command suggestions cannot outrank meaningful local matches
(`fallback` rows always rank last).
- [x] Conservative exact/prefix PATH command discovery; never execute
candidate binaries to discover capabilities.
- [ ] User-saved TUI profiles.

## 1b. Speed and Omarchy parity (0.10.0; native verification pending)

- [x] Streamed partial results, routing hints, warm-on-open, background
indexes for files/apps, cache-first AT-SPI menus.
- [x] Tiered ranking with stable ties and bounded frecency.
- [x] Full native-menu parity through `omarchy-menu summon`, with guards and
confirmations; shell panels; key-bound system controls; Omarchy
default apps/web apps and web-app searches.
- [ ] Verify on a native Omarchy session: overlay open time, streaming
without flicker, guard results matching the native menu, confirmations,
failure notifications.
- [ ] Evaluate `checked` menu state (currently not shown).

### Terminal application usage

Expand Down Expand Up @@ -79,7 +96,8 @@ not launch terminals, install packages, or read personal vaults.

## 4. Recents and favorites

- [ ] Empty-query recents, pinning, bounded ranking boosts, and stale-result
- [x] Bounded ranking boosts from history (0.10.0).
- [ ] Empty-query recents, pinning, and stale-result
cleanup. History can be cleared or disabled; commands/secrets are not
recorded by default.

Expand Down
4 changes: 2 additions & 2 deletions manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@
"schemaVersion": 1,
"id": "io.github.macifyer.pallet",
"name": "Pallet",
"version": "0.9.1",
"version": "0.10.0",
"author": "macifyer",
"license": "MIT",
"description": "A keyboard-driven command palette for Omarchy: applications, windows, AT-SPI menus, files, system actions, packages, Omarchy parity, plugins, run-any-command, and Obsidian actions with scoped provider prefixes in one Quickshell overlay.",
"description": "A keyboard-driven command palette for Omarchy: applications, windows, AT-SPI menus, files, the full Omarchy menu, system controls, Omarchy default apps and web apps, plugins, run-any-command with PATH discovery, and Obsidian actions with scoped provider prefixes in one Quickshell overlay.",
"kinds": [
"overlay",
"service"
Expand Down
26 changes: 23 additions & 3 deletions providers/apps/provider.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
import shlex
import shutil
import sys
import threading
import time

MAX_RESULTS = 15
Expand Down Expand Up @@ -155,12 +156,29 @@ def load_apps() -> list[dict]:
return sorted(apps, key=lambda a: (a['name'].lower(), a['desktop_id']))


_refreshing = threading.Lock()


def _refresh() -> None:
global _apps, _checked_at
try:
apps = load_apps()
_apps, _checked_at = apps, time.monotonic() # atomic swap
finally:
_refreshing.release()


def ensure_fresh(force: bool = False) -> None:
"""Load synchronously the first time (or when forced); afterwards a stale
list keeps serving while a background thread rescans the .desktop dirs,
so a keystroke never pays for the rescan."""
global _apps, _checked_at
now = time.monotonic()
if force or now - _checked_at >= CHECK_TTL_S:
_apps = load_apps()
_checked_at = now
if force or _checked_at == float('-inf'):
_apps, _checked_at = load_apps(), time.monotonic()
return
if now - _checked_at >= CHECK_TTL_S and _refreshing.acquire(blocking=False):
threading.Thread(target=_refresh, name='apps-refresh', daemon=True).start()


def score(query: str, app: dict) -> float:
Expand Down Expand Up @@ -226,6 +244,8 @@ def main() -> None:
continue
if msg.get('op') == 'search':
print(json.dumps({'id': msg.get('id', ''), 'results': search(str(msg.get('query', '')))}), flush=True)
elif msg.get('op') == 'warm':
ensure_fresh()
elif msg.get('op') == 'cancel':
print(json.dumps({'id': msg.get('target', ''), 'cancelled': True}), flush=True)
elif msg.get('op') == 'execute':
Expand Down
Loading
Loading