commit cca08c5645d933970fd5b179ea36e2dcc38e2b67 Author: Factor Date: Thu Nov 19 10:17:56 2026 +0100 docs: Unified Prompt Experience design spec Co-Authored-By: Claude Opus 5.5 diff --git a/docs/superpowers/specs/2026-11-19-unified-prompt-design.md b/docs/superpowers/specs/2026-11-19-unified-prompt-design.md new file mode 100644 index 0000000..98a46bc --- /dev/null +++ b/docs/superpowers/specs/2026-11-19-unified-prompt-design.md @@ -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 `/.ovis/` (z `.gitignore` `*`) + wzmianka `@` 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:")`, 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:` (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 `/.ovis/paste-.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 --json` → `remotePath` → stan `ready` + wzmianka `@` 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 `/.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.