Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Skill catalog + advisor + status-snapshot operation cluster — pure move
* from operations.ts (v0.46.x tranche 2). Op consts stay module-private;
* `skillsCatalogOperations` below lists them in EXACTLY the order they
* appear in the canonical `operations` array in ../operations.ts. Never
* import from '../operations.ts' here (cycle).
*/
import type { Operation } from './contract.ts';
import { opError } from './contract.ts';
import { hostFix, invalidParam } from './op-fix.ts';
import { sourceScopeOpts } from './context.ts';
import {
LIST_SKILLS_DESCRIPTION,
GET_SKILL_DESCRIPTION,
} from '../operations-descriptions.ts';
// --- PR1: skill catalog over MCP (host-repo skills for thin clients) ---
// Both ops dynamically import ./skill-catalog.ts to avoid an import cycle
// (skill-catalog statically imports the `operations` array for D7 tool honesty).
// Read-scope, non-localOnly: a thin client (Codex/Perplexity/Cowork) reaches
// these over HTTP. The host-filesystem read is gated by mcp.publish_skills +
// path confinement — see the trust-boundary memo in skill-catalog.ts.
const list_skills: Operation = {
name: 'list_skills',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description: LIST_SKILLS_DESCRIPTION,
publishGateKey: 'mcp.publish_skills',
params: {
schema_version: { type: 'number', minimum: 1, description: '2 for the source-qualified catalog.', fullSurfaceOnly: true },
limit: { type: 'number', description: 'Page size or rank cap (1-100).' },
cursor: { type: 'string', description: 'Version 2 cursor.', fullSurfaceOnly: true },
source_id: { type: 'string', description: 'Version 2: one source.', fullSurfaceOnly: true },
section: {
type: 'string',
description: 'Only this routing section.',
fullSurfaceOnly: true,
},
query: {
type: 'string',
description: 'Version 1 host catalog: rank skills by word overlap with this task (name, triggers, description), drop the rest, cap at limit (default 10). Refused on a shared catalog.',
fullSurfaceOnly: true,
},
},
handler: async (ctx, p) => {
if (p.query !== undefined && typeof p.query !== 'string') throw invalidParam(ctx, 'list_skills', 'query', 'query must be a string naming the task.', { example: 'prepare for a meeting' });
const query = typeof p.query === 'string' && p.query.trim().length > 0 ? p.query : undefined;
// #6471: the shared catalogs do not rank yet; refusing beats a silently unranked list.
const refuseQueryOnSharedCatalog = (which: string) => opError('invalid_params',
`query ranks the version 1 host skill catalog only; ${which} does not support it yet.`,
'Drop query and narrow the shared catalog with section (and source_id for version 2) instead; rank the host catalog by calling list_skills with query on a brain that serves it.');
if (p.schema_version === 2) {
if (query) throw refuseQueryOnSharedCatalog('the version 2 catalog');
return (await import('../shared-skills/catalog.ts')).listSharedSkills(ctx, p);
}
if (p.schema_version !== undefined && p.schema_version !== 1) throw invalidParam(ctx, 'list_skills', 'schema_version', 'Supported skill catalog schema versions are 1 and 2.', { choices: ['1', '2'], example: 2 });
const compatibility = await import('../shared-skills/compatibility.ts');
if (await compatibility.sharedCatalogActive(ctx)) {
if (query) throw refuseQueryOnSharedCatalog("this brain's shared catalog");
return compatibility.listLegacySharedSkills(ctx, typeof p.section === 'string' ? p.section : undefined);
}
const sc = await import('../skill-catalog.ts');
const publish = await sc.readMcpPublishSkills(ctx);
sc.assertPublishEnabled(ctx, publish);
const override = await sc.readMcpSkillsDir(ctx);
const { dir, source } = sc.resolveSkillsDir(ctx, override);
const section = typeof p.section === 'string' ? p.section : undefined;
const limit = typeof p.limit === 'number' ? p.limit : undefined;
return sc.buildSkillCatalog(ctx, dir, source, { section, query, limit, gateDisabled: await sc.readSkillToolGates(ctx) });
},
scope: 'read',
cliHints: { name: 'skills', positional: [] },
};
const get_skill: Operation = {
name: 'get_skill',
mutating: false,
idempotent: true,
outputRedaction: { exempt: 'skill catalog files are installed instructions read verbatim; redaction would corrupt approved revisions' },
description: GET_SKILL_DESCRIPTION,
publishGateKey: 'mcp.publish_skills',
params: {
schema_version: { type: 'number', minimum: 1, description: '2 for an exact canonical revision.', fullSurfaceOnly: true },
qualified_id: { type: 'string', description: 'Version 2 skill id.', fullSurfaceOnly: true },
expected_brain_id: { type: 'string', description: 'Brain id to assert.', fullSurfaceOnly: true },
source_incarnation: { type: 'string', description: 'From discovery.', fullSurfaceOnly: true },
pack_id: { type: 'string', description: 'Pack id.', fullSurfaceOnly: true },
revision: { type: 'string', description: 'Exact revision (default: head).', fullSurfaceOnly: true },
name: {
type: 'string',
description: 'Skill name from list_skills.',
},
source_id: {
type: 'string',
description: 'Brain-resident pack skill from this source.',
},
},
handler: async (ctx, p) => {
if (p.schema_version === 2) return (await import('../shared-skills/catalog.ts')).getSharedSkill(ctx, sharedSkillReadSelector(p));
if (p.expected_brain_id !== undefined) throw opError('invalid_params', 'expected_brain_id requires schema_version 2; it asserts identity and never selects a brain connection.', 'Pass schema_version: 2 with expected_brain_id, or drop expected_brain_id.');
if (p.schema_version !== undefined && p.schema_version !== 1) throw invalidParam(ctx, 'get_skill', 'schema_version', 'Supported skill catalog schema versions are 1 and 2.', { choices: ['1', '2'], example: 2 });
const compatibility = await import('../shared-skills/compatibility.ts');
if (await compatibility.sharedCatalogActive(ctx)) return compatibility.getLegacySharedSkill(ctx, p.name, typeof p.source_id === 'string' ? p.source_id : undefined);
const sc = await import('../skill-catalog.ts');
const publish = await sc.readMcpPublishSkills(ctx);
sc.assertPublishEnabled(ctx, publish);
// Brain-resident path: when source_id is supplied, fetch the per-source pack
// skill (confined to that source's pack root) rather than the host catalog.
if (typeof p.source_id === 'string' && p.source_id.length > 0) {
const brl = await import('../skillpack/brain-resident-locate.ts');
return brl.getResidentSkillDetail(ctx, p.source_id, typeof p.name === 'string' ? p.name : '');
}
const override = await sc.readMcpSkillsDir(ctx);
const { dir } = sc.resolveSkillsDir(ctx, override);
const name = typeof p.name === 'string' ? p.name : '';
return sc.getSkillDetail(ctx, dir, name, { gateDisabled: await sc.readSkillToolGates(ctx) });
},
scope: 'read',
cliHints: { name: 'skill', positional: ['name'] },
};
const sharedSkillKeyParams: Operation['params'] = {
source_id: { type: 'string', description: 'Exactly one granted source.' },
source_incarnation: { type: 'string', description: 'From the qualified catalog.' },
pack_id: { type: 'string', required: true, description: 'Canonical pack identifier.' },
name: { type: 'string', required: true, description: 'Canonical skill name.' },
};
function sharedSkillReadSelector(p: Record<string, unknown>) {
return { name: p.name as string | undefined, qualified_id: p.qualified_id as string | undefined,
brain_id: p.expected_brain_id as string | undefined, source_id: p.source_id as string | undefined,
source_incarnation: p.source_incarnation as string | undefined, pack_id: p.pack_id as string | undefined,
revision: p.revision as string | undefined };
}
const sharedSkillMutationParams: Operation['params'] = {
...sharedSkillKeyParams,
request_id: { type: 'string', required: true, description: 'Durable idempotency UUID; reuse only with identical intent.' },
expected_revision: { type: 'string', description: 'Current revision UUID; JSON null for creation.' },
};
const get_skill_asset: Operation = {
name: 'get_skill_asset', description: 'Read an approved file from an exact skill revision (data, never executed).',
mutating: false,
idempotent: true,
outputRedaction: { exempt: 'skill catalog files are installed instructions read verbatim; redaction would corrupt approved revisions' },
scope: 'read', publishGateKey: 'mcp.publish_skills',
cliHints: { name: 'skill-asset', positional: [] },
params: { source_id: sharedSkillKeyParams.source_id, source_incarnation: { ...sharedSkillKeyParams.source_incarnation, fullSurfaceOnly: true },
name: { type: 'string', description: 'Skill name.' },
pack_id: { type: 'string', description: 'Pack id.', fullSurfaceOnly: true },
qualified_id: { type: 'string', description: 'Version 2 skill id.', fullSurfaceOnly: true },
expected_brain_id: { type: 'string', description: 'Brain id to assert.', fullSurfaceOnly: true },
revision: { type: 'string', required: true, description: 'Revision from get_skill.' },
path: { type: 'string', required: true, description: 'Path in that revision manifest.' } },
handler: async (ctx, p) => (await import('../shared-skills/catalog.ts')).getSharedSkillAsset(ctx, { ...sharedSkillReadSelector(p), path: String(p.path ?? '') }),
};
const put_skill: Operation = {
name: 'put_skill', description: 'Publish a complete file-canonical skill revision with CAS and a durable receipt. Requires explicit skill editor authority; cannot expand publication policy.',
idempotent: true,
outputRedaction: 'no_stored_text',
scope: 'write', requiredScopes: ['skill_editor'], mutating: true,
cliHints: { name: 'put-skill', positional: [] },
params: { ...sharedSkillMutationParams, description: { type: 'string', description: 'Compact routing description.' },
triggers: { type: 'array', items: { type: 'string' }, description: 'Routing phrases.' },
requirements: { type: 'array', items: { type: 'string' }, description: 'Approved runtime and tool requirement tokens.' },
private: { type: 'boolean', description: 'Exclude this skill from remote publication.' },
files: { type: 'array', items: { type: 'object' }, required: true, description: 'Complete closure: path, content, encoding (utf8/base64), file_class, audience, media_type, depends_on.' } },
handler: async (ctx, p) => (await import('../shared-skills/catalog.ts')).submitSharedSkillMutation(ctx, 'put_skill', p),
};
const delete_skill: Operation = {
name: 'delete_skill', description: 'CAS-delete a canonical shared skill and revoke future managed activation. Previously downloaded bytes are not recalled.',
idempotent: true,
outputRedaction: 'no_stored_text',
scope: 'write', requiredScopes: ['skill_editor'], mutating: true, params: sharedSkillMutationParams,
cliHints: { name: 'delete-skill', positional: [] },
handler: async (ctx, p) => (await import('../shared-skills/catalog.ts')).submitSharedSkillMutation(ctx, 'delete_skill', p),
};
const import_skill_proposal: Operation = {
name: 'import_skill_proposal', description: 'Publish explicitly reviewed human-edited canonical skill files through the durable coordinator. Requires exact current file hashes and skill revision; trusted local operator only.',
idempotent: true,
outputRedaction: 'no_stored_text',
scope: 'admin', localOnly: true, cliOnly: { argv: ['gbrain', 'call', 'import_skill_proposal', '<params_json>'] }, mutating: true,
params: { ...put_skill.params, expected_hashes: { type: 'object', required: true, description: 'Reviewed current SHA-256 hashes for every affected file and skillpack.json; null denotes an absent file.' } },
handler: async (ctx, p) => (await import('../shared-skills/publication.ts')).importSharedSkillProposal(ctx, p),
};
const set_skill_policy: Operation = {
name: 'set_skill_policy', description: 'Explicitly approve a versioned shared-skill disclosure and follow policy. Separate publisher authority is required; editing a skill never grants this permission.',
idempotent: true,
outputRedaction: 'no_stored_text',
scope: 'admin', requiredScopes: ['skill_publisher'], mutating: true,
cliHints: { name: 'set-skill-policy', positional: [] },
params: { source_id: { type: 'string', required: true, description: 'Source whose publication policy is approved.' },
expected_policy_epoch: { type: 'string', description: 'Previously reviewed policy epoch; null for initial policy.' },
policy: { type: 'object', required: true, description: 'version:1, enabled, classes, audiences, requirements, allow_follow.' } },
handler: async (ctx, p) => (await import('../shared-skills/policy.ts')).setSharedSkillPolicy(ctx, String(p.source_id),
p.policy as import('../shared-skills/model.ts').SharedSkillPolicy, p.expected_policy_epoch as string | null | undefined),
};
const get_skill_policy: Operation = {
name: 'get_skill_policy', description: 'Read the owner publication policy and CAS epoch, including when sharing is disabled. Does not approve or change disclosure.',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
scope: 'admin', requiredScopes: ['skill_publisher'],
cliHints: { name: 'skill-policy', positional: [] },
params: { source_id: { type: 'string', required: true, description: 'Source whose publication policy is reviewed.' } },
handler: async (ctx, p) => (await import('../shared-skills/policy.ts')).getSharedSkillPolicy(ctx, String(p.source_id)),
};
const get_skill_retention: Operation = {
name: 'get_skill_retention', description: 'Inspect retained shared-skill revision counts, protected leases and source storage capacity. Trusted host operator only.',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
scope: 'admin', localOnly: true, cliOnly: { argv: ['gbrain', 'skill-retention'] },
cliHints: { name: 'skill-retention', positional: [] },
params: { source_id: { type: 'string', description: 'Canonical source to inspect.' } },
handler: async (ctx, p) => (await import('../shared-skills/retention.ts')).getSharedSkillRetention(ctx, typeof p.source_id === 'string' ? p.source_id : ctx.sourceId),
};
const prune_skill_revisions: Operation = {
name: 'prune_skill_revisions', description: 'Prune one bounded batch of expired shared-skill history. Preserves heads, tombstones, pending publication refs, delivery leases, pins and permanent write receipts.',
idempotent: false,
outputRedaction: 'no_stored_text',
scope: 'admin', localOnly: true, cliOnly: { argv: ['gbrain', 'prune-skill-revisions'] }, mutating: true,
cliHints: { name: 'prune-skill-revisions', positional: [] },
params: { source_id: { type: 'string', description: 'Canonical source to prune.' } },
handler: async (ctx, p) => (await import('../shared-skills/retention.ts')).pruneSharedSkillRevisions(ctx, typeof p.source_id === 'string' ? p.source_id : ctx.sourceId),
};
const retain_skill_revision: Operation = {
name: 'retain_skill_revision', description: 'Pin an exact shared-skill revision for up to 24 hours under a bounded operator quota. Does not grant read or execution permission.',
idempotent: false,
outputRedaction: 'no_stored_text',
scope: 'admin', localOnly: true, cliOnly: { argv: ['gbrain', 'retain-skill-revision'] }, mutating: true,
cliHints: { name: 'retain-skill-revision', positional: [] },
params: { ...sharedSkillKeyParams, source_incarnation: { type: 'string', required: true, description: 'Exact source incarnation.' },
revision: { type: 'string', required: true, description: 'Exact existing immutable revision.' }, hours: { type: 'number', description: 'Pin lifetime greater than zero and at most 24 hours.' } },
handler: async (ctx, p) => (await import('../shared-skills/retention.ts')).retainSharedSkillRevision(ctx,
p as unknown as Parameters<typeof import('../shared-skills/retention.ts').retainSharedSkillRevision>[1]),
};
const list_brain_skillpack: Operation = {
name: 'list_brain_skillpack',
mutating: false,
idempotent: true,
outputRedaction: { exempt: 'skill catalog files are installed instructions read verbatim; redaction would corrupt approved revisions' },
description: 'Skillpacks this brain ships: skills and a scaffold spec to offer the user.',
publishGateKey: 'mcp.publish_skills',
params: {},
handler: async (ctx) => {
const compatibility = await import('../shared-skills/compatibility.ts');
if (await compatibility.sharedCatalogActive(ctx)) return compatibility.listLegacySharedPacks(ctx);
const sc = await import('../skill-catalog.ts');
const publish = await sc.readMcpPublishSkills(ctx);
sc.assertPublishEnabled(ctx, publish);
const brl = await import('../skillpack/brain-resident-locate.ts');
return brl.loadResidentPacksForServer(ctx);
},
scope: 'read',
cliHints: { name: 'brain-skillpack', positional: [] },
};
const advisor: Operation = {
name: 'advisor',
mutating: false,
idempotent: true,
outputRedaction: 'retrieval',
description:
'Ranked, read-only "what to do next" for this brain: version drift, pending migrations, ' +
'schema-pack issues, stalled jobs, usage-shape gaps, and setup smells. Each finding has a ' +
'severity, why-it-matters, and the exact fix command. Never mutates. Tell the user; ask ' +
'before running any fix. On by default for the local stdio server; remote HTTP callers need ' +
'mcp.publish_advisor (separate from mcp.publish_skills because diagnostics are not prose skills).',
publishGateKey: 'mcp.publish_advisor',
params: {},
handler: async (ctx) => {
// Publish gate: a remote caller needs mcp.publish_advisor=true. Local
// (ctx.remote === false) callers bypass — the trust boundary is the OS.
if (ctx.remote !== false) {
// F7: on by default for the owner's stdio pipe; opt-in over HTTP.
const { readPublishGate } = await import('../../mcp/publish-gates.ts');
const enabled = await readPublishGate(ctx.engine, ctx.config, 'mcp.publish_advisor', ctx.transport);
if (!enabled) {
// Same k=v detail grammar as assertPublishEnabled (WP1): honest
// catalogs hide this op at list time; the throw is the backstop.
const err = opError(
'permission_denied',
'The advisor is not published over MCP by the brain owner, so it is hidden from your ' +
'tool catalog. Ask the owner to enable it if you need it.',
'The owner can enable it with `gbrain config set mcp.publish_advisor true`.',
{ fix: hostFix(ctx, ['gbrain', 'config', 'set', 'mcp.publish_advisor', 'true'],
'Publishing the advisor over MCP is the brain owner\'s choice; only the trusted CLI on the brain host changes it.') },
);
err.detail = 'config_key=mcp.publish_advisor';
throw err;
}
}
const { runAdvisor } = await import('../advisor/run.ts');
const { VERSION } = await import('../../version.ts');
// Over MCP there is no agent workspace on the server side: remote=true makes
// runAdvisor drop workspace-dependent collectors (A1). The op never writes
// history or nag state — it is strictly read-only.
const report = await runAdvisor({
engine: ctx.engine,
config: ctx.config,
version: VERSION,
workspace: null,
skillsDir: null,
now: new Date(),
remote: ctx.remote !== false,
});
return report;
},
scope: 'read',
// NOT localOnly — exposed over MCP (E1) behind mcp.publish_advisor.
// No cliHints: the CLI surface is the richer `gbrain advisor` command
// (commands/advisor.ts) which adds --json exit codes + --apply.
cliHints: { name: 'advisor', hidden: true },
};
/**
* v0.41.19.0 — `gbrain status` thin-client surface.
*
* Returns a snapshot of sync freshness + last cycle state for thin-client
* `gbrain status` callers. Per D2/D10 in the plan:
*
* - Scope: admin (NOT localOnly). The op exposes operational state
* including sync timestamps and cycle metadata. Locking it to admin
* matches the `run_doctor` posture and prevents future feature creep
* from quietly leaking ops state to read-scoped clients.
*
* - Payload (schema_version 2, Minions-visibility wave): `{schema_version,
* version, sync, cycle, queue, workers}`. `queue` (status counts +
* per-queue waiting depth + oldest-waiting age) and `workers`
* (supervisor liveness via pidfile/DB-lock + last completed job) were
* added so a remote submitter can see whether the lane its job ids point
* at is actually alive. Locks and Autopilot stay deliberately omitted —
* host-local concerns the thin client renders as "N/A on remote brain".
*
* - Fail-soft (amendment 26): each v2 section computes in its own
* try/catch and degrades to `{error: 'unavailable'}` without failing
* the whole snapshot.
*
* - The local CLI composes the same data plus the local-only sections
* directly (no MCP round-trip when running against ~/.gbrain).
*/
const get_status_snapshot: Operation = {
name: 'get_status_snapshot',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Snapshot for `gbrain status` thin-client mode: sync freshness + last cycle + queue depths + worker liveness. Admin-scope.',
params: {},
handler: async (ctx) => {
const { buildSyncStatusReport } = await import('../../commands/sync.ts');
const { buildCycleSnapshot } = await import('../../commands/status.ts');
// Pull sources first (handles brains with zero declared sources too).
let sources: Array<{ id: string; name: string; local_path: string | null; config: Record<string, unknown> }> = [];
try {
const rows = await ctx.engine.executeRaw<{
id: string;
name: string;
local_path: string | null;
config: Record<string, unknown> | null;
}>(
`SELECT id, name, local_path, config FROM sources WHERE COALESCE(archived, FALSE) = FALSE ORDER BY id`,
);
sources = rows.map((r) => ({
id: r.id,
name: r.name,
local_path: r.local_path,
config: r.config ?? {},
}));
} catch {
// Pre-v0.26.5 brains may lack the `archived` column; degrade to all rows.
const rows = await ctx.engine.executeRaw<{
id: string;
name: string;
local_path: string | null;
config: Record<string, unknown> | null;
}>(`SELECT id, name, local_path, config FROM sources ORDER BY id`);
sources = rows.map((r) => ({
id: r.id,
name: r.name,
local_path: r.local_path,
config: r.config ?? {},
}));
}
// Remote callers see only the sources their grant reads (the sources_list / get_health ladder); the trusted local CLI keeps every source.
const scope = ctx.remote === false ? {} : sourceScopeOpts(ctx);
const allowed = scope.sourceIds ?? (scope.sourceId !== undefined ? [scope.sourceId] : undefined);
if (allowed) sources = sources.filter((s) => allowed.includes(s.id));
const sync = await buildSyncStatusReport(ctx.engine, sources);
const cycle = await buildCycleSnapshot(ctx.engine);
// v2 sections, each fail-soft (amendment 26): a broken/pre-migration
// queue table must not take down the sync/cycle payload that v1 clients
// already depend on.
let queue: unknown;
try {
const { buildQueueCounts, buildQueueDepths } = await import('../../commands/status.ts');
queue = { counts: await buildQueueCounts(ctx.engine), by_queue: await buildQueueDepths(ctx.engine) };
} catch {
queue = { error: 'unavailable' as const };
}
let workers: unknown;
try {
const { buildWorkersSnapshot } = await import('../../commands/status.ts');
workers = await buildWorkersSnapshot(ctx.engine);
} catch {
workers = { error: 'unavailable' as const };
}
// #1984: report the brain server's version so a thin-client `gbrain status`
// can surface remote_version alongside its own local CLI version.
const { VERSION } = await import('../../version.ts');
return { schema_version: 2 as const, version: VERSION, sync, cycle, queue, workers };
},
scope: 'admin',
localOnly: false,
};
// Ops in EXACTLY the canonical `operations` array order.
export const skillsCatalogOperations: Operation[] = [
list_skills, get_skill, list_brain_skillpack, advisor, get_status_snapshot,
get_skill_asset, put_skill, delete_skill, set_skill_policy, get_skill_policy,
get_skill_retention, prune_skill_revisions, retain_skill_revision,
import_skill_proposal,
];