237 lines
16 KiB
Markdown
237 lines
16 KiB
Markdown
# 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.
|