From dc5dcc9cc67359a8db363adc8f8e2a88b4d91588 Mon Sep 17 00:00:00 2001 From: Factor Date: Fri, 20 Nov 2026 08:58:36 +0100 Subject: [PATCH] feat: the composer reads agent profiles from composer-agents.json Co-Authored-By: Ovis Fast (Claude) --- README.md | 50 ++++++- herdr/herdr-composer/RECIPE.md | 2 +- .../mods/herdr-composer/catalog.js | 15 +++ .../mods/herdr-composer/main.js | 123 ++++++++++++++---- tests/catalog.test.mjs | 23 ++++ 5 files changed, 183 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index b6fb98b..319785f 100644 --- a/README.md +++ b/README.md @@ -79,14 +79,60 @@ Usuwa `mods\herdr-composer`, `layouts\herdr-composer.json` i skrót z `keys.json **Dane:** historia (500 wpisów), ulubione (100), dock (30 przycisków), drafty i kolejki zapisują się lokalnie w `~\.config\herdr-app\shared.json` (klucze `herdr-composer.*`). Obrazy ze schowka trafiają do `~\.config\herdr-app\data\herdr-composer\paste\` i są usuwane po 7 dniach. Nic nie jest wysyłane poza ten komputer. +## Inni agenci + +Menu `/` podpowiada komendy według **profilu agenta**. Domyślne profile są dla Claude Code (alias `claude`) i `codex`. Dla innego agenta menu pokazuje komendy, które wysłałeś mu wcześniej (grupa „Z historii”) oraz szary wiersz „Nieznany agent `` – dodaj profil w ~/.config/herdr-app/composer-agents.json”. Klucz z tego wiersza wpisz w polu `match`. + +Profile dopisujesz w pliku `~\.config\herdr-app\composer-agents.json` (albo `$HERDR_APP_HOME\composer-agents.json`) na komputerze, na którym działa agent. Zmiana pojawia się w menu w ciągu minuty, bez restartu i bez reinstalacji. + +```json +{ + "agents": [ + { + "id": "nazwa-profilu", + "match": ["klucz-agenta"], + "builtins": [{ "key": "model", "desc": "Wybiera model." }], + "sources": [ + { "scope": "project", "path": ".agent/prompts", "pattern": "*.md" }, + { "scope": "home", "path": ".agent/prompts", "pattern": "*/SKILL.md", "prefix": "@" } + ] + } + ] +} +``` + +- `id` (wymagany): nazwa profilu. Profil z tym samym `id` co domyślny **zastępuje go w całości**, bez łączenia list. +- `match` (wymagany, niepusta lista): klucze agenta, bez rozróżniania wielkości liter. Najpierw sprawdzane są profile z pliku, potem domyślne. +- `builtins` (opcjonalny): `{ "key", "desc" }`, grupa „Wbudowane”. +- `sources` (opcjonalny): `scope` to `"project"` (względem folderu panelu; grupa „Projekt”) albo `"home"` (względem folderu domowego; grupa „Użytkownik”). `path` jest względna, bez `..`. `pattern` to `"*.md"` (nazwa komendy = nazwa pliku bez `.md`) albo `"*/SKILL.md"` (nazwa skilla z `name:` we frontmatterze, a w projekcie z nazwy folderu). `prefix` (domyślnie `"/"`) to tekst wstawiany przed nazwą. Źródło `{ "scope": "home", "kind": "claude-plugins" }` czyta pluginy Claude Code. +- Brak pliku to norma. Uszkodzony plik jest ignorowany (działają profile domyślne), a menu pokazuje wiersz „`composer-agents.json`: ”. + +**Przykład dla kiro-cli: niesprawdzony.** Nie znamy klucza ani komend tego agenta, więc poniższe wartości są tylko ilustracją. Klucz weź z wiersza „Nieznany agent …” na maszynie z kiro. + +```json +{ + "agents": [ + { + "id": "kiro", + "match": ["kiro-cli", "kiro"], + "builtins": [{ "key": "context" }, { "key": "model" }], + "sources": [ + { "scope": "project", "path": ".kiro/prompts", "pattern": "*.md" }, + { "scope": "home", "path": ".kiro/prompts", "pattern": "*.md", "prefix": "@" } + ] + } + ] +} +``` + ## Co mod uruchamia i czyta Agent instalujący paczkę poinformuje o tym przed instalacją. - **`hc`:** `send`, `put`, `get`, `interrupt`, `keys`. Tak mod rozmawia z terminalami agentów. -- **`powershell`:** odczyt schowka, okno wyboru pliku, rozmiary plików, odczyt komend i skilli z `.claude/` projektu. Ścieżki trafiają do skryptów wyłącznie jako Base64. +- **`powershell`:** odczyt schowka, okno wyboru pliku, rozmiary plików, odczyt komend i skilli z folderów projektu wskazanych w profilu agenta (dla Claude Code `.claude/`). Ścieżki trafiają do skryptów wyłącznie jako Base64. - **`git ls-files`** w folderze agenta: podpowiedzi `@`. -- **Pliki spoza folderu modu:** pliki, które sam dodajesz jako załączniki, oraz `.claude/commands` i `.claude/skills` projektu. +- **Pliki spoza folderu modu:** pliki, które sam dodajesz jako załączniki, foldery komend z profilu agenta (dla Claude Code `.claude/commands`, `.claude/skills` projektu i `~\.claude`) oraz `composer-agents.json` w `~\.config\herdr-app\`. - **Sieć:** mod nie korzysta z sieci. ## Przejście z ovis-composer diff --git a/herdr/herdr-composer/RECIPE.md b/herdr/herdr-composer/RECIPE.md index 668b216..5961596 100644 --- a/herdr/herdr-composer/RECIPE.md +++ b/herdr/herdr-composer/RECIPE.md @@ -123,7 +123,7 @@ a `focus` border in `accent`. **Mod** `mods/herdr-composer/` (`mod.json`: `place: none`, `focusable: true`): `main.js` (the view), `state.js` (drafts, attachments, queue; pure), `delivery.js` (sending, the gate, countdown rules), `storage.js` (the shared store, migration from `ovis-composer.*`), -`history.js`, `attachments.js`, `clipboard.js`, `suggest.js`, `catalog.js`, `keys.js`, +`history.js`, `attachments.js`, `clipboard.js`, `suggest.js`, `catalog.js`, `profiles.js` (agent profiles), `keys.js`, `dock.js` (the dock and its menus; pure), `view.js` (helpers), `panel.js` (the panel and the preview). The pure modules import nothing from Herdr and are tested with Node (`npm test`). diff --git a/herdr/herdr-composer/mods/herdr-composer/catalog.js b/herdr/herdr-composer/mods/herdr-composer/catalog.js index effbfce..d181b4b 100644 --- a/herdr/herdr-composer/mods/herdr-composer/catalog.js +++ b/herdr/herdr-composer/mods/herdr-composer/catalog.js @@ -74,6 +74,21 @@ export function profileProblemMessage(problem) { return `\`composer-agents.json\`: ${problem}`; } +/** + * The grey rows under the items of the `/` menu: the agent has no profile + * (once the file of the profiles was read - before that we do not know yet) + * and the file of the profiles could not be read whole. They cannot be picked. + * + * @param {{profile:object|null, agent:string, profilesLoaded:boolean, problem:string|null}} state + * @returns {string[]} + */ +export function menuNotes({ profile, agent, profilesLoaded, problem }) { + const notes = []; + if (!profile && profilesLoaded) notes.push(unknownAgentMessage(agent)); + if (problem) notes.push(profileProblemMessage(problem)); + return notes; +} + /** * The listing with a POSIX shell, for the project and for the home folder: * the arguments come in threes - the index of the spec, its kind (`file`, diff --git a/herdr/herdr-composer/mods/herdr-composer/main.js b/herdr/herdr-composer/mods/herdr-composer/main.js index e67e253..802fd0d 100644 --- a/herdr/herdr-composer/mods/herdr-composer/main.js +++ b/herdr/herdr-composer/mods/herdr-composer/main.js @@ -56,6 +56,7 @@ import { } from "./delivery.js"; import { detect as detectTrigger, rank, merge, startsLine } from "./suggest.js"; import * as catalog from "./catalog.js"; +import { PROFILES_FILE, parseProfiles, resolveProfile } from "./profiles.js"; import { LIMITS, validate, mention, removeMention, kindOf, formatBytes, relativeTo } from "./attachments.js"; import { clipboardScript, @@ -195,11 +196,16 @@ export default class Composer extends View { // The menu of suggestions: what it shows, which row is picked. this.menu = null; - // The person's and the plugins' commands: read once, in the background, - // and again when older than a minute (see refreshGlobal). The menu list + // The profiles of the agents from `composer-agents.json` and the commands + // of the home folder, per profile (`id`): read in the background, and + // again when older than a minute (see refreshGlobal). The menu list // scrolls, and the arrows keep the picked row in view through the handle. - this.globalCommands = null; - this.globalLoadedAt = 0; + this.userProfiles = []; + this.profileProblem = null; + this.profilesLoaded = false; + this.profilesLoadedAt = 0; + this.globalCommands = new Map(); + this.globalLoadedAt = new Map(); this.globalLoading = false; this.menuScroll = ScrollHandle.new(); this.debounce = null; @@ -2215,41 +2221,85 @@ export default class Composer extends View { this.closeMenu(); return; } - // `~/.claude` is read for Claude Code only - no other agent understands it. - if (token.trigger === "/" && catalog.isClaudeCode(agentName(agent))) this.refreshGlobal(cx); + // The profile of the agent says what is read for it (profiles.js). + if (token.trigger === "/") this.refreshGlobal(cx); this.scheduleLoad(agent, token, cx); } /** - * The global commands (`~/.claude`, the plugins) are read in the background: - * when there is no catalog yet or it is older than a minute, one read at a - * time. Typing never waits for it and never starts a read of its own. + * The file of the profiles and the commands of the home folder of the + * agent's profile are read in the background: when there is nothing yet or + * it is older than a minute, one read at a time. Typing never waits for it + * and never starts a read of its own. */ async refreshGlobal(cx) { if (this.globalLoading || checking()) return; - if (this.globalCommands !== null && Date.now() - this.globalLoadedAt < GLOBAL_TTL_MS) return; + + const stale = (at) => at === undefined || Date.now() - at >= GLOBAL_TTL_MS; + const wanted = () => { + const agent = this.target(); + if (!agent) return null; + const profile = resolveProfile(this.userProfiles, agentName(agent)); + const homeSources = (profile?.sources ?? []).some((source) => source.scope === "home"); + return profile && homeSources ? profile : null; + }; + + const profilesStale = !this.profilesLoaded || stale(this.profilesLoadedAt); + if (!profilesStale) { + const profile = wanted(); + if (!profile || !stale(this.globalLoadedAt.get(profile.id))) return; + } this.globalLoading = true; - let failed = false; + let changed = false; try { - const items = await catalog.globalCommands(home(), exec, readTextFile, { - onReadError: () => { + if (profilesStale) { + let text = null; + let unreadable = false; + try { + text = await readTextFile([appHome(), PROFILES_FILE].join("\\")); + } catch { + unreadable = true; + } + const parsed = unreadable + ? { profiles: [], problem: "nie udało się odczytać pliku" } + : parseProfiles(text); + this.userProfiles = parsed.profiles; + this.profileProblem = parsed.problem; + this.profilesLoaded = true; + this.profilesLoadedAt = Date.now(); + changed = true; + } + + const profile = wanted(); + if (profile && (profilesStale || stale(this.globalLoadedAt.get(profile.id)))) { + let failed = false; + try { + const items = await catalog.globalCommands(home(), exec, readTextFile, { + sources: profile.sources, + onReadError: () => { + failed = true; + }, + }); + // A failed read keeps the catalog the menu already has. + if (!failed) { + this.globalCommands.set(profile.id, items); + changed = true; + } + } catch { failed = true; - }, - }); - // A failed read keeps the catalog the menu already has. - if (!failed) this.globalCommands = items; - } catch { - failed = true; + } + // Failed or not, the next try is a minute away - not at every key. + this.globalLoadedAt.set(profile.id, Date.now()); + } + } finally { + this.globalLoading = false; } - // Failed or not, the next try is a minute away - not at every key. - this.globalLoadedAt = Date.now(); - this.globalLoading = false; // The menu of `/` is open: it shows the new catalog now. const agent = this.target(); const menu = this.menu; - if (!failed && agent && menu?.trigger === "/" && this.value.length >= menu.start) { + if (changed && agent && menu?.trigger === "/" && this.value.length >= menu.start) { this.loadSuggestions(agent, { trigger: menu.trigger, needle: menu.needle, start: menu.start }, cx); } } @@ -2287,14 +2337,26 @@ export default class Composer extends View { }; let items = []; + let notes = []; + let unknownAgent = false; try { if (token.trigger === "/") { + const name = agentName(agent); + const profile = resolveProfile(this.userProfiles, name); const raw = await catalog.commands(cwd, exec, { - agent: agentName(agent), + profile, snippets: [], - global: this.globalCommands ?? [], + global: (profile && this.globalCommands.get(profile.id)) ?? [], + history: catalog.historyCommands(storage.loadHistory(this.store), name), onReadError, }); + unknownAgent = !profile && this.profilesLoaded; + notes = catalog.menuNotes({ + profile, + agent: name, + profilesLoaded: this.profilesLoaded, + problem: this.profileProblem, + }); const usage = storage.loadUsage(this.store); const withUses = raw.map((item) => ({ ...item, uses: usage[item.key] ?? 0 })); items = @@ -2313,7 +2375,7 @@ export default class Composer extends View { // again. if (this.value !== text) return; - this.menu = { ...token, caret: this.caret(), items, index: 0, error: failed }; + this.menu = { ...token, caret: this.caret(), items, index: 0, error: failed, notes, unknownAgent }; // A new list starts at its top. try { this.menuScroll.scroll_to_item(0); @@ -2852,10 +2914,17 @@ export default class Composer extends View { .gap(1) .children( [ - menu.error || all.length === 0 + // An unknown agent with nothing to offer: the note says why, so + // "no command fits" would only be noise. + menu.error || (all.length === 0 && !menu.unknownAgent) ? div().px(6).py(5).text_size(11.5).text_color(menu.error ? t.blocked : t.dim).child(empty) : null, ...items.map((item, index) => this.renderMenuItem(t, item, index, menu)), + // Notes sit under the items, cannot be picked and do not move + // the index of any item. + ...(menu.notes ?? []).map((note, i) => + div().id(`menu-note-${i}`).px(6).py(3).text_size(11.5).text_color(t.dim).child(note), + ), ].filter(Boolean), ), ); diff --git a/tests/catalog.test.mjs b/tests/catalog.test.mjs index c6dfb96..bf60f37 100644 --- a/tests/catalog.test.mjs +++ b/tests/catalog.test.mjs @@ -5,6 +5,7 @@ import { commands, globalCommands, historyCommands, + menuNotes, } from "../herdr/herdr-composer/mods/herdr-composer/catalog.js"; import { DEFAULT_PROFILES, @@ -433,3 +434,25 @@ test("commands: a history command that is a builtin shows once, as Wbudowane", a test("GROUPS has Z historii right after Pluginy", () => { assert.equal(GROUPS[GROUPS.indexOf("Pluginy") + 1], "Z historii"); }); + +test("menuNotes: an unknown agent names the key, but only once the file was read", () => { + const loaded = menuNotes({ profile: null, agent: "kiro-cli", profilesLoaded: true, problem: null }); + assert.equal(loaded.length, 1); + assert.ok(loaded[0].includes("`kiro-cli`")); + assert.ok(loaded[0].includes("composer-agents.json")); + assert.deepEqual(menuNotes({ profile: null, agent: "kiro-cli", profilesLoaded: false, problem: null }), []); +}); + +test("menuNotes: a problem with the file is one row", () => { + assert.deepEqual( + menuNotes({ profile: CC_PROFILE, agent: "claude", profilesLoaded: true, problem: "nieczytelny JSON" }), + ["`composer-agents.json`: nieczytelny JSON"], + ); +}); + +test("menuNotes: unknown agent first, then the problem", () => { + const notes = menuNotes({ profile: null, agent: "kiro-cli", profilesLoaded: true, problem: "brak listy agents" }); + assert.equal(notes.length, 2); + assert.ok(notes[0].startsWith("Nieznany agent")); + assert.equal(notes[1], "`composer-agents.json`: brak listy agents"); +});