# 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. - Wybrany tekst wstawia się od razu w miejscu kursora draftu (zaznaczenie, jeśli jest, zostaje zastąpione), bez pytania (decyzja użytkownika 2026-11-19). Draft nigdy nie jest nadpisywany w całości. Kursor za wstawionym tekstem, fokus w edytorze. Nigdy nie wysyła. Ctrl+Z cofa wstawienie. - 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 (zdejmuje wiadomość z kolejki i wstawia ją w miejscu kursora draftu, jak wpis 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.