Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

skills: doctor reads past the spring-loaded index (resolver_health, skill_currency)

garrytana2e0e07d2842
diff --git a/scripts/structural-suites.tsv b/scripts/structural-suites.tsv
index 97501f50bf..e9c70534ed 100644
--- a/scripts/structural-suites.tsv
+++ b/scripts/structural-suites.tsv
@@ -387,7 +387,7 @@ test/snapshot-shape-guard.test.ts (file-level) 10 readFileSync
test/sources-webhook.test.ts Webhook sync job extraction contract 1 source-surface-helper
test/spec-drain-lease-constants.test.ts the TLA+ workflow runs when anything a mutant names changes 1 readFileSync
test/spend-off-switch.test.ts reindex / onboard off-switch dispatch (regression guards) 3 bun-file
-test/spring-skill-index.test.ts spring-loaded skill index 9 readFileSync
+test/spring-skill-index.test.ts spring-loaded skill index 10 readFileSync
test/strict-source-unmanaged-import.test.ts (file-level) 2 readFileSync
test/supervisor.test.ts recovery hook timeout bound (structural) 1 source-surface-helper
test/sync-failures.test.ts #4543 blocked output names failing files 4 doctor-source-helper,source-surface-helper
diff --git a/src/commands/doctor/skill-checks.ts b/src/commands/doctor/skill-checks.ts
index 1113a4554f..6bf7b0a85a 100644
--- a/src/commands/doctor/skill-checks.ts
+++ b/src/commands/doctor/skill-checks.ts
@@ -16,6 +16,8 @@ import {
import { loadOrDeriveManifest } from '../../core/skill-manifest.ts';
import { computeSkillCurrency } from '../../core/skillpack/skill-currency.ts';
import { findGbrainRoot } from '../../core/skillpack/bundle.ts';
+import { findAllResolverFiles } from '../../core/resolver-filenames.ts';
+import { skillsIndexedIn } from '../../core/skills/index-block.ts';
import { checkPreconditions, type PreconditionContext } from '../../core/skillpack/preconditions.ts';
import { parseSkillFrontmatter } from '../../core/skill-frontmatter.ts';
import {
@@ -160,20 +162,25 @@ export function skillCurrencyCheck(skillsDir: string): Check {
const msg = err instanceof Error ? err.message : String(err);
return { name, status: 'ok', message: `skill currency check skipped (${msg})` };
}
- const { counts, skills } = report;
+ const { counts } = report;
+ const indexed = new Set(findAllResolverFiles(targetWorkspace).flatMap(p => skillsIndexedIn(readFileSync(p, 'utf-8'))));
+ const skills = report.skills.filter(k => k.status !== 'new' || !indexed.has(k.slug));
+ const onDemand = report.skills.length - skills.length;
+ const newCount = counts.new - onDemand;
const sample = (status: 'new' | 'drifted'): string => {
const s = skills.filter(k => k.status === status).map(k => k.slug);
return s.slice(0, 8).join(', ') + (s.length > 8 ? `, … +${s.length - 8} more` : '');
};
- if (counts.new === 0) {
+ if (newCount === 0) {
const drift = counts.drifted > 0 ? ` (${counts.drifted} drifted — local edits are fine)` : '';
- return { name, status: 'ok', message: `${counts.current}/${counts.total} built-in skills current${drift}` };
+ const spring = onDemand > 0 ? `; ${onDemand} more load on demand through the spring-loaded skill index` : '';
+ return { name, status: 'ok', message: `${counts.current}/${counts.total} built-in skills current${spring}${drift}` };
}
return {
name,
status: 'warn',
message:
- `${counts.new} new built-in skill(s) available that this workspace hasn't installed: ${sample('new')}. ` +
+ `${newCount} new built-in skill(s) available that this workspace hasn't installed: ${sample('new')}. ` +
(isManagedFilesystemPath(skillsDir)
// #5606: on a managed canonical worktree skillpack sync is refused; name the route that works there.
? 'This is a managed canonical worktree, where `gbrain skillpack sync` is refused: publish each reviewed bundle through `gbrain call --source <source> import_skill_proposal` (docs/guides/shared-brain-skills.md#publish-reviewed-filesystem-edits).'
diff --git a/src/core/check-resolvable.ts b/src/core/check-resolvable.ts
index eaa366c639..937a93f329 100644
--- a/src/core/check-resolvable.ts
+++ b/src/core/check-resolvable.ts
@@ -28,6 +28,7 @@ import {
loadSkillTriggerIndex,
} from './skill-trigger-index.ts';
import { parseSkillFrontmatter } from './skill-frontmatter.ts';
+import { SKILLS_BLOCK_BEGIN, SKILLS_BLOCK_END } from './skills/index-block.ts';
// ---------------------------------------------------------------------------
// Types
@@ -150,8 +151,12 @@ export interface ResolverEntry {
export function parseResolverEntries(resolverContent: string): ResolverEntry[] {
const entries: ResolverEntry[] = [];
let currentSection = '';
+ let inSkillsIndex = false;
for (const line of resolverContent.split('\n')) {
+ if (line.trim() === SKILLS_BLOCK_BEGIN) { inSkillsIndex = true; continue; }
+ if (line.trim() === SKILLS_BLOCK_END) { inSkillsIndex = false; continue; }
+ if (inSkillsIndex) continue;
// Track section headings
const headingMatch = line.match(/^##\s+(.+)/);
if (headingMatch) {
diff --git a/src/core/setup/skills-block.ts b/src/core/setup/skills-block.ts
index 2869f5f259..a62bc1b18e 100644
--- a/src/core/setup/skills-block.ts
+++ b/src/core/setup/skills-block.ts
@@ -33,10 +33,10 @@ import { ensureGitExcluded } from '../context/compiled-core.ts';
import { bundledCatalogId, bundledSkills, type SkillAudience } from '../skills/bundled.ts';
import { shellQuote } from '../shell-quote.ts';
import { renderSkillIndexBlock, SKILL_INDEX_VERSION, SkillIndexTooLarge, skillIndexCatalog } from '../skills/spring-index.ts';
+import { SKILLS_BLOCK_BEGIN, SKILLS_BLOCK_END } from '../skills/index-block.ts';
import { BRAIN_FIRST_END, brainFirstTargetAt, CURSOR_HEAD, direntExists, readBrainFirstLedger, writeUnlessChanged, type BrainFirstHarness, type BrainFirstTarget } from './brain-first.ts';
-export const SKILLS_BLOCK_BEGIN = '<!-- gbrain:skills:begin -->';
-export const SKILLS_BLOCK_END = '<!-- gbrain:skills:end -->';
+export { SKILLS_BLOCK_BEGIN, SKILLS_BLOCK_END };
export const SKILL_LOADING_ENV = 'GBRAIN_SKILL_LOADING';
export const SKILL_LOADING_MODES = ['off', 'spring'] as const;
export type SkillLoading = (typeof SKILL_LOADING_MODES)[number];
diff --git a/src/core/skills/index-block.ts b/src/core/skills/index-block.ts
new file mode 100644
index 0000000000..8e8876fd77
--- /dev/null
+++ b/src/core/skills/index-block.ts
@@ -0,0 +1,11 @@
+/** The managed spring-loaded skill index block: setup/skills-block.ts writes it; check-resolvable.ts and doctor's skill_currency read past it. */
+export const SKILLS_BLOCK_BEGIN = '<!-- gbrain:skills:begin -->';
+export const SKILLS_BLOCK_END = '<!-- gbrain:skills:end -->';
+
+/** Names of the skills a file's managed index lists (its `- <name>: …` lines); empty when the file has no index. */
+export function skillsIndexedIn(text: string): string[] {
+ const begin = text.indexOf(SKILLS_BLOCK_BEGIN);
+ const end = text.indexOf(SKILLS_BLOCK_END, begin);
+ if (begin < 0 || end < 0) return [];
+ return text.slice(begin, end).split('\n').flatMap(l => /^- ([a-z][a-z0-9-]*)(?::|$)/.exec(l)?.[1] ?? []);
+}
diff --git a/test/doctor-skill-checks.test.ts b/test/doctor-skill-checks.test.ts
index e8e9d2539b..7662a6903b 100644
--- a/test/doctor-skill-checks.test.ts
+++ b/test/doctor-skill-checks.test.ts
@@ -30,6 +30,8 @@ import {
computeSkillsManifest,
} from '../src/core/skills-integrity.ts';
import { findGbrainRoot } from '../src/core/skillpack/bundle.ts';
+import { renderSkillsBlock, SKILLS_BLOCK_BEGIN, SKILLS_BLOCK_END } from '../src/core/setup/skills-block.ts';
+import { skillsIndexedIn } from '../src/core/skills/index-block.ts';
const cleanups: string[] = [];
@@ -135,6 +137,22 @@ describe('skillCurrencyCheck', () => {
expect(details.new.length).toBeGreaterThan(0);
});
+ test('skills the spring-loaded index already lists are not reported as missing or sent to `gbrain skillpack sync`', () => {
+ const workspace = makeDir('gbrain-currency-spring-');
+ const skillsDir = join(workspace, 'skills');
+ mkdirSync(skillsDir, { recursive: true });
+ const without = (skillCurrencyCheck(skillsDir).details as { new: string[] }).new;
+ const agents = `# Agent\n\n${SKILLS_BLOCK_BEGIN}\n${renderSkillsBlock('openclaw', '/home/alice-example/.bun/bin/gbrain')}\n${SKILLS_BLOCK_END}\n`;
+ writeFileSync(join(workspace, 'AGENTS.md'), agents);
+ const indexed = skillsIndexedIn(agents);
+ const check = skillCurrencyCheck(skillsDir);
+ const reported = (check.details as { new: string[] }).new;
+ expect(indexed.length).toBeGreaterThan(0);
+ expect(reported).toEqual(without.filter(s => !indexed.includes(s)));
+ expect(check.message).toStartWith(`${reported.length} new built-in skill(s)`);
+ expect(reported.some(s => indexed.includes(s))).toBe(false);
+ });
+
// #5606: on a managed canonical worktree `skillpack sync` is refused, so the hint names the coordinator route instead.
test('a managed workspace is pointed at import_skill_proposal, never at `gbrain skillpack sync`', () => {
const workspace = makeDir('gbrain-currency-managed-');
diff --git a/test/spring-skill-index.test.ts b/test/spring-skill-index.test.ts
index 8c9d15e712..4ffef22f56 100644
--- a/test/spring-skill-index.test.ts
+++ b/test/spring-skill-index.test.ts
@@ -20,7 +20,10 @@ import { BUNDLED_SKILL_FILES } from '../src/core/skills/bundled-skills.generated
import { bundledCatalogId, bundledSkills, bundledSkillTriggers } from '../src/core/skills/bundled.ts';
import { renderSkillIndexBlock, SKILL_INDEX_BUDGET_BYTES, SkillIndexTooLarge, skillIndexCatalog } from '../src/core/skills/spring-index.ts';
import { renderBundledSkillsModule } from '../scripts/generate-bundled-skills.ts';
-import { loaderAllowRule } from '../src/core/setup/skills-block.ts';
+import { loaderAllowRule, renderSkillsBlock, SKILLS_BLOCK_BEGIN, SKILLS_BLOCK_END } from '../src/core/setup/skills-block.ts';
+import { checkResolvable } from '../src/core/check-resolvable.ts';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
import { spawnSync } from 'node:child_process';
const OPTS = { refresh: 'gbrain setup claude-code --instructions-only', optOut: 'gbrain setup claude-code --instructions-only --skill-loading off' };
@@ -30,6 +33,18 @@ const entries = (block: string) => block.split('\n').filter(l => l.startsWith('-
const SKILLS_DIR = join(import.meta.dir, '..', 'skills');
describe('spring-loaded skill index', () => {
+ test('a workspace AGENTS.md carrying the index is not read as resolver rows for workspace skills', () => {
+ const ws = mkdtempSync(join(tmpdir(), 'spring-resolver-'));
+ try {
+ mkdirSync(join(ws, 'skills'));
+ writeFileSync(join(ws, 'AGENTS.md'), `# Agent\n\n${SKILLS_BLOCK_BEGIN}\n${renderSkillsBlock('openclaw', LAUNCHER)}\n${SKILLS_BLOCK_END}\n`);
+ const report = checkResolvable(join(ws, 'skills'));
+ expect(report.issues.filter(i => i.type === 'missing_file' || i.type === 'orphan_trigger')).toEqual([]);
+ } finally {
+ rmSync(ws, { recursive: true, force: true });
+ }
+ });
+
test('a launcher path with spaces, an apostrophe or shell characters prints as one shell word the index and the loader rule share', () => {
for (const launcher of ["/home/alice-example/o'brien dir/gbrain", '/opt/a b/$(x)/gbrain', '/opt/semi;colon/gbrain']) {
const block = renderSkillIndexBlock(bundledSkills('owner'), launcher, OPTS);