Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Resolution & Chunks operation cluster — pure move from operations.ts
* (v0.46.x tranche 2). Op consts stay module-private; `chunksOperations`
* 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 { MIN_TRUST_PARAM, resolveReadEligibility } from '../eligibility/policy.ts';
import { dropHeldFenceRows, stampPageTrust } from '../eligibility/stamp.ts';
import { worldOnlyFacts } from '../search/private-visibility.ts';
import { pageTypesById, quotePageText, quotesStored } from '../search/transcript-quote.ts';
import type { Operation } from './contract.ts';
import { readPolicyOpts } from './context.ts';
import { federatedSearchScope, parseSourceIdParam } from './context.ts';
import { invalidParam } from './op-fix.ts';
import { GET_CHUNKS_DEFAULT_LIMIT, GET_CHUNKS_REMOTE_MAX_LIMIT, pagingLimit, reportChunkPage } from './read-paging.ts';
// --- Resolution & Chunks ---
const resolve_slugs: Operation = {
name: 'resolve_slugs',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Fuzzy-match a partial slug or title to page slugs. Use when a slug is uncertain. Needs read scope.',
params: {
partial: { type: 'string', required: true, description: 'Partial slug or title.' },
source_id: {
type: 'string',
description: "One source, or '__all__'.",
},
},
handler: async (ctx, p) => {
// #3242: was fully UNSCOPED — the one read that leaked every source's
// slugs to any caller (the reporter's "resolve_slugs sees them but
// get_page doesn't" matrix). Route through the same visibility set as
// get_page/search: grant > federated set > scalar source. An explicit
// per-call source_id narrows through resolveRequestedScope.
const sourceIdParam = parseSourceIdParam(p.source_id, 'resolve_slugs', { allowAll: true });
const scope = federatedSearchScope(ctx, sourceIdParam);
return ctx.engine.resolveSlugs(p.partial as string, await readPolicyOpts(ctx, scope));
},
scope: 'read',
};
const get_chunks: Operation = {
name: 'get_chunks',
mutating: false,
idempotent: true,
outputRedaction: { exempt: 'explicit chunk read by slug, the page-read twin of get_page (CEO-17 raw-read exception)' },
description: `Return a page's indexed content chunks (the units search ranks), in chunk_index order, ${GET_CHUNKS_DEFAULT_LIMIT} at a time by default. Use when debugging why search did or did not match a page. A large page has more chunks than one call returns: the last chunk of a cut list carries truncated: true and next_from_index, _meta.pagination carries total_chunks and next_from_index, and a listing_truncated notice names the next call (from_index). Needs read scope. On page_not_found: resolve the slug with resolve_slugs.`,
params: {
slug: { type: 'string', required: true, description: 'Slug of the page whose content chunks to return.' },
min_trust: MIN_TRUST_PARAM,
from_index: { type: 'number', description: 'Return chunks from this chunk_index on (a non-negative integer). Default 0.' },
limit: { type: 'number', minimum: 1, description: `How many chunk_index positions to return (a positive integer). Default ${GET_CHUNKS_DEFAULT_LIMIT}; MCP callers are capped at ${GET_CHUNKS_REMOTE_MAX_LIMIT}.` },
},
handler: async (ctx, p) => {
const fromIndex = p.from_index === undefined || p.from_index === null ? 0 : p.from_index;
if (!(typeof fromIndex === 'number' && Number.isSafeInteger(fromIndex) && fromIndex >= 0)) {
throw invalidParam(ctx, 'get_chunks', 'from_index', 'get_chunks: from_index must be a non-negative integer.', { example: 50 });
}
const { limit, clampedFrom } = pagingLimit(ctx, 'get_chunks', p.limit, GET_CHUNKS_DEFAULT_LIMIT, GET_CHUNKS_REMOTE_MAX_LIMIT);
// #2555: route through the canonical scope ladder (federated array >
// scalar floor > nothing) instead of the pre-#2200 scalar-only pattern —
// a federated grant could read the page via get_page but got [] here.
const scope = await readPolicyOpts(ctx);
// #4352 remediation: a `visibility: private` page's chunks read exactly
// like a missing page's ([]) for untrusted callers — no existence oracle.
// Large pages: one range of chunk_index per call, never every chunk.
const page = await ctx.engine.getChunkPage(p.slug as string, { ...scope, fromIndex, limit });
// #5575: a chunk's tier is its page's (lowered by a fence trust marker); rows below the floor read as missing.
const { floor } = await resolveReadEligibility(ctx, { minTrust: p.min_trust });
// GST-2891: a held row is looked up under the source and slug of the page each chunk belongs to.
const owners = worldOnlyFacts(ctx.remote) && page.chunks.length ? new Map((await ctx.engine.executeRaw<{ id: number; slug: string; source_id: string }>(
'SELECT id, slug, source_id FROM pages WHERE id = ANY($1::int[])', [[...new Set(page.chunks.map(c => c.page_id))]])).map(o => [Number(o.id), o] as const)) : null;
const kept = owners ? (await dropHeldFenceRows(ctx.engine, page.chunks.map(c => ({ ...c, slug: owners.get(c.page_id)?.slug ?? '', source_id: owners.get(c.page_id)?.source_id }))))
.map(({ source_id: _source, slug: _slug, ...chunk }) => chunk) : page.chunks;
const stamped = (await stampPageTrust(ctx.engine, kept.map(c => ({ ...c, slug: p.slug as string })), floor)).map(({ slug: _slug, ...chunk }) => chunk);
// GST-687: an untrusted reader gets a chat page's chunks, or chunks below the owner's tier, quoted (tool calls summarized on a chat page).
const types = ctx.remote === false ? null : await pageTypesById(ctx.engine, stamped.map(c => c.page_id));
const chunks = types === null ? stamped : stamped.map(c => {
const type = types.get(c.page_id);
return quotesStored(type, (c as { trust_tier?: unknown }).trust_tier) ? { ...c, chunk_text: quotePageText(c.chunk_text, p.slug as string, type), quoted: 'transcript' as const } : c;
});
const next = reportChunkPage(ctx, p, { fromIndex, limit, clampedFrom, returned: chunks.length, totalChunks: page.total_chunks, maxChunkIndex: page.max_chunk_index });
if (next === undefined || chunks.length === 0) return chunks;
return [...chunks.slice(0, -1), { ...chunks[chunks.length - 1], truncated: true, next_from_index: next }];
},
scope: 'read',
};
// Ops in EXACTLY the canonical `operations` array order.
export const chunksOperations: Operation[] = [resolve_slugs, get_chunks];