Files
herdrMario/docs/superpowers/specs/2026-11-19-unified-prompt-design.md
T
2026-11-19 10:17:56 +01:00

16 KiB
Raw Blame History

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.