diff --git a/docs/superpowers/specs/2026-11-20-agent-profiles-design.md b/docs/superpowers/specs/2026-11-20-agent-profiles-design.md new file mode 100644 index 0000000..3f92c83 --- /dev/null +++ b/docs/superpowers/specs/2026-11-20-agent-profiles-design.md @@ -0,0 +1,122 @@ +# Profile agentów dla menu `/` — projekt + +Data: 2026-11-20 · Gałąź: `feature/composer-dock` · Mod: `herdr/herdr-composer/mods/herdr-composer/` + +## Cel i powód +Menu `/` composera ma podpowiadać komendy każdego agenta, nie tylko Claude Code. Na tej maszynie są Claude Code i codex. Kiro-cli i Antigravity CLI działają na innych komputerach i nie da się ich tu uruchomić. Nie znamy więc ich kluczy `agentName()` ani ich komend i nie wolno ich zgadywać. Rozwiązanie musi działać bez tej wiedzy w kodzie. Użytkownik dopisuje ją w pliku na maszynie, na której agent działa, bez zmian w kodzie i bez reinstalacji moda. + +## Dziś +- `agentName(agent)` (`view.js:60`) zwraca `agent.app`, potem `program.key`, a w ostateczności `"default"`. +- `catalog.js` ma na sztywno: + - `BUILTINS["claude-code"]` (49 komend) i `BUILTINS.codex` (4 komendy); + - alias `claude` → `claude-code`; + - `isClaudeCode()`, które decyduje, czy czytać `.claude/commands`, `.claude/skills` projektu oraz `~/.claude` z pluginami (`globalCommands`). +- Agent spoza tej listy dostaje w menu `/` tylko snippety, a te dziś są zawsze puste (`snippets: []` w `main.js`). +- Historia (`storage.loadHistory`, do 500 wpisów, wspólna) zapisuje każdą wysłaną wiadomość z polem `agentName` = `agentName(agent)` (`main.js`, `recordSent`). + +## Cele +1. **Profil agenta** opisuje: jakie nazwy z `agentName()` do niego pasują, jakie ma wbudowane komendy i skąd czytać jego własne komendy (folder projektu i folder domowy). +2. **Domyślne profile w kodzie** dla `claude-code` (z aliasem `claude`) i `codex`. Zachowują dzisiejsze działanie: te same komendy, grupy, kolejność i deduplikację. +3. **Plik użytkownika** `~/.config/herdr-app/composer-agents.json` (obok `shared.json`) dodaje nowe profile albo nadpisuje domyślne. +4. **Komendy z historii:** każde `/słowo` z początku wiadomości wysłanej wcześniej do agenta o tym samym `agentName` trafia do menu jako osobna grupa. +5. **Nieznany agent:** kiedy żaden profil nie pasuje, menu pokazuje wiersz informacyjny z dokładnym kluczem, który trzeba wpisać w pliku. + +## Układ maszyn +Każdy komputer ma własną instalację herdr-app z tym modem, a agent działa lokalnie obok GUI (decyzja użytkownika). Plik profili, folder domowy i źródła są czytane lokalnie, bez `on: machine`. Agenci na zdalnych maszynach przez herdr-core są poza zakresem. + +## Poza zakresem +- Edytor profili w GUI. +- Wpisywanie do kodu profili kiro-cli i Antigravity. Dostarczamy tylko przykład w README, wyraźnie oznaczony jako niesprawdzony. +- Inny wyzwalacz menu niż `/`. +- Zagnieżdżone skille (`~/.claude/skills/synced/`), czyli znany brak, który zostaje. +- `clipboard.js` `IMAGE_APPS`. + +## Anty-cele (porażka, nawet jeśli działa) +- Jakakolwiek zmiana menu `/` dla Claude Code: inna lista, inne grupy, inna kolejność albo wolniejsze działanie. +- Uszkodzony lub brakujący plik użytkownika psuje menu. Ma wtedy działać na domyślnych profilach. +- Zgadywanie w kodzie kluczy lub komend agentów, których nie widzieliśmy. + +## Podejścia (rozważone) +- **Skąd brać komendy nieznanego agenta:** (1) profile w pliku, (2) nauka z użycia, (3) oba. **Wybrane: oba** (decyzja użytkownika). +- **Gdzie trzymać profile:** + - **A.** Domyślne w kodzie plus plik w home. + - **B.** `shared()` z edytorem w GUI. + - **C.** `agents.json` w folderze moda. + - **Wybrane: A** (decyzja użytkownika). B oznacza dużo GUI do rzadkiej czynności. C nadpisuje `install.ps1` przy aktualizacji. +- **Nauka z użycia:** nowy magazyn albo odczyt historii. **Wybrane: historia** (moja decyzja). Ma już `agentName`, więc nie trzeba nowego klucza ani nowego zapisu. + +## Format pliku `composer-agents.json` +```json +{ + "agents": [ + { + "id": "kiro", + "match": ["kiro-cli", "kiro"], + "builtins": [ + { "key": "context", "desc": "Zarządza kontekstem." }, + { "key": "model" } + ], + "sources": [ + { "scope": "project", "path": ".kiro/prompts", "pattern": "*.md" }, + { "scope": "home", "path": ".kiro/prompts", "pattern": "*.md", "prefix": "@" } + ] + } + ] +} +``` +- `id` (wymagany, string): nazwa profilu. Profil z pliku o tym samym `id` co domyślny **zastępuje go w całości**. Bez łączenia list, żeby zachowanie było przewidywalne. +- `match` (wymagany, niepusta lista stringów): wartości `agentName()`, które pasują do profilu. Porównanie dokładne, bez rozróżniania wielkości liter. Pierwszy pasujący profil wygrywa, profile z pliku są sprawdzane przed domyślnymi. +- `builtins` (opcjonalny): `{key, desc?}` trafiają do grupy `Wbudowane`. +- `sources` (opcjonalny): lista źródeł. + - `scope`: `"project"` (względem `cwd` panelu, czytane przez `exec` jak dziś `projectItems`) albo `"home"` (względem folderu domowego, czytane jak dziś `globalCommands`). Odpowiadają grupom `Projekt` i `Użytkownik`. + - `path`: folder względny. Ścieżka bezwzględna i `..` są odrzucane. + - `pattern`: `"*.md"` (nazwa komendy = nazwa pliku bez `.md`) albo `"*/SKILL.md"`. Inne wzorce są odrzucane. Nazwa skilla zależy od zakresu, tak jak dziś *(moja decyzja: CC bez zmian)*: + - `home`: `name:` z frontmattera, a gdy go brak, nazwa folderu; pomija `user-invocable: false`; + - `project`: zawsze nazwa folderu, bez filtra. + - `prefix` (opcjonalny, domyślnie `"/"`): co wstawia wybór z menu (`insert: prefix + key + " "`). Przydaje się agentowi, który wywołuje prompty inaczej niż `/`. + - Specjalne `{ "scope": "home", "kind": "claude-plugins" }` oznacza dzisiejszą logikę pluginów (`settings.json` → `enabledPlugins`, `installed_plugins.json`, `plugin.json`) i daje grupę `Pluginy`. Używa go domyślny profil `claude-code`. Inny profil może go użyć, ale nic poza tym nie robi. +- Domyślny profil `claude-code` w kodzie wyrażony w tym formacie: + - `match: ["claude-code", "claude"]`; + - `builtins`: dzisiejsze 49; + - `sources`: projekt `.claude/commands` `*.md`, projekt `.claude/skills` `*/SKILL.md`, home `.claude/commands` `*.md`, home `.claude/skills` `*/SKILL.md`, `claude-plugins`. +- Domyślny `codex`: `match: ["codex"]`, dzisiejsze 4 builtins, bez źródeł. +- `isClaudeCode()` znika z logiki katalogu. To, czy czytać `.claude`, wynika wyłącznie z profilu. + +**Błędy w pliku.** Brak pliku jest normalny i oznacza same domyślne profile. Nieczytelny JSON albo zły kształt (`agents` nie jest listą) oznacza ignorowanie całego pliku. Pojedynczy zły profil lub źródło jest pomijany, reszta działa. Gdy plik został odrzucony w całości albo częściowo, menu `/` pokazuje u dołu jeden wiersz informacyjny: „`composer-agents.json`: ”. + +## Komendy z historii +- Źródło: `storage.loadHistory(store)`. Bierzemy wpisy, których `agentName` jest równe bieżącemu `agentName(agent)` (porównanie bez rozróżniania wielkości liter). +- Z tekstu wpisu bierzemy pierwszy token, jeśli tekst po `trimStart()` zaczyna się od `/`, a token pasuje do `^/[A-Za-z0-9][\w:.-]*$`. Klucz to token bez `/`. +- Grupa: nowa `GROUP_HISTORY = "Z historii"`, dopisana na końcu `GROUPS` w `suggest.js` (przed `Terminal`, jeśli ta grupa jest używana w tym menu, inaczej na końcu). Opis to pusty string. `insert: "/" + key + " "`. +- Działa dla każdego agenta, także Claude Code. + +## Kolejność i deduplikacja +Źródła są łączone w tej kolejności: builtins, źródła `project` profilu, źródła `home` profilu (w tym pluginy), snippety, historia. Nazwa pojawia się raz: wygrywa pierwsze źródło, które ją ma, tak jak dziś. Dla Claude Code bez historii lista jest identyczna z dzisiejszą. + +## Nieznany agent +Żaden profil nie pasuje: menu pokazuje komendy z historii i snippety oraz jeden wiersz informacyjny „Nieznany agent `` – dodaj profil w `~/.config/herdr-app/composer-agents.json`”. Wiersza nie da się wybrać (Enter/Tab go pomija, tak jak dzisiejsze komunikaty `NO_MATCH_MESSAGE` / `READ_ERROR_MESSAGE`). Agent o `agentName` = `"default"` też jest „nieznany”. + +## Odświeżanie +Ścieżka pliku pochodzi z `appHome()` modułu `herdr` (honoruje `$HERDR_APP_HOME`), nie jest wpisana na sztywno *(moja decyzja)*. Plik profili i źródła `home` są czytane w tle (dzisiejsze `refreshGlobal`) z tym samym TTL 60 s. Pierwsze `/` po starcie nie czeka na plik. Dopóki plik nie został wczytany ani razu, wiersz „Nieznany agent” się nie pokazuje. Po wczytaniu otwarte menu przeładowuje się tak jak dziś *(moja decyzja: bez spowolnienia CC i bez fałszywego komunikatu)*. Zmiana pliku pojawia się w menu w ciągu minuty, bez restartu. Cache źródeł `home` jest trzymany **per profil** (`id`), bo dwa terminale mogą mieć różnych agentów. Źródła `project` są czytane jak dziś, przy każdym otwarciu menu. + +## Testy +- Dzisiejsze testy `catalog.test.mjs` przechodzą bez zmian albo z mechaniczną zmianą wywołania. +- Nowe przypadki: + - wynik dla CC identyczny z wynikiem sprzed zmiany (lista kluczy, grup i `insert`); + - plik nadpisuje profil domyślny; + - plik dodaje profil z `prefix: "@"`; + - uszkodzony JSON → domyślne profile i wiersz informacyjny; + - zły profil pominięty, dobry działa; + - ścieżka z `..` odrzucona; + - komendy z historii (filtr agenta, regex, dedup z builtins); + - nieznany agent → wiersz z kluczem. +- GUI na tej maszynie: menu `/` dla CC wygląda tak jak przed zmianą. Plik testowy z profilem dla `codex` (albo z fałszywym `match` dla CC) pokazuje własne komendy w ciągu minuty. + +## README +Krótka sekcja „Inni agenci”: +- skąd wziąć klucz (wiersz „Nieznany agent …” w menu); +- format pliku; +- przykład dla kiro, oznaczony jako niesprawdzony. + +## Pozostawione wykonawcy +Podział funkcji między `catalog.js` a ewentualny nowy `profiles.js`, nazwy funkcji i dokładny kształt cache w `main.js`. Byle `catalog.js` dalej działał w czystym Node z wstrzykniętymi `exec` i `readText`.