Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* put_page admission for slugs that end in `.md`/`.mdx` (#4807, E-D17).
*
* A page is stored at `<slug>.md`, so a new `notes/foo.md` page would land on
* disk as `notes/foo.md.md`: reported as written, invisible to the file the
* caller meant, and re-imported by sync under the same suffixed slug. A new
* suffixed slug is refused with the bare slug as the recovery. A live page
* that already has the exact suffixed `(source_id, slug)` identity (written
* before this check) stays updatable, so its chunks and deep-research id keep
* working; the response carries an advisory naming the bare slug and the
* manual move, since master has no rename operation. A file import that takes
* its identity from a frontmatter `slug:` follows the same rule through the
* held-file path; path-derived import slugs, `validateSlug` and every internal
* stored-identity reader are unchanged.
*
* The same admission refuses a new identity whose file name no supported
* platform can store (GBRA-130 B-5, B-12: a Windows reserved device name such
* as `companies/aux`, or a segment over the 240-byte file-name budget;
* portable-slug.ts), naming the portable slug to write instead. A live page
* already holding such a slug keeps accepting updates with an advisory, and a
* replayed request never reaches this check.
*
* #7305: put_page and capture also refuse a new slug with a hyphen run or a
* segment-final hyphen (three hyphens between `notes/x-1900` and `2000-ab`, or `notes/x-`), naming the
* folded slug (`notes/x-1900-2000-ab`): import and sync derive that folded slug
* from the file, so the page would keep its identity only through the `slug:`
* line its file is stamped with (#5966), and a file rewritten without it forks
* a second page. A live page that already holds the exact slug keeps updating
* with an advisory, like the rules above; nothing is ever redirected to the
* folded slug's page.
*/
import type { BrainEngine } from '../engine.ts';
import type { ContentRefusal } from '../import-screen.ts';
import { opError, type OperationContext, type OperationError } from '../ops/contract.ts';
import { opTransport, readFix } from '../ops/op-fix.ts';
import { slugPortabilityProblem, type SlugPortabilityProblem } from '../portable-slug.ts';
import { hyphenFoldedSlug } from '../sync.ts';
const MARKDOWN_SUFFIX = /(\.mdx?)+$/i;
/** The slug without its trailing markdown extensions, or null when it has none. */
export function bareSlugOf(slug: string): string | null {
return MARKDOWN_SUFFIX.test(slug) ? slug.replace(MARKDOWN_SUFFIX, '') : null;
}
function refusal(ctx: OperationContext, bare: string): OperationError {
const cli = opTransport(ctx) === 'cli';
return opError('invalid_params', 'put_page slugs must not end in .md or .mdx.',
cli ? `Write the page as ${bare}: gbrain put ${bare} (the .md file name is added for you).`
: `Call put_page again with slug "${bare}" and the same content (the .md file name is added for you).`, {
why: 'A page is stored at <slug>.md, so a slug ending in .md would create a second extension on disk (<slug>.md.md) that the intended file never sees.',
fix: {
...readFix('Checks whether the bare slug already holds a page before writing it there.',
{ argv: ['gbrain', 'get', bare], mcp: { tool: 'get_page', arguments: { slug: bare } } }),
verify: { argv: ['gbrain', 'get', bare], mcp: { tool: 'get_page', arguments: { slug: bare } } },
},
});
}
function portabilityRefusal(ctx: OperationContext, slug: string, problem: SlugPortabilityProblem): OperationError {
const cli = opTransport(ctx) === 'cli';
const what = problem.reason === 'reserved_name' ? `"${problem.segment}" is a name Windows reserves for a device`
: `"${problem.segment.slice(0, 24)}…" is longer than the 240-byte file-name budget`;
return opError('invalid_params', `New page slugs must be portable file names: ${what}.`,
cli ? `Write the page as ${problem.suggestion}: gbrain put ${problem.suggestion}`
: `Call put_page again with slug "${problem.suggestion}" and the same content.`, {
detail: 'slug_not_portable',
why: 'Each slug segment becomes a file or directory name on disk and in exports, and that name cannot be stored on every supported platform.',
fix: {
...readFix('Checks whether the portable slug already holds a page before writing it there.',
{ argv: ['gbrain', 'get', problem.suggestion], mcp: { tool: 'get_page', arguments: { slug: problem.suggestion } } }),
verify: { argv: ['gbrain', 'get', problem.suggestion], mcp: { tool: 'get_page', arguments: { slug: problem.suggestion } } },
},
});
}
function hyphenRunRefusal(ctx: OperationContext, operation: SlugAdmissionOperation, folded: string): OperationError {
const cli = opTransport(ctx) === 'cli';
return opError('invalid_params', 'New page slugs must not contain a hyphen run or end a segment in a hyphen.',
cli ? `Write the page as ${folded}: ${operation === 'capture' ? `gbrain capture --slug ${folded}` : `gbrain put ${folded}`}`
: `Call ${operation} again with slug "${folded}" and the same content.`, {
detail: 'slug_hyphen_run',
why: `A page is stored at <slug>.md, and import and sync derive a file's slug with every hyphen run folded to one hyphen, so this file would import as ${folded}. `
+ 'The page would keep its identity only through the slug: line in its file; a copy of the file without that line forks a second page.',
fix: {
...readFix('Checks whether the folded slug already holds a page before writing it there.',
{ argv: ['gbrain', 'get', folded], mcp: { tool: 'get_page', arguments: { slug: folded } } }),
verify: { argv: ['gbrain', 'get', folded], mcp: { tool: 'get_page', arguments: { slug: folded } } },
},
});
}
type SlugAdmissionOperation = 'put_page' | 'capture';
/**
* Refuses a new slug that is suffixed, unportable (put_page only) or not
* hyphen-folded (put_page and capture); for a live exact-identity page returns
* the advisory to attach to the response. Null for every other slug.
*/
export function suffixedSlugAdmission(ctx: OperationContext, slug: string, liveExactRow: boolean, operation: SlugAdmissionOperation = 'put_page'): string | null {
const bare = operation === 'put_page' ? bareSlugOf(slug) : null;
const problem = operation === 'put_page' ? slugPortabilityProblem(bare ?? slug) : null;
const folded = bare === null && problem === null ? hyphenFoldedSlug(slug) : null;
if (bare === null && problem === null && folded === null) return null;
if (!liveExactRow) throw bare !== null ? refusal(ctx, bare) : problem !== null ? portabilityRefusal(ctx, slug, problem) : hyphenRunRefusal(ctx, operation, folded!);
const target = problem?.suggestion ?? bare ?? folded!;
const why = bare !== null ? 'ends in .md, which new pages cannot use'
: problem !== null ? 'is not a portable file name, which new pages need'
: `has a hyphen run or a segment-final hyphen, which new pages cannot use: its file path imports as "${folded}", so the page keeps its identity only through the slug: line in its file`;
return `This page's slug ${why}. To move it, put_page its content under "${target}", then delete_page "${slug}".`;
}
async function liveExactRow(engine: BrainEngine, sourceId: string, slug: string): Promise<boolean> {
const snapshot = await engine.readPageSnapshot(slug, { sourceId, includeDeleted: true });
return !!snapshot && !snapshot.page.deleted_at;
}
/** Dry-run form: reads the exact `(source_id, slug)` row itself. */
export async function suffixedSlugDryRun(ctx: OperationContext, sourceId: string, slug: string, operation: SlugAdmissionOperation = 'put_page'): Promise<void> {
if (suffixedSlugAdmission(ctx, slug, true, operation) === null) return;
suffixedSlugAdmission(ctx, slug, await liveExactRow(ctx.engine, sourceId, slug.toLowerCase()), operation);
}
/**
* The hold for a file import whose frontmatter `slug:` ends in `.md`/`.mdx`
* and names no live page. The message names the file, never the declared value.
*/
export async function suffixedFrontmatterSlugHold(engine: BrainEngine, sourceId: string | undefined, relativePath: string, slug: string): Promise<ContentRefusal | null> {
if (bareSlugOf(slug) === null || await liveExactRow(engine, sourceId ?? 'default', slug)) return null;
return { code: 'frontmatter_slug_conflict', key: 'slug',
message: `The frontmatter slug of ${relativePath} must not end in .md or .mdx: a page is stored at <slug>.md, so it would create a second extension on disk. Remove the extension from the "slug:" line, or remove the line.` };
}