16 KiB
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 layoucieovis-composer. - Dane tylko lokalnie (
shared.jsonprzezsetShared); 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
execPowerShell. 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 wkeys.jsonwysyłający komendęfocusdo modu; mechanizmnextCommandjuż 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):
- Przycisk
+→exec powershellzOpenFileDialog(multi-select) → lista ścieżek. - Drag & Drop →
on_drop→event.paths(istnieje). - Ctrl+V z obrazem → zdarzenie
paste_other→exec powershellzapisujeClipboard::GetImage()jako PNG do<cwd agenta>/.ovis/paste-<czas>.png(katalog dostaje.gitignorez*) → ś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.
- 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(brakerrors),herdr-app shotdo zrzutów. - Weryfikacja obrazu end-to-end: wklej obraz → wyślij do Claude Code → agent opisuje treść obrazu.
8. Ryzyka
paste_othermoż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 stanieaddingod razu. - Aktualizacja Herdr zmienia API modów →
herdr-app checkpo każdej aktualizacji;.d.tssą przepisywane przy starcie. hc sendnie 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 zawszehc 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ż
programi czas startu terminala (zterminals()/hc get). Niezgodność po restarcie → kolejka całaheld, 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 sendbez błędu (kod 0 i brakerrorw JSON) — zgodnie z F10 oznacza „wklejono do terminala”, nie „agent przyjął”. - Aktywny layout: instalacja przełącza na
ovis-composer(layout.switch);mainpozostaje 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.