skill-autoroute 0.10.1 → 0.11.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +36 -10
- package/bin/cli.js +2 -2
- package/hook/route.js +57 -9
- package/package.json +3 -2
- package/skill/SKILL.md +3 -1
- package/src/discover.js +5 -2
- package/src/flow.js +32 -16
- package/src/tools/hermes.js +163 -0
- package/src/triggers.js +1 -1
package/README.md
CHANGED
|
@@ -4,11 +4,11 @@
|
|
|
4
4
|
|
|
5
5
|
**Your agent has dozens of skills. This tells it which one fits the prompt you just typed.**
|
|
6
6
|
|
|
7
|
-
For Claude Code and
|
|
7
|
+
For Claude Code, Codex and Hermes · No API key · Zero tokens when nothing matches
|
|
8
8
|
|
|
9
9
|
[](https://www.npmjs.com/package/skill-autoroute)
|
|
10
10
|

|
|
11
|
-

|
|
11
|
+

|
|
12
12
|

|
|
13
13
|
|
|
14
14
|
</div>
|
|
@@ -89,7 +89,7 @@ npx skill-autoroute install
|
|
|
89
89
|
|
|
90
90
|
The installer walks you through it:
|
|
91
91
|
|
|
92
|
-
1. Pick your tools: Claude Code, Codex, or
|
|
92
|
+
1. Pick your tools: Claude Code, Codex, Hermes, or any mix.
|
|
93
93
|
2. Pick an AI helper: `claude`, `codex`, or `none` (keyword triggers, no AI calls).
|
|
94
94
|
3. Review the skill list. Flagged skills start **unchecked**, with the reason beside the name.
|
|
95
95
|
4. Try test prompts and see which hints they produce.
|
|
@@ -99,6 +99,9 @@ Each AI step shows a token estimate and asks before it runs.
|
|
|
99
99
|
|
|
100
100
|
**Codex users:** after install, open Codex, run `/hooks`, and trust the skill-autoroute hook once.
|
|
101
101
|
|
|
102
|
+
**Hermes users:** the next time Hermes starts, it asks once to allow the new hook. Say yes. `hermes hooks list` shows
|
|
103
|
+
whether it is allowed. Hermes is a routed tool only: pick `claude`, `codex` or `none` as the AI helper.
|
|
104
|
+
|
|
102
105
|
### Prefer to let your agent do it?
|
|
103
106
|
|
|
104
107
|
Paste this into Claude Code or Codex:
|
|
@@ -108,7 +111,7 @@ Paste this into Claude Code or Codex:
|
|
|
108
111
|
|
|
109
112
|
```text
|
|
110
113
|
Set up skill-autoroute for me. Follow these steps exactly.
|
|
111
|
-
1. Ask me which tools to route (claude, codex, or
|
|
114
|
+
1. Ask me which tools to route (claude, codex, hermes, or a mix) and which AI helper to use (claude, codex, or none).
|
|
112
115
|
2. Run: npx skill-autoroute install --dry-run --tools <tools> --ai <ai>
|
|
113
116
|
Show me the whole output, including the token estimates. Do not summarise it.
|
|
114
117
|
3. Ask me whether to go ahead. Wait for a clear yes. If I say no, stop.
|
|
@@ -157,7 +160,7 @@ The optional AI scan can make a result stricter. It can never clear a high findi
|
|
|
157
160
|
|
|
158
161
|
> [!WARNING]
|
|
159
162
|
> "No issues found" means these rules found nothing. It is **not** a safety guarantee. Read skills you do not trust.
|
|
160
|
-
> Unchecking a skill only removes its hints.
|
|
163
|
+
> Unchecking a skill only removes its hints. The tool still loads the skill.
|
|
161
164
|
|
|
162
165
|
<details>
|
|
163
166
|
<summary>More about scan limits</summary>
|
|
@@ -380,7 +383,7 @@ npx skill-autoroute install --model triggers=haiku
|
|
|
380
383
|
| `uninstall` | Remove the hook, the table and the hook copy |
|
|
381
384
|
|
|
382
385
|
|
|
383
|
-
**Flags:** `--yes` (accept defaults) · `--dry-run` (estimates only, writes nothing) · `--project` · `--tools claude,codex`
|
|
386
|
+
**Flags:** `--yes` (accept defaults) · `--dry-run` (estimates only, writes nothing) · `--project` · `--tools claude,codex,hermes`
|
|
384
387
|
· `--ai claude|codex|none` · `--model step=model` · `--log`
|
|
385
388
|
|
|
386
389
|
When your skills change, the hint line tells you so. Run `regenerate`.
|
|
@@ -430,6 +433,27 @@ Enabled means eligible for routing on matching prompts, not that the agent has i
|
|
|
430
433
|
- **Project level** goes into the repository, so teammates get it on clone. It adds a hook to `.claude/settings.json`.
|
|
431
434
|
Paths are stored relative to the project, and entries that point outside the project are skipped.
|
|
432
435
|
- **Codex** has a user-level hook only. That hook still reads the project table of the folder you run Codex in.
|
|
436
|
+
- **Hermes** also has a user-level hook only (`hooks.pre_llm_call` in `~/.hermes/config.yaml`, written with
|
|
437
|
+
`hermes config set`). It reads the project table of the folder Hermes runs in, and `--project` lists the skills in a
|
|
438
|
+
trusted project's `.hermes/skills` and `.agents/skills`.
|
|
439
|
+
|
|
440
|
+
<details>
|
|
441
|
+
<summary>How the Hermes adapter works</summary>
|
|
442
|
+
|
|
443
|
+
- **Skills:** it lists `$HERMES_HOME/skills` (default `~/.hermes/skills`) with its category folders, plus every folder in
|
|
444
|
+
`skills.external_dirs`. It leaves out what Hermes does not load in a normal session: skills in `skills.disabled`,
|
|
445
|
+
skills for another platform (`platforms:`) and skills limited to special environments such as Kanban workers
|
|
446
|
+
(`environments:`). It reads the settings with `hermes config get`, so it needs no YAML parser.
|
|
447
|
+
- **Hook:** `pre_llm_call` fires once per user turn, before the model runs. The hook reads the prompt from
|
|
448
|
+
`extra.user_message` (the text parts on an image or file turn) and replies `{"context": "..."}`, which Hermes adds to
|
|
449
|
+
the user message. No match prints nothing.
|
|
450
|
+
- **Subagents:** a second entry on `subagent_start` records each `delegate_task` child's session id, and the child's
|
|
451
|
+
turns get no hints. The parent already chose the work.
|
|
452
|
+
- **Gateway notices:** turns Hermes itself sends (a finished background process or delegation, marked
|
|
453
|
+
`[INTERNAL NOTIFICATION`) get no hints.
|
|
454
|
+
- **Config:** the first change backs up `config.yaml` to `config.yaml.bak-skill-autoroute`. Other hooks stay as they are.
|
|
455
|
+
|
|
456
|
+
</details>
|
|
433
457
|
|
|
434
458
|
<details class="orca-details">
|
|
435
459
|
<summary>How the hook stays safe and quiet</summary>
|
|
@@ -459,13 +483,14 @@ It removes only its own hook entries. Backups of your config files (`*.bak-skill
|
|
|
459
483
|
## Requirements
|
|
460
484
|
|
|
461
485
|
- Node **20.12+**
|
|
462
|
-
- Claude Code and/or
|
|
486
|
+
- Claude Code, Codex and/or Hermes. For AI steps, log in to `claude` or `codex`, or use `--ai none`.
|
|
463
487
|
- Linux or macOS. Windows is untested.
|
|
464
488
|
|
|
465
489
|
## Supported tools
|
|
466
490
|
|
|
467
|
-
Version 1 supports **Claude Code** and **
|
|
468
|
-
your normal login.
|
|
491
|
+
Version 1 supports **Claude Code**, **Codex** and **Hermes**. Claude Code and Codex have both a prompt hook and a
|
|
492
|
+
headless mode that work with your normal login. Hermes has the prompt hook (`pre_llm_call`) but is not used as the AI
|
|
493
|
+
helper: its one-shot mode has no schema-checked output and no read-only switch for reading untrusted skill text. Notes on Kiro, Cline, opencode, Amp, Cursor, Copilot CLI, Windsurf and Antigravity are in
|
|
469
494
|
[the design document](docs/specs/2026-10-28-skill-autoroute-design.md#12). Each tool is one adapter file in
|
|
470
495
|
`src/tools/`.
|
|
471
496
|
|
|
@@ -475,7 +500,8 @@ your normal login. Notes on Kiro, Cline, opencode, Amp, Cursor, Copilot CLI, Win
|
|
|
475
500
|
npm test
|
|
476
501
|
```
|
|
477
502
|
|
|
478
|
-
The tests use fake `claude` and `
|
|
503
|
+
The tests use fake `claude`, `codex` and `hermes` programs and a fake `HOME`. They make no real AI calls and never touch
|
|
504
|
+
your real Hermes config.
|
|
479
505
|
|
|
480
506
|
## License
|
|
481
507
|
|
package/bin/cli.js
CHANGED
|
@@ -7,7 +7,7 @@ import { STEP_DEFAULTS } from '../src/models.js';
|
|
|
7
7
|
|
|
8
8
|
const USAGE = `usage: skill-autoroute <command> [flags]
|
|
9
9
|
commands: install | regenerate | scan | list [<skill>] | set <skill> on|off | words [<skill> [add|remove <word>...]] | status | tokens | bench | uninstall
|
|
10
|
-
flags: --yes --dry-run --project --tools claude,codex --ai claude|codex|none --model step=model (repeatable) --log`;
|
|
10
|
+
flags: --yes --dry-run --project --tools claude,codex,hermes --ai claude|codex|none --model step=model (repeatable) --log`;
|
|
11
11
|
|
|
12
12
|
const COMMANDS = {
|
|
13
13
|
install: flow.install, regenerate: flow.regenerate, scan: flow.scan, set: flow.setSkill, words: flow.setWords,
|
|
@@ -23,7 +23,7 @@ function options() {
|
|
|
23
23
|
},
|
|
24
24
|
});
|
|
25
25
|
const tools = v.tools?.split(',').map((t) => t.trim()).filter(Boolean);
|
|
26
|
-
for (const t of tools ?? []) if (!flow.ADAPTERS[t]) throw new Error(`unknown tool "${t}" (claude, codex)`);
|
|
26
|
+
for (const t of tools ?? []) if (!flow.ADAPTERS[t]) throw new Error(`unknown tool "${t}" (claude, codex, hermes)`);
|
|
27
27
|
if (v.ai && !['claude', 'codex', 'none'].includes(v.ai)) throw new Error(`unknown --ai "${v.ai}" (claude, codex, none)`);
|
|
28
28
|
const models = {};
|
|
29
29
|
for (const m of v.model ?? []) {
|
package/hook/route.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
// Per-prompt hook for Claude Code and
|
|
2
|
-
// argv[2] names the tool (claude or
|
|
3
|
-
import { readFileSync, statSync, readdirSync, realpathSync, appendFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
|
|
1
|
+
// Per-prompt hook for Claude Code, Codex and Hermes. Node built-ins only; any error means no output, exit 0.
|
|
2
|
+
// argv[2] names the tool (claude, codex or hermes): only that tool's skills are hinted; no argument hints all.
|
|
3
|
+
import { readFileSync, statSync, readdirSync, realpathSync, appendFileSync, mkdirSync, existsSync, unlinkSync, writeFileSync } from 'node:fs';
|
|
4
4
|
import { join, dirname, resolve, sep } from 'node:path';
|
|
5
5
|
import { homedir } from 'node:os';
|
|
6
6
|
import { pathToFileURL } from 'node:url';
|
|
@@ -151,7 +151,8 @@ const ownFits = (s, text) => { const src = wordsPattern(s.words); return Boolean
|
|
|
151
151
|
export function staleCount(table, fs = FS) {
|
|
152
152
|
const gen = Date.parse(table.generatedAt);
|
|
153
153
|
const entries = table.skills.filter((s) => s && typeof s.path === 'string');
|
|
154
|
-
|
|
154
|
+
// `ignored`: skill folders the tool does not load (turned off, other platform). They are not new skills.
|
|
155
|
+
const known = new Set([...entries.map((s) => dirname(s.path)), ...(Array.isArray(table.ignored) ? table.ignored : [])]);
|
|
155
156
|
let n = 0;
|
|
156
157
|
for (const { path: p, project } of entries) {
|
|
157
158
|
const m = fs.mtime(p);
|
|
@@ -227,6 +228,7 @@ function clean(t) {
|
|
|
227
228
|
...t,
|
|
228
229
|
skills: t.skills.filter((s) => s && typeof s === 'object' && !Array.isArray(s)),
|
|
229
230
|
roots: Array.isArray(t.roots) ? t.roots.filter((r) => typeof r === 'string') : [],
|
|
231
|
+
ignored: Array.isArray(t.ignored) ? t.ignored.filter((r) => typeof r === 'string') : [],
|
|
230
232
|
};
|
|
231
233
|
}
|
|
232
234
|
|
|
@@ -240,6 +242,7 @@ export function resolveProject(table, base) {
|
|
|
240
242
|
return {
|
|
241
243
|
...t,
|
|
242
244
|
roots: t.roots.map(abs).filter(under),
|
|
245
|
+
ignored: t.ignored.map(abs).filter(under),
|
|
243
246
|
skills: t.skills.filter((s) => typeof s.path === 'string' && under(abs(s.path))).map((s) => ({ ...s, path: abs(s.path), project: true })),
|
|
244
247
|
};
|
|
245
248
|
}
|
|
@@ -254,6 +257,7 @@ export function merge(user, project) {
|
|
|
254
257
|
...u,
|
|
255
258
|
generatedAt: gens[0] ?? '',
|
|
256
259
|
roots: [...new Set([...u.roots, ...p.roots])],
|
|
260
|
+
ignored: [...new Set([...u.ignored, ...p.ignored])],
|
|
257
261
|
skills: [...u.skills.filter((s) => !names.has(s.name)), ...p.skills],
|
|
258
262
|
...(u.log === true || p.log === true ? { log: true } : {}),
|
|
259
263
|
};
|
|
@@ -351,6 +355,50 @@ function suggestJson(udir, args, i) {
|
|
|
351
355
|
if (selected.length) remember(file, detail.map((d) => d.name));
|
|
352
356
|
}
|
|
353
357
|
|
|
358
|
+
// The text of a Hermes user message: a string, or (an image or file turn) a list of content parts.
|
|
359
|
+
export function messageText(m) {
|
|
360
|
+
if (typeof m === 'string') return m;
|
|
361
|
+
if (!Array.isArray(m)) return null;
|
|
362
|
+
const parts = m.map((p) => (typeof p === 'string' ? p : p && p.type === 'text' && typeof p.text === 'string' ? p.text : null)).filter((t) => t !== null);
|
|
363
|
+
return parts.length ? parts.join('\n') : null;
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
// Hermes delegated children: `subagent_start` names the child session before it runs, and its turns get no hints
|
|
367
|
+
// (the parent already chose the work). One empty marker file per child, pruned with the session files.
|
|
368
|
+
const childFile = (udir, sid) => sessionFile(udir, 'hermes-child', sid);
|
|
369
|
+
function markChild(udir, sid) {
|
|
370
|
+
const file = childFile(udir, sid);
|
|
371
|
+
if (!file) return;
|
|
372
|
+
try { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, ''); } catch { /* a read-only folder only loses the mark */ }
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
// Hermes delivers its own notices (a finished background process or delegation) as user turns. They are not the
|
|
376
|
+
// user's work, so they get no hints. The gateway marks them; these are its fixed openings and marker.
|
|
377
|
+
const HERMES_NOTICE = /^\s*\[(ASYNC DELEGATION|IMPORTANT: Background process)\b|\[INTERNAL NOTIFICATION\b/;
|
|
378
|
+
export const isHermesNotice = (text) => HERMES_NOTICE.test(text);
|
|
379
|
+
|
|
380
|
+
// What the tool sent, as {prompt, sid, base}; null when there is nothing to route.
|
|
381
|
+
// Claude Code and Codex send {prompt, session_id}. Hermes sends {hook_event_name, session_id, cwd, extra: {user_message}}.
|
|
382
|
+
export function readInput(input, tool, udir) {
|
|
383
|
+
if (!input || typeof input !== 'object') return null;
|
|
384
|
+
if (tool === 'hermes') {
|
|
385
|
+
if (input.hook_event_name === 'subagent_start') { markChild(udir, input.extra?.child_session_id); return null; }
|
|
386
|
+
if (input.hook_event_name !== undefined && input.hook_event_name !== 'pre_llm_call') return null;
|
|
387
|
+
const sid = input.session_id;
|
|
388
|
+
if (childFile(udir, sid) && existsSync(childFile(udir, sid))) return null;
|
|
389
|
+
const prompt = messageText(input.extra?.user_message);
|
|
390
|
+
if (prompt === null || isHermesNotice(prompt)) return null;
|
|
391
|
+
return { prompt, sid, base: typeof input.cwd === 'string' && input.cwd ? input.cwd : process.cwd() };
|
|
392
|
+
}
|
|
393
|
+
if (typeof input.prompt !== 'string') return null;
|
|
394
|
+
return { prompt: input.prompt, sid: input.session_id, base: process.env.CLAUDE_PROJECT_DIR || process.cwd() };
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
// Hermes reads {"context"}; Claude Code and Codex read hookSpecificOutput.additionalContext.
|
|
398
|
+
export const hookOutput = (tool, ctx) => (tool === 'hermes'
|
|
399
|
+
? { context: ctx }
|
|
400
|
+
: { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: ctx } });
|
|
401
|
+
|
|
354
402
|
function main(self) {
|
|
355
403
|
if (process.env.SKILL_AUTOROUTE_DISABLE === '1') return;
|
|
356
404
|
const udir = join(homedir(), '.config', 'skill-autoroute');
|
|
@@ -361,12 +409,12 @@ function main(self) {
|
|
|
361
409
|
// Only a Claude user hook counts: a Codex-only user install must not silence the Claude project hook.
|
|
362
410
|
if (self.endsWith(`${sep}.skill-autoroute${sep}route.mjs`) && userClaudeHook(udir)) return;
|
|
363
411
|
try {
|
|
364
|
-
const
|
|
365
|
-
|
|
366
|
-
|
|
412
|
+
const tool = args[0];
|
|
413
|
+
const input = readInput(JSON.parse(readFileSync(0, 'utf8')), tool, udir);
|
|
414
|
+
if (!input) return;
|
|
415
|
+
const { prompt, sid, base } = input;
|
|
367
416
|
const table = loadTable(udir, base);
|
|
368
417
|
if (!table) return;
|
|
369
|
-
const tool = args[0];
|
|
370
418
|
const file = sessionFile(udir, tool, sid);
|
|
371
419
|
const known = file && remembered(file);
|
|
372
420
|
const hit = pick(prompt, table, { tool, base, skip: known ?? undefined });
|
|
@@ -377,7 +425,7 @@ function main(self) {
|
|
|
377
425
|
if (!hit && !tell) return;
|
|
378
426
|
remember(file, hit ? hit.names : []);
|
|
379
427
|
const ctx = [hit?.out, tell].filter(Boolean).join('\n');
|
|
380
|
-
process.stdout.write(JSON.stringify(
|
|
428
|
+
process.stdout.write(JSON.stringify(hookOutput(tool, ctx)) + '\n');
|
|
381
429
|
if (process.env.SKILL_AUTOROUTE_LOG === '1' || table.log === true) {
|
|
382
430
|
try {
|
|
383
431
|
mkdirSync(udir, { recursive: true });
|
package/package.json
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "skill-autoroute",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Per-prompt skill router hook for Claude Code and
|
|
3
|
+
"version": "0.11.1",
|
|
4
|
+
"description": "Per-prompt skill router hook for Claude Code, Codex and Hermes",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude-code",
|
|
7
7
|
"codex",
|
|
8
|
+
"hermes",
|
|
8
9
|
"skills",
|
|
9
10
|
"agent",
|
|
10
11
|
"hook",
|
package/skill/SKILL.md
CHANGED
|
@@ -19,7 +19,7 @@ relaying the output. You do not do any of the work yourself.
|
|
|
19
19
|
|
|
20
20
|
## Steps
|
|
21
21
|
|
|
22
|
-
1. Ask which tools to route (`claude`, `codex`, or
|
|
22
|
+
1. Ask which tools to route (`claude`, `codex`, `hermes`, or a mix) and which AI helper makes the scan and the triggers (`claude`,
|
|
23
23
|
`codex`, or `none` for keyword triggers with no AI calls). If the user does not know, run
|
|
24
24
|
`npx skill-autoroute status` and show which CLIs it found.
|
|
25
25
|
2. Run the dry run, with the answers from step 1:
|
|
@@ -48,6 +48,8 @@ relaying the output. You do not do any of the work yourself.
|
|
|
48
48
|
A skill turned on this way has no trigger rules until `npx skill-autoroute regenerate` runs.
|
|
49
49
|
7. If Codex was chosen, tell the user to run `/hooks` once inside Codex and trust the new hook. Until then Codex does
|
|
50
50
|
not run it.
|
|
51
|
+
8. If Hermes was chosen, tell the user that Hermes asks once to allow the new hook the next time it starts, and that
|
|
52
|
+
`hermes hooks list` shows whether it is allowed. Hermes cannot be the AI helper; use `claude`, `codex` or `none`.
|
|
51
53
|
|
|
52
54
|
## Later
|
|
53
55
|
|
package/src/discover.js
CHANGED
|
@@ -63,10 +63,11 @@ function walk(root, realDir, rel, seen, found, outside, skipped) {
|
|
|
63
63
|
}
|
|
64
64
|
}
|
|
65
65
|
|
|
66
|
-
|
|
66
|
+
// `ignored` (optional) collects the real folders a `skip` callback left out.
|
|
67
|
+
export function discover(dirs, ignored = []) {
|
|
67
68
|
const skills = [];
|
|
68
69
|
const done = new Map(); // real dir -> skill, so a folder shared by two tools lists both
|
|
69
|
-
for (const { dir, tool, source, projects, only } of dirs) {
|
|
70
|
+
for (const { dir, tool, source, projects, only, skip } of dirs) {
|
|
70
71
|
let names;
|
|
71
72
|
try { names = readdirSync(dir).sort(); } catch { continue; }
|
|
72
73
|
if (Array.isArray(only)) names = names.filter((n) => only.includes(n));
|
|
@@ -90,6 +91,8 @@ export function discover(dirs) {
|
|
|
90
91
|
if (!inside(real, sr) || !statSync(sr).isFile()) continue;
|
|
91
92
|
text = readFileSync(sr, 'utf8');
|
|
92
93
|
} catch { continue; }
|
|
94
|
+
// `skip(name, text)` is true for a skill the tool does not load; another tool listing the same folder still lists it.
|
|
95
|
+
if (typeof skip === 'function' && skip(parseFrontmatter(text).name || folder, text)) { if (!ignored.includes(real)) ignored.push(real); continue; }
|
|
93
96
|
done.set(real, null);
|
|
94
97
|
const found = [];
|
|
95
98
|
const outside = [];
|
package/src/flow.js
CHANGED
|
@@ -5,6 +5,7 @@ import { createHash } from 'node:crypto';
|
|
|
5
5
|
import { relative, sep } from 'node:path';
|
|
6
6
|
import * as claude from './tools/claude.js';
|
|
7
7
|
import * as codex from './tools/codex.js';
|
|
8
|
+
import * as hermes from './tools/hermes.js';
|
|
8
9
|
import { discover } from './discover.js';
|
|
9
10
|
import { scanStatic, label } from './scan/static.js';
|
|
10
11
|
import { aiScan, mergeScan } from './scan/ai.js';
|
|
@@ -17,7 +18,9 @@ import { routesPath, reportPath, hookCopyPath, logPath } from './paths.js';
|
|
|
17
18
|
import { installHookCopy, hookCommand, checkConfig } from './tools/hookconfig.js';
|
|
18
19
|
import { route, staleCount, resolveProject, wordsPattern } from '../hook/route.js';
|
|
19
20
|
|
|
20
|
-
export const ADAPTERS = { claude, codex };
|
|
21
|
+
export const ADAPTERS = { claude, codex, hermes };
|
|
22
|
+
// Tools whose CLI can run the AI helper steps (Hermes routes prompts but has no schema-checked headless mode).
|
|
23
|
+
const helpers = () => Object.keys(ADAPTERS).filter((n) => typeof ADAPTERS[n].headless === 'function');
|
|
21
24
|
export class Cancel extends Error {}
|
|
22
25
|
|
|
23
26
|
const BATCH = 20;
|
|
@@ -49,7 +52,11 @@ export function findTools() {
|
|
|
49
52
|
|
|
50
53
|
export function findSkills(tools, scope) {
|
|
51
54
|
const dirs = tools.flatMap((t) => ADAPTERS[t].skillDirs(scope));
|
|
52
|
-
|
|
55
|
+
const ignored = [];
|
|
56
|
+
const skills = discover(dirs, ignored);
|
|
57
|
+
// A folder skipped by one tool but listed by another is a known skill, not an ignored one.
|
|
58
|
+
const listed = new Set(skills.map((s) => s.dir));
|
|
59
|
+
return { skills, roots: dirs.map((d) => d.dir).filter((d) => existsSync(d)), ignored: ignored.filter((d) => !listed.has(d)) };
|
|
53
60
|
}
|
|
54
61
|
|
|
55
62
|
// Characters sent: exact trigger prompts; scan and dedupe approximated from file sizes, capped as the modules cap them.
|
|
@@ -200,15 +207,19 @@ const entry = (r, gen, scope) => {
|
|
|
200
207
|
// Every entry stores a hash of the rules as generated. A rule list that no longer matches its hash was edited by the user.
|
|
201
208
|
export const rulesHash = (patterns) => createHash('sha256').update(JSON.stringify(patterns ?? [])).digest('hex').slice(0, 16);
|
|
202
209
|
const edited = (w) => Boolean(w?.rulesHash) && rulesHash(w.patterns) !== w.rulesHash;
|
|
203
|
-
const tableOf = (ctx, skills, roots, log) => ({
|
|
210
|
+
const tableOf = (ctx, skills, roots, log, ignored = []) => ({
|
|
204
211
|
version: 1, generatedAt: new Date().toISOString(),
|
|
205
212
|
generator: { ai: ctx.ai ? ctx.aiName : 'none', model: ctx.ai ? pickModel(ctx.aiName, 'triggers', ctx.overrides).model ?? null : null, overheadPerCall: ctx.overhead, cacheReadPerCall: ctx.cacheOverhead, rules: RULES_VERSION },
|
|
206
|
-
roots, ...(log ? { log: true } : {}), skills: skills.map((s) => (s.rulesHash ? s : { ...s, rulesHash: rulesHash(s.patterns) })),
|
|
213
|
+
roots, ...(ignored.length ? { ignored } : {}), ...(log ? { log: true } : {}), skills: skills.map((s) => (s.rulesHash ? s : { ...s, rulesHash: rulesHash(s.patterns) })),
|
|
207
214
|
});
|
|
208
215
|
|
|
209
216
|
// Every tool config must parse before anything is written (throws naming the bad file).
|
|
210
217
|
export function preflight(scope, tools) {
|
|
211
|
-
for (const t of tools) {
|
|
218
|
+
for (const t of tools) {
|
|
219
|
+
const a = ADAPTERS[t];
|
|
220
|
+
if (a.checkConfig) a.checkConfig(scope);
|
|
221
|
+
else { const p = a.hookConfig(scope); if (p) checkConfig(p); }
|
|
222
|
+
}
|
|
212
223
|
}
|
|
213
224
|
|
|
214
225
|
export function write(scope, table, tools, ctx) {
|
|
@@ -230,13 +241,18 @@ export function write(scope, table, tools, ctx) {
|
|
|
230
241
|
|
|
231
242
|
// Runs the exact hook command written to the tool config and checks the output shape (empty, or one JSON line with additionalContext).
|
|
232
243
|
export function selfTest(scope, tool) {
|
|
244
|
+
const a = ADAPTERS[tool];
|
|
245
|
+
const text = 'skill-autoroute self-test';
|
|
233
246
|
const r = spawnSync(hookCommand(scope, tool), {
|
|
234
|
-
shell: true, input: JSON.stringify({ prompt:
|
|
247
|
+
shell: true, input: JSON.stringify(a?.testInput ? a.testInput(text, process.cwd()) : { prompt: text }), encoding: 'utf8', timeout: 10000,
|
|
235
248
|
env: { ...process.env, CLAUDE_PROJECT_DIR: process.cwd() },
|
|
236
249
|
});
|
|
237
250
|
if (r.status !== 0) return false;
|
|
238
251
|
if (!r.stdout.trim()) return true;
|
|
239
|
-
try {
|
|
252
|
+
try {
|
|
253
|
+
const o = JSON.parse(r.stdout);
|
|
254
|
+
return a?.outputOk ? a.outputOk(o) : typeof o.hookSpecificOutput.additionalContext === 'string';
|
|
255
|
+
} catch { return false; }
|
|
240
256
|
}
|
|
241
257
|
|
|
242
258
|
// Steps 1 to 5 shared by install and scan: tools, AI helper with probe, skills, static scan.
|
|
@@ -244,8 +260,8 @@ async function prelude(o, ui) {
|
|
|
244
260
|
const found = findTools();
|
|
245
261
|
const avail = found.filter((t) => t.cli || t.configDir).map((t) => t.name);
|
|
246
262
|
const tools = o.tools ?? (await ui.multiselect('Tools to route', found.map((t) => ({ value: t.name, label: t.name, hint: t.cli ? 'CLI found' : t.configDir ? 'config only' : 'not found' })), avail));
|
|
247
|
-
if (!tools.length) throw new Error('no tool chosen; pass --tools claude,codex');
|
|
248
|
-
const clis = found.filter((t) => t.cli).map((t) => t.name);
|
|
263
|
+
if (!tools.length) throw new Error('no tool chosen; pass --tools claude,codex,hermes');
|
|
264
|
+
const clis = found.filter((t) => t.cli && helpers().includes(t.name)).map((t) => t.name);
|
|
249
265
|
const aiName = o.ai ?? (await ui.select('AI helper for scan, duplicates and triggers', [...clis.map((n) => ({ value: n, label: n })), { value: 'none', label: 'none (keywords only)' }], clis.find((n) => tools.includes(n)) ?? clis[0] ?? 'none'));
|
|
250
266
|
const ctx = context(aiName, o);
|
|
251
267
|
if (ctx.ai) {
|
|
@@ -261,11 +277,11 @@ async function prelude(o, ui) {
|
|
|
261
277
|
}
|
|
262
278
|
}
|
|
263
279
|
const scope = scopeOf(o);
|
|
264
|
-
const { skills, roots } = findSkills(tools, scope);
|
|
280
|
+
const { skills, roots, ignored } = findSkills(tools, scope);
|
|
265
281
|
const counts = {};
|
|
266
282
|
for (const s of skills) { const k = `${s.tool} ${show(s.source)}`; counts[k] = (counts[k] ?? 0) + 1; }
|
|
267
283
|
ui.log(`skills found: ${skills.length}${Object.keys(counts).length ? ` (${Object.entries(counts).map(([k, v]) => `${k}: ${v}`).join(', ')})` : ''}`);
|
|
268
|
-
return { scope, tools, ctx, skills, roots };
|
|
284
|
+
return { scope, tools, ctx, skills, roots, ignored };
|
|
269
285
|
}
|
|
270
286
|
|
|
271
287
|
function dryRun(ctx, skills, ui) {
|
|
@@ -291,13 +307,13 @@ function summary(ctx, gen, notes, ui) {
|
|
|
291
307
|
}
|
|
292
308
|
|
|
293
309
|
export async function install(o, ui) {
|
|
294
|
-
const { scope, tools, ctx, skills, roots } = await prelude(o, ui);
|
|
310
|
+
const { scope, tools, ctx, skills, roots, ignored } = await prelude(o, ui);
|
|
295
311
|
if (o.dryRun) return dryRun(ctx, skills, ui);
|
|
296
312
|
preflight(scope, tools); // fail before spending AI calls
|
|
297
313
|
const scans = await runScans(skills, ctx, ui);
|
|
298
314
|
const rows = await pickRows(buildRows(skills, scans, await runDedupe(skills, ctx, ui)), ui);
|
|
299
315
|
const gen = await generate(rows.filter((r) => r.enabled).map((r) => r.skill), ctx, ui);
|
|
300
|
-
const table = tableOf(ctx, rows.map((r) => entry(r, gen, scope)), roots.map(keyOf(scope)), o.log);
|
|
316
|
+
const table = tableOf(ctx, rows.map((r) => entry(r, gen, scope)), roots.map(keyOf(scope)), o.log, ignored.map(keyOf(scope)));
|
|
301
317
|
keepWords(table, readTable(routesPath(scope)));
|
|
302
318
|
keepEdited(table, readTable(routesPath(scope)), ui);
|
|
303
319
|
while (!ui.yes) {
|
|
@@ -329,7 +345,7 @@ export async function regenerate(o, ui) {
|
|
|
329
345
|
const key = keyOf(scope);
|
|
330
346
|
const prev = new Map(old.skills.map((s) => [s.path, s]));
|
|
331
347
|
const was = (s) => prev.get(key(s.skillPath));
|
|
332
|
-
const { skills, roots } = findSkills(tools, scope);
|
|
348
|
+
const { skills, roots, ignored } = findSkills(tools, scope);
|
|
333
349
|
ctx.cacheOverhead = Number(old.generator?.cacheReadPerCall) || 0;
|
|
334
350
|
const fresh = skills.filter((s) => was(s)?.hash !== s.hash);
|
|
335
351
|
// unchanged and enabled but without rules (turned on with `set` after generate), or with rules from an older RULES_VERSION: they only need rules
|
|
@@ -355,7 +371,7 @@ export async function regenerate(o, ui) {
|
|
|
355
371
|
}
|
|
356
372
|
// Scope comes from this discovery, not the old entry: enabling a plugin in another project changes no skill file.
|
|
357
373
|
const scoped = ({ projects, ...e }, s) => (s.projects ? { ...e, projects: s.projects } : e);
|
|
358
|
-
const table = tableOf(ctx, skills.map((s) => scoped(byPath.get(s.skillPath) ?? was(s), s)), roots.map(key), old.log);
|
|
374
|
+
const table = tableOf(ctx, skills.map((s) => scoped(byPath.get(s.skillPath) ?? was(s), s)), roots.map(key), old.log, ignored.map(key));
|
|
359
375
|
keepWords(table, old);
|
|
360
376
|
keepEdited(table, old, ui);
|
|
361
377
|
// unchanged rules still come from the old generator; after a full rebuild the new model wrote them all
|
|
@@ -553,7 +569,7 @@ const SAMPLES = [
|
|
|
553
569
|
|
|
554
570
|
// Ruling R31: the CLI runs with the user's settings so the hook fires; DISABLE=1 gives the baseline.
|
|
555
571
|
export async function bench(o, ui) {
|
|
556
|
-
const aiName = o.ai ?? findTools().find((t) => t.cli)?.name;
|
|
572
|
+
const aiName = o.ai ?? findTools().find((t) => t.cli && helpers().includes(t.name))?.name;
|
|
557
573
|
if (!aiName || aiName === 'none') throw new Error('bench needs an AI CLI: pass --ai claude or --ai codex');
|
|
558
574
|
const ctx = context(aiName, o);
|
|
559
575
|
const m = model(ctx, 'probe');
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
import { existsSync, readdirSync, statSync, copyFileSync } from 'node:fs';
|
|
2
|
+
import { spawnSync } from 'node:child_process';
|
|
3
|
+
import { homedir } from 'node:os';
|
|
4
|
+
import { join } from 'node:path';
|
|
5
|
+
import { onPath } from './run.js';
|
|
6
|
+
|
|
7
|
+
export const name = 'hermes';
|
|
8
|
+
|
|
9
|
+
// Hermes keeps every file under HERMES_HOME (a profile sets it); the default is ~/.hermes.
|
|
10
|
+
export const hermesHome = () => process.env.HERMES_HOME || join(homedir(), '.hermes');
|
|
11
|
+
const configFile = () => join(hermesHome(), 'config.yaml');
|
|
12
|
+
|
|
13
|
+
const MARK = 'skill-autoroute/route.mjs';
|
|
14
|
+
// pre_llm_call fires once per user turn and injects {"context"}; subagent_start lets the hook skip delegated children.
|
|
15
|
+
export const EVENTS = ['pre_llm_call', 'subagent_start'];
|
|
16
|
+
const TIMEOUT = 10;
|
|
17
|
+
const NO_PROJECT = { changed: false, note: 'hermes uses the user-level hook; it reads the project table' };
|
|
18
|
+
const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
|
|
19
|
+
const ours = (h) => isObj(h) && typeof h.command === 'string' && h.command.includes(MARK);
|
|
20
|
+
|
|
21
|
+
export const detect = () => ({ cli: onPath('hermes'), configDir: existsSync(hermesHome()) });
|
|
22
|
+
|
|
23
|
+
// Settings are read and written through the Hermes CLI: no YAML parser here, and Hermes keeps its own
|
|
24
|
+
// file checks. The CLI runs only when a Hermes folder exists, so a machine without Hermes never spawns it.
|
|
25
|
+
function cli(args) {
|
|
26
|
+
if (!existsSync(hermesHome()) || !onPath('hermes')) return null;
|
|
27
|
+
return spawnSync('hermes', args, { encoding: 'utf8', timeout: 60000 });
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
// The JSON value of `key`; undefined when the key is unset, Hermes is missing or the output is not JSON.
|
|
31
|
+
export function getKey(key) {
|
|
32
|
+
const r = cli(['config', 'get', '--json', key]);
|
|
33
|
+
if (!r || r.status !== 0) return undefined;
|
|
34
|
+
try { return JSON.parse(r.stdout); } catch { return undefined; }
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function setKey(key, value) {
|
|
38
|
+
const r = cli(['config', 'set', key, JSON.stringify(value)]);
|
|
39
|
+
if (!r) throw new Error('the hermes CLI was not found on PATH; install or start Hermes first, nothing was changed');
|
|
40
|
+
if (r.status !== 0) throw new Error(`hermes config set ${key} failed: ${(r.stderr || r.stdout).trim().slice(0, 200)}`);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
const names = (v) => (Array.isArray(v) ? v : typeof v === 'string' ? [v] : []).map((s) => String(s).trim()).filter(Boolean);
|
|
44
|
+
|
|
45
|
+
// `~` and ${VAR} / $VAR, as Hermes expands skills.external_dirs.
|
|
46
|
+
const expand = (p) => String(p)
|
|
47
|
+
.replace(/^~(?=$|[\\/])/, homedir())
|
|
48
|
+
.replace(/\$\{(\w+)\}|\$(\w+)/g, (m, a, b) => process.env[a ?? b] ?? m);
|
|
49
|
+
|
|
50
|
+
// Hermes nests skills in category folders (skills/<category>/<skill>/SKILL.md). discover() lists the skill
|
|
51
|
+
// folders inside one dir, so every folder without a SKILL.md is a container whose children are listed too.
|
|
52
|
+
// Skill folders are never walked: their subfolders are references and scripts.
|
|
53
|
+
function containers(root, depth = 0, out = []) {
|
|
54
|
+
out.push(root);
|
|
55
|
+
if (depth >= 3) return out;
|
|
56
|
+
let entries;
|
|
57
|
+
try { entries = readdirSync(root).sort(); } catch { return out; }
|
|
58
|
+
for (const n of entries) {
|
|
59
|
+
if (n.startsWith('.') || n === 'node_modules') continue;
|
|
60
|
+
const p = join(root, n);
|
|
61
|
+
try {
|
|
62
|
+
if (!statSync(p).isDirectory() || existsSync(join(p, 'SKILL.md'))) continue;
|
|
63
|
+
} catch { continue; }
|
|
64
|
+
containers(p, depth + 1, out);
|
|
65
|
+
}
|
|
66
|
+
return out;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
const PLATFORM = { darwin: 'macos', win32: 'windows', linux: 'linux' }[process.platform] ?? process.platform;
|
|
70
|
+
|
|
71
|
+
// The values of a top-level frontmatter list (`key: [a, b]` or an indented `- a` block); null when the key is absent.
|
|
72
|
+
export function frontmatterList(text, key) {
|
|
73
|
+
const fm = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1];
|
|
74
|
+
if (!fm) return null;
|
|
75
|
+
const m = new RegExp(`^${key}:[ \\t]*(.*)$`, 'm').exec(fm);
|
|
76
|
+
if (!m) return null;
|
|
77
|
+
if (m[1].trim()) return m[1].replace(/^\[|\]$/g, '').split(',').map((s) => s.trim().replace(/^(["'])(.*)\1$/, '$2')).filter(Boolean);
|
|
78
|
+
const after = fm.slice(m.index + m[0].length).split(/\r?\n/).slice(1);
|
|
79
|
+
const out = [];
|
|
80
|
+
for (const l of after) {
|
|
81
|
+
const item = /^\s+-\s*(.+)$/.exec(l);
|
|
82
|
+
if (!item) break;
|
|
83
|
+
out.push(item[1].trim().replace(/^(["'])(.*)\1$/, '$2'));
|
|
84
|
+
}
|
|
85
|
+
return out;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
// True for a skill Hermes does not load in a normal session: turned off in skills.disabled, made for another
|
|
89
|
+
// platform (`platforms:`), or limited to special environments such as Kanban workers (`environments:`).
|
|
90
|
+
export const hiddenBy = (disabled) => (skillName, text) => {
|
|
91
|
+
if (disabled.includes(skillName)) return true;
|
|
92
|
+
const platforms = frontmatterList(text, 'platforms');
|
|
93
|
+
if (platforms && platforms.length && !platforms.includes(PLATFORM)) return true;
|
|
94
|
+
return Boolean(frontmatterList(text, 'environments')?.length);
|
|
95
|
+
};
|
|
96
|
+
|
|
97
|
+
// Each scope lists only its own dirs, without the skills Hermes would not load.
|
|
98
|
+
export function skillDirs(scope) {
|
|
99
|
+
if (scope === 'project') {
|
|
100
|
+
// A trusted project's own skills (`hermes skills trust`).
|
|
101
|
+
return ['.hermes', '.agents'].map((d) => ({ dir: join(process.cwd(), d, 'skills'), tool: 'hermes', source: 'project', skip: hiddenBy([]) }));
|
|
102
|
+
}
|
|
103
|
+
const skip = hiddenBy(names(getKey('skills.disabled')));
|
|
104
|
+
const roots = [join(hermesHome(), 'skills'), ...names(getKey('skills.external_dirs')).map(expand)];
|
|
105
|
+
return roots.flatMap((r) => containers(r)).map((dir) => ({ dir, tool: 'hermes', source: 'user', skip }));
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
// {event: [entries]}; throws (naming the key) when a hook list has an unexpected shape.
|
|
109
|
+
function hookLists() {
|
|
110
|
+
const hooks = getKey('hooks');
|
|
111
|
+
if (hooks !== undefined && hooks !== null && !isObj(hooks)) throw new Error(`${configFile()}: hooks must be a mapping; nothing was changed`);
|
|
112
|
+
const out = {};
|
|
113
|
+
for (const e of EVENTS) {
|
|
114
|
+
const list = hooks?.[e];
|
|
115
|
+
if (list !== undefined && list !== null && !Array.isArray(list)) throw new Error(`${configFile()}: hooks.${e} must be a list; nothing was changed`);
|
|
116
|
+
out[e] = list ?? [];
|
|
117
|
+
}
|
|
118
|
+
return out;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
// Called before any write: Hermes must be installed and its hook settings must have the expected shape.
|
|
122
|
+
export function checkConfig(scope) {
|
|
123
|
+
if (scope === 'project') return;
|
|
124
|
+
if (!onPath('hermes')) throw new Error('the hermes CLI was not found on PATH; nothing was changed');
|
|
125
|
+
hookLists();
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
export function installHook(scope, command) {
|
|
129
|
+
if (scope === 'project') return { ...NO_PROJECT };
|
|
130
|
+
if (!command.includes(MARK)) throw new Error(`hook command must contain "${MARK}"`);
|
|
131
|
+
const lists = hookLists();
|
|
132
|
+
const todo = EVENTS.filter((e) => {
|
|
133
|
+
const mine = lists[e].filter(ours);
|
|
134
|
+
return !(mine.length === 1 && mine[0].command === command);
|
|
135
|
+
});
|
|
136
|
+
if (!todo.length) return { changed: false };
|
|
137
|
+
const bak = `${configFile()}.bak-skill-autoroute`;
|
|
138
|
+
if (existsSync(configFile()) && !existsSync(bak)) copyFileSync(configFile(), bak);
|
|
139
|
+
for (const e of todo) setKey(`hooks.${e}`, [...lists[e].filter((h) => !ours(h)), { command, timeout: TIMEOUT }]);
|
|
140
|
+
return { changed: true, note: 'Hermes asks once to allow the new hook the next time it starts (or run: hermes hooks list)' };
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
export function removeHook(scope) {
|
|
144
|
+
if (scope === 'project') return { ...NO_PROJECT };
|
|
145
|
+
if (!detect().cli || !detect().configDir) return { changed: false };
|
|
146
|
+
const lists = hookLists();
|
|
147
|
+
let changed = false;
|
|
148
|
+
for (const e of EVENTS) {
|
|
149
|
+
if (!lists[e].some(ours)) continue;
|
|
150
|
+
setKey(`hooks.${e}`, lists[e].filter((h) => !ours(h)));
|
|
151
|
+
changed = true;
|
|
152
|
+
}
|
|
153
|
+
return { changed };
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
export function hasHook() {
|
|
157
|
+
try { return hookLists().pre_llm_call.some(ours); } catch { return false; }
|
|
158
|
+
}
|
|
159
|
+
export const hookConfig = (scope) => (scope === 'project' ? null : configFile());
|
|
160
|
+
|
|
161
|
+
// What Hermes sends a pre_llm_call shell hook, and whether a reply has the shape it reads.
|
|
162
|
+
export const testInput = (text, cwd) => ({ hook_event_name: 'pre_llm_call', session_id: '', cwd, extra: { user_message: text } });
|
|
163
|
+
export const outputOk = (o) => isObj(o) && typeof o.context === 'string';
|
package/src/triggers.js
CHANGED
|
@@ -13,7 +13,7 @@ const BASE_STOP = 'use when user asks code file files help want wants task work
|
|
|
13
13
|
const MORE_STOP = `about ahead after before also any all can each from have how into its more new not only other our out over some
|
|
14
14
|
such than that them then there these they this those very what which while will your you using used writing write writes
|
|
15
15
|
building build create add change update error errors handling pattern patterns project projects feature features app apps
|
|
16
|
-
need needs like best practice practices guide guidelines skill skills tool tools agent agents claude codex`;
|
|
16
|
+
need needs like best practice practices guide guidelines skill skills tool tools agent agents claude codex hermes`;
|
|
17
17
|
export const STOP_WORDS = new Set(`${BASE_STOP} ${MORE_STOP}`.split(/\s+/));
|
|
18
18
|
|
|
19
19
|
// R29: a rule that fires on any of these is a catch-all and is dropped.
|