Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* skillpack/brain-resident-locate.ts — server-side discovery of brain-resident
* skillpacks for the `list_brain_skillpack` MCP tool (Topology B).
*
* Distinct from skill-catalog.ts (host-global prose skills): brain-resident
* packs are per-SOURCE — a brain can mount several sources, each carrying its
* own pack. So discovery is scoped by `sourceScopeOpts(ctx)` (in-DB tenancy),
* not the single host skills dir.
*
* Trust posture mirrors skill-catalog: contents are surfaced over HTTP only
* behind the publish gate (enforced by the op). We NEVER emit a server-side
* filesystem path to a thin client (#6) — the install hint is the source's git
* remote spec, which the client can `resolveSource` on its own machine.
*/
import { existsSync, readFileSync, realpathSync, statSync } from 'fs';
import { join, relative, resolve } from 'path';
import { createHash } from 'crypto';
import { parseMarkdown, coerceFrontmatterString } from '../markdown.ts';
import { loadAllSources } from '../sources-load.ts';
import { loadSkillpackManifest } from './manifest-v1.ts';
import { loadState, findEntry } from './state.ts';
import { MAX_SKILL_MD_BYTES } from '../skill-catalog.ts';
import type { Action } from '../agent-output.ts';
import type { BrainEngine } from '../engine.ts';
import { opError, type OperationContext } from '../operations.ts';
import { sourceScopeOpts } from '../operations.ts';
import { hostFix, readFix } from '../ops/op-fix.ts';
import { relativeEscapesRoot } from '../path-confine.ts';
export interface ResidentPackSkill {
/** Skill name, as get_skill takes it. Never `slug`: page slugs and skill
* names are different things, and readers treat every slug as a page. */
name: string;
description: string;
}
export interface ResidentPackEntry {
/** The source id this pack was discovered under (provenance). */
source_id: string;
name: string;
version: string;
/** Schema pack the pack targets (null when it declares none). */
schema_pack: string | null;
/** The brain's active schema pack for THIS source (server-computed, #7). */
active_schema_pack: string | null;
/** true/false when the pack declares a schema_pack; null when it doesn't. */
schema_pack_match: boolean | null;
skills: ResidentPackSkill[];
/**
* Git-source spec a thin client can `gbrain skillpack scaffold <spec>` on its
* OWN machine. Null when the source has no git remote (local-only source —
* the thin client cannot install it remotely; binary install is PR2 work).
*/
scaffold_spec: string | null;
/** Whether this pack is already scaffolded at this exact version. */
installed: boolean;
}
export interface ResidentPackResult {
packs: ResidentPackEntry[];
}
/**
* Derive a stable brain-id for a source from its canonical git remote (the repo
* carrying the pack) when available; else a deterministic hash of the canonical
* local path. NOT the brain DB identity (a different axis). Shared by the
* Topology-A nag hook and any server-side discovery that needs the same key.
*/
export function deriveBrainId(remoteUrl: string | null | undefined, localPath: string | null | undefined): string {
if (remoteUrl && remoteUrl.length > 0) return `git:${remoteUrl}`;
const p = localPath ?? '';
return `path:${createHash('sha256').update(p).digest('hex').slice(0, 16)}`;
}
function readSkillDescription(packRoot: string, skillDir: string): string {
const skillMd = join(packRoot, skillDir, 'SKILL.md');
if (!existsSync(skillMd)) return '(no description)';
try {
const desc = coerceFrontmatterString(
parseMarkdown(readFileSync(skillMd, 'utf-8'), skillMd).frontmatter.description,
);
return desc && desc.length > 0 ? desc : '(no description)';
} catch {
return '(no description)';
}
}
/**
* Source-aware active schema pack for the mismatch check (#7): per-source DB
* config wins, then brain-wide, then the 'gbrain-base' default. Read-only.
*/
async function activeSchemaPackForSource(engine: BrainEngine, sourceId: string): Promise<string> {
try {
const perSource = await engine.getConfig(`schema_pack.source.${sourceId}`);
if (perSource && perSource.length > 0) return perSource;
} catch {
/* ignore */
}
try {
const brainWide = await engine.getConfig('schema_pack');
if (brainWide && brainWide.length > 0) return brainWide;
} catch {
/* ignore */
}
return 'gbrain-base';
}
/**
* Enumerate brain-resident packs across the sources in scope for this caller.
* Fail-open per source: a malformed/absent pack on one source never aborts the
* whole listing. Returns one entry per in-scope source that ships a
* `brain_resident: true` pack.
*/
export async function loadResidentPacksForServer(ctx: OperationContext): Promise<ResidentPackResult> {
const scope = sourceScopeOpts(ctx);
const allowed: Set<string> | null = scope.sourceIds
? new Set(scope.sourceIds)
: scope.sourceId
? new Set([scope.sourceId])
: null; // null = owner, all sources
let sources;
try {
sources = await loadAllSources(ctx.engine);
} catch {
return { packs: [] };
}
const state = loadState();
const packs: ResidentPackEntry[] = [];
for (const src of sources) {
if (allowed && !allowed.has(src.id)) continue;
const localPath = src.local_path;
if (!localPath || !existsSync(join(localPath, 'skillpack.json'))) continue;
try {
const manifest = loadSkillpackManifest(localPath);
if (manifest.brain_resident !== true) continue;
const active = await activeSchemaPackForSource(ctx.engine, src.id);
const wantSchema = manifest.schema_pack ?? null;
const stateEntry = findEntry(state, manifest.name);
const remoteUrl = (src.config as Record<string, unknown>)?.remote_url as string | undefined;
packs.push({
source_id: src.id,
name: manifest.name,
version: manifest.version,
schema_pack: wantSchema,
active_schema_pack: active,
schema_pack_match: wantSchema === null ? null : wantSchema === active,
skills: manifest.skills.map((s) => ({
name: s.replace(/^skills\//, ''),
description: readSkillDescription(localPath, s),
})),
scaffold_spec: remoteUrl && remoteUrl.length > 0 ? remoteUrl : null,
installed: !!stateEntry && stateEntry.version === manifest.version,
});
} catch {
continue; // malformed pack on this source → skip, keep going
}
}
return { packs };
}
function listPacksFix(why: string): Action {
return readFix(why, { argv: ['gbrain', 'brain-skillpack'], mcp: { tool: 'list_brain_skillpack', arguments: {} } });
}
export interface ResidentSkillDetail {
source_id: string;
pack_name: string;
name: string;
description: string;
/** Full SKILL.md body (size-capped). */
body: string;
}
/**
* Fetch one brain-resident skill's SKILL.md body from a specific source, for
* `get_skill` when a `source_id` is supplied (disambiguates a skill name that exists
* on more than one source). Same confinement as skill-catalog: realpath +
* relative-contained to the pack root, regular file named SKILL.md, size-capped.
*
* Throws OperationError (not_found / storage_error) on any miss so the MCP
* dispatcher surfaces a structured error.
*/
export async function getResidentSkillDetail(
ctx: OperationContext,
sourceId: string,
name: string,
): Promise<ResidentSkillDetail> {
if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(name)) {
throw opError('invalid_params', `Invalid skill name: ${JSON.stringify(name)}`,
'Pass the skill name exactly as list_brain_skillpack returns it: lowercase letters, digits, and hyphens, at most 64 characters.',
{ fix: listPacksFix('Lists every brain-resident pack with its source id and skill names.') });
}
// Respect source scoping: a scoped caller can only reach its own sources.
const scope = sourceScopeOpts(ctx);
if ((scope.sourceIds && !scope.sourceIds.includes(sourceId)) || (scope.sourceId && scope.sourceId !== sourceId)) {
throw opError('not_found', `Source not in scope: ${sourceId}`,
`This connection cannot read source ${sourceId}. List the packs it can see and use one of their source ids.`,
{ fix: listPacksFix('Lists only the brain-resident packs on sources this connection may read.') });
}
let sources;
try {
sources = await loadAllSources(ctx.engine);
} catch {
throw opError('storage_error', 'Could not enumerate sources.',
'The brain could not read its sources table; this is a server-side storage failure, not a caller mistake. Run the doctor check on the brain host; if it repeats, report it to the user.',
{ fix: hostFix(ctx, ['gbrain', 'doctor', '--json'], 'Checks the brain\'s database connection and schema.') });
}
const src = sources.find((s) => s.id === sourceId);
if (!src || !src.local_path) {
throw opError('not_found', `Source ${sourceId} has no local path.`,
`Source ${sourceId} is not registered or has no local checkout on the brain host, so it ships no brain-resident pack here. List the packs this brain does ship.`,
{ fix: listPacksFix('Lists the sources that ship a brain-resident pack.') });
}
const packRoot = src.local_path;
let manifest;
try {
manifest = loadSkillpackManifest(packRoot);
} catch {
throw opError('not_found', `Source ${sourceId} has no valid skillpack.`,
`Source ${sourceId}'s skillpack.json is missing or invalid, so its pack cannot load. List the packs that do load; tell the user if they expected this source to ship one.`,
{ fix: listPacksFix('Lists the brain-resident packs that load successfully.') });
}
if (manifest.brain_resident !== true) {
throw opError('not_found', `Source ${sourceId} does not ship a brain-resident pack.`,
`Source ${sourceId}'s skillpack is not marked brain_resident, so it is not served here. List the packs this brain does serve.`,
{ fix: listPacksFix('Lists the sources that ship a brain-resident pack.') });
}
const skillDir = `skills/${name}`;
if (!manifest.skills.includes(skillDir)) {
throw opError('not_found', `Skill "${name}" not in pack ${manifest.name}.`,
`Pack ${manifest.name} on source ${sourceId} has no skill ${name}. List its skills and pass one of the names it returns.`,
{ fix: listPacksFix(`Lists pack ${manifest.name}'s skill names.`) });
}
// Confinement: realpath the resolved SKILL.md and require it stays under the
// realpath'd pack root (defeats symlink/.. escape, including a poisoned pack).
const skillMd = join(packRoot, skillDir, 'SKILL.md');
let realRoot: string;
let realFile: string;
try {
realRoot = realpathSync(packRoot);
realFile = realpathSync(skillMd);
} catch {
throw opError('not_found', `SKILL.md missing for ${name} in ${sourceId}.`,
`Pack ${manifest.name} lists skill ${name}, but its SKILL.md is missing on the brain host. Tell the user the pack is incomplete so its maintainer can add the file.`);
}
const rel = relative(realRoot, realFile);
if (relativeEscapesRoot(rel) || resolve(realRoot, rel) !== realFile) { // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- rel comes from relative() of two realpaths; resolve only re-joins it to confirm containment, no file is opened here
throw opError('storage_error', 'Skill path escaped the pack root.',
`Skill ${name} in source ${sourceId} resolves outside its pack root (a symlink or '..'), so it was refused. Do not retry; tell the user so the pack's maintainer replaces it with a regular file inside the pack.`);
}
const st = statSync(realFile);
if (!st.isFile()) {
throw opError('storage_error', 'Resolved skill path is not a file.',
`Skill ${name}'s SKILL.md in source ${sourceId} is not a regular file. Tell the user so the pack's maintainer can fix the pack.`);
}
if (st.size > MAX_SKILL_MD_BYTES) {
throw opError('storage_error', `SKILL.md exceeds ${MAX_SKILL_MD_BYTES} bytes.`,
`Skill ${name}'s SKILL.md in source ${sourceId} is larger than the ${MAX_SKILL_MD_BYTES}-byte limit and cannot be served. Tell the user so the pack's maintainer can shorten it.`);
}
const body = readFileSync(realFile, 'utf-8');
return {
source_id: sourceId,
pack_name: manifest.name,
name,
description: readSkillDescription(packRoot, skillDir),
body,
};
}