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.mdindex 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.mdindex 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 maximumidf, `ln(1 + (n - 0.5) / 1.5)` for a catalog of `n` skills, is below thethreshold (0 to 100; unset or 0 is off). With merged catalogs it takes thehighest of those candidates. A skill named in the turn bypasses it. Thediff --git a/docs/schemas/skill-resolver.v1.turn-input.json b/docs/schemas/skill-resolver.v1.turn-input.jsonindex 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.tsindex 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'smaximum word weight (0-100; default off); a skill named in theturn 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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(' ') }));