Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
OpenClaw: never suggest a skill the agent's model cannot use
garrytand2b010b52dea
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 86da4d739c..75164a3097 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -24,6 +24,14 @@ identifiers and attribution are available in the pre-removal Git revision- Pinned skills for Hermes (`gbrain skills pin add <id> --catalog hermes-user`) go in a marked block in `$HERMES_HOME/SOUL.md` while the resolver is on. With no pins there is no block, and SOUL.md is never created.- `gbrain doctor`'s `skill_resolver` check now covers Hermes, and warns when Hermes's allowlist no longer approves the hook.+### The OpenClaw skill resolver no longer suggests skills the agent cannot use++**`gbrain setup openclaw --skill-loading resolve` now leaves out of each agent's suggestions the skills OpenClaw hides from that agent's model.** Before, the catalog came from the agent's skill folders alone, so a suggestion could name a skill that is not eligible on the host, that the agent's skill filter excludes, or that OpenClaw dropped at load, and the model could not open it.++- Setup reads `openclaw skills list --json --agent <id>` for each agent and adds every catalog skill it does not show the model (`modelVisible` false, or not listed) to that agent's `exclude_ids`. It names those skills, and tags the ones OpenClaw did not list with `skill_resolver_host_load_cut`.+- When the command fails, or lists none of the catalog's skills, nothing is filtered and setup says why. With no openclaw on PATH nothing changes.+- Run setup again after changing which skills an agent can use; the plugin reads the new list from its state file without a gateway reload.+## [0.60.699.0] - 2026-11-12### The Ubicloud gate VMs run a current gitdiff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.mdindex 8d6a62a3d7..9adf3a3bc2 100644--- a/docs/guides/error-codes.md+++ b/docs/guides/error-codes.md@@ -4786,7 +4786,7 @@ More: [docs/guides/skill-resolver.md#skill_resolver_config_unreadable](../../doc| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable ||---|---|---|---|---|---|---|-| OpenClaw lists fewer skills than the agent's skill directories hold, so some suggestions name skills OpenClaw dropped at load (skills.limits.maxCandidatesPerRoot) and skills_read cannot open them. | The request itself was wrong or no longer matches the brain; nothing was changed. | Raise skills.limits.maxCandidatesPerRoot in openclaw.json, or split the skill root. | agent | `repeat the read that failed` | 1 | no |+| OpenClaw does not list some skills in the agent's skill directories (dropped at load by skills.limits.maxCandidatesPerRoot), so setup leaves them out of the agent's suggestions. | The request itself was wrong or no longer matches the brain; nothing was changed. | Raise skills.limits.maxCandidatesPerRoot in openclaw.json, or split the skill root, then run setup again. | agent | `repeat the read that failed` | 1 | no |More: [docs/guides/skill-resolver.md#skill_resolver_host_load_cut](../../docs/guides/skill-resolver.md#skill_resolver_host_load_cut)diff --git a/docs/guides/skill-resolver.md b/docs/guides/skill-resolver.mdindex 08261c0fd7..328b0e062a 100644--- a/docs/guides/skill-resolver.md+++ b/docs/guides/skill-resolver.md@@ -198,6 +198,16 @@ gateway's Node process instead:loaded plugin exits 3 with `skill_resolver_plugin_not_installed` and thecommands still to run; it never reports a partial install as done.+Setup also asks OpenClaw which skills each agent's model can use+(`openclaw skills list --json --agent <id>`, its `modelVisible` field). A+skill in the agent's directories that OpenClaw hides from it (not eligible on+this host, outside the agent's skill filter, model invocation off) or does not+list at all (cut at load, see `skill_resolver_host_load_cut`) goes into that+agent's `exclude_ids` and is never suggested, and setup names it. If the+command fails, or lists none of the catalog's skills (usually a different+workspace), nothing is filtered and setup says so. Run setup again after you+change which skills an agent can use.+The plugin never adds to or edits OpenClaw's own skill list. On each real userturn (`before_prompt_build`; inter-session and other internal turns areskipped) it puts up to 3 suggestions with at least a description match in@@ -628,6 +638,8 @@ run. Run `gbrain setup openclaw --skill-loading resolve --agent <id>`.### skill_resolver_host_load_cut-OpenClaw lists fewer skills than the agent's skill directories hold (it caps-each root with `skills.limits.maxCandidatesPerRoot`), so a suggestion can name-a skill `skills_read` cannot open. Raise that limit or split the root.+OpenClaw does not list some of the skills in the agent's skill directories (it+caps each root with `skills.limits.maxCandidatesPerRoot`), so `skills_read`+could not open them. Setup leaves those skills out of the agent's suggestions+and names them. To get them back, raise that limit or split the root, then run+setup again.diff --git a/src/core/error-registry.ts b/src/core/error-registry.tsindex 5de3c80547..2717d14278 100644--- a/src/core/error-registry.ts+++ b/src/core/error-registry.ts@@ -765,7 +765,7 @@ export const CODES = {skill_resolver_worker_stuck: { class: 'retryable', summary: 'The OpenClaw skill-resolver worker missed the turn deadline three times in a row, so it was restarted with backoff.', docs: 'docs/guides/skill-resolver.md#skill_resolver_worker_stuck', suggestion: 'Check the deadline-miss rate with gbrain doctor --only skill_resolver; a loaded host misses more often.' },skill_resolver_worker_unavailable: { class: 'retryable', summary: 'The OpenClaw skill-resolver worker is restarting after a crash or a stall, so this turn proceeded without suggestions.', docs: 'docs/guides/skill-resolver.md#skill_resolver_worker_unavailable', suggestion: 'Nothing to do if it is rare; gbrain doctor --only skill_resolver shows the rate.' },skill_resolver_state_missing: { class: 'caller', summary: 'The OpenClaw skill-resolver state file has no entry for this agent, so the self-test had nothing to run.', docs: 'docs/guides/skill-resolver.md#skill_resolver_state_missing', suggestion: 'Run gbrain setup openclaw --skill-loading resolve --agent <id>.' },- skill_resolver_host_load_cut: { class: 'caller', summary: 'OpenClaw lists fewer skills than the agent\'s skill directories hold, so some suggestions name skills OpenClaw dropped at load (skills.limits.maxCandidatesPerRoot) and skills_read cannot open them.', docs: 'docs/guides/skill-resolver.md#skill_resolver_host_load_cut', suggestion: 'Raise skills.limits.maxCandidatesPerRoot in openclaw.json, or split the skill root.' },+ skill_resolver_host_load_cut: { class: 'caller', summary: 'OpenClaw does not list some skills in the agent\'s skill directories (dropped at load by skills.limits.maxCandidatesPerRoot), so setup leaves them out of the agent\'s suggestions.', docs: 'docs/guides/skill-resolver.md#skill_resolver_host_load_cut', suggestion: 'Raise skills.limits.maxCandidatesPerRoot in openclaw.json, or split the skill root, then run setup again.' },skill_resolver_internal: { class: 'server', summary: 'The skill resolver failed unexpectedly; a scrubbed trace (no turn text) was written under skill-index/logs/.', docs: 'docs/guides/skill-resolver.md#skill_resolver_internal', suggestion: 'Run gbrain skills index status and report the trace if it repeats.', fix: { argv: ['gbrain', 'skills', 'index', 'status', '--json'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Shows each catalog and its last build error; changes nothing.' } },skill_source_invalid: { class: 'caller', exit: 2, summary: 'The --from-json catalog or --routing file is not valid (not JSON, a malformed entry, over 10,000 skills or 8 MB, or a routing file over 1 MB), so nothing was built.', docs: 'docs/guides/skill-resolver.md#skill_source_invalid', suggestion: 'Pass a JSON array of {id, name, description, triggers?, routing?, body?, path?, eligible?} objects.' },skill_source_unreadable: { class: 'caller', summary: 'A --dir or --routing path (or, for `gbrain skills library`, gbrain\'s own source in a compiled binary) does not exist or cannot be read, so nothing was built.', docs: 'docs/guides/skill-resolver.md#skill_source_unreadable', suggestion: 'Pass an existing directory (or file) you can read; for the Node library from a compiled binary, download the release asset.' },diff --git a/src/core/setup/openclaw-skill-plugin.ts b/src/core/setup/openclaw-skill-plugin.tsindex da9b2088e1..94778d97c6 100644--- a/src/core/setup/openclaw-skill-plugin.ts+++ b/src/core/setup/openclaw-skill-plugin.ts@@ -16,6 +16,14 @@* the plugin's index.js;* - the plugin itself under <OpenClaw state dir>/gbrain/gbrain-skill-resolver.*+ * Each agent's catalog is checked against what OpenClaw shows that agent's+ * model (`openclaw skills list --json --agent <id>`, `modelVisible`): a+ * skill OpenClaw hides from it (ineligible on this host, left out by the+ * agent's skill filter, model invocation disabled, or cut at load) is added+ * to the agent's exclude_ids, so it is never suggested. With no openclaw on+ * PATH, or a list that names none of the catalog's skills, nothing is+ * filtered and the result says so.+ ** OpenClaw's CLI (install --link, enable, the conversation-access grant) runs* only when the plugin files changed or OpenClaw's config does not show the* plugin installed, enabled and allowed, so a mode flip, a pin change or a@@ -36,7 +44,7 @@ import { logsDir, skillIndexRoot } from '../skills/resolver/paths.ts';import { readDirSources } from '../skills/resolver/sources.ts';import { openclawConfigPath, openclawStateDir, parseJson5ish, resolveOpenclawWorkspace } from './brain-first.ts';import { openclawSkillLoaderJs, openclawSkillWorkerJs } from './openclaw-skill-plugin-code.ts';-import { pinnedBlockFor } from './skill-pins.ts';+import { catalogSkillIds, pinnedBlockFor } from './skill-pins.ts';import { readResolverConfig } from './skill-resolver-config.ts';import { laneTurnSettings } from '../skills/resolver/config.ts';@@ -193,16 +201,23 @@ function selfTest(node: string, dir: string, agentId: string, message: string, rreturn { ok: false, detail: `the plugin's self-test under ${node} failed (${doc.code ?? lastLine(r.output)})` };}-function hostCount(run: Run, bin: string, agentId: string): number | null {+/** What `openclaw skills list --json --agent <id>` lists for one agent, and which of those its model can use (modelVisible; else eligible and not hidden); null when the call or its JSON fails. */+function hostSkills(run: Run, bin: string, agentId: string): { listed: Set<string>; visible: Set<string> } | null {const r = run([bin, 'skills', 'list', '--json', '--agent', agentId]);if (!r.ok) return null;try {- const j = JSON.parse(r.output) as unknown;- const list = Array.isArray(j) ? j : Array.isArray((j as { skills?: unknown })?.skills) ? (j as { skills: unknown[] }).skills : null;- return list ? list.length : null;+ const j = JSON.parse(r.output.slice(r.output.indexOf('{'))) as unknown;+ const list = Array.isArray((j as { skills?: unknown })?.skills) ? (j as { skills: Array<Record<string, unknown>> }).skills : null;+ if (!list) return null;+ const named = list.filter((e) => e && typeof e.name === 'string');+ const shows = (e: Record<string, unknown>) => (typeof e.modelVisible === 'boolean' ? e.modelVisible+ : e.eligible === true && e.disabled !== true && e.blockedByAgentFilter !== true && e.blockedByAllowlist !== true);+ return { listed: new Set(named.map((e) => e.name as string)), visible: new Set(named.filter(shows).map((e) => e.name as string)) };} catch { return null; }}+const someNames = (ids: string[]) => `${ids.slice(0, 10).join(', ')}${ids.length > 10 ? ` and ${ids.length - 10} more` : ''}`;+export interface OpenclawSkillSyncOptions {mode: 'live' | 'shadow' | null;agents: string[] | 'all' | null;@@ -270,14 +285,24 @@ export async function syncOpenclawSkillPlugin(opts: OpenclawSkillSyncOptions): P}if (skills < 1) { out.notes.push(`agent ${id}: no model-invocable skill in ${dirs.join(', ')}, so it was skipped`); continue; }out.steps.push({ step: 'catalog', action: fresh ? 'keep' : 'write', detail: `${catalog}: ${skills} skills from ${dirs.join(', ')}` });+ const host = bin ? hostSkills(run, bin, id) : null;+ const catalogIds = dryRun && !fresh ? readDirSources(dirs).skills.map((s) => s.id) : [...(catalogSkillIds(home, catalog) ?? [])];+ let hidden: string[] = [];+ if (bin && !host) out.notes.push(`agent ${id}: \`openclaw skills list --json --agent ${id}\` failed, so skills OpenClaw hides from this agent were not filtered out of ${catalog}`);+ else if (host && !catalogIds.some((n) => host.listed.has(n))) out.notes.push(`agent ${id}: OpenClaw lists none of ${catalog}'s skills for this agent, so the catalog was not filtered (check that the agent's workspace is ${dirs[0]})`);+ else if (host) hidden = catalogIds.filter((n) => !host.visible.has(n));+ const cut = host ? hidden.filter((n) => !host.listed.has(n)) : [];+ const shut = hidden.filter((n) => !cut.includes(n));+ if (shut.length) out.notes.push(`agent ${id}: ${shut.length} skill(s) OpenClaw hides from this agent's model (ineligible on this host, outside its skill filter, or model invocation off) are never suggested: ${someNames(shut)}`);+ if (cut.length) out.notes.push(`agent ${id}: OpenClaw does not list ${cut.length} of ${catalog}'s skills (dropped at load by skills.limits.maxCandidatesPerRoot, or not in its skill roots), so they are never suggested: ${someNames(cut)} (skill_resolver_host_load_cut)`);const pins = dryRun ? { block: '', ids: [], unknown: [] as string[] } : pinnedBlockFor(home, catalog, 'openclaw');agents[id] = {mode: opts.mode ?? before?.mode ?? 'live', catalog, skill_dirs: dirs,- top_k: lane.top_k, min_match: lane.min_match, exclude_ids: lane.exclude_ids,+ top_k: lane.top_k, min_match: lane.min_match, exclude_ids: [...new Set([...lane.exclude_ids, ...hidden])],live_fraction: tune.live_fraction ?? before?.live_fraction ?? 1, pins_route: tune.pins_route ?? before?.pins_route ?? 'system',pinned_block: pins.block, pinned_ids: pins.ids, owner_sender_ids: tune.owner_sender_ids ?? before?.owner_sender_ids ?? [],};- out.agents.push({ id, mode: agents[id]!.mode, catalog, skills, pins: pins.ids.length, unknown_pins: pins.unknown });+ out.agents.push({ id, mode: agents[id]!.mode, catalog, skills: skills - hidden.length, pins: pins.ids.length, unknown_pins: pins.unknown });if (pins.unknown.length) out.notes.push(`agent ${id}: pinned skill(s) not in ${catalog}, left out of the block: ${pins.unknown.join(', ')} (skill_resolver_pin_unknown)`);}if (out.agents.length === 0) return fail({ code: 'skill_resolver_setup_incomplete', message: `The skill resolver was not turned on for any agent: ${out.notes.join('; ')}. Nothing was written.` });@@ -332,12 +357,6 @@ export async function syncOpenclawSkillPlugin(opts: OpenclawSkillSyncOptions): Pif (!loaded) return fail({ code: 'skill_resolver_plugin_not_installed', message: `\`openclaw plugins inspect ${OPENCLAW_SKILL_PLUGIN_ID} --runtime --json\` does not show the plugin loaded with before_prompt_build (${lastLine(inspect.output)}).`, commands: [shown([bin, 'plugins', 'inspect', OPENCLAW_SKILL_PLUGIN_ID, '--runtime', '--json'])], argv: [bin, 'plugins', 'inspect', OPENCLAW_SKILL_PLUGIN_ID, '--runtime', '--json'], recovery: `partial: files written, ${commands.length} of ${commands.length} commands ran, but OpenClaw does not load the plugin; check the inspect output, then gbrain doctor --only skill_resolver` });out.steps.push({ step: 'verify', action: 'run', detail: 'openclaw loads it with before_prompt_build' });}- if (bin) {- for (const a of out.agents) {- const n = hostCount(run, bin, a.id);- if (n !== null && n < a.skills) out.notes.push(`agent ${a.id}: OpenClaw lists ${n} skills but ${a.catalog} holds ${a.skills}; OpenClaw dropped some at load (skills.limits.maxCandidatesPerRoot), and skills_read cannot open those (skill_resolver_host_load_cut)`);- }- }const node = deps.nodeBin !== undefined ? deps.nodeBin : which('node');if (!node) out.notes.push('no node on PATH, so the plugin self-test did not run; the gateway runs it under its own Node');else {diff --git a/test/openclaw-skill-plugin.test.ts b/test/openclaw-skill-plugin.test.tsindex 8a4469d7e8..ed654af29d 100644--- a/test/openclaw-skill-plugin.test.ts+++ b/test/openclaw-skill-plugin.test.ts@@ -12,6 +12,9 @@* on live turns, nothing on shadow, internal or off turns, commits a retried* turn once, refuses a library writable by others, gives up on a stuck worker* within the deadline and logs each miss; a brainless home stays brainless.+ * PR 2: a skill OpenClaw hides from the agent's model, or does not list, is+ * excluded and never suggested; a failed list or one naming none of the+ * catalog filters nothing.*/import { afterAll, describe, expect, setDefaultTimeout, test } from 'bun:test';import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';@@ -45,7 +48,7 @@ case "$1 $2" in"config set") node -e 'const f=require("fs"),p=process.argv[1],c=JSON.parse(f.readFileSync(p,"utf8"));const id=process.argv[2].split(".")[2];c.plugins.entries[id].hooks={allowConversationAccess:true};f.writeFileSync(p,JSON.stringify(c))' "$cfg" "$3";;"plugins inspect") [ -n "$INSPECT_BROKEN" ] && { echo '{"status":"error"}'; exit 0; }; echo '{"status":"loaded","hooks":["before_prompt_build"]}';;"plugins uninstall") ;;- "skills list") echo '[]' > /dev/null; exit 1;;+ "skills list") [ -n "$SKILLS_LIST_JSON" ] && { echo "[plugins] loaded"; cat "$SKILLS_LIST_JSON"; exit 0; }; exit 1;;esac`;@@ -211,6 +214,51 @@ describe.skipIf(!NODE)('gbrain setup openclaw --skill-loading', () => {});});+describe.skipIf(!NODE)('the OpenClaw eligibility filter', () => {+ const listed = (b: Box, skills: object[]) => { const f = join(b.root, 'skills-list.json'); writeFileSync(f, JSON.stringify({ workspaceDir: join(b.state, 'workspace'), skills })); return { SKILLS_LIST_JSON: f }; };++ test('a skill OpenClaw hides from the agent, or does not list, goes into exclude_ids and is never suggested', async () => {+ const b = box();+ const env = listed(b, [+ { name: 'deploy-service', eligible: true, disabled: false, blockedByAgentFilter: false },+ { name: 'email-triage', eligible: true, disabled: false, blockedByAgentFilter: true, modelVisible: false },+ { name: 'weather', eligible: false, modelVisible: false },+ ]);+ const r = await setup(b, ['--skill-loading', 'resolve'], env);+ expect(r.exitCode).toBe(0);+ expect([...readState(b).agents.main.exclude_ids].sort()).toEqual(['calendar-sync', 'email-triage']);+ expect(r.resolver.agents[0]).toMatchObject({ id: 'main', skills: 1 });+ const notes = r.resolver.notes.join('\n');+ expect(notes).toContain('hides from this agent' + "'" + 's model');+ expect(notes).toContain('email-triage');+ expect(notes).toMatch(/does not list 1 of openclaw-main's skills.*calendar-sync.*skill_resolver_host_load_cut/);+ const out = drive(b, [['turn', { text: 'deploy the service to production, triage the email inbox and sync the calendar', id: 'm1' }]]);+ expect(out[0].appendContext).toContain('deploy-service');+ expect(out[0].appendContext).not.toContain('email-triage');+ expect(out[0].appendContext).not.toContain('calendar-sync');+ });++ test('a list naming none of the catalog' + "'" + 's skills filters nothing and says so', async () => {+ const b = box();+ const r = await setup(b, ['--skill-loading', 'resolve'], listed(b, [{ name: 'weather', eligible: true, modelVisible: true }]));+ expect(r.exitCode).toBe(0);+ expect(readState(b).agents.main.exclude_ids).toEqual([]);+ expect(r.resolver.agents[0].skills).toBe(3);+ expect(r.resolver.notes.join('\n')).toContain('lists none of openclaw-main' + "'" + 's skills for this agent, so the catalog was not filtered');+ });++ test('a failed list, or no openclaw on PATH, filters nothing', async () => {+ const b = box();+ const r = await setup(b, ['--skill-loading', 'resolve']);+ expect(r.exitCode).toBe(0);+ expect(readState(b).agents.main.exclude_ids).toEqual([]);+ expect(r.resolver.notes.join('\n')).toContain('--agent main' + String.fromCharCode(96) + ' failed, so skills OpenClaw hides from this agent were not filtered');+ const none = box({ openclaw: false });+ expect((await setup(none, ['--skill-loading', 'resolve'])).exitCode).toBe(3);+ expect(readState(none).agents.main.exclude_ids).toEqual([]);+ });+});+describe.skipIf(!NODE)('gbrain skills pin', () => {test('validates against the catalog, updates the plugin state hot, and survives --skill-loading off', async () => {const b = box();