docs: Unified Prompt Experience design spec

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
FactorandClaude Opus 5.5 committed 2026-11-19 10:17:56 +01:00
commit cca08c5645
1 file changed
+235
@@ -0,0 +1,235 @@
# Herdr — Unified Prompt Experience: projekt
Data: 2026-11-19 · Gałąź: `feature/unified-prompt` · Status: projekt (bramka A), przed makietą
## 1. Cel i powód
Jeden, stale widoczny Prompt Composer w Herdr do pracy z agentami AI uruchomionymi w terminalach
(Claude Code, Codex itd.). Wygoda pisania dłuższych promptów, załączniki (także obraz ze schowka),
historia, ulubione, autouzupełnianie i kolejka — jako jeden przepływ, wzorowany na UX Ovis.
## 2. Fakty z audytu (podstawa decyzji)
| # | Fakt | Źródło |
|---|---|---|
| F1 | Herdr to natywna aplikacja GPUI; rozszerzenia to mody JS (gpui-kit), layouty JSON, `keys.json`; wszystko przeładowuje się na żywo, bez rekompilacji. | `~/.config/herdr-app/AGENTS.md` |
| F2 | Agent w Herdr = terminal z programem TUI raportującym status (OSC 7501: `working/blocked/done/idle`). **Herdr nie ma widoku Chat.** | `AGENTS.md` („Agents are terminals…”) |
| F3 | Mod `prompt` to okno nazwy (rename), nie pole czatu. Pole wpisywania widoczne w terminalu rysuje program agenta. Mod nie może zmienić rysowania terminala. | `mods/prompt/main.js`, `AGENTS.md` („You can't … change how a terminal itself draws text”) |
| F4 | Istnieje mod `ovis-composer` (~2,3 tys. linii) i layout `ovis-composer` (klon `main`) z composerem w bloku `composer` (260 px) pod `work-body`. | `layouts/ovis-composer.json`, `mods/ovis-composer/*` |
| F5 | `ovis-composer` ma: drafty/załączniki/kolejkę per agent, wysyłkę `hc send`, załączniki przez `hc put` + `@path`, Drag & Drop (`on_drop`), autouzupełnianie `/` i `@` (`suggest.js`, `catalog.js`), stop (`hc interrupt`). | pliki modu |
| F6 | `storage.js` ma History (limit 500) i Favorites (limit 100), ale UI ich nie używa. Drafty nie są trwałe. Brak katalogu `tests/`, choć komentarze go wskazują. | `storage.js`, `main.js` |
| F7 | Composer dziś zabiera klawiaturę terminalowi (`reclaim`/`watchFocus`). | `main.js:401-430` |
| F8 | Mody czytają ze schowka tylko tekst; `Textarea` emituje `paste_other`, gdy schowek nie ma tekstu. | `gpui-kit.d.ts:346, 21469` |
| F9 | Mody mają `pickFolder`, nie mają wyboru pliku. Mają `exec`, `hc`, `shared/setShared`, `openOverlay`. | `herdr.d.ts` |
| F10 | `hc send` wkleja tekst i naciska Enter; nie potwierdza dostarczenia (zawsze `exit 0`). | `delivery.js` (pomiar 2026-11-17) |
| F11 | Ovis dostarcza obraz agentowi jako plik w `<cwd>/.ovis/` (z `.gitignore` `*`) + wzmianka `@<path>` w tekście. To jedyny kanał obrazu przez strumień PTY. | Ovis `server/paste.ts`, `lib/compose.ts:177` |
| F12 | `powershell Clipboard::GetImage()` działa na tej maszynie z poziomu `exec`. | próba 2026-11-19 |
## 3. Cele, nie-cele, anty-cele
**Cele**
- Jeden composer w globalnym layoucie, widoczny cały czas, jedna instancja i jeden stan.
- Drafty, załączniki i kolejka per agent; przełączanie agenta, zakładki, przestrzeni i layoutu nic nie gubi.
- History i Favorites w jednym panelu.
- Załączniki z trzech źródeł (przycisk, Drag & Drop, Ctrl+V) przez jeden mechanizm.
- Obraz realnie trafia do agenta jako plik + `@path`.
- Kolejka wiadomości podczas pracy agenta, bez dublowania.
- Fokus zawsze tam, gdzie kliknął użytkownik.
**Nie-cele**
- Widok Chat (transkrypt) — ewentualnie osobny, późniejszy projekt.
- Ukrywanie pola wpisywania w TUI agenta — technicznie niemożliwe bez rekompilacji i zmiany samego agenta (F3).
- Wsparcie macOS/Linux dla wyboru pliku i schowka obrazów w tym etapie.
**Anty-cele (porażka, nawet jeśli „działa”)**
- Composer przechwytuje klawisze, gdy fokus jest w terminalu.
- Załącznik widoczny w UI, który nie trafia do agenta.
- Utrata draftu lub wiadomości z kolejki przy przełączaniu, restarcie lub przerwaniu agenta.
- Podwójne wysłanie tej samej wiadomości.
- Zmiany w plikach dostarczanych przez Herdr (layout `main`, mody shipped).
## 4. Ograniczenia
- Bez rekompilacji Herdr. Tylko mod, layout-klon, `keys.json`.
- Mody shipped są tylko do odczytu; pracujemy wyłącznie na `ovis-composer` (nasz klon) i layoucie `ovis-composer`.
- Dane tylko lokalnie (`shared.json` przez `setShared`); nic do usług zewnętrznych.
- Wysyłka tylko przez `hc` (`send`, `put`, `interrupt`, `keys`, `wait`).
## 5. Rozważone podejścia (decyzje użytkownika z 2026-11-19)
**Widok Chat**
- A — bez widoku Chat, composer pod terminalem agenta. **Wybrane.** Najmniej pracy, zgodne z architekturą Herdr (F2).
- B — mod Chat renderujący transkrypt + stack Chat/Terminal. Odrzucone na ten etap: parser per agent, duży zakres.
**Baza kodu**
- Rozbudowa istniejącego `ovis-composer`. **Wybrane.** Działa już globalny blok, kolejka, `hc put`, autocomplete (F4, F5).
- Pisanie od zera. Odrzucone: powiela gotową, zmierzoną logikę (F10).
**Fokus i klawiatura**
- 1a — fokus tam, gdzie klik; powrót do composera kliknięciem lub skrótem. **Wybrane.**
- 1b — composer stale zabiera fokus (stan obecny). Odrzucone: łamie wymóg pisania wprost w terminalu.
**History i Favorites**
- 2a — jeden panel z zakładkami `Historia | Ulubione`. **Wybrane.**
- 2b — osobne przyciski i panele. Odrzucone: więcej kontrolek.
**Przycisk „dodaj plik”**
- 3a — systemowy dialog Windows przez `exec` PowerShell. **Wybrane.**
- 3b — bez przycisku. Odrzucone.
## 6. Projekt
### 6.1. Układ (layout `ovis-composer`)
Bez zmian strukturalnych: blok `composer` pod `work-body`, nad `status`. Rozmiar bloku: wysokość dopasowana
do treści — edytor auto 1–10 linii (wzór Ovis), ręczne przeciąganie granicy bloku (`resizable` layoutu).
Panel History/Favorites, menu autouzupełniania i podgląd obrazu otwierają się jako nakładki nad composerem
(`openOverlay` / floating), więc nie zmieniają wysokości obszaru terminala.
```
┌ tabs ─────────────────────────────────────────────────────┐
│ terminal agenta (TUI z własnym polem — zostaje widoczne) │
├ kolejka (tylko gdy niepusta) ──────────────────────────────┤
│ ⏳ Następna tura: „popraw testy…” [↑ Teraz][✎][✕] │
├ composer ──────────────────────────────────────────────────┤
│ [img][plik.ts ✕] │
│ Napisz do Claude Code… │
│ [+][🕘] /komenda @plik Claude Code · working [■]│
│ ~/repo · main │
└────────────────────────────────────────────────────────────┘
```
### 6.2. Fokus i klawiatura
- Usuwamy `reclaim`/`watchFocus` (F7). Composer nigdy sam nie zabiera fokusu.
- Fokus do composera: kliknięcie w composer lub skrót `ctrl-shift-space` (wpis w `keys.json` wysyłający komendę
`focus` do modu; mechanizm `nextCommand` już istnieje, `main.js:165`).
- W composerze: Enter — wyślij; Shift+Enter — nowa linia; Ctrl+Enter — wyślij teraz (gdy agent pracuje);
Alt+Enter — wstrzymaj (do kolejki bez automatycznej wysyłki); Esc — zamyka menu/panel, a gdy nic nie jest
otwarte i agent pracuje — przerywa agenta tylko przy pustym polu (wzór Ovis, ochrona przed przypadkiem).
Strażnik IME (`isComposing`).
- Fokus w terminalu: composer nie reaguje na żaden klawisz. Ctrl+V, `/`, `@` działają po stronie terminala.
### 6.3. Model danych
Klucz kontekstu: **adres agenta** (np. `t2`), bo to on jest celem `hc`. (Uwaga: `state.js` w komentarzu mówi
„agent name”, `main.js` — adres; ujednolicamy na adres.)
| Byt | Cykl życia | Przechowywanie |
|---|---|---|
| Draft `{text, caret}` | od pisania do wysłania | `shared("ovis-composer.draft:<agent>")`, zapis z opóźnieniem ~500 ms — **nowe**: drafty przeżywają restart |
| Załącznik `{id, kind:image/file, name, localPath, remotePath, bytes, state: adding/ready/error, error}` | od dodania do wysłania/usunięcia | razem z draftem |
| Wpis kolejki `{id, text, attachments, state, createdAt, reason}` | od zakolejkowania do wysłania/usunięcia | `ovis-composer.queue:<agent>` (istnieje) |
| Wpis historii `{id, text, sentAt, agent, agentName, space, spaceName}` | po faktycznym `hc send` z `exit 0` | `ovis-composer.history`, limit 500, duplikaty zachowane |
| Ulubiony `{id, text, createdAt}` | od oznaczenia do usunięcia | `ovis-composer.favorites`, limit 100 |
Historia i ulubione są niezależne: gwiazdka na wpisie historii kopiuje tekst do ulubionych.
### 6.4. Załączniki — jeden potok
Trzy wejścia → jedna funkcja `addFiles(paths)`:
1. **Przycisk `+`** → `exec powershell` z `OpenFileDialog` (multi-select) → lista ścieżek.
2. **Drag & Drop** → `on_drop` → `event.paths` (istnieje).
3. **Ctrl+V z obrazem** → zdarzenie `paste_other` → `exec powershell` zapisuje `Clipboard::GetImage()` jako PNG
do `<cwd agenta>/.ovis/paste-<czas>.png` (katalog dostaje `.gitignore` z `*`) → ścieżka. Brak obrazu → komunikat
„Schowek nie zawiera tekstu ani obrazu”. Ctrl+V z tekstem — standard pola tekstowego, bez zmian.
Schowek z plikami (skopiowanymi w Eksploratorze) → `Clipboard::GetFileDropList()` → te same ścieżki.
`addFiles`: walidacja (`attachments.js`: 32 MiB, typy, 100 na akcję) → kafelek w stanie `adding` →
`hc put <agent> <plik> --json` → `remotePath` → stan `ready` + wzmianka `@<remotePath>` w tekście
(istniejący mechanizm `mention`). Błąd → kafelek `error` z powodem i przyciskiem ponów.
Usunięcie kafelka usuwa wzmiankę (`removeMention`, istnieje). Miniatura obrazu: `image(localPath)`;
kliknięcie → nakładka podglądu (proporcje zachowane, `fit: contain`), Esc zamyka.
Gdy obraz jest dodany, a program agenta nie jest znany jako obsługujący obrazy (lista: claude, codex, gemini,
opencode), composer pokazuje ostrzeżenie przed wysłaniem — nie blokuje.
### 6.5. History / Favorites
- Przycisk 🕘 w pasku composera i skrót `ctrl-r` (tylko gdy fokus w composerze) otwierają panel nad composerem.
- Zakładki `Historia | Ulubione` (Tab przełącza), pole wyszukiwania z fokusem na starcie.
- Wyszukiwanie na żywo, bez wielkości liter, po fragmentach; dopasowania podświetlone; `×` czyści.
- Wiersz: tekst (2 linie, skrót), data i godzina, przestrzeń · agent; gwiazdka.
- Historia od najnowszych, ze wszystkich przestrzeni i agentów. Lista wirtualna (`v_virtual_list`).
- Strzałki — wybór; Enter — wstaw; Esc — zamknij i wróć do edytora.
- Wstawienie do niepustego draftu → mały wybór w panelu: `Zastąp` / `Dopisz na końcu` / `Anuluj`.
Pusty draft — wstawia od razu. Kursor na końcu tekstu, fokus w edytorze. Nigdy nie wysyła.
- Stany: pusta historia, brak wyników.
- Gwiazdka w composerze (przy niepustym drafcie) dodaje bieżący tekst do Ulubionych.
### 6.6. Autouzupełnianie
Bez zmian koncepcyjnych (F5): `/` na początku słowa — komendy i skille z katalogu (`catalog.js`), `@` — pliki
(`git ls-files`). Menu nad composerem, max 5 widocznych wierszy, grupy, ranking po użyciu (`ovis-composer.usage`).
Strzałki, Enter/Tab — akceptuj, Esc — zamknij. `/` i `@` zawsze wpisują się normalnie.
### 6.7. Kolejka i stany wiadomości
Decyzja wg statusu agenta (istnieje, `delivery.decide`): `idle/done` → wyślij; `working` → kolejka;
`blocked` → Enter z composera wysyła od razu (odpowiedź na pytanie agenta); kolejka stoi, dopóki agent nie
wróci do `working`/`idle` (decyzja użytkownika 2026-11-19, 2a).
Automatyczna wysyłka z kolejki (agent `working → idle/done`) poprzedzona jest 3-sekundowym odliczaniem
„Wysyłam za 3 s [Anuluj]” na wierszu; Anuluj → `held`. Powód: Ctrl+C wciśnięte bezpośrednio w terminalu
wygląda dla Herdr jak koniec tury (decyzja użytkownika 2026-11-19, 1a). Stop/Esc z composera → cała kolejka `held` od razu.
| Stan wewnętrzny | Co widzi użytkownik |
|---|---|
| `idle` (brak wiadomości w locie) | nic |
| `queued` | „Następna tura” |
| `held` | „Wstrzymana — wyślij ręcznie” |
| `sending` | spinner na wierszu |
| `sent` | wiadomość znika z kolejki, trafia do historii; krótko „Wysłano do terminala” |
| `uncertain` / `delivery_error` | „Nie potwierdzono” + [Ponów] [Edytuj] [Usuń] |
| `stopped` (agent przerwany) | kolejka **wstrzymana** (wszystko → `held`), nic nie wysyła się samo |
Akcje wiersza: Wyślij teraz, Edytuj (wraca do edytora; jeśli draft niepusty — ten sam wybór co w historii),
Usuń. Ochrona przed duplikatem: stan `sending` zapisywany przed `hc send` (istnieje), przycisk Wyślij
nieaktywny w `sending`. Po restarcie `sending` → `uncertain` (istnieje, `onRestart`).
### 6.8. Kontekst
Pasek pod edytorem: nazwa agenta + status (kropka), przestrzeń, folder i gałąź (z `panes()`), liczba załączników.
Bez modelu — Herdr go nie udostępnia. Gdy fokus Herdr nie wskazuje agenta: composer nieaktywny z napisem
„Wybierz agenta”, draft zachowany.
### 6.9. Obsługa błędów (wspólna)
Jedno miejsce na komunikat (`notice`, istnieje) + stan na konkretnym elemencie (kafelek, wiersz kolejki).
`hc` z `error` w JSON lub kodem ≠ 0 → komunikat ze `stderr`. Błąd zapisu `shared` → komunikat, dane w pamięci.
## 7. Repozytorium, instalacja, testy
- Źródła modu i testy w repo `herdrMario`: `mod/ovis-composer/*`, `layouts/ovis-composer.json`, `keys` (fragment),
`tests/*.test.mjs` (Node, `node --test`) dla modułów czystych (`state`, `delivery`, `storage`, `suggest`,
`attachments`, `view`, nowe: `history`, `clipboard`).
- Instalacja: junction `~/.config/herdr-app/mods/ovis-composer` → `herdrMario/mod/ovis-composer`
(najpierw kopia zapasowa obecnego katalogu). Layout kopiowany skryptem.
- Weryfikacja w aplikacji: `herdr-app check mods/ovis-composer`, `herdr-app status` (brak `errors`),
`herdr-app shot` do zrzutów.
- Weryfikacja obrazu end-to-end: wklej obraz → wyślij do Claude Code → agent opisuje treść obrazu.
## 8. Ryzyka
- `paste_other` może nie odpalać przy obrazie z niektórych programów → próba na starcie implementacji (spike).
- Opóźnienie `exec powershell` (~300–800 ms) → kafelek w stanie `adding` od razu.
- Aktualizacja Herdr zmienia API modów → `herdr-app check` po każdej aktualizacji; `.d.ts` są przepisywane przy starcie.
- `hc send` nie potwierdza dostarczenia (F10) → stan „Wysłano do terminala”, potwierdzenie ze statusu agenta.
## 8a. Decyzje po przeglądzie wykonawcy (decyzje architekta, do korekty przez użytkownika)
- **Obrazy i agenci zdalni:** obraz ze schowka zapisywany lokalnie w `~/.config/herdr-app/data/ovis-composer/paste/`
(nie w repo agenta), potem zawsze `hc put` — działa dla agenta lokalnego i zdalnego, jedna ścieżka dla
wszystkich trzech źródeł. Pliki starsze niż 7 dni są usuwane przy starcie modu. Zastępuje `<cwd>/.ovis/` z 6.4.
- **Ponowne użycie adresu agenta:** draft i kolejka zapisują też `program` i czas startu terminala
(z `terminals()`/`hc get`). Niezgodność po restarcie → kolejka cała `held`, draft przywrócony z komunikatem
„Szkic z poprzedniej sesji agenta”. Nic nie wysyła się samo do innego agenta.
- **Ctrl+C w composerze:** kopiuje zaznaczenie (standard). Przerwanie agenta: przycisk Stop lub Esc przy pustym polu.
- **Historia:** wpis po `hc send` bez błędu (kod 0 i brak `error` w JSON) — zgodnie z F10 oznacza „wklejono
do terminala”, nie „agent przyjął”.
- **Aktywny layout:** instalacja przełącza na `ovis-composer` (`layout.switch`); `main` pozostaje nietknięty.
## 9. Pozostawione wykonawcy
Nazwy funkcji i podział `main.js` na moduły; dokładne kolory i odstępy (wg makiety i `theme()`);
sposób zapisu draftu z opóźnieniem; komunikaty — w języku polskim, spójne z istniejącymi.