Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Skill resolver: the top gate measures the skills a turn actually delivers, and setup drops the user catalog when no skill dir is left

garrytan27ba9fc8d6f8
diff --git a/docs/architecture/key-files/skills.md b/docs/architecture/key-files/skills.md
index 0cdddebb8b..4becbb53af 100644
--- a/docs/architecture/key-files/skills.md
+++ b/docs/architecture/key-files/skills.md
@@ -46,7 +46,7 @@ Contract schemas: `docs/schemas/skill-resolver.v1.*.json`. Every module under
`skill-catalog.ts` import, static or dynamic (`test/skill-resolver-module-graph.test.ts`).
- `src/core/skills/resolver/index.ts` — the library entry (`gbrain/skill-resolver` export, and the entry of the Node bundle `gbrain-skill-resolver.mjs`). Re-exports build, status, remove, resolve, `openCatalog`, `buildSkillIndexOffThread`, `ResolverError`, `resolverHome`; `resetSkillSession` deletes one session's state; `gcSkillSessions` runs one bounded async GC pass; `RESOLVER_FEATURES` names what an adapter may rely on.
-- `src/core/skills/resolver/resolve.ts` — one turn: `normalizeTurnInput` (the turn-input schema, unknown fields refused, message capped at 8 KB), catalog loading through a `TurnSource` (`openCatalogIndex`: receipt and ranker identity, index size; then per turn the gbrain version and, for `dir` and `claude_plugins` catalogs, the sliced stat freshness check: at most `STAT_CHECK_SLICE` entries per turn, a full sweep at most once per `STAT_CHECK_INTERVAL_MS`, cursor in `stat-check`; `stale.stamp` is written without fsync, only when absent and only for a catalog with `rebuild_argv`, never an adapter-owned stdin one), ack and no_match, explicit mentions first, merged-catalog interleave, the `min_match_strength` floor before the cut to k, the off-by-default `top_gate` (best score over `maxIdf(n)` of its catalog, highest across catalogs, below the threshold empties the block as `weak_top_match`; an explicit mention bypasses it), `previous_user_message` as the no-match fallback, the session rules (k 5/3/1 at 50%/80% of the budget, strong-match pacing, no-repeat, one re-suggestion after 10 turns, a named skill past a spent budget, `budget_exhausted` kept on ack and no-match turns), the block and its `block_reason`, `explain`, `failOpen`, `deadlineMs`. Returns `commit()`; session state changes only through it. Pinned by `test/skill-resolver.test.ts` and `test/skill-resolver-contract.test.ts`.
+- `src/core/skills/resolver/resolve.ts` — one turn: `normalizeTurnInput` (the turn-input schema, unknown fields refused, message capped at 8 KB), catalog loading through a `TurnSource` (`openCatalogIndex`: receipt and ranker identity, index size; then per turn the gbrain version and, for `dir` and `claude_plugins` catalogs, the sliced stat freshness check: at most `STAT_CHECK_SLICE` entries per turn, a full sweep at most once per `STAT_CHECK_INTERVAL_MS`, cursor in `stat-check`; `stale.stamp` is written without fsync, only when absent and only for a catalog with `rebuild_argv`, never an adapter-owned stdin one), ack and no_match, explicit mentions first, merged-catalog interleave, the `min_match_strength` floor before the cut to k, the off-by-default `top_gate` (over the skills the block would deliver, after exclude, `min_match_strength`, session dedupe and pacing: the best score over `maxIdf(n)` of its catalog, highest across catalogs, below the threshold empties the block as `weak_top_match`; an explicit mention bypasses it), `previous_user_message` as the no-match fallback, the session rules (k 5/3/1 at 50%/80% of the budget, strong-match pacing, no-repeat, one re-suggestion after 10 turns, a named skill past a spent budget, `budget_exhausted` kept on ack and no-match turns), the block and its `block_reason`, `explain`, `failOpen`, `deadlineMs`. Returns `commit()`; session state changes only through it. Pinned by `test/skill-resolver.test.ts` and `test/skill-resolver-contract.test.ts`.
- `src/core/skills/resolver/rank.ts` — the A5 BM25F ranker over an `IndexReader` (scores summed in the prototype's order, ranked by score over summed idf, ties by name then id), `maxIdf(n)` (the BM25 idf of a term in one of `n` skills, the `top_gate` divisor), the multilingual acknowledgement list, `mentionsSkill` (a `/name` counts only as a leading slash command) and `reasonText`. `test/skill-resolver-reproduction.test.ts` pins top-5 equality with the Step 1 prototype.
- `src/core/skills/resolver/tokenize.ts` — `splitWords` (shared with `scoreSkillMatch` in `skill-catalog.ts`) and `lexTerms`, the frozen Step 1 term rule (stopwords, light stemming); CJK runs become overlapping bigrams. Vectors: `test/fixtures/skill-resolver/tokenizer-vectors.json`.
- `src/core/skills/resolver/index-format.ts` — `index.bin` (magic `GBSKIDX1`, JSON header, field-length averages, per-skill lengths, sorted term dictionary, flat postings with per-field tf, per-skill meta), byte-identical for identical records; `VARIANT_PARAMS` (D and T constants), `fieldText`, `summaryOf` (the description cut at 120 characters), `IndexReader` (lazy postings and meta reads).
diff --git a/docs/guides/skill-resolver.md b/docs/guides/skill-resolver.md
index c7eed2722d..d295c115bf 100644
--- a/docs/guides/skill-resolver.md
+++ b/docs/guides/skill-resolver.md
@@ -213,8 +213,8 @@ as "do it again"), `previous_user_message` (`--previous`) is ranked instead.
### top_gate: an experimental gate, off by default
`top_gate` (`--top-gate`, `skills.resolver.top_gate`) empties the block
-when the best skill the block would show (after `exclude`, pinned skills
-and `min_match_strength`) has a score that, divided by its catalog's maximum
+when the best skill the block would show (after `exclude`, pinned skills,
+`min_match_strength`, session dedupe and pacing) has a score that, divided by its catalog's maximum
idf, `ln(1 + (n - 0.5) / 1.5)` for a catalog of `n` skills, is below the
threshold (0 to 100; unset or 0 is off). With merged catalogs it takes the
highest of those candidates. A skill named in the turn bypasses it. The
diff --git a/docs/schemas/skill-resolver.v1.turn-input.json b/docs/schemas/skill-resolver.v1.turn-input.json
index 6e0f52fc1f..7767667083 100644
--- a/docs/schemas/skill-resolver.v1.turn-input.json
+++ b/docs/schemas/skill-resolver.v1.turn-input.json
@@ -74,7 +74,7 @@
"type": "number",
"minimum": 0,
"maximum": 100,
- "description": "Empty the block (block_reason weak_top_match) when the best skill the block would show (after exclude and min_match_strength) has a score that, divided by its catalog's maximum idf, ln(1 + (n - 0.5) / 1.5) for n skills, is below this; with merged catalogs, the highest of those candidates. A skill named in the turn bypasses it. Omit it or pass 0 to keep the gate off (the default)."
+ "description": "Empty the block (block_reason weak_top_match) when the best skill the block would show (after exclude, min_match_strength, session dedupe and pacing) has a score that, divided by its catalog's maximum idf, ln(1 + (n - 0.5) / 1.5) for n skills, is below this; with merged catalogs, the highest of those candidates. A skill named in the turn bypasses it. Omit it or pass 0 to keep the gate off (the default)."
},
"reset_session": {
"type": "boolean",
diff --git a/src/commands/skill-resolver.ts b/src/commands/skill-resolver.ts
index 06f0a25d42..c71792a5c2 100644
--- a/src/commands/skill-resolver.ts
+++ b/src/commands/skill-resolver.ts
@@ -70,7 +70,7 @@ and no brain connection is needed.
routing, description or body (default: every match). It filters;
stronger matches still fill the block, so it never empties it
--top-gate <x> empty the block when the best skill it would show (after
- --exclude and --min-match) scores below x over its catalog's
+ --exclude, --min-match and session dedupe) scores below x over its catalog's
maximum word weight (0-100; default off); a skill named in the
turn bypasses it
--shadow compute the block without injecting it (block "" on stdout);
diff --git a/src/core/setup/skill-resolver-setup.ts b/src/core/setup/skill-resolver-setup.ts
index c53b9d390b..e2d0d25812 100644
--- a/src/core/setup/skill-resolver-setup.ts
+++ b/src/core/setup/skill-resolver-setup.ts
@@ -119,6 +119,9 @@ export async function syncSkillResolverSetup(opts: { harness: ResolverHarness; g
} else if (dirs.length) {
skills = status!.receipt!.skill_count;
out.steps.push({ step: 'catalog', action: 'keep', detail: `${skills} skills from ${dirs.join(', ')} in ${where}` });
+ } else if (status) {
+ if (!dryRun) await removeSkillIndex(catalog, { home });
+ out.steps.push({ step: 'catalog', action: 'remove', detail: `${where} (no skill directory is left for it)` });
}
let pluginSkills = 0;
if (harness === 'claude-code') {
diff --git a/src/core/skills/resolver/hook-worker.ts b/src/core/skills/resolver/hook-worker.ts
index 791e7019ca..8d81b36388 100644
--- a/src/core/skills/resolver/hook-worker.ts
+++ b/src/core/skills/resolver/hook-worker.ts
@@ -13,7 +13,8 @@
* 300 ms), load-error (throws while loading), exit (waits on nothing, so
* the thread ends without answering); commit-held and commit-written
* (hook-lane.ts) stop the main thread's commit once it holds the lease, or
- * once its temp file is written. GBRAIN_TEST_SKILL_LANE_DEADLINE_MS (tests only, hook-lane.ts)
+ * once its temp file is written; gc (hook-lane.ts) makes the session GC pass
+ * after the logged turn never settle. GBRAIN_TEST_SKILL_LANE_DEADLINE_MS (tests only, hook-lane.ts)
* widens the lane's deadline so a loaded test machine can assert delivery.
*/
import { parentPort, workerData } from 'node:worker_threads';
diff --git a/src/core/skills/resolver/resolve.ts b/src/core/skills/resolver/resolve.ts
index dde51d9c52..5aa265eb20 100644
--- a/src/core/skills/resolver/resolve.ts
+++ b/src/core/skills/resolver/resolve.ts
@@ -22,9 +22,10 @@
* min_match_strength drops weaker matches before the cut to k, so a floor
* never shrinks the block below what the stronger matches fill: it filters
* candidates and does not gate the block. top_gate (off unless set) does:
- * when the best skill the block would show (after exclude and
- * min_match_strength) scores below it over its catalog's maxIdf, the block is
- * empty (block_reason weak_top_match), unless the turn names a skill. A message that matches no catalog word falls back to
+ * when the best skill the block would show (after exclude,
+ * min_match_strength, session dedupe and pacing) scores below it over its
+ * catalog's maxIdf, the block is empty (block_reason weak_top_match), unless
+ * the turn names a skill. A message that matches no catalog word falls back to
* previous_user_message.
*/
import { existsSync, readFileSync, statSync } from 'node:fs';
@@ -382,10 +383,8 @@ async function resolveInner(input: ReturnType<typeof normalizeTurnInput>, opts:
const resuggested: string[] = [];
const deduped: string[] = [];
let paced = false;
- const gated = input.top_gate !== undefined && window.length > 0 && !window.some(x => x.explicit)
- && Math.max(...window.map(x => x.score / maxIdf(loaded[x.c]!.ix.n))) < input.top_gate;
if (budget > 0 && window.length && spentFrac >= 0.5 && !strong(window[0]!)) paced = true;
- if (!paced && !gated) {
+ if (!paced) {
window.forEach((x, i) => {
const last = state.last[x.id];
if (last !== undefined) {
@@ -396,6 +395,9 @@ async function resolveInner(input: ReturnType<typeof normalizeTurnInput>, opts:
picked.push(x);
});
}
+ const gated = input.top_gate !== undefined && picked.length > 0 && !picked.some(x => x.explicit)
+ && Math.max(...picked.map(x => x.score / maxIdf(loaded[x.c]!.ix.n))) < input.top_gate;
+ if (gated) picked.length = 0;
const remaining = Math.max(0, budget - state.spent);
const lines: BlockLine[] = picked.map(x => {
const m = metaOf(x.c, x.doc);
diff --git a/test/setup-skill-resolver.test.ts b/test/setup-skill-resolver.test.ts
index 5d146309ab..6de37a0741 100644
--- a/test/setup-skill-resolver.test.ts
+++ b/test/setup-skill-resolver.test.ts
@@ -310,6 +310,29 @@ describe('per_harness.<harness>.dirs: extra skill directories setup keeps', () =
expect(receipt(b).catalog.source.dirs).toEqual([HARNESS['claude-code'].skills(b)]);
});
+ test('unsetting the last configured dir when the default dir is missing drops the user catalog; the plugin catalog keeps working', async () => {
+ const b = box();
+ const claude = join(b.home, '.claude');
+ const p = join(claude, 'plugins', 'cache', 'market-a', 'acme', '1.0.0');
+ mkdirSync(join(p, '.claude-plugin'), { recursive: true });
+ writeFileSync(join(p, '.claude-plugin', 'plugin.json'), JSON.stringify({ name: 'acme-tools' }));
+ skill(join(p, 'skills'), 'deploy', 'Deploy a service with the acme rollout.');
+ writeFileSync(join(claude, 'plugins', 'installed_plugins.json'), JSON.stringify({ version: 2, plugins: { 'acme@market-a': [{ scope: 'user', installPath: p }] } }));
+ writeFileSync(join(claude, 'settings.json'), JSON.stringify({ enabledPlugins: { 'acme@market-a': true } }));
+ const extra = join(b.root, 'shared-skills');
+ skill(extra, 'citation-fixer', 'Fix broken citations across brain pages.');
+ expect((await run(b, 'set', 'skills.resolver.per_harness.claude-code.dirs', extra)).exitCode).toBe(0);
+ expect((await setup(b, 'claude-code', ['--skill-loading', 'resolve'])).exitCode).toBe(0);
+ expect(catalogs(b).sort()).toEqual(['claude-code-plugins', 'claude-code-user']);
+ expect((await run(b, 'unset', 'skills.resolver.per_harness.claude-code.dirs')).exitCode).toBe(0);
+ const off = await setup(b, 'claude-code', ['--skill-loading', 'resolve']);
+ expect(off.exitCode, off.stderr).toBe(0);
+ expect(off.stdout).toMatch(/remove\s+resolver catalog/);
+ expect(catalogs(b)).toEqual(['claude-code-plugins']);
+ const hit = await runCli(['skills', 'resolve', '--text', 'fix the broken citations', '--json'], { env: b.env, cwd: b.project });
+ expect(JSON.parse(hit.stdout).suggestions.map((s: { id: string }) => s.id)).not.toContain('citation-fixer');
+ });
+
test('a hand-edited dir with a trailing or doubled slash is the same directory: one source dir, and a re-run keeps the catalog', async () => {
const b = box();
skill(HARNESS['claude-code'].skills(b), 'deploy-widget', 'Deploy the widget service.');
diff --git a/test/skill-resolver.test.ts b/test/skill-resolver.test.ts
index e41122d30a..1081333be3 100644
--- a/test/skill-resolver.test.ts
+++ b/test/skill-resolver.test.ts
@@ -146,6 +146,28 @@ describe('turn rules', () => {
expect(none.output.block_reason).toBe('filtered');
});
+ test('top_gate reads the skills left after session dedupe: a deduped strong skill does not open it for a weak one', async () => {
+ const home = tmp();
+ await jsonCatalog(home, 'c', [
+ { id: 'x:release-widget', name: 'release-widget', description: 'Release the widget staging service' },
+ { id: 'x:deploy-notes', name: 'deploy-notes', description: 'Write deploy notes for the team' },
+ ]);
+ const msg = 'deploy release widget staging service';
+ const open = await resolveSkills({ message: msg }, { home });
+ expect(open.output.suggestions.map(s => s.id)).toEqual(['x:release-widget', 'x:deploy-notes']);
+ const [strong, weak] = open.output.suggestions.map(s => s.score / maxIdf(2));
+ const gate = (strong! + weak!) / 2;
+ expect(weak!).toBeLessThan(gate);
+ const first = await resolveSkills({ message: 'release widget staging service', session_id: 'dd', top_gate: gate }, { home });
+ expect(first.output.suggestions.map(s => s.id)).toEqual(['x:release-widget']);
+ expect(await first.commit()).toBe(true);
+ const again = await resolveSkills({ message: msg, session_id: 'dd', top_gate: gate }, { home });
+ expect([again.output.suggestions, again.output.block, again.output.block_reason, again.output.deduped]).toEqual([[], '', 'weak_top_match', ['x:release-widget']]);
+ expect(again.pending!.delta.suggested).toEqual([]);
+ const named = await resolveSkills({ message: 'use the deploy-notes skill', session_id: 'dd', top_gate: 100 }, { home });
+ expect(named.output.suggestions.map(s => s.id)).toEqual(['x:deploy-notes']);
+ });
+
test('top_gate reads the same at any catalog size: the score is divided by the maxIdf of its own catalog', async () => {
const home = tmp();
const pad = (n: number) => Array.from({ length: n }, (_, i) => ({ id: `p:${word(i, 3)}`, name: word(i, 3), description: Array.from({ length: 8 }, (_, s) => word(i, 5 + s)).join(' ') }));