feat: the composer reads agent profiles from composer-agents.json

Co-Authored-By: Ovis Fast (Claude) <[email protected]>
This commit is contained in:
FactorandOvis Fast committed 2026-11-20 08:58:36 +01:00
1 parent 1b12550d04
commit dc5dcc9cc6
5 files changed
+183 -30

No files matched your search

+48 -2
View File
@@ -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 `<klucz>` – 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`: <powód>”.
**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
+1 -1
View File
@@ -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`).
@@ -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`,
@@ -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),
),
);
+23
View File
@@ -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");
});