Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { funnelPassThrough } from '../funnel.ts';
import { suffixedSlugDryRun } from '../persistence/suffixed-slug.ts';
import { AGENT_CONTENT_PARAMS, PAGE_MUTATION_PARAMS, CAPTURE_EVENT_PARAMS, CAPTURE_CLI_PROVENANCE_PARAMS, REASON_PARAM, WRITE_WAIT_PARAM } from '../persistence/params.ts';
import { assertPurgeParams } from '../persistence/purge-params.ts';
/**
* Page CRUD operation cluster — pure move from operations.ts (v0.46.x
* tranche 1). Op consts stay module-private; `pagesOperations` below lists
* them in EXACTLY the order they appear in the canonical `operations` array
* in ../operations.ts (order is contractual — docs/TOOL_CATALOG.md is
* generated from that array). Never import from '../operations.ts' here
* (cycle); shared contract/context helpers come from the ops/ foundation.
*/
import { clampSearchLimit, type BrainEngine } from '../engine.ts';
import type { Page } from '../types.ts';
import { decodeDeepResearchAnchor, decodeDeepResearchId, deepResearchPageUrl } from '../deep-research-id.ts';
import { PageSnapshotAmbiguousError, type PageSnapshot } from '../page-state/types.ts';
import { serializePageToMarkdown } from '../markdown.ts';
import { neutralizesBody, pageTrustForRead, projectFetchText, projectGetPage, quotedPageMeta, quotesBody, readQuarantined, unverifiedOriginNotice } from './get-page-projection.ts';
import { assertLargePageAdmission } from '../persistence/large-page-guard.ts';
import { assertFullReadFits, bodyBytes, fetchWindowResult, GET_PAGE_BODY_PARAMS, inlineBodyBytes, parseBodyRequest, readPartialBody, segmentedFullReadError, authorizedReadPin } from './get-page-body.ts';
import { isSegmentedPage } from '../page-body/page-shape.ts';
import { MIN_TRUST_PARAM } from '../eligibility/policy.ts';
import { getPageKnownAsOf, KNOWN_AS_OF_PARAM } from './known-as-of.ts';
import { AS_OF_PARAM, getPageAsOf } from './valid-time-read.ts';
import { currentValidTime } from '../valid-time.ts';
import { stampRowTrust } from '../eligibility/stamp.ts';
import { quoteTimelineRows } from './timeline-quote.ts';
import { isAutoLinkEnabled } from '../link-extraction.ts';
import { sanitizeRemoteBody } from '../remote-body.ts';
import { getContentFlag } from '../quarantine.ts';
import { fileHeldField, readHeldPages } from '../persistence/held-reads.ts';
import { bumpLastRetrievedAt } from '../last-retrieved.ts';
import { resolveExcludePrivatePages, isPrivatePage, findPrivateOnlySlugs, isPrivatePageForCaller } from '../search/private-visibility.ts';
import { heldRowsForCaller } from '../eligibility/fence-overlay.ts';
import { unquoteAnyTranscriptText } from '../search/transcript-quote.ts';
import { withIgnoredPrivacyLabelNotice } from '../search/ignored-privacy-labels.ts';
import { withImplicitPlacement } from '../access/implicit-placement.ts';
import { LIST_PAGES_DESCRIPTION, CAPTURE_DESCRIPTION } from '../operations-descriptions.ts';
import { listPagesPagination, listingTruncatedNotice, unusedTypeNotice } from './list-pages-pagination.ts';
import { OperationError, opError, type Operation, type OperationContext } from './contract.ts';
import { invalidParam, readFix } from './op-fix.ts';
import { WHERE_PARAM, whereOpParam } from './where-param.ts';
import { parseSourceIdsParam, requestSourceScope, SOURCE_IDS_PARAM } from './search-source-scope.ts';
import { isDatetimeInputError } from '../utils.ts';
import { rethrowNamingRevisionSource } from './put-page-revision-source.ts';
import {
assertExplicitSourceLive,
enforceSubagentSlugFence,
slugOutsideCallerFence,
enforceClientSlugFence,
federatedSearchScope,
normalizeSlugPrefix,
parseSourceIdParam,
readPolicyOpts,
validatePageSlug, pageNotFoundError,
} from './context.ts';
/** The write path (journal, persistence service, sync), loaded by the mutating handlers only: a cold `gbrain get` never needs it (#7147). */
const pageMutations = () => import('../persistence/page-mutations.ts');
// --- Page CRUD ---
/**
* #4352 remediation — filter fuzzy-resolution candidates so get_page's
* ambiguous_slug candidate list can't enumerate private slugs to an
* untrusted caller. Probe SQL lives ONCE in findPrivateOnlySlugs (a slug
* with at least one non-private in-scope page stays visible; candidates
* come from resolveSlugs, so every slug has a live page row).
* Order-preserving (resolveSlugs returns ranked candidates). Read-only,
* scope-threaded — not a getPage/putPage pair (no unscoped-check/scoped-write
* hazard).
*/
async function dropPrivateSlugs(
engine: BrainEngine,
candidates: string[],
scope: { sourceId?: string; sourceIds?: string[] },
includeDeleted: boolean,
): Promise<string[]> {
const hidden = await findPrivateOnlySlugs(engine, candidates, scope, { includeDeleted });
return candidates.filter(c => !hidden.has(c));
}
/**
* #3625: strip the takes/private-facts fences from BOTH compiled_truth and
* timeline before a page reaches an untrusted reader. Pre-#3625 this only
* covered compiled_truth — a `## Facts` fence written below the
* `<!-- timeline -->` sentinel lands in the `timeline` column (splitBody's
* split boundary), which get_page/fetch_page returned verbatim, unstripped.
* A private fact fence misplaced there was fully readable by any remote MCP
* caller. Same stripping rule as compiled_truth: takes fence dropped
* entirely, facts fence keeps only `world`-visibility rows, less those held from a world-only caller (GST-2891).
*/
async function stripPrivacyFencesForRemoteReader(ctx: OperationContext, page: Page): Promise<Page> {
const omitRows = await heldRowsForCaller(ctx.engine, ctx.remote, { sourceId: page.source_id, slug: page.slug, compiled_truth: page.compiled_truth, timeline: page.timeline });
const opts = { includeWithdrawn: true, keepMaterializedMarkers: true, omitRows }; // #5567: markers round-trip remote edits
return { ...page, compiled_truth: sanitizeRemoteBody(page.compiled_truth, opts), timeline: sanitizeRemoteBody(page.timeline ?? '', opts) };
}
const get_page: Operation = {
name: 'get_page',
idempotent: true,
outputRedaction: { exempt: 'explicit page read by slug/id; governed by page visibility, not output redaction (CEO-17 raw-read exception)' },
description: 'Read a page; `section`/`grep` reads one part. Window selector order: cursor, around_chunk_id, lines, bytes (context only with grep). Edit: include_content:true, `content` to put_page, or edit_page. >256 KB: outline+window, then `next`.',
params: {
slug: { type: 'string', description: 'Page slug.', required: true },
fuzzy: { type: 'boolean', description: 'Fuzzy match.', fullSurfaceOnly: true },
include_content: { type: 'boolean', description: 'Markdown + revision.' },
content_only: { type: 'boolean', description: 'Round-trip fields.', fullSurfaceOnly: true },
...GET_PAGE_BODY_PARAMS,
include_deleted: { type: 'boolean', description: 'Soft-deleted too.', fullSurfaceOnly: true },
include_timeline_entries: { type: 'boolean', description: 'Timeline rows.', fullSurfaceOnly: true },
grammar_diagnostics: { type: 'boolean', description: 'Also return every line-grammar finding for the page.', fullSurfaceOnly: true },
source_id: { type: 'string', description: "One source, or '__all__'." },
include_quarantined: { type: 'boolean', description: 'Admin: quarantined body.', fullSurfaceOnly: true },
min_trust: MIN_TRUST_PARAM,
known_as_of: KNOWN_AS_OF_PARAM,
as_of: AS_OF_PARAM,
},
handler: async (ctx, p) => {
if (p.as_of !== undefined) return getPageAsOf(ctx, p);
if (p.known_as_of !== undefined) return getPageKnownAsOf(ctx, p);
const slug = p.slug as string;
const fuzzy = (p.fuzzy as boolean) || false;
const includeDeleted = (p.include_deleted as boolean) === true;
// Large pages: resolve the body mode first, so a malformed selector fails before any read.
const bodyRequest = parseBodyRequest(ctx, p);
const contentOnly = p.content_only === true;
const includeContent = p.include_content === true;
const includeTimelineEntries = (p.include_timeline_entries as boolean) === true;
// #4329: honor a per-call source_id (pre-fix it was silently dropped).
// resolveRequestedScope (inside federatedSearchScope) enforces the remote
// caller's grant on the explicit value.
const sourceIdParam = parseSourceIdParam(p.source_id, 'get_page', { allowAll: true });
// #1393: route BOTH the exact-match read and the fuzzy resolveSlugs through
// the canonical precedence ladder (federated array > scalar > nothing). The
// exact path previously used scalar `ctx.sourceId` only, so a remote client
// with a federated `allowedSources` grant (and no single ctx.sourceId) got
// an UNSCOPED exact lookup — a cross-source read of any page by slug. getPage
// now honors sourceIds[] (both engines), so the same scope closes both paths.
// #3242: federatedSearchScope (not bare sourceScopeOpts) so an unqualified
// read sees pages in `federated: true` sources, matching search/query.
const sourceOpts = federatedSearchScope(ctx, sourceIdParam);
// #4620: an explicit source_id must name a live source (after the grant check).
await assertExplicitSourceLive(ctx, sourceIdParam);
const fuzzyScope = sourceOpts;
// #4352 remediation: untrusted callers never read `visibility: private`
// bodies — the same resolveExcludePrivatePages gate search/recall/entity
// already apply (trusted local + the operator opt-outs resolve to false).
// A gated private page behaves exactly like a missing one (no existence
// oracle), composing with — not replacing — the source-grant scope above.
const excludePrivate = await resolveExcludePrivatePages(ctx.engine, ctx.remote);
let snapshot = await ctx.engine.readPageSnapshot(slug, { includeDeleted, excludePrivate, ...sourceOpts, resolveAlias: true });
let page = snapshot?.page ?? null;
if (page && excludePrivate && isPrivatePageForCaller(page)) page = null;
let resolved_slug: string | undefined = page && page.slug !== slug ? page.slug : undefined;
if (!page && fuzzy) {
const fallback = await ctx.engine.transaction(async tx => {
await tx.executeRaw('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ');
let candidates = await tx.resolveSlugs(slug, { ...fuzzyScope, excludePrivate });
if (excludePrivate && candidates.length > 0) {
candidates = await dropPrivateSlugs(tx, candidates, fuzzyScope, includeDeleted);
}
return { candidates, snapshot: candidates.length === 1
? await tx.readPageSnapshot(candidates[0], { includeDeleted, excludePrivate, ...sourceOpts }) : null };
});
if (fallback.candidates.length > 1) return { error: 'ambiguous_slug', candidates: fallback.candidates };
if (fallback.snapshot && !(excludePrivate && isPrivatePageForCaller(fallback.snapshot.page))) {
snapshot = fallback.snapshot;
page = snapshot.page;
resolved_slug = page.slug;
}
}
if (!page) {
let elsewhereSource: string | undefined;
// #4516: source scoping is by-design isolation, but the miss diagnostic
// should say WHERE the slug actually lives. Trusted local callers only
// (`ctx.remote === false`) — for a remote caller the probe would be a
// cross-source existence oracle outside its grant. Only when the lookup
// was actually scoped (an unscoped read already spanned every source).
if (ctx.remote === false && (sourceOpts.sourceId !== undefined || sourceOpts.sourceIds !== undefined)) {
try {
// gbrain-allow-unscoped-getpage: read-only diagnostic existence probe —
// deliberately spans all sources to name where the slug lives.
const elsewhere = await ctx.engine.getPage(slug, { includeDeleted });
if (elsewhere && !(excludePrivate && isPrivatePage(elsewhere))) {
elsewhereSource = elsewhere.source_id;
}
} catch {
// Diagnostic only — a probe failure must never mask the real error.
}
}
throw pageNotFoundError(ctx, slug, { includeDeleted, sourceIdParam, elsewhereSource });
}
const readable = await pageTrustForRead(ctx, page, p.min_trust); // #5575: below the read floor reads as missing
if (!readable) throw pageNotFoundError(ctx, slug, { includeDeleted, sourceIdParam });
// v0.37.0 (D11): op-layer write-back for the `last_retrieved_at` stale
// signal. Fire-and-forget — caller does NOT await. Internal callers
// (sync, migrations, dream cycle) bypass this op handler so the signal
// stays clean. Throttled to ~1 write / 5 min per page via the SQL clause
// inside bumpLastRetrievedAt (D2).
bumpLastRetrievedAt(ctx.engine, [page.id]);
// #2200: tags come from the concrete page's source: federated `sourceOpts` has no
// scalar sourceId, and getTags would fall back to 'default' (the wrong source).
const tags = snapshot!.tags;
// Only explicitly trusted local reads retain protected body sections.
// Holder grants and page-visibility opt-outs do not bypass this boundary.
const isUntrustedReader = ctx.remote !== false;
const visibleBody = isUntrustedReader && page.body_storage !== 'segmented' ? await stripPrivacyFencesForRemoteReader(ctx, page) : page;
// v0.42 (#1699) agent-warning channel: surface the page's content_flag
// marker as a top-level field (parallel to SearchResult.content_flag) so
// an agent reading a page directly gets the same "this looks odd, examine
// it" signal it would get from search. The marker is also in frontmatter;
// this is the clean, documented accessor.
const content_flag = getContentFlag(page.frontmatter as Record<string, unknown> | null);
// #5988: sync holds the page's newer file (one indexed lookup, fail-open).
const held = (await readHeldPages(ctx.engine, [page.id], ctx).catch(() => null))?.get(page.id);
// #2225: `content` is the canonical serialized markdown (frontmatter +
// compiled_truth + `<!-- timeline -->` sentinel + timeline). Clients that
// edit-and-put_page this field round-trip losslessly; hand-concatenating
// compiled_truth + timeline without the sentinel used to silently destroy
// pages.timeline on the next write. Built from visibleBody so the
// privacy-fence strip above applies to untrusted readers here too.
// Opt-in (include_content: true): get_page is the most-called read op, and
// `content` roughly duplicates compiled_truth + timeline — always emitting
// it would double every reader's payload for the round-trip minority.
const timelineEntries = includeTimelineEntries
? await quoteTimelineRows(ctx, page.slug, await stampRowTrust(ctx.engine, 'timeline_entries', await ctx.engine.getTimeline(page.slug, { ...await readPolicyOpts(ctx, { sourceId: page.source_id }), eligibility: readable.eligibility }), e => e.id)) : undefined;
// Read-only, over the same visibility-filtered body the reader gets.
const lineGrammar = p.grammar_diagnostics !== true ? undefined : await (await import('../line-grammar-report.ts')).grammarDiagnosticsForPage(ctx.engine, page, visibleBody);
const quarantined = readQuarantined(ctx, page, p.include_quarantined === true); // #6259
unverifiedOriginNotice(ctx, page, readable.trust);
const fenceHeld = (await (await import('../generations/fence.ts')).fenceHoldEntries(ctx.engine, [page.source_id], { slug: page.slug }).catch(() => [])).map(({ source_id: _s, slug: _g, ...hold }) => hold); const fileHeld = { ...(held ? { file_held: fileHeldField(held, isUntrustedReader) } : {}), ...(fenceHeld.length ? { fence_held: fenceHeld } : {}) };
const segmented = isSegmentedPage(page);
// GBRA-217 (B7): a current page not in force today says so; a page with no valid_from / valid_until reads as before.
const validTime = currentValidTime(page.frontmatter as Record<string, unknown> | null);
const pin = authorizedReadPin(ctx, page, snapshot!.bodyGeneration, p.min_trust, () => pageNotFoundError(ctx, slug, { includeDeleted, sourceIdParam }));
const whole = bodyRequest.mode === 'full'
|| (bodyRequest.mode === 'auto' && !segmented && bodyBytes(visibleBody) <= await inlineBodyBytes(ctx));
if (!whole) {
const partial = await readPartialBody(ctx, { page, visibleBody, revision: snapshot!.revision, tags, quarantined, trust: readable.trust, pin, quote: quotesBody(ctx, page, readable.trust), neutralize: neutralizesBody(ctx, page),
extras: { ...(quarantined ? { quarantined } : {}), ...(timelineEntries ? { timeline_entries: timelineEntries } : {}), ...fileHeld,
...(resolved_slug ? { resolved_slug } : {}), ...(content_flag ? { content_flag } : {}), ...(validTime ? { valid_time: validTime } : {}) } }, bodyRequest);
return lineGrammar ? { ...partial, line_grammar: lineGrammar } : partial;
}
if (segmented) throw await segmentedFullReadError(ctx, page, bodyRequest, { ...pin, revision: snapshot!.revision });
const projected = projectGetPage(visibleBody, {
revision: snapshot!.revision, tags, includeContent, contentOnly, resolved_slug, content_flag, quarantined, trust: readable.trust, quote: quotesBody(ctx, page, readable.trust), neutralize: neutralizesBody(ctx, page),
...(timelineEntries ? { timeline_entries: timelineEntries } : {}),
...fileHeld,
});
if (ctx.remote !== false) await assertFullReadFits(ctx, visibleBody, projected, bodyRequest);
const withValidTime = validTime ? { ...projected, valid_time: validTime } : projected;
return lineGrammar ? { ...withValidTime, line_grammar: lineGrammar } : withValidTime;
},
scope: 'read', mutating: false,
cliHints: { name: 'get', positional: ['slug'] },
};
const fetch_page: Operation = {
name: 'fetch',
idempotent: true,
outputRedaction: { exempt: 'explicit page read by slug/id; governed by page visibility, not output redaction (CEO-17 raw-read exception)' },
description: "Fetch the full text of one search result by its opaque, source-qualified `id` (OpenAI deep-research contract: the search/fetch pair). Pass the id unchanged; it does not grant access. Legacy slug ids work only when unambiguous within your current read scope. Returns { id, title, text, url, metadata } — `text` is the page's canonical markdown; a page over 256 KB returns the window around the searched chunk instead, with metadata.total_bytes and metadata.next_id (fetch it to read on). For fuzzy slugs, soft-delete recovery, or lossless edit round-trips, use get_page.",
params: {
id: { type: 'string', required: true, description: 'Opaque result id from a prior `search` call. Pass unchanged. Unambiguous legacy slugs are also accepted.' },
include_quarantined: { type: 'boolean', description: 'Admin: quarantined body.' },
min_trust: MIN_TRUST_PARAM,
},
handler: async (ctx, p) => {
const id = p.id as string;
if (typeof id !== 'string' || !id.trim()) {
throw opError('invalid_params', 'fetch requires a non-empty id', 'Pass the `id` field from a `search` result. Search rows carry `id` only when `fetch` is callable on this connection, so a row from a search run before `fetch` was callable has none: re-run `search` now that `fetch` is callable, or pass the row\'s `slug` as `id` (accepted when it is unambiguous within your read scope).');
}
let identity: ReturnType<typeof decodeDeepResearchId>;
try { identity = decodeDeepResearchId(id); }
catch { throw opError('invalid_params', 'Invalid fetch result id', 'Pass the unchanged `id` field from a `search` result.'); }
const slug = identity?.slug ?? id.trim();
const missing = () => opError('page_not_found', 'Page not found', 'Pass an id returned by a current `search` call.');
let sourceOpts: ReturnType<typeof federatedSearchScope>;
try { sourceOpts = federatedSearchScope(ctx, identity?.sourceId); }
catch (error) {
if (error instanceof OperationError && error.code === 'permission_denied') throw missing();
throw error;
}
if (ctx.remote !== false && sourceOpts.sourceIds === undefined && sourceOpts.sourceId === undefined) throw missing();
if (identity) {
if (ctx.remote !== false && (sourceOpts.sourceIds !== undefined
? !sourceOpts.sourceIds.includes(identity.sourceId)
: sourceOpts.sourceId !== undefined && sourceOpts.sourceId !== identity.sourceId)) throw missing();
sourceOpts = { sourceId: identity.sourceId };
}
const excludePrivate = await resolveExcludePrivatePages(ctx.engine, ctx.remote);
let snapshot: PageSnapshot | null;
try {
snapshot = await ctx.engine.readPageSnapshot(slug, {
...sourceOpts, excludePrivate, resolveAlias: true, requireUnambiguous: identity === null, requireLiveSource: true, preserveExactIdentity: true,
});
} catch (error) {
if (error instanceof PageSnapshotAmbiguousError) {
throw opError('ambiguous_id', 'The legacy id matches multiple readable pages', 'Search again and pass the source-qualified result id.');
}
throw error;
}
const page = snapshot?.page;
if (!page || (excludePrivate && isPrivatePageForCaller(page))) throw missing();
const readable = await pageTrustForRead(ctx, page, p.min_trust); // #5575: below the read floor reads as missing
if (!readable) throw missing();
bumpLastRetrievedAt(ctx.engine, [page.id]);
const tags = snapshot!.tags;
// Same boundaries as get_page: untrusted readers never see takes or private facts fences, nor a quarantined body (#6259).
const segmented = isSegmentedPage(page);
const visibleBody = ctx.remote === false || segmented ? page : await stripPrivacyFencesForRemoteReader(ctx, page);
const quarantined = readQuarantined(ctx, page, p.include_quarantined === true);
unverifiedOriginNotice(ctx, page, readable.trust);
if (!quarantined?.body_omitted && (segmented || (ctx.remote !== false && bodyBytes(visibleBody) > await inlineBodyBytes(ctx)))) {
const pin = authorizedReadPin(ctx, page, snapshot!.bodyGeneration, p.min_trust, missing);
return fetchWindowResult(ctx, { page, visibleBody: visibleBody as Page, revision: snapshot!.revision, tags, quarantined, trust: readable.trust, extras: {}, pin, quote: quotesBody(ctx, page, readable.trust), neutralize: neutralizesBody(ctx, page) }, id, identity ? decodeDeepResearchAnchor(id) : null);
}
const meta = quotedPageMeta(page, quotesBody(ctx, page, readable.trust), tags);
return { id: identity ? id : page.slug, title: meta.title,
text: projectFetchText(visibleBody as Page, tags, quarantined, readable.trust, quotesBody(ctx, page, readable.trust), neutralizesBody(ctx, page)),
// Pages have no public http home; a stable brain-local URI satisfies
// the contract's citation slot without inventing a fake web URL.
url: deepResearchPageUrl(page.source_id, page.slug),
metadata: {
revision: snapshot!.revision,
type: page.type,
source_id: page.source_id,
updated_at: page.updated_at,
tags: meta.tags, ...(quarantined ? { quarantined } : {}), ...readable.trust, ...(quotesBody(ctx, page, readable.trust) ? { quoted: 'transcript' } : {}),
},
};
},
scope: 'read', mutating: false,
cliHints: { name: 'fetch', positional: ['id'] },
};
const put_page: Operation = {
name: 'put_page',
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Complete content REPLACES the whole page: read get_page include_content:true; its revision is expected_revision. Keep a request_id UUID; retry with identical arguments. Remote callers: existing-page [[links]] become mentions; typed links are skipped (stdio `gbrain serve` sweeps later, `gbrain serve --http` does not self-sweep). Edits: edit_page; appends: append_page; >3 pages: put_pages.',
params: {
...AGENT_CONTENT_PARAMS,
slug: { type: 'string', description: 'Page slug.', required: true },
content: { type: 'string', required: true, description: 'Complete markdown (get_page include_content:true).' },
allow_empty: { type: 'boolean', required: false, description: 'Allow an empty page.', fullSurfaceOnly: true },
allow_shrink: { type: 'boolean', required: false, description: 'Allow content under half a >256 KB page. To add text use append_page, not a re-put; a page over one request goes by begin_page_upload.', fullSurfaceOnly: true },
drop_timeline: { type: 'boolean', required: false, description: 'No Timeline in content: delete its entries.', fullSurfaceOnly: true },
wait_ms: WRITE_WAIT_PARAM, reason: REASON_PARAM,
// v0.39.3.0 provenance write-through (WARN-8 + A1 + CV6). Optional fields
// for trusted local callers (capture CLI, autopilot, dream cycle). Remote
// MCP callers (ctx.remote !== false) have their values OVERRIDDEN with
// server stamps below; the params are accepted on the wire only so the
// op schema stays uniform across transports. Audit-trail spoofing is
// closed structurally — clients cannot poison source_kind labels.
source_kind: { type: 'string', description: 'Server-set remotely.', required: false, fullSurfaceOnly: true },
source_uri: { type: 'string', description: 'Server-set remotely.', required: false, fullSurfaceOnly: true },
ingested_via: { type: 'string', description: 'Server-set remotely.', required: false, fullSurfaceOnly: true },
},
mutating: true,
scope: 'write',
handler: async (ctx, p) => {
const { pageMutationSource, submitPageMutation } = await pageMutations();
const sourceId = pageMutationSource(ctx, p, 'put_page');
if (ctx.dryRun) {
if (typeof p.slug === 'string') {
validatePageSlug(p.slug);
enforceClientSlugFence(ctx, p.slug, 'put_page');
enforceSubagentSlugFence(ctx, p.slug, 'put_page');
await suffixedSlugDryRun(ctx, sourceId, p.slug);
}
return { dry_run: true, action: 'put_page', slug: p.slug };
}
if (ctx.remote !== false && typeof p.slug === 'string') await assertLargePageAdmission(ctx.engine, p.slug, sourceId, p);
(await import('../persistence/page-visibility.ts')).assertSubmittedReaders(ctx.remote, p.slug, p.content);
return submitPageMutation(ctx, { operation: 'put_page', params: p }).then(funnelPassThrough('save')).catch(error => rethrowNamingRevisionSource(ctx, sourceId, p, error)).then(result => withIgnoredPrivacyLabelNotice(ctx, sourceId, p, result)).then(result => withImplicitPlacement(ctx, sourceId, p, result));
},
cliHints: { name: 'put', positional: ['slug'], stdin: 'content' },
};
// v0.31.2: isFactsBackstopEligible moved to src/core/facts/eligibility.ts
// so sync.ts, file_upload, code_import, and runFactsBackstop all share one
// predicate. Imported above.
/** Legacy key export retained for callers; publication now uses canonical page guards. */
export function autoLinkLockKey(sourceId: string | undefined, slug: string): string {
return `auto_link:${sourceId ?? ''}:${slug}`;
}
/** Revisit forward references after a oneshot batch, conditional on its current snapshot. */
export async function autoLinkWrittenPage(
engine: BrainEngine,
slug: string,
opts?: { sourceId?: string },
): Promise<void> {
try {
if (!(await isAutoLinkEnabled(engine))) return;
await runAutoLink(engine, slug, opts);
} catch (e) {
process.stderr.write(`[oneshot] post-batch auto-link for ${slug} failed (best-effort): ${e instanceof Error ? e.message : String(e)}\n`);
}
}
/** Reconcile derived links only if the prepared canonical snapshot is still current. */
async function runAutoLink(
engine: BrainEngine,
slug: string,
opts?: { sourceId?: string },
) {
const sourceId = opts?.sourceId ?? 'default';
const snapshot = await engine.readPageSnapshot(slug, { sourceId });
if (!snapshot) return;
const { prepareAutomaticLinks } = await import('../persistence/links-preparation.ts');
snapshot.page.frontmatter ??= {};
const prepared = await prepareAutomaticLinks(engine, slug, snapshot.page, sourceId);
return engine.transaction(async tx => {
await tx.lockPageKeys([{sourceId,slug}, ...prepared.pageKeys]);
const current = await tx.readPageSnapshot(slug, {sourceId});
if (!current || current.page.id !== snapshot.page.id || current.revision !== snapshot.revision) return;
return prepared.apply(tx);
});
}
const delete_page: Operation = {
name: 'delete_page',
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Soft-delete a page and remove its markdown file from the source working tree (the source local_path, or sync.repo_path when the source has none). File removal is skipped when sync.write_through is off; the committed receipt reports the persistence mode and write_through outcome. Read the page revision first and pass expected_revision; retain request_id for replay. The row is hidden from search and from get_page/list_pages, but is recoverable via restore_page within 72h, which re-creates the file. The autopilot purge phase hard-deletes after the recovery window. Pass include_deleted: true to get_page to verify the soft-delete landed. A page whose file another live page of the source records is hidden without touching that file (receipt write_through.skipped: shared_origin): the file and the surviving page remain, nothing is erased, and the warning names gbrain repair file-drift --prefer file, which imports the file\'s current content into the surviving page (sync holds that page file_drift rather than overwrite it). purge: true is trusted-local CLI only and removes the row, chunks, links and raw data immediately after its recorded markdown artifact is removed. Purge uses the same revision, request_id and recovery protocol, including for existing tombstones. A removal failure preserves the prior row and never reports purge success; repair the artifact and submit a new request_id. A purge of a page whose file is shared refuses and names the soft delete. A committed purge warns that git history, synced copies, exports and derived rows may retain content; rotate exposed credentials. Before the row is removed, pages that are private only through this page get their own visibility: private; a purge that cannot label them soft-deletes the page instead and returns purge_held (doctor derived_origin_parked).',
params: {
...PAGE_MUTATION_PARAMS, expected_revision: { type: 'string', description: 'Revision read; required unless force.' },
slug: { type: 'string', required: true, description: "Slug of the page to soft-delete, e.g. 'people/alice-example'." },
source_id: { type: 'string', description: "#4329: source holding the row to soft-delete (a multi-source brain can hold the same slug in several sources). Defaults to ctx.sourceId. Remote callers may only target their write source — federated read grants do not confer delete access." },
purge: { type: 'boolean', description: 'Hard-delete after coordinated artifact removal (no 72h recovery; status purged). Honored only for the trusted local CLI; remote/MCP callers get permission_denied (a non-boolean value is invalid_params) and keep the soft-delete path.' },
},
mutating: true,
scope: 'write',
handler: async (ctx, p) => {
const { pageMutationSource, validateMutationSlug } = await pageMutations();
const sourceId = pageMutationSource(ctx, p, 'delete_page');
assertPurgeParams(p, ctx.remote);
if (ctx.dryRun) {
if (typeof p.slug === 'string') {
await validateMutationSlug(ctx, 'delete_page', p.slug, sourceId);
enforceClientSlugFence(ctx, p.slug, 'delete_page');
enforceSubagentSlugFence(ctx, p.slug, 'delete_page');
}
return { dry_run: true, action: p.purge === true ? 'purge_page' : 'delete_page', slug: p.slug };
}
return (await import('../repair/origin-carry.ts')).deletePageCarryingPrivate(ctx, p, sourceId);
},
cliHints: { name: 'delete', positional: ['slug'] },
};
const restore_page: Operation = {
name: 'restore_page',
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Restore a soft-deleted page (clear deleted_at) and re-create its markdown file on disk (the counterpart to delete_page removing it; the result write_through field reports the outcome). Returns success only if the page was actually soft-deleted. After this op, the page reappears in search and in get_page/list_pages without the include_deleted flag. A restore that writes no file refuses (source_changed, detail canonical_file_absent) when the page\'s recorded file is gone from the checkout, because the next full sync would delete it again; the user chooses between putting the file back and detach: true.',
params: {
...PAGE_MUTATION_PARAMS,
slug: { type: 'string', required: true, description: "Slug of the soft-deleted page to restore, e.g. 'people/alice-example'." },
source_id: { type: 'string', description: "#4329: source holding the row to restore (a multi-source brain can hold the same slug in several sources). Defaults to ctx.sourceId. Remote callers may only target their write source — federated read grants do not confer restore access." },
detach: { type: 'boolean', description: 'Restore a page whose recorded canonical file is gone from the checkout as a database-only page: it forgets the file, so sync never deletes it again. Only accepted when a plain restore refuses with canonical_file_absent, or for a page under a declared storage.db_only dir whose recorded file left the checkout; ask the user first.' },
},
mutating: true,
scope: 'write',
handler: async (ctx, p) => {
const { pageMutationSource, submitPageMutation, validateMutationSlug } = await pageMutations();
const sourceId = pageMutationSource(ctx, p, 'restore_page');
if (ctx.dryRun) {
if (typeof p.slug === 'string') {
await validateMutationSlug(ctx, 'restore_page', p.slug, sourceId);
enforceClientSlugFence(ctx, p.slug, 'restore_page');
enforceSubagentSlugFence(ctx, p.slug, 'restore_page');
}
return { dry_run: true, action: 'restore_page', slug: p.slug };
}
return submitPageMutation(ctx, { operation: 'restore_page', params: p });
},
cliHints: { name: 'restore', positional: ['slug'] },
};
const purge_deleted_pages: Operation = {
name: 'purge_deleted_pages',
idempotent: false,
outputRedaction: 'no_stored_text',
description: 'Admin-only. Hard-deletes pages whose deleted_at is older than older_than_hours (default 72), in every source. Cascades through content_chunks, page_links, chunk_relations. Trusted local CLI only; the command is `gbrain pages purge-deleted`, which asks first (yes: true is the consent). Manual escape hatch alongside the autopilot purge phase.',
params: {
older_than_hours: { type: 'number', description: 'Age cutoff in hours. Default 72.' },
yes: { type: 'boolean', description: 'Consent to the irreversible brain-wide purge. Ask the user first.' },
},
mutating: true,
scope: 'admin',
localOnly: true, cliOnly: { argv: ['gbrain', 'pages', 'purge-deleted', '--dry-run', '--json'] },
handler: async (ctx, p) => {
const olderThanHours = (p.older_than_hours as number | undefined) ?? 72;
if (ctx.dryRun) return { dry_run: true, action: 'purge_deleted_pages', older_than_hours: olderThanHours };
if (ctx.remote !== false) throw (await import('./callable.ts')).cliOnlyRefusal(purge_deleted_pages);
return (await import('../persistence/purge-deleted.ts')).consentedPurgeDeletedPages(ctx.engine, olderThanHours, p.yes === true);
},
cliHints: { name: 'purge-deleted', hidden: true },
};
const LIST_PAGES_SORT_VALUES = ['updated_desc', 'updated_asc', 'created_desc', 'slug'] as const;
type ListPagesSort = typeof LIST_PAGES_SORT_VALUES[number];
const list_pages: Operation = {
name: 'list_pages',
idempotent: true,
outputRedaction: 'retrieval',
description: LIST_PAGES_DESCRIPTION,
params: {
type: { type: 'string', description: 'Page type.' },
tag: { type: 'string', description: 'Tag.' },
limit: { type: 'number', description: 'Remote max 100.' },
offset: {
type: 'number', description: 'Rows to skip.', fullSurfaceOnly: true,
},
// v0.29 — surface filter that already exists on PageFilters.
updated_after: {
type: 'string',
description: 'ISO time.',
},
updated_after_slug: {
type: 'string',
description: "Last row's slug (with updated_after).",
},
sort: {
type: 'string', description: 'Default updated_desc.',
enum: [...LIST_PAGES_SORT_VALUES],
},
include_deleted: { type: 'boolean', description: 'Include soft-deleted pages.', fullSurfaceOnly: true },
slug_prefix: { type: 'string', description: "Literal slug prefix, e.g. 'deals/'.", fullSurfaceOnly: true },
where: WHERE_PARAM,
// #4400 — list_pages had no source-scoping param at all: unlike
// search/query it silently ignored any caller-supplied source and always
// fell back to whatever federatedSearchScope() resolved from ctx alone,
// so a non-federated source's pages could never be enumerated remotely
// (get_stats counts them; list_pages could not list them). Mirrors the
// `source_id` param already on search/query, same '__all__' semantics.
source_id: {
type: 'string',
description: "One source, or '__all__'.",
},
source_ids: { ...SOURCE_IDS_PARAM, fullSurfaceOnly: true },
},
handler: async (ctx, p) => {
// Whitelist the sort enum at the handler before passing to the engine.
// Engines also whitelist via PAGE_SORT_SQL but defending here keeps
// unsupported strings from reaching the SQL layer.
const rawSort = p.sort as string | undefined;
let sort = rawSort && (LIST_PAGES_SORT_VALUES as readonly string[]).includes(rawSort)
? (rawSort as ListPagesSort)
: undefined;
// The keyset is only coherent under updated_asc's (updated_at, slug) total order.
const updatedAfter = typeof p.updated_after === 'string' ? p.updated_after : undefined;
const updatedAfterSlug = typeof p.updated_after_slug === 'string' ? p.updated_after_slug : undefined;
if (updatedAfterSlug !== undefined && updatedAfter === undefined) {
throw invalidParam(ctx, 'list_pages', 'updated_after', "list_pages: updated_after_slug requires updated_after (the cursor row's updated_at_iso).", { def: list_pages.params.updated_after, example: '2026-08-11T00:00:00.000000Z' });
}
const updatedAfterKeyset = updatedAfter !== undefined && updatedAfterSlug !== undefined
? { updatedAt: updatedAfter, slug: updatedAfterSlug }
: undefined;
if (updatedAfterKeyset) sort = 'updated_asc';
// v0.34.1 (#861 — P0 leak seal): thread the auth'd client's source scope
// into the listPages filter so an OAuth client scoped to src-A cannot
// enumerate src-B pages. Pre-fix, ctx.sourceId / ctx.auth?.allowedSources
// were ignored at this op handler and the engine returned every source's
// pages indiscriminately.
// #3242 / #4400: federatedSearchScope so unqualified listing spans
// federated sources (same visibility set as search / get_page); an
// explicit per-call source_id (including '__all__') wins, same contract
// as search/query's sourceIdParam. parseSourceIdParam (same as get_page)
// rejects whitespace/malformed/non-string ids loudly instead of letting
// them silently return [] or, for the CLI's `--source-id ""`, widen to
// every source.
const sourceIdParam = parseSourceIdParam(p.source_id, 'list_pages', { allowAll: true });
const scope = await requestSourceScope(ctx, sourceIdParam, parseSourceIdsParam(ctx, 'list_pages', p.source_ids));
// #4352 remediation: untrusted listing never enumerates
// `visibility: private` pages (slugs + titles are the leak surface here).
// Composes with the #4400 per-call source_id and the v0.34.1 grant scope
// above — an ADDITIONAL predicate threaded into PageFilters, never a
// replacement for the source filter. Trusted local enumeration unchanged.
const excludePrivate = await resolveExcludePrivatePages(ctx.engine, ctx.remote);
// The 100-row cap exists to protect remote MCP/OAuth transports from
// unbounded result dumps. Local CLI callers (ctx.remote === false — the
// same trust boundary that already bypasses scope enforcement, see the
// Operation.scope doc above) own the machine, and a full enumeration is a
// legitimate local operation, so an explicit limit above 100 is honored.
// Anything that is not strictly `false` stays remote/untrusted (defense
// in depth, matching the ctx.remote contract).
const requestedLimit = p.limit as number | undefined;
const isLocal = ctx.remote === false;
const limit = isLocal
? clampSearchLimit(requestedLimit, 50, Number.MAX_SAFE_INTEGER)
: clampSearchLimit(requestedLimit, 50, 100);
if (!isLocal && requestedLimit !== undefined && Number.isFinite(requestedLimit) && requestedLimit > limit) {
// Loud clamp, parity with the three search paths ("search limit clamped
// from N to 100"). logger.warn goes to stderr — `list` stdout is
// tab-separated and consumed by scripts, so it must stay clean.
ctx.logger.warn(`[gbrain] Warning: list limit clamped from ${requestedLimit} to ${limit}; use offset to paginate`);
}
// Thread offset through — PageFilters has supported it all along; the op
// layer just never passed it, so `--offset` was accepted and ignored.
const requestedOffset = p.offset as number | undefined;
const offset =
requestedOffset !== undefined && Number.isFinite(requestedOffset) && requestedOffset > 0
? Math.floor(requestedOffset)
: undefined;
// Probe one row past the effective limit so truncation is detectable
// without a COUNT query. The bug class sealed here is SILENT truncation
// — an exhaustive consumer (audit, scan, backfill) gets a full-looking
// list and never learns rows were dropped, and with the default
// updated_desc sort the dropped rows are always the OLDEST, i.e. exactly
// the pages such consumers exist to find.
const rows = scope.sourceIds?.length === 0 ? [] : await ctx.engine.listPages({
type: p.type as any,
tag: typeof p.tag === 'string' && ctx.remote !== false ? unquoteAnyTranscriptText(p.tag) : p.tag as string,
limit: limit + 1,
offset,
includeDeleted: (p.include_deleted as boolean) === true,
updated_after: updatedAfterKeyset ? undefined : updatedAfter,
updatedAfterKeyset,
sort,
excludePrivate,
listColumnsOnly: true,
where: whereOpParam(ctx, 'list_pages', p.where),
...(typeof p.slug_prefix === 'string' && p.slug_prefix ? { slugPrefix: p.slug_prefix } : {}),
...scope,
}).catch((e: unknown) => {
// #6103: an updated_after the database cannot parse is the caller's input, not a server fault.
if (updatedAfter === undefined || !isDatetimeInputError(e)) throw e;
throw invalidParam(ctx, 'list_pages', 'updated_after', 'list_pages: updated_after is not a date or timestamp the database can read.', {
def: list_pages.params.updated_after, example: '2026-08-11T00:00:00Z',
fix: readFix('Lists pages updated after a well-formed ISO timestamp.', { argv: ['gbrain', 'list', '--updated-after', '2026-08-11T00:00:00Z', '--limit', '1'],
mcp: { tool: 'list_pages', arguments: { updated_after: '2026-08-11T00:00:00Z', limit: 1 } } }),
});
});
const truncated = rows.length > limit;
const pages = truncated ? rows.slice(0, limit) : rows;
// Warn only when the caller's limit was NOT honored (unset → default 50):
// an explicit honored limit that happens to land on more rows is ordinary
// pagination, not a trap. Local (CLI) only — same operator-facing stderr
// channel as the put_page unknown-type hint above — but with no isTTY
// gate: scripted callers are precisely the consumers that cannot detect
// truncation any other way, and stderr keeps stdout parseable for them.
// (Local explicit limits are honored unbounded since #3322, so the
// requestedLimit > limit arm is defense in depth only.)
if (truncated && isLocal && (requestedLimit === undefined || requestedLimit > limit)) {
console.error(
`[list_pages] output truncated at ${limit} rows (default 50). ` +
`Pass an explicit limit, page through with ` +
`updated_after=<last row's updated_at_iso> + ` +
`updated_after_slug=<last row's slug>, or narrow with type/tag.`,
);
}
// MCP callers see neither that notice nor the clamp warning (server log):
// `_meta.pagination` carries the data, the listing_truncated notice tells the model.
const pagination = listPagesPagination({ truncated, limit, requestedLimit, offset, sort, last: pages[pages.length - 1] });
ctx.emitResponseMeta?.('pagination', pagination);
const truncatedNotice = isLocal ? null : listingTruncatedNotice(pagination, p);
if (truncatedNotice) ctx.emitNotice?.(truncatedNotice);
if (pages.length === 0 && typeof p.type === 'string' && p.type) {
const notice = unusedTypeNotice(p.type, await (await import('./stats-by.ts')).visiblePageTypes(ctx, scope).catch(() => null));
if (notice) ctx.emitNotice?.(notice);
}
return pages.map(pg => ({
slug: pg.slug,
source_id: pg.source_id,
type: pg.type,
title: pg.title,
updated_at: pg.updated_at,
updated_at_iso: pg.updated_at_iso,
...(pg.deleted_at ? { deleted_at: pg.deleted_at } : {}),
}));
},
scope: 'read', mutating: false,
cliHints: { name: 'list' },
};
// Ops in EXACTLY the order they appear in the canonical `operations` array
/**
* CLI→MCP gap-closure wave — `capture` over MCP (D2A). The documented "just
* get this into my brain" entrypoint: three separate docs carried the
* "unknown tool: capture → use put_page" FAQ because agents kept reaching for
* it. Thin sugar that DELEGATES to the put_page handler with the same ctx
* (inheriting every fence: slug fence, dedupe, unknown-type audit,
* write-through, remote auto-link skip) after adding what agents had to
* hand-roll: a stable content-derived default slug + the frontmatter merge +
* the binary/empty guards. Remote provenance stays the CV6 server-stamp
* `mcp:put_page` (the write API truthfully IS put_page); the result carries
* channel: 'capture' for the receipt. Joins STARTER_OPS as a direct literal
* [EV8] so the plugin/starter lanes that retired the FAQ can actually call it.
*/
const capture: Operation = {
name: 'capture',
idempotent: true,
outputRedaction: 'no_stored_text',
description: CAPTURE_DESCRIPTION,
params: {
...AGENT_CONTENT_PARAMS, expected_revision: { ...AGENT_CONTENT_PARAMS.expected_revision, fullSurfaceOnly: true }, force: { ...AGENT_CONTENT_PARAMS.force, fullSurfaceOnly: true },
...CAPTURE_EVENT_PARAMS, ...CAPTURE_CLI_PROVENANCE_PARAMS,
content: { type: 'string', required: true, description: 'Markdown or text (not a file path).' },
local_file: { type: 'string', description: 'Local CLI only.', required: false, fullSurfaceOnly: true },
slug: { type: 'string', required: false, description: 'Default inbox/<date>-<hash>.' },
type: { type: 'string', required: false, description: 'Page type (default note).' },
},
scope: 'write',
mutating: true,
area: 'pages',
// 'capture' is in CLI_ONLY (rich local UX: --file/--stdin/event sugar);
// hidden hint per the advisor pattern.
cliHints: { name: 'capture', hidden: true },
handler: async (ctx, p) => {
const { pageMutationSource, submitPageMutation } = await pageMutations();
const sourceId = pageMutationSource(ctx, p, 'capture');
if (ctx.dryRun) {
if (typeof p.slug === 'string') {
validatePageSlug(p.slug);
enforceClientSlugFence(ctx, p.slug, 'capture');
enforceSubagentSlugFence(ctx, p.slug, 'capture');
await suffixedSlugDryRun(ctx, sourceId, p.slug, 'capture');
}
return { dry_run: true, action: 'capture', slug: p.slug };
}
return submitPageMutation(ctx, { operation: 'capture', params: p });
},
};
// (Page CRUD quartet first, then the v0.26.5 destructive-guard ops:
// page-level soft-delete recovery + admin purge, then capture.)
export const pagesOperations: Operation[] = [
get_page, put_page, delete_page, list_pages,
restore_page, purge_deleted_pages, capture,
fetch_page,
];