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.mdindex 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.mdindex 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.mdindex 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 thedefaults (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 skillsPins 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.```bashgbrain 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.tsindex 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.tsindex 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, resolveOpenclawWorimport { 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): Pif (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): Pconst 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.tsindex 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);});