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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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: 'uexport 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: booleantry {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.tsindex 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: striconst 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: striconst 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.tsindex 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.tsindex 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.tsindex 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): booleareturn 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.tsindex 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, validateSessionTokenBudgetimport { 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, 'messif (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, 'messreset_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.tsindex 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.tsindex 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.tsindex 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.tsindex 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');}