Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

OpenClaw skill plugin: read lane settings through core, honor skills.resolver.pinned, use the library's native floor

garrytanf9a0286d8573
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 610be42644..974376e9af 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,7 +16,7 @@ identifiers and attribution are available in the pre-removal Git revision
### OpenClaw skill resolver (off by default)
-- `gbrain setup openclaw --skill-loading resolve|shadow|off`: a separate OpenClaw plugin, `gbrain-skill-resolver`, that puts up to 3 relevant skills in front of the model on each real user turn, ranked inside the gateway's Node process in a worker thread with a 50 ms deadline, so a busy gateway never waits on gbrain. It leaves OpenClaw's own skill list alone. `shadow` ranks and logs what it would have suggested without injecting anything; `--live-fraction`, `--pins-route` and `--owner-sender` stage a rollout. Switching modes or pins rewrites only gbrain's state file, so no OpenClaw command runs and the gateway does not reload. A partial install is never reported as done: it exits 3 with `skill_resolver_plugin_not_installed` and the commands still to run. Off by default.
+- `gbrain setup openclaw --skill-loading resolve|shadow|off`: a separate OpenClaw plugin, `gbrain-skill-resolver`, that puts up to 3 relevant skills in front of the model on each real user turn, ranked inside the gateway's Node process in a worker thread with a 50 ms deadline, so a busy gateway never waits on gbrain. It leaves OpenClaw's own skill list alone. `shadow` ranks and logs what it would have suggested without injecting anything; `--live-fraction`, `--pins-route` and `--owner-sender` stage a rollout. Switching modes or pins rewrites only gbrain's state file, so no OpenClaw command runs and the gateway does not reload. It reads `top_k`, `min_match` and `pinned` from `skills.resolver` the way the other lanes do. A partial install is never reported as done: it exits 3 with `skill_resolver_plugin_not_installed` and the commands still to run. Off by default.
- `gbrain skills pin add|remove|list --catalog <c>`: operator-chosen always-on skills, shown as a pinned block and never suggested twice. gbrain ships none; pins must name a skill in the catalog.
- `gbrain doctor --only skill_resolver` reports the OpenClaw plugin, its library, each agent's catalog and pins, and over the last 24 hours the outcomes, how often a suggested skill was opened and the deadline-miss rate; it warns when more than 5% of at least 20 turns missed the deadline.
diff --git a/docs/architecture/key-files/skills.md b/docs/architecture/key-files/skills.md
index d0390515a1..674d4ac882 100644
--- a/docs/architecture/key-files/skills.md
+++ b/docs/architecture/key-files/skills.md
@@ -64,7 +64,7 @@ Contract schemas: `docs/schemas/skill-resolver.v1.*.json`. Every module under
- `src/core/skill-description.ts` — `oneLineDescription` (frontmatter description, block scalars folded, else the first body paragraph), shared by `skill-catalog.ts`, `bundled.ts` and the bundled source.
- `src/core/skills/resolver/hook-lane.ts` + `hook-worker.ts` — the hook lane (`GBRAIN_HOOK_LANE=skill-resolver`, dispatched first in `src/commands/hook.ts` after the `GBRAIN_HOOKS=0` check): async config/stdin/carrier reads on the main thread, ranking in a worker (source: `hook-worker.ts` beside it; compiled binary: the second build entrypoint at `WORKER_SRC_PATH`, so every `bun build --compile` that ships a binary lists it), a 50 ms deadline that exits the process with no output and no commit, the commit (`commitSessionAsync`) on the main thread after delivery, the payload budget (`skills.resolver.lane_payload_chars`, dropped whole as `payload_dropped`), the one-owner rule (first carrier entry whose home has the lane on), the SessionStart compaction reset, the Claude Code project catalog (`claude-code-project-<root hash>`, built by a detached `skills index build`, stamp-limited to once a minute) and the daily lane log (`daily-log.ts`: `skill-index/logs/lane-<date>.jsonl`, kept 14 days). Test seams: `GBRAIN_TEST_SKILL_LANE_STALL`, `GBRAIN_TEST_SKILL_LANE_DEADLINE_MS`. Pinned by `test/skill-resolver-hook-lane.test.ts`.
- `src/core/setup/skill-resolver-{lane,hook,config,setup}.ts` — `setup <claude-code|codex> --skill-loading resolve|off` and `--remove`: the lane identity leaf (marker `skill-resolver-v1`, which every other lane's ownership and yield test excludes), the Claude Code entries and the Codex group plus its `config.toml` trust, the file-plane keys (`skills.resolver.*`, engine-free in `gbrain config`; an unreadable file is never rewritten), and the build-then-write order (≥1 skill or `skill_resolver_setup_incomplete`). Pinned by `test/setup-skill-resolver.test.ts`.
-- `src/core/setup/openclaw-skill-plugin.ts` + `openclaw-skill-plugin-code.ts` — `setup openclaw --skill-loading resolve|shadow|off`: the separate `gbrain-skill-resolver` OpenClaw plugin. Builds one `openclaw-<agent>` catalog per agent, writes the content-addressed library (`~/.gbrain/lib/<sha256>.mjs`), the 0600 state file `openclaw-skill-resolver.json` (per agent: mode, catalog, top_k 3, floor `description`, live_fraction, pins route, pinned block, owner senders; `skills.resolver.per_harness.openclaw` then the global keys), the generated loader and worker (Node worker thread, 50 ms deadline, resolve then commit/discard, library uid/mode/sha checks, stuck-worker restart, daily `skill-index/logs/openclaw-<date>.jsonl`), and runs the openclaw CLI only to install, enable, allow and inspect; a mode or pin change rewrites only the state. A partial install is `skill_resolver_plugin_not_installed` (exit 3). Pinned by `test/openclaw-skill-plugin.test.ts`.
+- `src/core/setup/openclaw-skill-plugin.ts` + `openclaw-skill-plugin-code.ts` — `setup openclaw --skill-loading resolve|shadow|off`: the separate `gbrain-skill-resolver` OpenClaw plugin. Builds one `openclaw-<agent>` catalog per agent, writes the content-addressed library (`~/.gbrain/lib/<sha256>.mjs`), the 0600 state file `openclaw-skill-resolver.json` (per agent: mode, catalog, top_k 3, floor `description`, live_fraction, pins route, pinned block, the `skills.resolver.pinned` exclude list, owner senders; read through core's `laneTurnSettings`), the generated loader and worker (Node worker thread, 50 ms deadline, resolve then commit/discard, library uid/mode/sha checks, stuck-worker restart, daily `skill-index/logs/openclaw-<date>.jsonl`), and runs the openclaw CLI only to install, enable, allow and inspect; a mode or pin change rewrites only the state. A partial install is `skill_resolver_plugin_not_installed` (exit 3). Pinned by `test/openclaw-skill-plugin.test.ts`.
- `src/core/setup/skill-pins.ts` — operator pins (`skills.resolver.pins.<catalog>` in config.json, 64 per catalog, 100-character lines, 600-token block, unknown names left out); `gbrain skills pin add|remove|list` in `src/commands/skill-resolver.ts`.
- `src/commands/doctor/checks/skill-resolver-openclaw.ts` — the OpenClaw part of doctor `skill_resolver`: plugin registration, library hash, per-agent catalog freshness and pins, and 24 hours of plugin logs (outcomes, error codes, reads of suggested skills, the deadline-miss rate; warns above 5% over at least 20 turns).
- `src/commands/doctor/checks/skill-resolver.ts` — doctor `skill_resolver` (emitted by the `harness_wiring` entry, whose details carry the same view): hook state, each catalog's content-tier freshness, recent lane outcomes and error codes; silent when nothing of the resolver exists.
diff --git a/docs/guides/skill-resolver.md b/docs/guides/skill-resolver.md
index f4785bcaf3..4f21883df0 100644
--- a/docs/guides/skill-resolver.md
+++ b/docs/guides/skill-resolver.md
@@ -173,7 +173,11 @@ on its next turn, so no OpenClaw command runs and the gateway does not reload:
`skills.resolver.per_harness.openclaw.{top_k,min_match}` overrides the
defaults (3 and `description`); the global `skills.resolver.top_k` and
-`min_match` apply when it is unset.
+`min_match` apply when it is unset, and `skills.resolver.pinned` lists skills
+OpenClaw already loads, which are never suggested. The plugin reads these the
+way every lane does, so a bad value makes setup refuse with
+`skill_resolver_config_invalid` and write nothing; a change takes effect at
+the next `gbrain setup openclaw`.
Each turn appends one line (agent, outcome, duration, error code, arm,
suggested ids; never turn text) to
@@ -188,7 +192,9 @@ is under that on the real host.
## Pinned skills
Pins are the operator's always-on skills for one catalog. gbrain ships none,
-and a catalog with no pins gets no pinned block.
+and a catalog with no pins gets no pinned block. They differ from
+`skills.resolver.pinned`: a pin is shown by gbrain on every turn, while a
+`pinned` skill is one the harness already shows, so gbrain only leaves it out.
```bash
gbrain skills pin add deploy-example --catalog openclaw-main --line "Before any production deploy"
diff --git a/src/core/setup/openclaw-skill-plugin-code.ts b/src/core/setup/openclaw-skill-plugin-code.ts
index 178408d65d..d43631ff99 100644
--- a/src/core/setup/openclaw-skill-plugin-code.ts
+++ b/src/core/setup/openclaw-skill-plugin-code.ts
@@ -52,8 +52,6 @@ function rebuild(lib, catalog, dirs) {
.finally(() => { building = null; });
}
-const STRENGTHS = ['named', 'name', 'triggers', 'routing', 'description', 'body'];
-
parentPort.on('message', async (m) => {
const loaded = await ready;
if (m.type === 'warm') { parentPort.postMessage({ type: 'warm', version: loaded.lib ? loaded.lib.GBRAIN_VERSION : null, code: loaded.code || null }); return; }
@@ -70,25 +68,11 @@ parentPort.on('message', async (m) => {
const lib = loaded.lib;
const now = Date.now();
for (const [id, p] of pending) if (now - p.at > 30_000) pending.delete(id);
- const input = { ...m.input };
- const features = Array.isArray(lib.RESOLVER_FEATURES) ? lib.RESOLVER_FEATURES : [];
- const nativeFloor = !!m.floor && features.includes('min_match_strength');
- if (nativeFloor) input.min_match_strength = m.floor;
- const floorRank = STRENGTHS.indexOf(m.floor);
- const weak = (o) => nativeFloor || floorRank < 0 ? [] : o.suggestions.filter((s) => !(STRENGTHS.indexOf(s.match_strength) >= 0 && STRENGTHS.indexOf(s.match_strength) <= floorRank));
+ const input = m.floor ? { ...m.input, min_match_strength: m.floor } : m.input;
try {
const opts = { home, catalogs: [m.catalog], failOpen: true, deadlineMs: m.deadlineMs, env: {} };
- let r = await lib.resolveSkills(input, opts);
- let out = input.shadow ? (r.shadowOutput || r.output) : r.output;
- const below = weak(out);
- if (below.length) {
- const left = m.deadlineMs - (Date.now() - now);
- const retry = below.length < out.suggestions.length && left > 5
- ? await lib.resolveSkills({ ...input, exclude: [...(input.exclude || []), ...below.map((s) => s.id)].slice(0, 64) }, { ...opts, deadlineMs: left }) : null;
- const retryOut = retry ? (input.shadow ? (retry.shadowOutput || retry.output) : retry.output) : null;
- if (retryOut && retryOut.suggestions.length && !weak(retryOut).length) { r = retry; out = retryOut; }
- else { parentPort.postMessage({ id: m.id, block: '', names: [], strengths: [], no_skill_reason: 'below_floor', deduped: 0, code: null, version: out.gbrain_version }); return; }
- }
+ const r = await lib.resolveSkills(input, opts);
+ const out = input.shadow ? (r.shadowOutput || r.output) : r.output;
if (r.pending) pending.set(m.id, { key: r.pending.key, delta: r.pending.delta, at: now });
const code = out.error ? out.error.code : null;
parentPort.postMessage({ id: m.id, block: out.block, names: out.suggestions.map((s) => s.name), strengths: out.suggestions.map((s) => s.match_strength),
@@ -322,7 +306,7 @@ async function resolveTurn(event, ctx, opts) {
const w = ensureWorker(s);
if (!w) return finish({ outcome: 'error', code: 'skill_resolver_worker_unavailable' });
const reset = resetNext.delete(sessionKey);
- const input = { message: text, session_id: sessionKey, harness: 'openclaw', top_k: Number.isInteger(a.top_k) ? a.top_k : 3, exclude: Array.isArray(a.pinned_ids) ? a.pinned_ids.slice(0, 64) : [], shadow: arm !== 'live', ...(reset ? { reset_session: true } : {}) };
+ const input = { message: text, session_id: sessionKey, harness: 'openclaw', top_k: Number.isInteger(a.top_k) ? a.top_k : 3, exclude: [...(Array.isArray(a.pinned_ids) ? a.pinned_ids : []), ...(Array.isArray(a.exclude_ids) ? a.exclude_ids : [])].slice(0, 1024), shadow: arm !== 'live', ...(reset ? { reset_session: true } : {}) };
const reply = await ask(w, { type: 'resolve', input, catalog: a.catalog, deadlineMs: DEADLINE_MS - 5, floor: a.min_match || null, dirs: a.skill_dirs || [] });
if (reply.late) {
if (reset) resetNext.add(sessionKey);
diff --git a/src/core/setup/openclaw-skill-plugin.ts b/src/core/setup/openclaw-skill-plugin.ts
index 03b131c481..da9b2088e1 100644
--- a/src/core/setup/openclaw-skill-plugin.ts
+++ b/src/core/setup/openclaw-skill-plugin.ts
@@ -38,6 +38,7 @@ import { openclawConfigPath, openclawStateDir, parseJson5ish, resolveOpenclawWor
import { openclawSkillLoaderJs, openclawSkillWorkerJs } from './openclaw-skill-plugin-code.ts';
import { pinnedBlockFor } from './skill-pins.ts';
import { readResolverConfig } from './skill-resolver-config.ts';
+import { laneTurnSettings } from '../skills/resolver/config.ts';
export const OPENCLAW_SKILL_PLUGIN_ID = 'gbrain-skill-resolver';
export const OPENCLAW_SKILL_STATE_FILE = 'openclaw-skill-resolver.json';
@@ -50,7 +51,9 @@ export interface OpenclawSkillAgentState {
catalog: string;
skill_dirs: string[];
top_k: number;
- min_match: string | null;
+ min_match: string;
+ /** skills.resolver.pinned: skills OpenClaw loads itself, so they are never suggested. */
+ exclude_ids: string[];
live_fraction: number;
pins_route: 'system' | 'first_turn';
pinned_block: string;
@@ -60,7 +63,7 @@ export interface OpenclawSkillAgentState {
export interface OpenclawSkillState { v: 1; gbrain_version: string; library_sha256: string; agents: Record<string, OpenclawSkillAgentState> }
export interface OpenclawSkillStep { step: 'library' | 'catalog' | 'state' | 'plugin' | 'install' | 'verify' | 'self-test'; action: 'write' | 'keep' | 'remove' | 'skip' | 'run'; detail: string }
-export interface OpenclawSkillError { code: 'skill_resolver_plugin_not_installed' | 'skill_resolver_setup_incomplete' | 'skill_resolver_host_not_local' | 'skill_resolver_selftest_failed' | 'skill_source_unreadable'; message: string; commands?: string[]; argv?: string[]; recovery?: string }
+export interface OpenclawSkillError { code: 'skill_resolver_plugin_not_installed' | 'skill_resolver_setup_incomplete' | 'skill_resolver_host_not_local' | 'skill_resolver_selftest_failed' | 'skill_source_unreadable' | 'skill_resolver_config_invalid'; message: string; commands?: string[]; argv?: string[]; recovery?: string }
export interface OpenclawSkillResult {
mode: OpenclawSkillMode;
steps: OpenclawSkillStep[];
@@ -214,17 +217,12 @@ export interface OpenclawSkillSyncOptions {
deps?: OpenclawSkillDeps;
}
-/** skills.resolver.per_harness.openclaw.{top_k,min_match} from config.json, else the global keys, else the OpenClaw defaults. */
-function openclawLaneConfig(home: string): { top_k: number; min_match: string | null } {
+/** The lane's own turn settings for openclaw (per_harness, then the global keys), else the OpenClaw defaults. Throws skill_resolver_config_invalid on a bad value, as every lane does. */
+function openclawLaneConfig(home: string): { top_k: number; min_match: string; exclude_ids: string[] } {
const read = readResolverConfig(home);
- const r = read.state === 'ok' ? (read.doc.skills as { resolver?: Record<string, unknown> } | undefined)?.resolver ?? {} : {};
- const per = ((r.per_harness as Record<string, unknown> | undefined)?.openclaw ?? {}) as Record<string, unknown>;
- const k = per.top_k ?? r.top_k;
- const m = per.min_match ?? r.min_match;
- return {
- top_k: Number.isInteger(k) && (k as number) >= 1 && (k as number) <= 8 ? k as number : OPENCLAW_TOP_K_DEFAULT,
- min_match: m === 'none' ? null : typeof m === 'string' && ['named', 'name', 'triggers', 'routing', 'description', 'body'].includes(m) ? m : OPENCLAW_FLOOR_DEFAULT,
- };
+ const section = read.state === 'ok' ? (read.doc.skills as { resolver?: Record<string, unknown> } | undefined)?.resolver ?? {} : {};
+ const s = laneTurnSettings(section, 'openclaw');
+ return { top_k: s.top_k ?? OPENCLAW_TOP_K_DEFAULT, min_match: s.min_match_strength ?? OPENCLAW_FLOOR_DEFAULT, exclude_ids: s.exclude ?? [] };
}
/** Turn the plugin on (live or shadow) for some agents, or refresh what is on. Never throws for an expected failure. */
@@ -248,7 +246,11 @@ export async function syncOpenclawSkillPlugin(opts: OpenclawSkillSyncOptions): P
if (ids.length === 0) return { ...out, notes: ['No agent has the skill resolver on; nothing to refresh.'] };
const agents: Record<string, OpenclawSkillAgentState> = { ...(prior?.agents ?? {}) };
- const lane = openclawLaneConfig(home);
+ let lane: ReturnType<typeof openclawLaneConfig>;
+ try { lane = openclawLaneConfig(home); } catch (e) {
+ if (e instanceof ResolverError && e.code === 'skill_resolver_config_invalid') return fail({ code: 'skill_resolver_config_invalid', message: `${e.message} Nothing was written.` });
+ throw e;
+ }
const tune = opts.tuning ?? {};
for (const id of ids) {
const before = prior?.agents[id];
@@ -271,7 +273,7 @@ export async function syncOpenclawSkillPlugin(opts: OpenclawSkillSyncOptions): P
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,
+ top_k: lane.top_k, min_match: lane.min_match, exclude_ids: lane.exclude_ids,
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 ?? [],
};
diff --git a/test/openclaw-skill-plugin.test.ts b/test/openclaw-skill-plugin.test.ts
index 79aef00d6d..55a38a1845 100644
--- a/test/openclaw-skill-plugin.test.ts
+++ b/test/openclaw-skill-plugin.test.ts
@@ -173,6 +173,26 @@ describe.skipIf(!NODE)('gbrain setup openclaw --skill-loading', () => {
expect(r.resolver.error.code).toBe('skill_resolver_plugin_not_installed');
});
+ test('lane settings come from core: a min_match only the plugin accepted refuses setup, and skills.resolver.pinned is never suggested', async () => {
+ const bad = box();
+ mkdirSync(gbrainHome(bad), { recursive: true });
+ writeFileSync(join(gbrainHome(bad), 'config.json'), JSON.stringify({ skills: { resolver: { per_harness: { openclaw: { min_match: 'none' } } } } }));
+ const refused = await setup(bad, ['--skill-loading', 'resolve']);
+ expect(refused.resolver.error.code).toBe('skill_resolver_config_invalid');
+ expect(refused.exitCode).not.toBe(0);
+ expect(existsSync(statePath(bad))).toBe(false);
+ expect(calls(bad)).toEqual([]);
+
+ const b = box();
+ mkdirSync(gbrainHome(b), { recursive: true });
+ writeFileSync(join(gbrainHome(b), 'config.json'), JSON.stringify({ skills: { resolver: { pinned: ['email-triage'], per_harness: { openclaw: { top_k: 2 } } } } }));
+ expect((await setup(b, ['--skill-loading', 'resolve'])).exitCode).toBe(0);
+ expect(readState(b).agents.main).toMatchObject({ top_k: 2, min_match: 'description', exclude_ids: ['email-triage'] });
+ const out = drive(b, [['turn', { text: 'deploy the service to production and triage the email inbox', id: 'm1' }]]);
+ expect(out[0].appendContext).toContain('deploy-service');
+ expect(out[0].appendContext).not.toContain('email-triage');
+ });
+
test('--dry-run writes nothing', async () => {
const b = box();
const r = await setup(b, ['--skill-loading', 'resolve', '--dry-run']);
@@ -262,7 +282,7 @@ describe.skipIf(!NODE)('the gbrain-skill-resolver plugin under Node', () => {
expect(sessions.length).toBeGreaterThan(0);
});
- test('the description floor holds on a library without native floor support: body-only matches are never suggested', async () => {
+ test('the description floor holds: body-only matches are never suggested', async () => {
const b = box();
const skills = join(b.state, 'workspace', 'skills');
mkdirSync(join(skills, 'zeta-notes'), { recursive: true });
@@ -276,7 +296,7 @@ describe.skipIf(!NODE)('the gbrain-skill-resolver plugin under Node', () => {
expect(out[1].appendContext).toContain('email-triage');
expect(out[1].appendContext).not.toContain('zeta-notes');
const lines = logLines(b).filter((l) => l.agent === 'main');
- expect(lines[0]).toMatchObject({ outcome: 'below_floor', suggested: [] });
+ expect(lines[0]).toMatchObject({ outcome: 'no_match', suggested: [] });
expect(lines[1].strengths.every((s: string) => ['named', 'name', 'triggers', 'routing', 'description'].includes(s))).toBe(true);
});