Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Schema-pack operation cluster — pure move from operations.ts (v0.46.x
* tranche 3): the v0.40.6.0 Schema Cathedral v3 ops (7 read + 2 admin —
* the admin pair is deliberately NOT localOnly per D2, so remote agents
* (your OpenClaw, etc.) can author packs behind admin OAuth scope). Op
* consts stay module-private; `schemaPacksOperations` 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 { sourceScopeOpts } from './context.ts';
// ──────────────────────────────────────────────────────────────────────
// v0.40.6.0 Schema Cathedral v3 — 9 new MCP ops for the agent on-ramp.
//
// Read ops (scope: read; NOT localOnly) — any read-scope OAuth client.
// Write ops (scope: admin; NOT localOnly per D2) — admin-scope client
// (your OpenClaw and similar remote agents) can author schema packs
// remotely. Audit log captures actor=mcp:<clientId8> on every mutation
// (see src/core/schema-pack/mutate-audit.ts privacy posture per D20).
//
// Per-call schema_pack opt STAYS rejected for remote callers — that
// trust boundary is enforced by op-trust-gate.ts and is separate from
// the localOnly posture (R2 regression preserved).
// ──────────────────────────────────────────────────────────────────────
const get_active_schema_pack: Operation = {
name: 'get_active_schema_pack',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Cheap identity packet for the active schema pack. Returns {pack_name, version, sha8, page_types_count, link_types_count, primitive_summary, source_tier}. Useful for agents to know which pack they are operating against without paying full manifest load cost.',
params: {},
scope: 'read',
handler: async (ctx) => {
const { loadActivePack, resolveActivePackNameOnly } = await import('../schema-pack/load-active.ts');
const { engineSchemaInput } = await import('../schema-pack/engine-resolution.ts');
// #3792/#7942: the DB-plane tiers (brain-wide and the caller source's
// override) so this packet reports the pack writes validate against.
const input = await engineSchemaInput(ctx.engine, { remote: ctx.remote ?? true, sourceId: ctx.sourceId });
const resolution = resolveActivePackNameOnly(input);
const pack = await loadActivePack(input);
const primitiveSummary: Record<string, number> = {};
for (const t of pack.manifest.page_types) {
primitiveSummary[t.primitive] = (primitiveSummary[t.primitive] ?? 0) + 1;
}
return {
pack_name: pack.manifest.name,
version: pack.manifest.version,
sha8: pack.manifest_sha8,
identity: pack.identity,
page_types_count: pack.manifest.page_types.length,
link_types_count: pack.manifest.link_types.length,
primitive_summary: primitiveSummary,
source_tier: resolution.source,
};
},
};
const list_schema_packs: Operation = {
name: 'list_schema_packs',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'List installed schema packs (bundled + user-installed). Returns {bundled: string[], installed: string[]}. Read-only directory listing.',
params: {},
scope: 'read',
handler: async (_ctx) => {
const { existsSync, readdirSync } = await import('node:fs');
const { join } = await import('node:path');
const { gbrainPath } = await import('../config.ts');
const { BUNDLED_PACK_NAMES } = await import('../schema-pack/bundled.ts');
const bundled = [...BUNDLED_PACK_NAMES];
const installedDir = gbrainPath('schema-packs');
const installed: string[] = [];
if (existsSync(installedDir)) {
for (const entry of readdirSync(installedDir)) {
const candidates = ['pack.yaml', 'pack.yml', 'pack.json'];
for (const c of candidates) {
if (existsSync(join(installedDir, entry, c))) { installed.push(entry); break; }
}
}
}
return { bundled, installed };
},
};
const schema_stats: Operation = {
name: 'schema_stats',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Per-type page counts + typed-coverage from the DB. Returns {schema_version:1, pack_identity, aggregate, per_source, dead_prefixes}. Multi-source aware via ctx.sourceId/allowedSources.',
params: {},
scope: 'read',
handler: async (ctx) => {
const { runStatsCore } = await import('../schema-pack/stats.ts');
const scope = sourceScopeOpts(ctx);
const opts: { sourceId?: string; sourceIds?: string[] } = {};
if (scope.sourceIds && scope.sourceIds.length > 0) opts.sourceIds = scope.sourceIds;
else if (scope.sourceId) opts.sourceId = scope.sourceId;
return runStatsCore(ctx, opts);
},
};
const schema_lint: Operation = {
name: 'schema_lint',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Lint the active (or named) schema pack. File-plane rules only over MCP — the with_db option is rejected for remote callers (DB-aware rules require local CLI). Returns {ok, errors, warnings} structured report.',
params: {
pack: { type: 'string', description: 'Pack name (default: active pack)' },
},
scope: 'read',
handler: async (ctx, p) => {
const { runAllLintRules } = await import('../schema-pack/lint-rules.ts');
const { resolveLoadedPack } = await import('../schema-pack/load-active.ts');
const { gbrainPath } = await import('../config.ts');
const { existsSync } = await import('node:fs');
const { join } = await import('node:path');
let manifest;
if (p.pack) {
// Locate by name without trust-gating per-call schema_pack opt
// (that's a separate axis — this is just file lookup).
const packName = p.pack as string;
// SECURITY: `pack` is caller-supplied on a remote-reachable read op and
// is joined into a filesystem path below — an unguarded '../'-shaped
// name escapes $GBRAIN_HOME/schema-packs/ (existence oracle + arbitrary
// pack.yaml parse). Reuse the SAME name guard the mutate path uses
// (isValidPackName in schema-pack/mutate.ts) BEFORE any join.
// Anti-enumeration: invalid names answer EXACTLY like missing packs
// (pack_not_found, no path echo), never a distinct "bad name" shape.
const { isValidPackName } = await import('../schema-pack/mutate.ts');
if (!isValidPackName(packName)) return { error: 'pack_not_found', pack: packName };
const candidates = ['pack.yaml', 'pack.yml', 'pack.json'];
let path: string | null = null;
for (const c of candidates) {
const candidate = join(gbrainPath('schema-packs', packName), c);
if (existsSync(candidate)) { path = candidate; break; }
}
if (!path) return { error: 'pack_not_found', pack: packName };
const { loadPackFromFile: loader } = await import('../schema-pack/loader.ts');
// #4373: lint the MERGED manifest so extends-inherited page types
// count as declared — parity with the active-pack branch below.
manifest = (await resolveLoadedPack(loader(path))).manifest;
} else {
// #4653/#7942: the DB-plane tiers, same resolution get_active_schema_pack does.
const { loadActivePackForEngine } = await import('../schema-pack/engine-resolution.ts');
manifest = (await loadActivePackForEngine(ctx.engine, { remote: ctx.remote ?? true, sourceId: ctx.sourceId })).manifest;
}
// File-plane only over MCP; the engine-aware --with-db opt-in is
// CLI-only (Phase 5 wiring). MCP callers get the 9 file-plane rules.
return await runAllLintRules(manifest);
},
};
const schema_graph: Operation = {
name: 'schema_graph',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Schema pack graph as JSON edges. Returns {nodes: [{name, primitive}], edges: [{from, verb, to}]} derived from link_types inference + frontmatter_links.',
params: {},
scope: 'read',
handler: async (ctx) => {
const { loadActivePackForEngine } = await import('../schema-pack/engine-resolution.ts');
// #4653/#7942: the DB-plane tiers, same resolution get_active_schema_pack does.
const pack = await loadActivePackForEngine(ctx.engine, { remote: ctx.remote ?? true, sourceId: ctx.sourceId });
const nodes = pack.manifest.page_types.map((t) => ({ name: t.name, primitive: t.primitive }));
const edges: Array<{ from: string; verb: string; to: string }> = [];
for (const lt of pack.manifest.link_types) {
if (lt.inference?.page_type) {
edges.push({
from: lt.inference.page_type,
verb: lt.name,
to: lt.inference.target_type ?? '*',
});
}
}
for (const fl of pack.manifest.frontmatter_links) {
edges.push({ from: fl.page_type, verb: fl.link_type, to: '*' });
}
return { schema_version: 1, pack: pack.manifest.name, nodes, edges };
},
};
const schema_explain_type: Operation = {
name: 'schema_explain_type',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Resolved settings for a single page_type in the active pack. Returns {pack, type, primitive, path_prefixes, aliases, extractable, expert_routing}.',
params: {
type: { type: 'string', required: true, description: 'Page type name to explain' },
},
scope: 'read',
handler: async (ctx, p) => {
const { loadActivePackForEngine } = await import('../schema-pack/engine-resolution.ts');
// #4653/#7942: the DB-plane tiers, same resolution get_active_schema_pack does.
const pack = await loadActivePackForEngine(ctx.engine, { remote: ctx.remote ?? true, sourceId: ctx.sourceId });
const found = pack.manifest.page_types.find((t) => t.name === p.type);
if (!found) return { error: 'type_not_found', type: p.type as string, pack: pack.manifest.name };
return { schema_version: 1, pack: pack.manifest.name, type: found };
},
};
const schema_review_orphans: Operation = {
name: 'schema_review_orphans',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'List pages with no active-pack type match. Returns {orphan_count, orphans: [{slug, source_id}]}.',
params: {
limit: { type: 'number', description: 'Max orphans to return (default 100)' },
},
scope: 'read',
handler: async (ctx, p) => {
const limit = Math.max(1, Math.min(10000, (p.limit as number) ?? 100));
const { loadActivePackBestEffort } = await import('../schema-pack/best-effort.ts');
const { findTypeOrphans } = await import('../schema-pack/review.ts');
const { isMissingSchemaObject } = await import('../utils.ts');
const pack = await loadActivePackBestEffort(ctx);
try {
return { schema_version: 1, ...await findTypeOrphans(ctx.engine, pack?.manifest ?? null, sourceScopeOpts(ctx), limit) };
} catch (err) {
if (isMissingSchemaObject(err, 'table', 'pages')) return { schema_version: 1, orphan_count: 0, orphans: [], undeclared_types: [], pack: pack?.manifest.name ?? null, truncated: false };
throw err;
}
},
};
const schema_apply_mutations: Operation = {
name: 'schema_apply_mutations',
idempotent: false,
outputRedaction: 'no_stored_text',
description: 'Batched schema pack mutation. ATOMIC: every mutation is validated against an in-memory manifest first, and the pack file is written to disk at most once, after the FULL batch has proven valid — so a failure at any point leaves the pack file byte-identical to its pre-batch state (never a partial write). Audit log records one batch_id. Admin scope; NOT localOnly so remote agents (your OpenClaw, etc.) can author packs over normal MCP. Mutation shape per ApplyMutationsRequest type — supports add_type / remove_type / update_type / add_alias / remove_alias / add_prefix / remove_prefix / add_link_type / remove_link_type / set_extractable / set_expert_routing.',
params: {
pack: { type: 'string', required: true, description: 'Pack to mutate (must not be bundled)' },
mutations: {
type: 'array',
required: true,
description: 'Array of {op, ...args} mutation records to apply atomically',
items: { type: 'object' },
},
force: { type: 'boolean', description: 'Steal stale per-pack lock' },
},
scope: 'admin',
mutating: true,
handler: async (ctx, p) => {
const pack = p.pack as string;
const mutations = p.mutations as Array<{ op: string; [k: string]: unknown }>;
const force = p.force === true;
if (!Array.isArray(mutations) || mutations.length === 0) {
return { error: 'invalid_request', message: 'mutations must be a non-empty array' };
}
const batchId = `batch-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
const actor = ctx.auth?.clientId ? `mcp:${ctx.auth.clientId.slice(0, 8)}` : 'cli';
const sourceId = ctx.sourceId; // codex C5: write-side scoping
// `applyMutationsAtomic` (issue #2581) owns the lock + single read +
// single write for the whole batch: every mutation is validated
// in-memory first, and the pack file is written at most once, only
// after the FULL batch checks out. That is what makes this actually
// atomic (a failure at any index can never leave earlier mutations on
// disk), vs. the old per-mutation-writes-as-it-goes shape.
const { applyMutationsAtomic } = await import('../schema-pack/mutate.ts');
try {
const results = await applyMutationsAtomic(pack, mutations, {
actor: actor as 'cli' | `mcp:${string}`,
batchId,
engine: ctx.engine,
...(sourceId ? { sourceId } : {}),
...(force ? { force: true } : {}),
});
return {
schema_version: 1,
pack,
batch_id: batchId,
mutations_applied: results.length,
results,
};
} catch (e) {
const code = (e as { code?: string }).code ?? 'UNKNOWN';
const failedAtIndex = (e as { details?: { index?: number } }).details?.index;
return {
error: 'mutation_failed',
code,
message: (e as Error).message,
batch_id: batchId,
// Nothing was written to disk — applyMutationsAtomic only writes
// once, after every mutation in the batch has validated cleanly.
// (Pre-fix, this field was `partial_results` and listed mutations
// that HAD already landed on disk, because the old implementation
// wrote as it went — that shape is gone; a failed batch can no
// longer imply partial application.)
mutations_applied: 0,
pack_unchanged: true,
...(failedAtIndex !== undefined ? { failed_at_index: failedAtIndex } : {}),
};
}
},
};
const reload_schema_pack: Operation = {
name: 'reload_schema_pack',
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Flush the in-process schema pack cache so the next loadActivePack re-reads from disk. Cascades through the extends chain. Admin scope; NOT localOnly. Returns {invalidated: string[]}.',
params: {
pack: { type: 'string', description: 'Pack name to invalidate (omit to flush all)' },
},
scope: 'admin',
mutating: false, // no DB writes
handler: async (_ctx, p) => {
const { invalidatePackCache } = await import('../schema-pack/registry.ts');
return invalidatePackCache(p.pack as string | undefined);
},
};
export const schemaPacksOperations: Operation[] = [
get_active_schema_pack, list_schema_packs,
schema_stats, schema_lint, schema_graph, schema_explain_type,
schema_review_orphans,
schema_apply_mutations, reload_schema_pack,
];