Files
herdrMario/docs/superpowers/plans/2026-11-19-unified-prompt.md
T
2026-11-19 10:49:54 +01:00

165 lines
20 KiB
Markdown
Raw 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 — plan implementacji
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Rozbudować mod `ovis-composer` o zaakceptowany Unified Prompt Experience (fokus „tam, gdzie klik”, trwałe drafty, History|Favorites, jeden potok załączników z Ctrl+V i „+”, kolejka z odliczaniem, kontekst) bez rekompilacji Herdr.
**Architecture:** Logika w czystych modułach ES (bez `gpui-kit`/`herdr`), testowana w Node (`node --test`). `main.js` tylko wiąże je z GPUI i `hc`. Źródła w repo `herdrMario/mod/ovis-composer`, podpięte do `~/.config/herdr-app/mods/ovis-composer` przez junction. Layout `ovis-composer` (klon `main`) i wpis w `keys.json`.
**Tech Stack:** gpui-kit / gpui-base (`TextareaState`, `openOverlay`, `v_virtual_list`), API `herdr` (`agents`, `focused`, `hc`, `exec`, `shared/setShared`, `nextCommand`), PowerShell 5 (schowek, `OpenFileDialog`), Node ≥ 20 (`node --test`).
**Spec:** `docs/superpowers/specs/2026-11-19-unified-prompt-design.md` · **Makieta (zaakceptowana, bramka B):** `docs/mockups/herdr-unified-prompt.html`
**Role:** zadania wykonuje *Fast* (sub-agent, model Sonnet); *Opus* (ta sesja) robi review każdego zadania i review całej gałęzi. Fast nie zmienia architektury ani UX — problem spoza zadania → STOP i raport do Opus.
## Global Constraints
- Bez rekompilacji Herdr; nie edytować plików shipped (`layouts/main.json`, `mods/<shipped>/*`, `frame/`).
- Praca tylko na gałęzi `feature/unified-prompt` repo `herdrMario`; nic na `main`.
- Zmiany w `~/.config/herdr-app` tylko: junction `mods/ovis-composer`, `layouts/ovis-composer.json`, wpis w `keys.json`. Przed każdą zmianą kopia zapasowa (`<plik>.bak-20261119`).
- Moduły czyste (`state`, `delivery`, `storage`, `suggest`, `catalog`, `attachments`, `view`, nowe `history`, `clipboard`, `keys`) nie importują `gpui-kit`, `gpui-base`, `herdr`.
- Klucz kontekstu = adres agenta (`AgentInfo.address`, np. `t2`); tożsamość terminala = `address` + `created_ms` z `hc get <t> --json`.
- Komunikaty UI po polsku, zgodne z makietą (dosłowne teksty w zadaniach).
- Limity: plik 32 MiB, 100 plików na akcję, 20 000 znaków (`attachments.LIMITS`); historia 500, ulubione 100 (`storage`).
- Obrazy ze schowka: `~/.config/herdr-app/data/ovis-composer/paste/`, sprzątanie plików starszych niż 7 dni przy starcie modu.
- Odliczanie przed automatyczną wysyłką z kolejki: 3 s.
- Programy obsługujące obrazy (`AgentInfo.app`): `claude-code`, `codex`, `gemini`, `opencode`.
- Każde zadanie kończy: `node --test tests/` zielone + `herdr-app check C:\Users\Factor\.config\herdr-app\mods\ovis-composer` bez błędów + `herdr-app status` z `"errors": []`.
## Review Focus
1. Fokus w terminalu + Ctrl+V / `/` / `@` / Enter → composer nic nie robi (Task 2: test `keyIntent` z `hasKeyboard:false` → `"none"`).
2. Restart Herdr w trakcie `sending` → po starcie wpis `uncertain`, nigdy automatycznie wysłany (Task 4: test `onRestart` + countdown nie startuje dla `uncertain`).
3. Nowy terminal dostaje stary adres → kolejka cała `held`, draft z komunikatem (Task 3: test `restoreFor` z innym `created_ms`).
4. Schowek pusty / tylko HTML bez tekstu / pliki z Eksploratora → odpowiednio komunikat / tekst / ścieżki (Task 6: testy `parseClipboardResult`).
5. Ścieżka ze spacjami i polskimi znakami w `@mention` i w `hc put` (Task 6: test `mention("D:\\Dev ws\\zrzut ęą.png")` zgodny z `removeMention`).
---
### Task 1: Repo, junction, testy bazowe
**Files:**
- Create: `mod/ovis-composer/*` (kopia z `~/.config/herdr-app/mods/ovis-composer`, bez `gpui-kit.d.ts`), `package.json` (`{"type":"module","private":true,"scripts":{"test":"node --test tests/"}}`), `.gitignore` (`mod/ovis-composer/gpui-kit.d.ts`, `node_modules/`), `layouts/ovis-composer.json` (kopia), `scripts/install.ps1`, `README.md` (instalacja/wycofanie)
- Test: `tests/state.test.mjs`, `tests/delivery.test.mjs`, `tests/storage.test.mjs`, `tests/suggest.test.mjs`, `tests/attachments.test.mjs`, `tests/view.test.mjs`
**Interfaces:** Produces: ścieżki importu w testach `../mod/ovis-composer/<modul>.js`; `scripts/install.ps1` (idempotentny: backup `mods\ovis-composer` → `mods\ovis-composer.bak-20261119` jeśli nie jest junction, `cmd /c mklink /J`, kopia layoutu, wpis klawisza z Task 2; przełącznik `-Uninstall` — patrz „Wycofanie”).
- [ ] **Step 1:** Skopiuj mod i layout do repo; dodaj `package.json`, `.gitignore`.
- [ ] **Step 2:** Testy charakteryzujące obecne zachowanie modułów czystych (min. 3 na moduł, m.in.: `decide("idle")→send`, `decide("working")→queue`; `onRestart` zamienia `sending`→`uncertain`; `saveHistory` obcina do 500; `detect("ala /re",7)` wykrywa `/`; `validate({bytes:33*2**20})` → błąd „Plik przekracza limit 32 MiB”; `targetAgent` po `focused.terminal`).
- [ ] **Step 3:** Run `npm test` → PASS (testy opisują stan obecny; jeśli któryś pada, to błąd w teście — popraw test, nie moduł).
- [ ] **Step 4:** `scripts/install.ps1`; uruchom; sprawdź `cmd /c dir C:\Users\Factor\.config\herdr-app\mods` → `<JUNCTION> ovis-composer`.
- [ ] **Step 5:** `herdr-app do layout.switch '{"name":"ovis-composer"}'`; `herdr-app check …\mods\ovis-composer` → OK; `herdr-app status` → `"layout": "ovis-composer"`, `"errors": []`.
- [ ] **Step 6:** Commit `chore: import ovis-composer into repo with baseline tests`.
### Task 2: Fokus „tam, gdzie klik” i klawisze
**Files:**
- Create: `mod/ovis-composer/keys.js` · Test: `tests/keys.test.mjs`
- Modify: `mod/ovis-composer/main.js` (init: `bind_keys`, `focus()`/`timer.after(600…)`, `watchFocus`, `reclaim`, debug `notice("dbg down…")` w pętli `nextCommand`; `key()`; `submitted()`), `scripts/install.ps1` (klawisz)
**Interfaces:**
- Produces: `keyIntent(e: {key:string, shift:boolean, ctrl:boolean, alt:boolean, composing:boolean}, ctx: {hasKeyboard:boolean, menuOpen:boolean, panelOpen:boolean, empty:boolean, status:Status|null}) → "none"|"send"|"send_now"|"hold"|"newline"|"interrupt"|"close_menu"|"close_panel"|"open_panel"|"menu_up"|"menu_down"|"menu_accept"`.
- [ ] **Step 1: Testy** `keys.test.mjs`: `hasKeyboard:false` → zawsze `"none"` (Enter, `v`+ctrl, Escape); `composing:true` → `"none"`; Enter→`send`; Shift+Enter→`newline`; Ctrl+Enter→`send_now`; Alt+Enter→`hold`; Escape+menuOpen→`close_menu`; Escape+panelOpen→`close_panel`; Escape+empty+working→`interrupt`; Escape+niepuste+working→`none`; Ctrl+R→`open_panel`; Tab+menuOpen→`menu_accept`; ArrowUp+menuOpen→`menu_up`; ArrowUp bez menu→`none`.
- [ ] **Step 2:** `npm test` → FAIL (brak `keys.js`).
- [ ] **Step 3:** Zaimplementuj `keyIntent` w `keys.js`.
- [ ] **Step 4:** `npm test` → PASS.
- [ ] **Step 5:** `main.js`: usuń `watchFocus`, `reclaim`, `focus()` w `init` i `timer.after(600…)`, debug notice; usuń wiązanie `ctrl-c` (Ctrl+C = kopiuj); dodaj `bind_keys` w kontekście `Input`: `ctrl-r`→`ovis-composer.panel`, `ctrl-enter`→`ovis-composer.send_now`, `alt-enter`→`ovis-composer.hold`, `escape`→`ovis-composer.escape`; obsługa w pętli `nextCommand` przez `keyIntent` (tylko gdy `this.hasKeyboard`); komenda `focus` → `this.textarea.focus()`.
- [ ] **Step 6:** `install.ps1`: dopisz do `keys.json` → `"global": {"ctrl-shift-space": "ovis-composer.focus"}` (merge JSON, backup). Sprawdź `keys.error` nie istnieje.
- [ ] **Step 7 (ręcznie, raport ze zrzutami `herdr-app shot`):** klik w terminal → pisanie trafia do terminala, composer nie odzyskuje fokusu przez 10 s; Ctrl+Shift+Space → fokus w composerze; Ctrl+C w composerze kopiuje zaznaczenie.
- [ ] **Step 8:** Commit `feat: focus follows click, composer key intents`.
### Task 3: Trwałe drafty i tożsamość agenta
**Files:** Modify: `mod/ovis-composer/storage.js`, `state.js`, `main.js` (`syncAgent`, `changed`) · Test: `tests/storage.test.mjs`, `tests/state.test.mjs`
**Interfaces:**
- Produces (`storage.js`): `KEYS.draft = "ovis-composer.draft"`; `draftKey(agent:string) → "ovis-composer.draft:<agent>"`; `loadDraft(store, agent) → Draft|null`; `saveDraft(store, agent, draft:Draft)`; typ `Draft = {text:string, caret:number, attachments:Attachment[], identity:{created_ms:number|null, app:string|null}, savedAt:number}`.
- Produces (`state.js`): akcja `{type:"restore_draft", agent, draft, identity}` → gdy `identity.created_ms` różne od zapisanego: draft przywrócony, `notice = {text:"Szkic z poprzedniej sesji agenta", level:"warn"}`, cała kolejka agenta → `held`; gdy zgodne: przywrócony bez komunikatu.
- Consumes: `hc(["get", address, "--json"])` → `created_ms` (zmierzone 2026-11-19).
- [ ] **Step 1: Testy:** round-trip `saveDraft/loadDraft`; śmieci w store (`"x"`, `[]`) → `null`; `restore_draft` z innym `created_ms` → kolejka `held` + notice; zgodny → bez notice; tekst > 20 000 znaków zachowany w całości (limit dotyczy wysyłki, nie draftu).
- [ ] **Step 2:** FAIL → **Step 3:** implementacja → **Step 4:** PASS.
- [ ] **Step 5:** `main.js`: zapis draftu z opóźnieniem 500 ms po `change` i natychmiast przy zmianie agenta; przy `syncAgent` odczyt `created_ms` (cache per adres) i `restore_draft`.
- [ ] **Step 6 (ręcznie):** wpisz tekst → zamknij i otwórz Herdr → tekst wraca; przełącz agenta i wróć → tekst i kursor wracają.
- [ ] **Step 7:** Commit `feat: persistent per-agent drafts with identity check`.
### Task 4: Kolejka — blocked, odliczanie, stop
**Files:** Modify: `delivery.js`, `state.js`, `view.js` (`queueLabel`), `main.js` (`watch`, `interrupt`, `renderQueue*`) · Test: `tests/delivery.test.mjs`, `tests/state.test.mjs`, `tests/view.test.mjs`
**Interfaces:**
- `decide(status)`: `blocked` → `{kind:"send"}` (zmiana; kolejka i tak nie startuje — patrz niżej).
- Nowy stan wpisu `"countdown"` z polem `left:number`. Akcje `state.js`: `{type:"countdown_start", agent, id}` (tylko pierwszy `queued`, tylko gdy brak `countdown`/`sending`), `{type:"countdown_tick", agent, id}` (left−1), `{type:"countdown_cancel", agent, id}` → `held`, `{type:"hold_all", agent}` (`queued`/`countdown` → `held`).
- `delivery.shouldDrain(prev:Status, next:Status, stoppedByComposer:boolean) → boolean`: `true` tylko dla `working|blocked → idle|done` i `!stoppedByComposer`.
- `queueLabel(item)`: `queued`→„Następna tura”, `held`→„Wstrzymana — wyślij ręcznie”, `sending`→„Wysyłanie…”, `uncertain`→„Nie potwierdzono”, `countdown`→„Wysyłam za {left} s”.
- [ ] **Step 1: Testy:** `shouldDrain` (tabela 4×4 + flaga); `countdown_start` gdy istnieje `uncertain` jako pierwszy → startuje od pierwszego `queued`, `uncertain` nietknięty; `countdown_cancel` → `held`; `hold_all`; `onRestart` z `countdown` → `held` (po restarcie nic nie wysyła się samo), z `sending` → `uncertain`; etykiety.
- [ ] **Step 2:** FAIL → **Step 3:** implementacja → **Step 4:** PASS.
- [ ] **Step 5:** `main.js`: zegar 1 s dla `countdown` (`cx.timer.every`), po `left==0` → istniejący drain/send; przycisk „Anuluj” na wierszu; Stop/Esc (`hc interrupt`) ustawia `stoppedByComposer` dla najbliższego przejścia i `hold_all` + notice „Przerwano agenta. Kolejka wstrzymana — nic nie wyśle się samo.”; Enter przy `blocked` wysyła od razu.
- [ ] **Step 6 (ręcznie, Claude Code w Herdr):** 2 wiadomości w kolejce podczas pracy → po turze odliczanie 3 s → wysyłka pierwszej, druga czeka na następną turę; Anuluj → wstrzymana; Ctrl+C w terminalu → odliczanie się pojawia; Stop z composera → kolejka `held`.
- [ ] **Step 7:** Commit `feat: queue countdown, hold on stop, reply when blocked`.
### Task 5: Historia i ulubione — model
**Files:** Create: `mod/ovis-composer/history.js` · Modify: `storage.js` · Test: `tests/history.test.mjs`
**Interfaces:**
- `HistoryEntry = {id, text, sentAt:number, agent:string, agentName:string, space:string, spaceName:string}`; `Favorite = {id, text, createdAt:number}`.
- `record(list:HistoryEntry[], entry) → HistoryEntry[]` (duplikaty zachowane, limit 500, najstarsze wypadają).
- `search(list, query:string) → {item, ranges:[start,end][]}[]` — bez wielkości liter, fragmenty, wszystkie wystąpienia, kolejność od najnowszych (`sentAt`/`createdAt` malejąco); pusty `query` → wszystko.
- `toggleFavorite(favs:Favorite[], text:string, now:number) → Favorite[]` (po `text.trim()`, limit 100); `isFavorite(favs, text) → boolean`.
- Migracja: `loadHistory` akceptuje stare wpisy bez `space/agentName` (pola → `""`).
- [ ] **Step 1: Testy:** duplikaty; limit 500; `search("TEST")` znajduje „uruchom testy” z `ranges` `[[8,12]]`; dwa wystąpienia → dwa zakresy; polskie znaki (`"ŁÓDŹ"` vs `"łódź"`); pusta lista; toggle dodaje/usuwa; stare wpisy.
- [ ] **Step 2:** FAIL → **Step 3:** implementacja → **Step 4:** PASS.
- [ ] **Step 5:** `main.js`: wpis do historii po `hc send` z kodem 0 i bez `error` w JSON (`hcOk`), z `space_name` i `tab_name` z `AgentInfo`.
- [ ] **Step 6:** Commit `feat: history and favorites model`.
### Task 6: Jeden potok załączników + Ctrl+V + „+”
**Files:** Create: `mod/ovis-composer/clipboard.js` · Modify: `attachments.js`, `main.js` (`drop` → `addFiles`) · Test: `tests/clipboard.test.mjs`, `tests/attachments.test.mjs`
**Interfaces:**
- `clipboardScript(outDir:string, stamp:string) → string` — PowerShell (`-NoProfile -STA`): najpierw `Clipboard::GetFileDropList()` → wypisz `FILES\t<path>` na linię; inaczej `Clipboard::GetImage()` → zapisz `<outDir>\paste-<stamp>.png` → `IMAGE\t<path>`; inaczej `NONE`.
- `parseClipboardResult({code, stdout, stderr}) → {kind:"image", paths:[string]}|{kind:"files", paths:string[]}|{kind:"none"}|{kind:"error", message:string}`.
- `pickerScript() → string` (`OpenFileDialog`, `Multiselect=$true`, wypisuje ścieżki po linii; Anuluj → pusto); `parsePickerResult(res) → string[]`.
- `staleFiles(entries:{path, mtimeMs}[], now:number, maxAgeMs=7*864e5) → string[]`.
- `supportsImages(app:string|null) → boolean` (lista z Global Constraints).
- `main.js`: `addFiles(paths:string[], origin:"drop"|"paste"|"picker", cx)` — jedyne wejście; walidacja → kafelek `adding` → `hc put <agent> <path> --json` → `ready` + `mention` / `error` + Ponów.
- [ ] **Step 0 (spike, ręcznie, przed kodem):** tymczasowy `on("paste_other", …)` z `notify`; skopiuj obraz z przeglądarki, Snipping Tool i Eksploratora (plik) → czy zdarzenie odpala? Zmierz czas `exec powershell` ze skryptem. **Jeśli `paste_other` nie odpala w którymkolwiek przypadku → STOP, raport do Opus.**
- [ ] **Step 1: Testy:** parse `IMAGE\tC:\…\paste-1.png`; `FILES` z dwiema ścieżkami (spacje, polskie znaki); `NONE`; kod ≠ 0 → `error` ze `stderr`; picker anulowany → `[]`; `staleFiles` (6 dni zostaje, 8 dni usunięte); `supportsImages("claude-code")`, `supportsImages("aider")===false`; `mention`/`removeMention` dla ścieżki ze spacją i `ęą` (Review Focus 5).
- [ ] **Step 2:** FAIL → **Step 3:** implementacja → **Step 4:** PASS.
- [ ] **Step 5:** `main.js`: `paste_other` → `exec("powershell", ["-NoProfile","-STA","-Command", clipboardScript(...)])` → `addFiles(..., "paste")`; `none` → notice „Schowek nie zawiera tekstu ani obrazu, który można wkleić.”; przycisk „+” → `pickerScript` → `addFiles(..., "picker")`; `on_drop` → `addFiles(..., "drop")`; sprzątanie `paste/` przy starcie; ostrzeżenie przy wysyłce obrazu do agenta bez `supportsImages`: „{program} może nie obsługiwać obrazów — obraz trafi do agenta tylko jako ścieżka w tekście.” + [Anuluj] [Wyślij mimo to].
- [ ] **Step 6 (ręcznie, end-to-end):** Ctrl+V zrzutu ekranu w composerze → miniatura → wyślij do Claude Code z pytaniem „co jest na obrazie?” → agent poprawnie opisuje treść (zrzut odpowiedzi w raporcie). To samo dla Drag & Drop i „+”. Ctrl+V tekstu działa jak dotąd. Ctrl+V z fokusem w terminalu — composer nic nie dodaje.
- [ ] **Step 7:** Commit `feat: unified attachment pipeline with clipboard image and file picker`.
### Task 7: UI — panel Historia | Ulubione, podgląd obrazu, kontekst
**Files:** Create: `mod/ovis-composer/panel.js` (widok panelu: GPUI, bez logiki), Modify: `main.js` (`renderCard`, `renderFiles`, `renderContext`, przycisk 🕘 i ☆) · Test: brak nowych czystych testów (logika w `history.js`); weryfikacja ręczna + `herdr-app shot`
**Interfaces:** Consumes: `search`, `toggleFavorite`, `isFavorite` (Task 5); `keyIntent` (Task 2). Wstawianie: `this.textarea.replace(text)` (zastępuje zaznaczenie / wstawia w kursorze), potem `focus()`.
- [ ] **Step 1:** Panel nad composerem (wzór: makieta, `pop hist`): zakładki „Historia N | Ulubione N”, pole „Szukaj w historii…”, lista `v_virtual_list` (wysokość stała z kontenera), wiersz: tekst 2 linie z podświetleniem `ranges`, meta `DD.MM HH:MM · przestrzeń · agent` / `zapisano DD.MM HH:MM`, gwiazdka; stopka ze skrótami. Stany: „Historia jest pusta”, „Brak ulubionych”, „Brak wyników dla „{q}”” + „wyczyść wyszukiwanie”.
- [ ] **Step 2:** Klawisze w panelu: ↑/↓, Enter → wstaw w miejscu zapamiętanego kursora (nie wysyła) + notice „Wstawiono w miejscu kursora — nic nie zostało wysłane. Ctrl+Z cofa.”, Tab → przełącz zakładkę, Esc → zamknij i przywróć kursor. Sprawdź, czy Ctrl+Z w `Textarea` cofa `replace`; jeśli nie — usuń „Ctrl+Z cofa.” z komunikatu i zgłoś w raporcie (odstępstwo od makiety → decyzja Opus).
- [ ] **Step 3:** Przycisk ☆ przy edytorze (toggle bieżącego tekstu), „Edytuj” w kolejce → `replace` w kursorze (Task 4 wiersz).
- [ ] **Step 4:** Miniatury `image(localPath)` 36×36, klik → overlay podglądu (`fit: contain`, nazwa · rozmiar · „Esc zamyka”).
- [ ] **Step 5:** Pigułka kontekstu: kropka statusu + nazwa karty + słowo statusu + 📎N; pasek: przestrzeń · folder · ⑂ gałąź (z `panes()`); fokus na terminalu nie-agenta → pole nieaktywne, placeholder „Ten terminal nie jest agentem. Wybierz agenta z listy, aby pisać.”, draft zachowany.
- [ ] **Step 5a:** Edytor: `set_auto_grow(1, 10)` (dziś 1–6); blok `composer` w `layouts/ovis-composer.json` → `"size": {"px": 260}`, `"min": 120`, `"max": 520` i rodzic `work` z `"resizable": true` (ręczna zmiana wysokości przeciąganiem granicy); po zmianie `layout.error` nie istnieje.
- [ ] **Step 6:** `herdr-app check` OK; `herdr-app shot` każdego stanu (pusty, wpisany, panel historii, brak wyników, załączniki, kolejka z odliczaniem, nie-agent) → raport do porównania z makietą.
- [ ] **Step 7:** Commit `feat: history/favorites panel, image preview, context strip`.
### Task 8: Regresja i weryfikacja końcowa (Fast), review gałęzi (Opus)
**Files:** Create: `docs/superpowers/verification/2026-11-19-unified-prompt.md` (wyniki)
- [ ] **Step 1:** `npm test` — pełny wynik w raporcie.
- [ ] **Step 2:** Lista ręczna (z wynikiem i zrzutem): scenariusze 1–7 z makiety; terminal PowerShell: pisanie, Ctrl+C, Ctrl+V tekstu, wklejanie obrazu do Claude Code wprost w terminalu (natywne zachowanie Herdr nietknięte); przełączenie layoutu `main` ↔ `ovis-composer` bez błędów; restart Herdr w trakcie `sending` → `uncertain`.
- [ ] **Step 3:** Dowód braku rekompilacji: `git -C <herdr>` nie dotyczy — w raporcie `herdr-app --version` przed i po (ta sama wersja) + lista zmienionych plików w `~/.config/herdr-app` (tylko junction, layout, `keys.json`).
- [ ] **Step 4:** Commit raportu. **Opus:** niezależny review całej gałęzi (`superpowers:requesting-code-review`), status `APPROVED` / `CHANGES_REQUIRED` / `BLOCKED`.
## Wycofanie
`scripts/install.ps1 -Uninstall`: usuń junction, przywróć `mods\ovis-composer.bak-20261119`, przywróć `keys.json.bak-20261119`, `herdr-app do layout.switch '{"name":"main"}'`.