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

237 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
- 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 `<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.