Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Skill resolver: top_gate, an off-by-default gate on the best skill's score

garrytan38416c8cd3c8
diff --git a/docs/schemas/skill-resolver.v1.turn-input.json b/docs/schemas/skill-resolver.v1.turn-input.json
index a016ebbdb0..e3952ca71a 100644
--- a/docs/schemas/skill-resolver.v1.turn-input.json
+++ b/docs/schemas/skill-resolver.v1.turn-input.json
@@ -68,7 +68,13 @@
"description",
"body"
],
- "description": "The weakest match_strength to suggest (strongest first: named, name, triggers, routing, description, body). Weaker matches are dropped before the cut to top_k. Omit it to keep every match."
+ "description": "The weakest match_strength to suggest (strongest first: named, name, triggers, routing, description, body). Weaker matches are dropped before the cut to top_k, so stronger ones still fill the block: it filters candidates and never empties the block. Omit it to keep every match."
+ },
+ "top_gate": {
+ "type": "number",
+ "minimum": 0,
+ "maximum": 100,
+ "description": "Empty the block (block_reason weak_top_match) when the best-ranked skill's score 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 each catalog's best. 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/docs/schemas/skill-resolver.v1.turn-output.json b/docs/schemas/skill-resolver.v1.turn-output.json
index 7f61adb783..1825595c4e 100644
--- a/docs/schemas/skill-resolver.v1.turn-output.json
+++ b/docs/schemas/skill-resolver.v1.turn-output.json
@@ -189,7 +189,7 @@
},
"block_reason": {
"description": "Why the block is empty; null when it has a suggestion.",
- "enum": ["ack", "no_match", "filtered", "deduped", "paced", "budget_exhausted", "shadow", "error", null]
+ "enum": ["ack", "no_match", "filtered", "weak_top_match", "deduped", "paced", "budget_exhausted", "shadow", "error", null]
},
"suggestions": {
"type": "array",
diff --git a/src/commands/skill-resolver.ts b/src/commands/skill-resolver.ts
index 5f26cd735a..c5c73d0e86 100644
--- a/src/commands/skill-resolver.ts
+++ b/src/commands/skill-resolver.ts
@@ -51,7 +51,7 @@ Guide: docs/guides/skill-resolver.md
`;
const HELP_RESOLVE = `Usage: gbrain skills resolve [--catalog <name>]... (--text <t> [--previous <t>] | --input-json -)
- [--session <id>] [--harness <h>] [--exclude a,b] [--top-k n] [--min-match <strength>] [--shadow [--shadow-log <file>]]
+ [--session <id>] [--harness <h>] [--exclude a,b] [--top-k n] [--min-match <strength>] [--top-gate <x>] [--shadow [--shadow-log <file>]]
[--expect-catalog <hash>] [--reset-session] [--names-only] [--load-hint <text>]
[--explain-target <id>] [--fail-open] [--json]
@@ -66,8 +66,12 @@ and no brain connection is needed.
--harness <h> picks the load line: openclaw, claude-code, codex, hermes, qm, pi or cursor
--top-k <n> at most n suggestions (1-8, default 5)
--exclude <ids> comma-separated skill ids to leave out
- --min-match <s> the weakest match to suggest: named, name, triggers, routing,
- description or body (default: every match)
+ --min-match <s> drop candidates weaker than this match: named, name, triggers,
+ 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's score over its catalog's
+ maximum word weight is below x (0-100; default off); a skill
+ named in the turn bypasses it
--shadow compute the block without injecting it (block "" on stdout);
--shadow-log <file> appends what would have been injected
--expect-catalog <h> refuse with skill_catalog_mismatch unless the catalog hash is h
@@ -203,7 +207,7 @@ async function runIndex(args: string[]): Promise<void> {
}
async function runResolve(args: string[]): Promise<void> {
- const p = parseFlags(args, ['--catalog', '--text', '--previous', '--input-json', '--session', '--harness', '--exclude', '--top-k', '--min-match', '--shadow-log', '--explain-target', '--expect-catalog', '--load-hint'],
+ const p = parseFlags(args, ['--catalog', '--text', '--previous', '--input-json', '--session', '--harness', '--exclude', '--top-k', '--min-match', '--top-gate', '--shadow-log', '--explain-target', '--expect-catalog', '--load-hint'],
['--shadow', '--json', '--fail-open', '--reset-session', '--names-only'], HELP_RESOLVE);
if (p.positionals.length) usage(`Unexpected argument "${p.positionals[0]}".`, 'Pass the message with --text "<message>" or turn JSON with --input-json -.');
const json = p.bools.has('--json');
@@ -229,6 +233,8 @@ async function runResolve(args: string[]): Promise<void> {
const topK = one(p, '--top-k');
if (topK !== undefined) { if (!/^\d+$/.test(topK)) throw new ResolverError('skill_resolve_invalid_input', '--top-k takes an integer from 1 to 8.', { suggestion: 'Example: --top-k 3' }); input.top_k = Number(topK); }
const minMatch = one(p, '--min-match'); if (minMatch !== undefined) input.min_match_strength = minMatch;
+ const topGate = one(p, '--top-gate');
+ if (topGate !== undefined) { if (!/^\d+(\.\d+)?$/.test(topGate)) throw new ResolverError('skill_resolve_invalid_input', '--top-gate takes a number from 0 to 100.', { suggestion: 'Example: --top-gate 1.5' }); input.top_gate = Number(topGate); }
if (p.bools.has('--shadow')) input.shadow = true;
if (p.bools.has('--reset-session')) input.reset_session = true;
const expect = one(p, '--expect-catalog'); if (expect !== undefined) input.expected_catalog_hash = expect;
diff --git a/src/core/cli-flag-registry.generated.ts b/src/core/cli-flag-registry.generated.ts
index 2d4df2aee1..b9ac0722f8 100644
--- a/src/core/cli-flag-registry.generated.ts
+++ b/src/core/cli-flag-registry.generated.ts
@@ -124,7 +124,7 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {
'self-upgrade': ['--apply', '--brain', '--channel', '--check-only', '--clear-never-installed', '--exit-code', '--ff-only', '--force', '--force-retry', '--help', '--is-ancestor', '--json', '--markdown', '--migrate-only', '--no-autopilot-install', '--no-bun-floor-check', '--no-restart', '--non-interactive', '--quiet', '--refresh-cache', '--refs', '--remediation-plan', '--restart-only', '--snooze', '--source', '--stop-mcp', '--swap-only', '--tags', '--version', '--yes'],
'serve': ['--access', '--add', '--adopt-columns', '--adopt-permissions', '--advertise', '--all-new', '--apply-rewrites', '--attest-actor', '--attest-ops', '--bind', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--budget-usd-per-day', '--cli-socket', '--client', '--days', '--delegated-namespace', '--delegated-slug-prefixes', '--enable-dcr', '--enable-dcr-insecure', '--expect', '--fail-fast', '--federated-read', '--grant-types', '--harness', '--help', '--http', '--id', '--if-version', '--json', '--log-full-params', '--may-act-for', '--member', '--migrate-legacy', '--min-trust', '--no-embedding', '--no-pull', '--oauth-request', '--only', '--operations', '--path', '--pglite', '--port', '--prefer-postgres', '--print-admin-token', '--private-pages', '--profile', '--provenance', '--public-url', '--read-sources', '--redirect-uri', '--refresh-operations', '--repair', '--reset-default', '--retry-failed', '--scopes', '--source', '--source-guard', '--source-id', '--sources', '--stale', '--stdio-idle-timeout', '--suppress-bootstrap-token', '--surface', '--takes-holders', '--token', '--token-endpoint-auth-method', '--token-ttl', '--tools-json', '--url', '--usage', '--yes'],
'setup': ['--accept-capabilities', '--advertise', '--agent', '--auto', '--bearer-token-env-var', '--brain', '--break-lock', '--capture', '--credentials-file', '--dry-run', '--env', '--force', '--gbrain-bin', '--harness', '--header', '--help', '--http', '--images', '--install', '--instructions', '--instructions-only', '--issuer-url', '--json', '--legacy-lock', '--link', '--mcp-only', '--mcp-url', '--name', '--no-capture', '--no-embedding', '--no-hooks', '--no-instructions', '--no-providers', '--oauth-client-id', '--oauth-client-secret', '--only', '--path', '--pglite', '--probe', '--providers', '--pure', '--remove', '--root', '--runtime', '--save', '--scope', '--skill-loading', '--skills-index-only', '--source', '--source-ids', '--stale', '--surface', '--token', '--url', '--workspace', '--yes'],
- 'skill-resolver': ['--brain', '--bundled', '--catalog', '--claude-plugins', '--dir', '--exclude', '--expect-catalog', '--explain-target', '--fail-open', '--from-json', '--harness', '--help', '--input-json', '--json', '--load-hint', '--min-match', '--names-only', '--out', '--previous', '--reset-session', '--routing', '--scope', '--session', '--shadow', '--shadow-log', '--source', '--text', '--top-k'],
+ 'skill-resolver': ['--brain', '--bundled', '--catalog', '--claude-plugins', '--dir', '--exclude', '--expect-catalog', '--explain-target', '--fail-open', '--from-json', '--harness', '--help', '--input-json', '--json', '--load-hint', '--min-match', '--names-only', '--out', '--previous', '--reset-session', '--routing', '--scope', '--session', '--shadow', '--shadow-log', '--source', '--text', '--top-gate', '--top-k'],
'skillify': ['--brain', '--description', '--dry-run', '--force', '--help', '--json', '--mutating', '--recent', '--skills-dir', '--source', '--strict', '--triggers', '--writes-pages', '--writes-to'],
'skillopt': ['--all', '--allow-mutate-bundled', '--background', '--batch-size', '--benchmark', '--bootstrap-from-routing', '--bootstrap-from-skill', '--bootstrap-reviewed', '--bootstrap-tasks', '--brain', '--brain-wide-max-cost-usd', '--dry-run', '--epochs', '--follow', '--force', '--held-out', '--help', '--json', '--judge-model', '--loop', '--lr', '--lr-schedule', '--max-cost-usd', '--max-runtime-min', '--max-usd', '--models-strict', '--no-max-cost', '--no-mutate', '--optimizer-model', '--patch', '--reflect-max-tokens', '--resume', '--rewrite', '--skills-dir', '--source', '--split', '--status', '--target-model', '--target-models'],
'skillpack': ['--all', '--apply-clean-hunks', '--author', '--auto', '--brain', '--dest', '--dry-run', '--env', '--exit-code', '--fast', '--fix', '--force-unlock', '--format', '--from', '--full', '--harness', '--help', '--homepage', '--json', '--license', '--list', '--minimal', '--name-only', '--no-cache', '--no-lint', '--note', '--out', '--overwrite-local', '--persona', '--probe', '--pure', '--push', '--quick', '--quiet', '--refresh', '--repo', '--schema-pack', '--scope', '--short', '--since', '--skill', '--skills', '--skills-dir', '--skip-doctor', '--source', '--strict', '--stub', '--supabase', '--target', '--tier', '--trust', '--url', '--verify', '--version', '--workspace', '--yes'],
diff --git a/src/core/setup/skill-resolver-config.ts b/src/core/setup/skill-resolver-config.ts
index 19391b7569..4a1d44da94 100644
--- a/src/core/setup/skill-resolver-config.ts
+++ b/src/core/setup/skill-resolver-config.ts
@@ -7,7 +7,7 @@
* skills.resolver.session_token_budget, skills.resolver.auto_rebuild
* (PR A's settings, src/core/skills/resolver/config.ts)
* skills.resolver.lane_payload_chars the hook lane's payload budget (500..10000, default 4000)
- * skills.resolver.top_k, min_match, pinned, per_harness.<harness>.{top_k,min_match}
+ * skills.resolver.top_k, min_match, top_gate, pinned, per_harness.<harness>.{top_k,min_match,top_gate}
* the hook lane's turn settings (src/core/skills/resolver/config.ts)
*
* A missing file is created with only these keys: no engine, no database, so
@@ -20,7 +20,7 @@ import { existsSync, readFileSync, statSync, unlinkSync } from 'node:fs';
import { join } from 'node:path';
import { atomicWriteTextFile } from '../bootstrap/atomic-write.ts';
import { setCliExitVerdict } from '../cli-force-exit.ts';
-import { laneTurnSettings, validateMinMatch, validatePinned, validateSessionTokenBudget, validateTopK } from '../skills/resolver/config.ts';
+import { laneTurnSettings, validateMinMatch, validatePinned, validateSessionTokenBudget, validateTopGate, validateTopK } from '../skills/resolver/config.ts';
const CONFIG_CAP_BYTES = 1024 * 1024;
const isPlainObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
@@ -89,8 +89,8 @@ export function setResolverHarness(read: Exclude<ResolverConfigRead, { state: 'u
export const SKILL_RESOLVER_KEY_PREFIX = 'skills.resolver.';
/** The leaves `gbrain config set|unset|get` accepts (harnesses is setup's: --skill-loading resolve|off). */
-export const SKILL_RESOLVER_CONFIG_LEAVES = ['enabled', 'session_token_budget', 'auto_rebuild', 'lane_payload_chars', 'top_k', 'min_match', 'pinned', 'per_harness.<harness>.top_k', 'per_harness.<harness>.min_match'] as const;
-const PER_HARNESS_LEAF = /^per_harness\.([a-z-]+)\.(top_k|min_match)$/;
+export const SKILL_RESOLVER_CONFIG_LEAVES = ['enabled', 'session_token_budget', 'auto_rebuild', 'lane_payload_chars', 'top_k', 'min_match', 'top_gate', 'pinned', 'per_harness.<harness>.top_k', 'per_harness.<harness>.min_match', 'per_harness.<harness>.top_gate'] as const;
+const PER_HARNESS_LEAF = /^per_harness\.([a-z-]+)\.(top_k|min_match|top_gate)$/;
function parseLeafValue(leaf: string, value: string): { ok: true; value: boolean | number | string | string[] } | { ok: false; error: string } {
const turnKey = leaf.match(PER_HARNESS_LEAF)?.[2] ?? leaf;
@@ -98,6 +98,7 @@ function parseLeafValue(leaf: string, value: string): { ok: true; value: boolean
try {
if (turnKey === 'top_k') return { ok: true, value: validateTopK(/^\d+$/.test(value) ? Number(value) : NaN, key) };
if (turnKey === 'min_match') return { ok: true, value: validateMinMatch(value, key) };
+ if (turnKey === 'top_gate') return { ok: true, value: validateTopGate(/^\d+(\.\d+)?$/.test(value) ? Number(value) : NaN, key) };
if (leaf === 'pinned') return { ok: true, value: validatePinned(value.split(',').map(s => s.trim()).filter(Boolean), key) };
} catch (e) { return { ok: false, error: (e as Error).message.slice(key.length + 1) }; }
if (leaf === 'enabled' || leaf === 'auto_rebuild') {
diff --git a/src/core/skills/resolver/config.ts b/src/core/skills/resolver/config.ts
index 1defacb2f4..16b9e3b991 100644
--- a/src/core/skills/resolver/config.ts
+++ b/src/core/skills/resolver/config.ts
@@ -17,7 +17,9 @@
* skills.resolver.top_k suggestions per turn (1..8, default 5)
* skills.resolver.min_match the weakest match_strength to suggest
* (default: every match)
- * skills.resolver.per_harness.<harness>.{top_k,min_match} overrides
+ * skills.resolver.top_gate empty the block when the best skill's score
+ * over its catalog's maxIdf is below this (0..100; default off)
+ * skills.resolver.per_harness.<harness>.{top_k,min_match,top_gate} overrides
* for one harness; a key it leaves out falls back to the global one, and
* an entry that is not an object (a hand-edited null) counts as unset
* skills.resolver.pinned skill ids the harness always loads itself,
@@ -27,7 +29,7 @@ import { readFileSync, statSync } from 'node:fs';
import { join } from 'node:path';
import { HARNESSES } from './block.ts';
import { ResolverError } from './errors.ts';
-import { EXCLUDE_MAX, MATCH_STRENGTHS, type MatchStrength, TOP_K_MAX } from './limits.ts';
+import { EXCLUDE_MAX, MATCH_STRENGTHS, type MatchStrength, TOP_GATE_MAX, TOP_K_MAX } from './limits.ts';
export const DEFAULT_SESSION_TOKEN_BUDGET = 2000;
export const MIN_SESSION_TOKEN_BUDGET = 100;
@@ -64,7 +66,7 @@ export function readResolverSettings(home: string, env: NodeJS.ProcessEnv = proc
}
/** What the hook lane adds to each turn's input. */
-export interface LaneTurnSettings { top_k?: number; min_match_strength?: MatchStrength; exclude?: string[] }
+export interface LaneTurnSettings { top_k?: number; min_match_strength?: MatchStrength; top_gate?: number; exclude?: string[] }
function configInvalid(key: string, rule: string): ResolverError {
return new ResolverError('skill_resolver_config_invalid', `${key} ${rule}.`, { suggestion: `Fix or unset ${key}: gbrain config unset ${key}` });
@@ -80,6 +82,11 @@ export function validateMinMatch(v: unknown, key: string): MatchStrength {
throw configInvalid(key, `must be one of ${MATCH_STRENGTHS.join(', ')}`);
}
+export function validateTopGate(v: unknown, key: string): number {
+ if (typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= TOP_GATE_MAX) return v;
+ throw configInvalid(key, `must be a number from 0 to ${TOP_GATE_MAX} (0 or unset: off)`);
+}
+
export function validatePinned(v: unknown, key: string): string[] {
if (Array.isArray(v) && v.length <= EXCLUDE_MAX && v.every(x => typeof x === 'string' && x.length > 0 && x.length <= 256)) return v as string[];
throw configInvalid(key, `must be a list of at most ${EXCLUDE_MAX} skill ids`);
@@ -91,6 +98,7 @@ export function laneTurnSettings(section: Record<string, unknown>, harness: stri
const global: LaneTurnSettings = {
...(section.top_k !== undefined ? { top_k: validateTopK(section.top_k, `${p}top_k`) } : {}),
...(section.min_match !== undefined ? { min_match_strength: validateMinMatch(section.min_match, `${p}min_match`) } : {}),
+ ...(section.top_gate !== undefined ? { top_gate: validateTopGate(section.top_gate, `${p}top_gate`) } : {}),
...(section.pinned !== undefined ? { exclude: validatePinned(section.pinned, `${p}pinned`) } : {}),
};
const per = section.per_harness;
@@ -101,11 +109,12 @@ export function laneTurnSettings(section: Record<string, unknown>, harness: stri
const key = `${p}per_harness.${h}`;
if (!(HARNESSES as readonly string[]).includes(h)) throw configInvalid(key, `names no harness (one of ${HARNESSES.join(', ')})`);
if (!o || typeof o !== 'object' || Array.isArray(o)) continue;
- if (Object.keys(o).some(k => k !== 'top_k' && k !== 'min_match')) throw configInvalid(key, 'may hold only top_k and min_match');
+ if (Object.keys(o).some(k => k !== 'top_k' && k !== 'min_match' && k !== 'top_gate')) throw configInvalid(key, 'may hold only top_k, min_match and top_gate');
const r = o as Record<string, unknown>;
const parsed: LaneTurnSettings = {
...(r.top_k !== undefined ? { top_k: validateTopK(r.top_k, `${key}.top_k`) } : {}),
...(r.min_match !== undefined ? { min_match_strength: validateMinMatch(r.min_match, `${key}.min_match`) } : {}),
+ ...(r.top_gate !== undefined ? { top_gate: validateTopGate(r.top_gate, `${key}.top_gate`) } : {}),
};
if (h === harness) mine = parsed;
}
diff --git a/src/core/skills/resolver/index.ts b/src/core/skills/resolver/index.ts
index 92e9ce03e3..8eb7f270ba 100644
--- a/src/core/skills/resolver/index.ts
+++ b/src/core/skills/resolver/index.ts
@@ -32,10 +32,11 @@ import { gcSessionsAsync, resetSession, sessionKey } from './session.ts';
* --dir bodies, Claude Code plugin catalogs, the warm handle (openCatalog),
* the worker-thread build (buildSkillIndexOffThread), gcSkillSessions, the
* hook lane for Hermes (`hook user-prompt --harness hermes`, answering
- * {"context"}) and the lane's Codex project catalog (codex-project-<hash>,
- * the .agents/skills dirs from the project root to cwd).
+ * {"context"}), the lane's Codex project catalog (codex-project-<hash>,
+ * the .agents/skills dirs from the project root to cwd) and top_gate in the
+ * turn input (block_reason weak_top_match).
*/
-export const RESOLVER_FEATURES: readonly string[] = ['min_match_strength', 'exclude_1024', 'mismatch_catalog_hash', 'named_past_budget', 'previous_user_message', 'harness_pi', 'harness_cursor', 'openclaw_skills_list', 'from_json_with_dirs', 'from_json_when_to_use', 'claude_plugins', 'open_catalog', 'build_off_thread', 'gc_sessions', 'harness_hermes_lane', 'codex_project_catalog'];
+export const RESOLVER_FEATURES: readonly string[] = ['min_match_strength', 'exclude_1024', 'mismatch_catalog_hash', 'named_past_budget', 'previous_user_message', 'harness_pi', 'harness_cursor', 'openclaw_skills_list', 'from_json_with_dirs', 'from_json_when_to_use', 'claude_plugins', 'open_catalog', 'build_off_thread', 'gc_sessions', 'harness_hermes_lane', 'codex_project_catalog', 'top_gate'];
/** One bounded pass (at most 1,000 files, async I/O) deleting session files idle for 7 days; returns how many it deleted. Commits already run one at most every 10 minutes. */
export async function gcSkillSessions(opts: { home?: string; now?: number } = {}): Promise<number> {
diff --git a/src/core/skills/resolver/limits.ts b/src/core/skills/resolver/limits.ts
index d6f624dbbf..7e53200e00 100644
--- a/src/core/skills/resolver/limits.ts
+++ b/src/core/skills/resolver/limits.ts
@@ -6,6 +6,8 @@
export const TOP_K_DEFAULT = 5;
export const TOP_K_MAX = 8;
export const EXCLUDE_MAX = 1024;
+/** top_gate's upper bound; 0 (or unset) turns the gate off. */
+export const TOP_GATE_MAX = 100;
/** The strongest way a suggestion matched the turn: named in it, then by field. A body-only match is the weakest. */
export type MatchStrength = 'named' | 'name' | 'triggers' | 'routing' | 'description' | 'body';
diff --git a/src/core/skills/resolver/rank.ts b/src/core/skills/resolver/rank.ts
index 33e4a37b96..bf62f13a39 100644
--- a/src/core/skills/resolver/rank.ts
+++ b/src/core/skills/resolver/rank.ts
@@ -63,6 +63,9 @@ export function mentionsSkill(message: string, id: string, name: string): boolea
return false;
}
+/** The idf of a term only one of n skills holds: the most one query word can weigh in a catalog of n, so a score over it reads the same at any catalog size. */
+export const maxIdf = (n: number) => Math.log(1 + (n - 0.5) / 1.5);
+
const byName = (ix: IndexReader) => (a: Ranked, b: Ranked) => {
const ma = ix.meta(a.doc);
const mb = ix.meta(b.doc);
diff --git a/src/core/skills/resolver/resolve.ts b/src/core/skills/resolver/resolve.ts
index 89371d0297..ff618e7fb3 100644
--- a/src/core/skills/resolver/resolve.ts
+++ b/src/core/skills/resolver/resolve.ts
@@ -20,8 +20,12 @@
* the turn names explicitly still gets its line (its tokens still count).
*
* min_match_strength drops weaker matches before the cut to k, so a floor
- * never shrinks the block below what the stronger matches fill. A message
- * that matches no catalog word falls back to previous_user_message.
+ * 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-ranked skill's score over its catalog's maxIdf is below it,
+ * 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';
import { createHash } from 'node:crypto';
@@ -34,10 +38,10 @@ import { readResolverSettings, type ResolverSettings, validateSessionTokenBudget
import { ResolverError } from './errors.ts';
import { appendDailyLogSync, RESOLVER_LOG } from './daily-log.ts';
import { ensureDir, writeFileAtomic } from './fsutil.ts';
-import { EXCLUDE_MAX, MATCH_STRENGTHS, type MatchStrength, STRENGTH_FIELDS, TOP_K_DEFAULT, TOP_K_MAX } from './limits.ts';
+import { EXCLUDE_MAX, MATCH_STRENGTHS, type MatchStrength, STRENGTH_FIELDS, TOP_GATE_MAX, TOP_K_DEFAULT, TOP_K_MAX } from './limits.ts';
import { IndexReader, RANKER_ID, RANKER_VERSION } from './index-format.ts';
import { assertCatalogName, catalogFile, logsDir, resolverHome } from './paths.ts';
-import { isAcknowledgement, mentionsSkill, rankIndex, reasonText, type RankResult } from './rank.ts';
+import { isAcknowledgement, maxIdf, mentionsSkill, rankIndex, reasonText, type RankResult } from './rank.ts';
import { commitSession, freshState, loadSession, sessionKey, type SessionState, type TurnDelta } from './session.ts';
export const SCHEMA_VERSION = 1;
@@ -59,12 +63,13 @@ export interface TurnInput {
expected_catalog_hash?: string;
reset_session?: boolean;
min_match_strength?: MatchStrength;
+ top_gate?: number;
}
export interface Suggestion { id: string; name: string; score: number; summary: string; reason: string; match_strength: MatchStrength; path?: string; catalog: string }
export interface TurnError { code: string; message: string; fix: { suggestion: string; command?: string } }
/** Why a block is empty; null when it has a suggestion. */
-export type BlockReason = 'ack' | 'no_match' | 'filtered' | 'deduped' | 'paced' | 'budget_exhausted' | 'shadow' | 'error';
+export type BlockReason = 'ack' | 'no_match' | 'filtered' | 'weak_top_match' | 'deduped' | 'paced' | 'budget_exhausted' | 'shadow' | 'error';
export interface TurnOutput {
schema_version: 1;
gbrain_version: string;
@@ -141,7 +146,7 @@ function capUtf8(s: string, max: number): string {
export function normalizeTurnInput(raw: unknown): Required<Pick<TurnInput, 'message' | 'top_k' | 'exclude' | 'shadow' | 'reset_session'>> & TurnInput {
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw invalid('The turn input must be a JSON object.', 'Send {"message": "..."} (see docs/schemas/skill-resolver.v1.turn-input.json).');
const o = raw as Record<string, unknown>;
- const known = new Set(['message', 'previous_user_message', 'session_id', 'harness', 'top_k', 'exclude', 'shadow', 'expected_catalog_hash', 'reset_session', 'min_match_strength']);
+ const known = new Set(['message', 'previous_user_message', 'session_id', 'harness', 'top_k', 'exclude', 'shadow', 'expected_catalog_hash', 'reset_session', 'min_match_strength', 'top_gate']);
const extra = Object.keys(o).find(k => !known.has(k));
if (extra) throw invalid(`Unknown turn input field "${extra}".`, 'Use only the fields in docs/schemas/skill-resolver.v1.turn-input.json.');
if (typeof o.message !== 'string') throw invalid('message is required and must be a string.', 'Send the user message as "message".');
@@ -153,6 +158,7 @@ export function normalizeTurnInput(raw: unknown): Required<Pick<TurnInput, 'mess
if (o.shadow !== undefined && typeof o.shadow !== 'boolean') throw invalid('shadow must be a boolean.', 'Pass true or false.');
if (o.reset_session !== undefined && typeof o.reset_session !== 'boolean') throw invalid('reset_session must be a boolean.', 'Pass true on the first turn after a compaction.');
if (o.min_match_strength !== undefined && !(MATCH_STRENGTHS as readonly unknown[]).includes(o.min_match_strength)) throw invalid(`min_match_strength must be one of ${MATCH_STRENGTHS.join(', ')}.`, 'Omit it to keep every match, or pass description to drop body-only matches.');
+ if (o.top_gate !== undefined && (typeof o.top_gate !== 'number' || !Number.isFinite(o.top_gate) || o.top_gate < 0 || o.top_gate > TOP_GATE_MAX)) throw invalid(`top_gate must be a number from 0 to ${TOP_GATE_MAX}.`, 'Omit it (or pass 0) to keep the gate off.');
if (o.expected_catalog_hash !== undefined && (typeof o.expected_catalog_hash !== 'string' || !/^[0-9a-f]{64}$/.test(o.expected_catalog_hash))) throw invalid('expected_catalog_hash must be a sha256 hex string.', 'Pass the catalog_hash from the build receipt.');
return {
message: capUtf8(o.message, MESSAGE_CAP_BYTES),
@@ -165,6 +171,7 @@ export function normalizeTurnInput(raw: unknown): Required<Pick<TurnInput, 'mess
reset_session: o.reset_session === true,
...(o.expected_catalog_hash !== undefined ? { expected_catalog_hash: o.expected_catalog_hash as string } : {}),
...(o.min_match_strength !== undefined ? { min_match_strength: o.min_match_strength as MatchStrength } : {}),
+ ...(o.top_gate ? { top_gate: o.top_gate as number } : {}),
};
}
@@ -375,8 +382,10 @@ async function resolveInner(input: ReturnType<typeof normalizeTurnInput>, opts:
const resuggested: string[] = [];
const deduped: string[] = [];
let paced = false;
+ const gated = input.top_gate !== undefined && !window.some(x => x.explicit)
+ && Math.max(...ranks.map((r, c) => (r.ranked[0] ? r.ranked[0].score / maxIdf(loaded[c]!.ix.n) : 0))) < input.top_gate;
if (budget > 0 && window.length && spentFrac >= 0.5 && !strong(window[0]!)) paced = true;
- if (!paced) {
+ if (!paced && !gated) {
window.forEach((x, i) => {
const last = state.last[x.id];
if (last !== undefined) {
@@ -404,7 +413,7 @@ async function resolveInner(input: ReturnType<typeof normalizeTurnInput>, opts:
const match_strength = strengthOf(x);
return { id: m.id, name: m.name, score: round4(x.score), summary: namesOnly ? '' : m.summary, reason: x.explicit ? `named in the turn; ${reasonText(fields)}` : reasonText(fields), match_strength, ...(m.path ? { path: m.path } : {}), catalog: loaded[x.c]!.name };
});
- const blockReason: BlockReason | null = suggestions.length ? null : exhausted ? 'budget_exhausted' : paced ? 'paced' : window.length ? 'deduped' : 'filtered';
+ const blockReason: BlockReason | null = suggestions.length ? null : exhausted ? 'budget_exhausted' : gated ? 'weak_top_match' : paced ? 'paced' : window.length ? 'deduped' : 'filtered';
const out: TurnOutput = { ...base, budget_exhausted: exhausted, block_reason: blockReason, suggestions, block: r.block, block_tokens: r.tokens, deduped };
let explain: Explain | undefined;
if (opts.explainTarget !== undefined) {
diff --git a/test/skill-resolver-cli.test.ts b/test/skill-resolver-cli.test.ts
index 3574f64ce8..269c2c3e0e 100644
--- a/test/skill-resolver-cli.test.ts
+++ b/test/skill-resolver-cli.test.ts
@@ -101,6 +101,8 @@ describe('gbrain skills (CLI)', () => {
[['skills', 'resolve', '--catalog', '../config', '--text', 'x'], undefined, 'skill_catalog_unknown'],
[['skills', 'resolve', '--text', 'x', '--top-k', '9'], undefined, 'skill_resolve_invalid_input'],
[['skills', 'resolve', '--text', 'x', '--min-match', 'weak'], undefined, 'skill_resolve_invalid_input'],
+ [['skills', 'resolve', '--text', 'x', '--top-gate', 'high'], undefined, 'skill_resolve_invalid_input'],
+ [['skills', 'resolve', '--text', 'x', '--top-gate', '101'], undefined, 'skill_resolve_invalid_input'],
[['skills', 'index', 'build', '--catalog', 'c', '--from-json', '-'], '{"skills": 1}', 'skill_source_invalid'],
[['skills', 'index', 'frobnicate'], undefined, 'Unknown subcommand'],
];
@@ -131,4 +133,14 @@ describe('gbrain skills (CLI)', () => {
expect(rec.shadow).toBe(true);
expect(rec.block).toContain('gbrain:deploy');
}, 60_000);
+
+ test('--top-gate empties the block with block_reason weak_top_match, and the output validates', () => {
+ const h = tmp();
+ expect(cli(h, ['skills', 'index', 'build', '--catalog', 'c', '--from-json', '-'], SKILLS).code).toBe(0);
+ const gated = cli(h, ['skills', 'resolve', '--text', 'deploy', '--top-gate', '100', '--json']);
+ const doc = JSON.parse(gated.out);
+ expect(validate(loadSchema('skill-resolver.v1.turn-output'), doc)).toEqual([]);
+ expect([gated.code, doc.block, doc.block_reason]).toEqual([0, '', 'weak_top_match']);
+ expect(JSON.parse(cli(h, ['skills', 'resolve', '--text', 'deploy', '--top-gate', '0', '--json']).out).block).toContain('gbrain:deploy');
+ }, 60_000);
});
diff --git a/test/skill-resolver-contract.test.ts b/test/skill-resolver-contract.test.ts
index 5af5806c64..dc4c8f441f 100644
--- a/test/skill-resolver-contract.test.ts
+++ b/test/skill-resolver-contract.test.ts
@@ -32,9 +32,9 @@ const SKILLS = [
];
describe('turn input', () => {
- const good = [{ message: 'deploy' }, { message: '', top_k: 8, exclude: [], shadow: false, reset_session: true }, { message: 'x', session_id: 'a'.repeat(256), harness: 'codex', expected_catalog_hash: 'a'.repeat(64), previous_user_message: 'y' }, { message: 'x', exclude: Array(1024).fill('a'), min_match_strength: 'description', harness: 'pi' }];
+ const good = [{ message: 'deploy' }, { message: '', top_k: 8, exclude: [], shadow: false, reset_session: true }, { message: 'x', session_id: 'a'.repeat(256), harness: 'codex', expected_catalog_hash: 'a'.repeat(64), previous_user_message: 'y' }, { message: 'x', exclude: Array(1024).fill('a'), min_match_strength: 'description', harness: 'pi' }, { message: 'x', top_gate: 1.5 }, { message: 'x', top_gate: 0 }];
const bad = [{}, { message: 1 }, { message: 'x', top_k: 0 }, { message: 'x', top_k: 9 }, { message: 'x', top_k: 2.5 }, { message: 'x', extra: true }, { message: 'x', harness: 'vim' },
- { message: 'x', session_id: '' }, { message: 'x', session_id: 'a b' }, { message: 'x', exclude: Array(1025).fill('a') }, { message: 'x', min_match_strength: 'weak' }, { message: 'x', exclude: [1] }, { message: 'x', expected_catalog_hash: 'ABC' }, { message: 'x', shadow: 'yes' }];
+ { message: 'x', session_id: '' }, { message: 'x', session_id: 'a b' }, { message: 'x', exclude: Array(1025).fill('a') }, { message: 'x', min_match_strength: 'weak' }, { message: 'x', top_gate: 101 }, { message: 'x', top_gate: -0.5 }, { message: 'x', exclude: [1] }, { message: 'x', expected_catalog_hash: 'ABC' }, { message: 'x', shadow: 'yes' }];
test('the schema and the resolver accept and refuse the same inputs', () => {
for (const g of good) { expect(validate(INPUT, g)).toEqual([]); expect(() => normalizeTurnInput(g)).not.toThrow(); }
for (const b of bad) {
diff --git a/test/skill-resolver-hook-lane.test.ts b/test/skill-resolver-hook-lane.test.ts
index f505166385..423b1778d5 100644
--- a/test/skill-resolver-hook-lane.test.ts
+++ b/test/skill-resolver-hook-lane.test.ts
@@ -255,6 +255,30 @@ describe('skill-resolver lane: turn settings from config', () => {
});
});
+describe('skill-resolver lane: top_gate from config', () => {
+ test('a gate above every score empties the block; per_harness 0 turns it off for one harness; a bad value is refused', async () => {
+ const b = box();
+ seedSkills(claudeSkills(b));
+ await setup(b, 'claude-code');
+ const cmd = wired(b, 'claude-code');
+ const config = (...args: string[]) => runCli(['config', ...args], { env: b.env, cwd: b.project });
+ const ask = (s: string) => hook(b, cmd, { prompt: 'please deploy the widget to staging', session_id: s }, WIDE);
+ expect((await config('set', 'skills.resolver.top_gate', '100')).exitCode).toBe(0);
+ const gated = await ask('tg1');
+ expect([gated.exitCode, gated.stdout]).toEqual([0, '']);
+ expect(laneLog(b).at(-1)).toMatchObject({ outcome: 'empty' });
+ expect((await config('set', 'skills.resolver.per_harness.claude-code.top_gate', '0')).exitCode).toBe(0);
+ expect(contextOf(await ask('tg2'))).toContain('deploy-widget');
+ for (const bad of ['high', '101']) {
+ const r = await config('set', 'skills.resolver.top_gate', bad);
+ expect(r.exitCode, bad).not.toBe(0);
+ expect(r.stderr).toContain('must be a number from 0 to 100');
+ }
+ expect((await config('set', 'skills.resolver.top_gate', '-1')).exitCode).not.toBe(0);
+ expect(JSON.parse(readFileSync(join(b.home, '.gbrain', 'config.json'), 'utf8')).skills.resolver).toMatchObject({ top_gate: 100, per_harness: { 'claude-code': { top_gate: 0 } } });
+ });
+});
+
describe('skill-resolver lane: session GC before the process exits', () => {
test('a delivered turn deletes idle session files and stamps the pass; a turn within the interval leaves new ones', async () => {
const b = box();
diff --git a/test/skill-resolver.test.ts b/test/skill-resolver.test.ts
index 4ad9e9d8f5..9a26308318 100644
--- a/test/skill-resolver.test.ts
+++ b/test/skill-resolver.test.ts
@@ -23,7 +23,7 @@ import {
buildSkillIndex, catalogStatus, removeSkillIndex, resolveSkills, sessionStatus, ResolverError, BLOCK_TOKEN_CAP, type TurnInput,
} from '../src/core/skills/resolver/index.ts';
import { lexTerms } from '../src/core/skills/resolver/tokenize.ts';
-import { isAcknowledgement, mentionsSkill } from '../src/core/skills/resolver/rank.ts';
+import { isAcknowledgement, maxIdf, mentionsSkill } from '../src/core/skills/resolver/rank.ts';
import { estimateTokens } from '../src/core/skills/resolver/block.ts';
import { acquireLease, holdsLease, releaseLease, tryAcquireLease } from '../src/core/skills/resolver/lock.ts';
import { commitSession, commitSessionAsync, gcSessions, gcSessionsAsync, loadSession, sessionGcSettled, sessionKey } from '../src/core/skills/resolver/session.ts';
@@ -117,6 +117,33 @@ describe('turn rules', () => {
expect(named.output.suggestions.map(s => s.id)).toEqual(['x:desc-3']);
});
+ test('top_gate empties the block when the best skill scores below it over its catalog maxIdf; off by default and at 0, a named skill bypasses it, nothing gated is committed', async () => {
+ const home = tmp();
+ await jsonCatalog(home, 'c', BASIC);
+ const open = await resolveSkills({ message: 'team status', session_id: 'g' }, { home });
+ expect(open.output.suggestions[0]!.id).toBe('gbrain:reports');
+ const top = open.output.suggestions[0]!.score / maxIdf(BASIC.length);
+ const below = await resolveSkills({ message: 'team status', top_gate: top + 0.01, session_id: 'g2' }, { home });
+ expect([below.output.block, below.output.suggestions, below.output.block_reason, below.output.no_skill]).toEqual(['', [], 'weak_top_match', false]);
+ expect(below.pending!.delta.suggested).toEqual([]);
+ expect((await resolveSkills({ message: 'team status', top_gate: top - 0.01 }, { home })).output.suggestions[0]!.id).toBe('gbrain:reports');
+ expect((await resolveSkills({ message: 'team status', top_gate: 0 }, { home })).output.suggestions).toEqual((await resolveSkills({ message: 'team status' }, { home })).output.suggestions);
+ const named = await resolveSkills({ message: 'use the deploy skill', top_gate: 100 }, { home });
+ expect(named.output.suggestions[0]).toMatchObject({ id: 'gbrain:deploy', match_strength: 'named' });
+ });
+
+ 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(' ') }));
+ await jsonCatalog(home, 'small', BASIC);
+ await jsonCatalog(home, 'large', [...BASIC, ...pad(400)]);
+ const small = await resolveSkills({ message: 'team status' }, { home, catalogs: ['small'] });
+ const large = await resolveSkills({ message: 'team status' }, { home, catalogs: ['large'] });
+ const ratio = (r: typeof small, n: number) => r.output.suggestions[0]!.score / maxIdf(n);
+ expect(large.output.suggestions[0]!.score).toBeGreaterThan(small.output.suggestions[0]!.score * 2);
+ expect(Math.abs(ratio(large, BASIC.length + 400) - ratio(small, BASIC.length))).toBeLessThan(0.15 * ratio(small, BASIC.length));
+ });
+
test('previous_user_message is ranked only when the current message matches nothing', async () => {
const home = tmp();
await jsonCatalog(home, 'c', BASIC);
@@ -217,6 +244,7 @@ describe('turn rules', () => {
expect(r.output.suggestions.length).toBe(2);
expect(r.output.suggestions.map(s => s.id)).not.toContain('gbrain:meeting-notes');
for (const bad of [{}, { message: 1 }, { message: 'x', top_k: 9 }, { message: 'x', top_k: 0 }, { message: 'x', extra: 1 }, { message: 'x', exclude: new Array(EXCLUDE_MAX + 1).fill('a') }, { message: 'x', min_match_strength: 'weak' },
+ { message: 'x', top_gate: -1 }, { message: 'x', top_gate: 101 }, { message: 'x', top_gate: '1' }, { message: 'x', top_gate: Number.NaN },
{ message: 'x', session_id: 'has space' }, { message: 'x', session_id: 'é' }, { message: 'x', session_id: 'a'.repeat(257) }, { message: 'x', harness: 'vim' }, { message: 'x', expected_catalog_hash: 'abc' }]) {
expect(await codeOf(resolveSkills(bad as TurnInput, { home }))).toBe('skill_resolve_invalid_input');
}