Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Orphans operation cluster — pure move from operations.ts (v0.46.x
* tranche 2). Op consts stay module-private; `orphansOperations` 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 { assertSourceInCallerScope, readPolicyOpts } from './context.ts';
import type { Operation } from './contract.ts';
import { invalidParam } from './op-fix.ts';
import { encodeListingCursor, LISTING_DEFAULT_LIMIT, LISTING_MAX_LIMIT, pageSortedRows } from '../bounded-listing.ts';
// --- Orphans ---
export const ORPHANS_DEFAULT_LIMIT = LISTING_DEFAULT_LIMIT;
export const ORPHANS_MAX_LIMIT = LISTING_MAX_LIMIT;
const find_orphans: Operation = {
name: 'find_orphans',
mutating: false,
idempotent: true,
outputRedaction: 'retrieval',
description: 'Find disconnected pages. Default mode "islanded" (no live inbound AND no outbound link) matches get_health.orphan_pages; mode "inbound" is the legacy no-inbound-only view. Essential for content enrichment cycles.',
params: {
include_pseudo: {
type: 'boolean',
description: 'Include auto-generated and pseudo pages (default: false)',
},
mode: {
type: 'string',
description: "#4524: orphan definition — 'islanded' (default; agrees with get_health.orphan_pages and doctor) or 'inbound' (legacy: no inbound links, even when the page links out).",
},
source_id: {
type: 'string',
description: 'Only orphans from this source (it must be inside your source grant). Each row carries source_id and type.',
},
limit: {
type: 'number',
minimum: 1,
description: `Rows per page (default ${ORPHANS_DEFAULT_LIMIT}, max ${ORPHANS_MAX_LIMIT}); total_orphans counts every orphan, complete says whether this page holds the rest, and next_cursor (or next_offset) names the next page.`,
},
offset: { type: 'number', description: 'Skip the first N orphans (ordered by source_id, then slug).' },
cursor: { type: 'string', description: 'next_cursor from the previous page, with the same filters (instead of offset).' },
count_only: { type: 'boolean', description: 'Return the totals with no rows.' },
},
scope: 'read',
handler: async (ctx, p) => {
const { findOrphans } = await import('../../commands/orphans.ts');
// #4524: validate rather than silently coerce — an unknown mode must not
// quietly fall back to the default and misreport the orphan set.
const mode = p.mode === undefined ? undefined : (p.mode as string);
if (mode !== undefined && mode !== 'inbound' && mode !== 'islanded') {
throw invalidParam(ctx, 'find_orphans', 'mode', 'find_orphans: invalid mode — use \'inbound\' or \'islanded\'', { choices: ['islanded', 'inbound'] });
}
// v0.41.29.0 (Codex F8): scope by the caller's source (ctx.sourceId /
// ctx.auth.allowedSources) via the canonical sourceScopeOpts ladder.
// Pre-fix, find_orphans returned brain-wide orphans regardless of a
// source-bound OAuth client's scope — a read leak in the v0.34.1
// source-isolation class. Local CLI callers route through `gbrain
// orphans --source` instead (ctx.remote === false → empty scope here).
// #5891: a named source narrows the caller's scope and never widens it.
// A remote caller's inbound links count only from referrers in its scope.
const named = p.source_id === undefined ? undefined : String(p.source_id);
if (named !== undefined) assertSourceInCallerScope(ctx, named);
const scope = named !== undefined ? await readPolicyOpts(ctx, { sourceId: named }) : await readPolicyOpts(ctx);
const limit = p.limit === undefined ? ORPHANS_DEFAULT_LIMIT : Number(p.limit);
const offset = p.offset === undefined ? 0 : Number(p.offset);
const limitOk = Number.isInteger(limit) && limit >= 1 && limit <= ORPHANS_MAX_LIMIT;
if (!limitOk || !Number.isInteger(offset) || offset < 0) {
throw invalidParam(ctx, 'find_orphans', limitOk ? 'offset' : 'limit',
`find_orphans: limit must be 1-${ORPHANS_MAX_LIMIT} and offset a non-negative integer`,
limitOk ? { def: find_orphans.params.offset, example: 0 } : { def: find_orphans.params.limit, example: ORPHANS_DEFAULT_LIMIT });
}
const result = await findOrphans(ctx.engine, {
includePseudo: (p.include_pseudo as boolean) || false,
...(mode ? { mode } : {}),
...scope,
scopeInbound: ctx.remote !== false,
});
const cursor = p.cursor === undefined ? undefined : String(p.cursor);
if (cursor !== undefined && offset !== 0) {
throw invalidParam(ctx, 'find_orphans', 'cursor', 'find_orphans: pass cursor or offset, not both', { def: find_orphans.params.cursor });
}
// #7246: one cursor kind per filter set, so a cursor never resumes a different listing.
const kind = `find_orphans:${mode ?? 'islanded'}:${named ?? '*'}:${p.include_pseudo === true ? 'all' : 'policy'}`;
const key = (row: { source_id?: string; slug: string }) => [row.source_id ?? '', row.slug];
if (p.count_only === true) {
return { ...result, orphans: [], limit, offset, next_offset: null, complete: result.total_orphans === 0, next_cursor: null };
}
if (cursor !== undefined) {
const page = pageSortedRows(result.orphans, key, { limit, cursor }, kind);
return { ...result, orphans: page.rows, limit, offset, next_offset: null, complete: page.complete, next_cursor: page.next_cursor };
}
const ordered = pageSortedRows(result.orphans, key, { limit: null }, kind).rows;
const rows = ordered.slice(offset, offset + limit);
const next = offset + limit < ordered.length ? offset + limit : null;
return { ...result, orphans: rows, limit, offset, next_offset: next, complete: next === null,
next_cursor: next === null ? null : encodeListingCursor(kind, key(rows[rows.length - 1]!)) };
},
cliHints: { name: 'orphans', hidden: true },
};
// Ops in EXACTLY the canonical `operations` array order.
export const orphansOperations: Operation[] = [find_orphans];