Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
42.0 KB
Raw Blame
import { managedPersistenceEnabled } from '../persistence/ownership.ts';
import { requestPrincipalForContext, submitPageMutation } from '../persistence/page-mutations.ts';
import { refuseGuestSourceWrite } from '../guests/admission.ts';
import { remoteTargetHidden } from '../persistence/page-visibility.ts';
import { WRITE_REQUEST_PARAM } from '../persistence/params.ts';
import { MANAGED_LINK_SOURCES } from '../links-fence.ts';
import { backlinkTypeFilter, readBacklinkPage, withLinkPageStatus } from './backlinks-paged.ts';
import { cutLinkPage, finishLinkPage, linkId, parseLinkListing, reportLinkPage } from './link-paging.ts';
/**
 * Links + graph operation cluster — pure move from operations.ts (v0.46.x
 * tranche 1). MANAGED_LINK_SOURCES stays exported (test suite + operations.ts
 * re-export depend on it); op consts stay module-private. `linksOperations`
 * 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 { opError, type Operation } from './contract.ts';
import type { Action } from '../agent-output.ts';
import { chainStoredEdge, presentEdgeContext, resolveChainAnchors, runRelationalChain, validateChainHops, type ChainEvidenceEdge, type ChainPlan } from '../search/relational-chain.ts';
import { storedEdge, worldLinkContexts } from '../eligibility/fence-overlay.ts';
import { invalidParam, paramUse, readFix } from './op-fix.ts';
import {
  assertExplicitSourceLive,
  enforceClientSlugFence,
  federatedSearchScope,
  linkReadScopeOpts,
  parseSourceIdParam,
  readPolicyOpts,
  reclassifyMutationTimePageMiss,
  requireWritablePage,
  sourceScopeOpts,
  assertSourceInCallerScope,
} from './context.ts';
import { listWantedPages } from '../wanted-links-store.ts';
import { privatePagesFilterForCaller } from '../search/private-visibility.ts';
import type { OperationContext } from './contract.ts';
import type { Link, PageReadPolicy } from '../types.ts';
import { ALL_SOURCES } from '../source-id.ts';
import { PageMissingError } from '../engine-errors.ts';
import { LINK_READ_CONTEXT_MAX_CHARS, LINK_READ_DEFAULT_LIMIT, LINK_READ_MAX_LIMIT, TRAVERSE_PATH_ROW_CAP, TRAVERSE_WALK_ROW_CAP } from '../engine-constants.ts';
// #4224: flag-gated cross-source identity union for the link read ops.
import { unionLinksAcrossIdentity } from '../entity-identity.ts';
import { TEMPORAL_EDGE_PARAMS, STARTER_STATUS_PARAM, STARTER_AS_OF_PARAM, resolveEdgeTemporal, filterTemporalLinks, reportTemporal } from './edge-temporal.ts';
import { isCalendarDate, relationSemantics, relationshipFilterSql, temporalLinkTypes, type LinkReadPage } from '../link-validity.ts';
import { writeManualTransitions, removeManualTransitions } from '../link-temporal-apply.ts';
import { maintenanceTransaction } from '../persistence/attribution.ts';
import { primeRelationSemantics } from '../link-semantics-pack.ts';
// #4655: write-time pack vocabulary enforcement for explicit link verbs.
import {
  loadActivePackForWriteVocabulary,
  packDeclaresLinkType,
  undeclaredLinkTypeMessage,
  undeclaredLinkTypeSuggestion,
} from '../schema-pack/write-vocabulary.ts';

// --- Links ---

/**
 * v114 (#1941): reconciliation-managed provenances a CALLER must not forge via
 * the add_link op. Internal writers (import-file frontmatter reconciliation,
 * extract --by-mention, wikilink resolution) write these straight through the
 * engine — they're excluded here, not at the DB CHECK. A hand-created edge
 * tagged 'frontmatter' with no origin_page_id would be a phantom that put_page
 * reconciliation (link_source='frontmatter' AND origin_page_id=written_page)
 * never cleans (see src/schema.sql). `manual` is intentionally absent — it IS
 * the user-facing provenance and the default for omitted link_source. The list
 * lives in links-fence.ts, whose rows cannot carry these provenances either.
 */
export { MANAGED_LINK_SOURCES };

/** add_link valid_from / valid_until: calendar dates on a dated relation type. Null when neither is given. */
export function validateLinkDates(ctx: OperationContext, p: Record<string, unknown>, linkType: string): { validFrom?: string; validUntil?: string } | null {
  const validFrom = p.valid_from, validUntil = p.valid_until;
  if (validFrom === undefined && validUntil === undefined) return null;
  for (const [name, value] of [['valid_from', validFrom], ['valid_until', validUntil]] as const) {
    if (value !== undefined && !isCalendarDate(value)) {
      throw opError('invalid_params', `add_link: ${name} must be a calendar date YYYY-MM-DD (got ${JSON.stringify(value)})`,
        `Pass ${paramUse(ctx, name, '2025-03-01')}; omit it when the date is unknown.`);
    }
  }
  if (typeof validFrom === 'string' && typeof validUntil === 'string' && validUntil < validFrom) {
    throw opError('invalid_params', 'add_link: valid_until is before valid_from', `Swap them, or pass only ${paramUse(ctx, 'valid_until')} to record when the relationship ended.`);
  }
  if (relationSemantics(linkType) === 'reference') {
    throw opError('invalid_params', `add_link: link_type '${linkType || '(none)'}' has no dates; valid_from/valid_until apply to dated relations (${temporalLinkTypes().join(', ')})`,
      `Pass link_type such as works_at with the dates, or drop valid_from/valid_until.`);
  }
  if (relationSemantics(linkType) === 'event' && validUntil !== undefined) {
    throw opError('invalid_params', `add_link: ${linkType} is an event and does not end; pass only valid_from (when it happened)`, `Drop ${paramUse(ctx, 'valid_until')}.`);
  }
  return { ...(typeof validFrom === 'string' ? { validFrom } : {}), ...(typeof validUntil === 'string' ? { validUntil } : {}) };
}

const add_link: Operation = {
  name: 'add_link',
  idempotent: true,
  outputRedaction: 'no_stored_text',
  description: 'Create a typed link (edge) from one page to another in the same source. Use when recording a relationship (works_at, invested_in, mentions); remote page writes already link [[wikilinks]] to existing pages as mentions (receipt auto_links), so add only typed links or ones the text lacks. Needs write scope; an explicit link_type must be declared by the active schema pack. On page_not_found: resolve both slugs with resolve_slugs.',
  params: {
    request_id: WRITE_REQUEST_PARAM,
    from: { type: 'string', required: true, description: "Slug of the page the link originates from (the edge renders on this page), e.g. 'people/alice-example'. These are page slugs — there is no `source`/`target` pair." },
    to: { type: 'string', required: true, description: "Slug of the page the link points to, e.g. 'companies/acme-example'." },
    link_type: { type: 'string', description: 'Link type (e.g., invested_in, works_at). When the active schema pack declares a link vocabulary, an explicit link_type must be one of its declared verbs (undeclared verbs are rejected, also under dry_run). Omitted = untyped edge.' },
    context: { type: 'string', description: 'Context for the link' },
    link_source: { type: 'string', description: "Provenance tag (kebab-case, e.g. 'citation-graph'). Defaults to 'manual'. Reconciliation-managed built-ins (markdown/frontmatter/mentions/wikilink-resolved) are rejected." },
    valid_from: { type: 'string', description: 'When the relationship started (YYYY-MM-DD), for dated relations such as works_at or invested_in.' },
    valid_until: { type: 'string', description: 'When it ended (YYYY-MM-DD, exclusive). Re-run add_link with valid_until to record that a relationship ended.' },
  },
  mutating: true,
  scope: 'write',
  handler: async (ctx, p) => {
    // Client fence on the `from` endpoint only: the edge originates from
    // (and renders on) the from page; linking TO a page outside the
    // binding is a reference, not a mutation of the target.
    enforceClientSlugFence(ctx, p.from as string, 'add_link');
    // #4655: an EXPLICIT link verb must be declared by the active pack (when
    // one resolves — best-effort, no pack means no vocabulary to enforce).
    // Runs before the dry-run return so a dry run previews the rejection.
    // Omitted/empty link_type stays unchecked (the untyped-edge default).
    const linkType = typeof p.link_type === 'string' ? p.link_type : '';
    if (linkType.length > 0) {
      const activePack = await loadActivePackForWriteVocabulary(ctx);
      if (activePack && !packDeclaresLinkType(activePack, linkType)) {
        throw opError(
          'invalid_params',
          undeclaredLinkTypeMessage(linkType, activePack, 'add_link'),
          undeclaredLinkTypeSuggestion(activePack),
        );
      }
    }
    await primeRelationSemantics(ctx.engine);
    const dates = validateLinkDates(ctx, p, linkType);
    if (ctx.dryRun) return { dry_run: true, action: 'add_link', from: p.from, to: p.to };
    // v114 (#1941): default omitted provenance to 'manual' (NOT the engine's
    // 'markdown' default) so hand/tool-created CLI edges are honestly manual,
    // and forbid forging the reconciliation-managed built-ins.
    const linkSource = ((p.link_source as string) || 'manual').trim();
    if (MANAGED_LINK_SOURCES.includes(linkSource)) {
      throw opError('invalid_params',
        `link_source '${linkSource}' is reconciliation-managed and cannot be set manually; ` +
        `use 'manual' (the default) or a custom kebab tag like 'citation-graph'`,
        `Omit link_source (defaults to 'manual') or pass a custom kebab tag such as 'citation-graph'; ${MANAGED_LINK_SOURCES.join(', ')} are reserved for reconciliation.`);
    }
    // v0.31.8 (D7): single ctx.sourceId scopes both endpoints + origin. Cross-
    // source link creation is out of scope for this wave; use the engine API
    // directly for that edge case.
    const linkOpts = ctx.sourceId
      ? { fromSourceId: ctx.sourceId, toSourceId: ctx.sourceId, originSourceId: ctx.sourceId }
      : undefined;
    await refuseGuestSourceWrite(ctx.engine, ctx.sourceId || 'default', () => requestPrincipalForContext(ctx), 'add_link');
    // #4109: per-endpoint source-boundary diagnostics before the mutation.
    await requireWritablePage(ctx, p.from as string, 'add_link', 'from');
    await requireWritablePage(ctx, p.to as string, 'add_link', 'to');
    // G5: on a managed brain the edge is a row of the from page's links fence, written through the page-mutation door.
    if (await managedPersistenceEnabled(ctx.engine)) {
      await submitPageMutation(ctx, { operation: 'add_link', params: { ...(p.request_id !== undefined ? { request_id: p.request_id } : {}),
        slug: p.from, to: p.to, link_type: linkType, link_source: linkSource, context: (p.context as string) || '',
        ...(dates?.validFrom ? { valid_from: dates.validFrom } : {}), ...(dates?.validUntil ? { valid_until: dates.validUntil } : {}) } });
      return { status: 'ok' };
    }
    try {
      if (!dates) await ctx.engine.addLink( // gbrain-allow-direct-insert: add_link MCP op is the explicit canonical surface for manual link creation; auto-link reconciliation runs separately via auto_link post-hook
        p.from as string, p.to as string,
        (p.context as string) || '', linkType,
        linkSource, undefined, undefined,
        linkOpts,
      );
      if (dates) {
        const sourceId = ctx.sourceId ?? 'default';
        await maintenanceTransaction(ctx.engine, async tx => {
          await tx.addLink(p.from as string, p.to as string, (p.context as string) || '', linkType, linkSource, undefined, undefined, // gbrain-allow-direct-insert: add_link with dated manual evidence, one maintenance transaction
            linkOpts);
          await writeManualTransitions(tx, { from: p.from as string, to: p.to as string, linkType, sourceId }, dates);
        });
      }
    } catch (error) {
      // An endpoint hard-deleted between preflight and mutation: reclassify
      // the typed engine miss instead of surfacing it as internal_error.
      if (error instanceof PageMissingError) {
        return reclassifyMutationTimePageMiss(ctx, error.slug, 'add_link', error.endpoint);
      }
      throw error;
    }
    return { status: 'ok' };
  },
  cliHints: { name: 'link', aliases: ['link-add'], positional: ['from', 'to'] },
};

const remove_link: Operation = {
  name: 'remove_link',
  idempotent: true,
  outputRedaction: 'no_stored_text',
  description: 'Remove a link between two pages (optionally only one link_type or link_source). Use when a relationship was recorded wrongly. Needs write scope. On page_not_found: resolve both slugs with resolve_slugs.',
  params: {
    request_id: WRITE_REQUEST_PARAM,
    from: { type: 'string', required: true, description: 'Slug of the page the link originates from (same endpoint order as add_link).' },
    to: { type: 'string', required: true, description: 'Slug of the page the link points to.' },
    link_type: { type: 'string', description: 'Only remove edges of this link type (omit = all types)' },
    link_source: { type: 'string', description: 'Only remove edges of this provenance (e.g. citation-graph); omit = any provenance' },
  },
  mutating: true,
  scope: 'write',
  handler: async (ctx, p) => {
    enforceClientSlugFence(ctx, p.from as string, 'remove_link');
    if (ctx.dryRun) return { dry_run: true, action: 'remove_link', from: p.from, to: p.to };
    const writeSource = ctx.sourceId || 'default';
    await refuseGuestSourceWrite(ctx.engine, writeSource, () => requestPrincipalForContext(ctx), 'remove_link');
    if (await remoteTargetHidden(ctx.engine, ctx.remote, writeSource, p.from as string)
      || await remoteTargetHidden(ctx.engine, ctx.remote, writeSource, p.to as string)) return { status: 'ok', removed: 0 };
    await primeRelationSemantics(ctx.engine);
    const linkOpts = ctx.sourceId
      ? { fromSourceId: ctx.sourceId, toSourceId: ctx.sourceId }
      : undefined;
    const remove = async (engine: typeof ctx.engine, opts: typeof linkOpts) => {
      const removed = await engine.removeLink(
        p.from as string, p.to as string,
        (p.link_type as string) || undefined,
        (p.link_source as string) || undefined,
        opts,
      );
      // Manual dated statements belong to manual edges; drop them with the edge.
      if (removed > 0 && (!p.link_source || p.link_source === 'manual')) {
        await removeManualTransitions(engine, { from: p.from as string, to: p.to as string, linkType: (p.link_type as string) || undefined, sourceId: opts?.fromSourceId ?? 'default' });
      }
      return removed;
    };
    // #4527: report how many edges actually died — an unconditional
    // `{ status: 'ok' }` made a zero-match delete (typo'd slug, wrong
    // link_type, already removed) indistinguishable from a real removal.
    // G5: a managed brain removes the from page's links fence rows through the page-mutation door, and with them
    // the matching database-only edges (persistence/manual-links.ts). A missing from page has no edges to remove.
    if (await managedPersistenceEnabled(ctx.engine)) {
      if (!await ctx.engine.getPage(p.from as string, { sourceId: ctx.sourceId || 'default' })) return { status: 'ok', removed: 0 };
      const result = await submitPageMutation(ctx, { operation: 'remove_link', params: { ...(p.request_id !== undefined ? { request_id: p.request_id } : {}),
        slug: p.from, to: p.to, ...(p.link_type ? { link_type: p.link_type } : {}), ...(p.link_source ? { link_source: p.link_source } : {}) } });
      return { status: 'ok', removed: Number(result.removed ?? 0),
        ...(Array.isArray(result.derived_from_text) ? { derived_from_text: result.derived_from_text, message: result.derived_message } : {}) };
    }
    return { status: 'ok', removed: await remove(ctx.engine, linkOpts) };
  },
  cliHints: { name: 'unlink', aliases: ['link-rm'], positional: ['from', 'to'] },
};

const LINK_SOURCE_ID_PARAM = {
  type: 'string',
  description: "One source, or '__all__'.",
} as const;
const LINK_ALL_SOURCES_PARAM = {
  type: 'boolean',
  description: 'Same as source_id __all__.',
  fullSurfaceOnly: true,
} as const;
const LINK_LIMIT_PARAM = { type: 'number', minimum: 1, description: `Rows per call (default ${LINK_READ_DEFAULT_LIMIT}, max ${LINK_READ_MAX_LIMIT}).` } as const;
const LINK_CURSOR_PARAM = { type: 'string', description: 'next_cursor from the previous call (same filters).' } as const;
const LINK_ALL_PARAM = { type: 'boolean', description: 'Local CLI only: every row, paging internally.', fullSurfaceOnly: true } as const;

/**
 * #5827: the per-call source scope of a link read (get_links, get_backlinks,
 * traverse_graph). `federatedSearchScope` is the single trust + grant
 * resolver (#5081 explicit-read admission; an unqualified no-grant read widens
 * to the transport-computed federated set; a grant never widens), the
 * liveness check runs strictly after it (an archived source the caller was
 * never granted answers permission_denied, not unknown_source), and
 * `linkReadScopeOpts` promotes a remote scalar to `sourceIds[]` so the
 * engine's #2200 all-endpoints branch applies. Trusted local callers get the
 * scope as resolved: an explicit source stays scalar, `__all__` is brain-wide,
 * and an unqualified read may come back as the federated `sourceIds[]`.
 */
async function resolveLinkReadScope(
  ctx: OperationContext,
  p: Record<string, unknown>,
  opName: string,
): Promise<{ requested: string | undefined; policy: PageReadPolicy }> {
  const sourceIdParam = parseSourceIdParam(p.source_id, opName, { allowAll: true });
  if (p.all_sources === true && sourceIdParam !== undefined && sourceIdParam !== ALL_SOURCES) {
    throw opError(
      'invalid_params',
      `${opName}: pass either source_id or all_sources, not both.`,
      `Drop ${paramUse(ctx, 'all_sources')} to read source ${sourceIdParam}, or drop source_id to span sources.`,
    );
  }
  const requested = p.all_sources === true ? ALL_SOURCES : sourceIdParam;
  const scope = federatedSearchScope(ctx, requested);
  await assertExplicitSourceLive(ctx, requested);
  return { requested, policy: await readPolicyOpts(ctx, linkReadScopeOpts(ctx, scope)) };
}

const linkIdentity = (l: Link) => JSON.stringify([
  l.from_source_id, l.from_slug, l.to_source_id, l.to_slug, l.link_type,
  l.link_source ?? null, l.origin_source_id ?? null, l.origin_slug ?? null, l.origin_field ?? null,
]);

/**
 * get_links / get_backlinks body: one page of a page's edges (#6876,
 * link-paging.ts). A trusted local unqualified read whose scope widened to
 * the federated set runs the scalar read once per federated source and
 * merges, de-duplicated on link identity: the scalar branch keeps the
 * cross-source far-endpoint view local callers rely on, which the
 * all-endpoints branch would drop for far pages in non-federated sources.
 * Every other caller runs one read. Each read is a keyset page with link_type,
 * get_backlinks' referrer type and the temporal policy in SQL; the cap applies after the merge and the
 * identity union, and hidden former relationships never count toward it.
 */
async function readLinkEdges(
  ctx: OperationContext,
  p: Record<string, unknown>,
  opName: 'get_links' | 'get_backlinks',
  direction: 'out' | 'in',
): Promise<{ links: Link[]; nextCursor?: string }> {
  const slug = p.slug as string;
  const { requested, policy } = await resolveLinkReadScope(ctx, p, opName);
  const temporal = await resolveEdgeTemporal(ctx, p, opName);
  const listing = parseLinkListing(ctx, opName, p, policy);
  const linkType = typeof p.link_type === 'string' && p.link_type ? p.link_type : undefined;
  const fromType = direction === 'in' ? await backlinkTypeFilter(ctx, p, policy) : undefined;
  // Rows come back annotated with their relationship status; the policy
  // itself runs in SQL (and a second read counts what it hid).
  const annotate = temporal.disabled ? undefined : { ...temporal, status: 'all' as const, during: undefined };
  const filtering = !temporal.disabled && relationshipFilterSql('l', temporal) !== 'TRUE';
  const scopes: PageReadPolicy[] = ctx.remote === false && policy.sourceIds
    ? policy.sourceIds.map((sourceId) => ({ ...policy, sourceIds: undefined, sourceId }))
    : [policy];
  const read = async (page: LinkReadPage) => {
    const streams: Link[][] = [];
    const merged = new Map<string, Link>();
    for (const sourceOpts of scopes) {
      const readOpts = { ...sourceOpts, ...(annotate ? { temporal: annotate } : {}), page };
      const links = direction === 'out'
        ? await ctx.engine.getLinks(slug, readOpts)
        : await ctx.engine.getBacklinks(slug, readOpts);
      streams.push(links);
      // #4224: flag-gated identity union — merge edges from the page's identity
      // co-members (entity_identity.union config, default off; pure no-op then).
      // Member visibility never widens past the caller's grant. The scalar base
      // scope (when present) pins group resolution to the page actually read.
      // The engine authorizes the base and every member read before merging;
      // each union contributor must preserve this policy because no final filter runs.
      const unioned = await unionLinksAcrossIdentity(ctx.engine, slug, links, direction, {
        sourceId: sourceOpts.sourceId,
        allowedSources: sourceOpts.sourceIds,
        excludePrivate: sourceOpts.excludePrivate,
        ...(annotate ? { temporal: annotate } : {}),
        page,
        onMemberRead: (rows) => streams.push(rows),
      });
      for (const l of unioned) if (!merged.has(linkIdentity(l))) merged.set(linkIdentity(l), l);
    }
    return { streams, rows: [...merged.values()].sort((a, b) => linkId(a) - linkId(b)) };
  };
  const base: LinkReadPage = { ...(linkType ? { linkType } : {}), ...(fromType ? { fromType } : {}), contextChars: LINK_READ_CONTEXT_MAX_CHARS };
  // A page every row of which a JS filter dropped (the identity union's
  // member pin, the temporal shape check) is never returned while the
  // listing continues: a bare empty array cannot carry its cursor.
  const kept: Link[] = [];
  let hidden = 0;
  let afterId = listing.afterId;
  let nextId: number | undefined;
  do {
    const { streams, rows } = await read({ ...base, afterId, limit: listing.limit + 1, ...(filtering ? { relationship: { policy: temporal, keep: 'match' as const } } : {}) });
    const page = cutLinkPage(streams, rows, listing.limit);
    if (filtering) {
      const counted = await read({ ...(linkType ? { linkType } : {}), ...(fromType ? { fromType } : {}), afterId, throughId: page.nextId, relationship: { policy: temporal, keep: 'hidden' }, count: true });
      for (const stream of counted.streams) hidden += Number((stream[0] as Link & { link_total?: number } | undefined)?.link_total ?? 0);
    }
    const shaped = filterTemporalLinks(page.rows, temporal);
    kept.push(...shaped.kept);
    hidden += shaped.hidden;
    nextId = page.nextId;
    afterId = nextId;
  } while ((listing.all || kept.length === 0) && nextId !== undefined);
  reportTemporal(ctx, opName, p, temporal, hidden);
  if (kept.length === 0 && hidden === 0 && listing.afterId === undefined && !fromType) await hintScopedLinkMiss(ctx, p, requested, policy, direction);
  const links = await worldLinkContexts(ctx.engine, ctx.remote, kept, storedEdge);
  return { links, nextCursor: reportLinkPage(ctx, opName, p, listing, { returned: kept.length, nextId }) };
}

/**
 * #5827: local scoped-miss hint. A trusted local unqualified link read that
 * found nothing, for a slug that has links in a source outside the read scope
 * (a non-federated source, or any other source when the read was pinned),
 * names the scope it read, the per-source link counts and the exact rerun
 * command on stderr. stdout keeps the empty result; quiet under --json; never
 * for remote callers (no cross-source existence oracle).
 */
async function hintScopedLinkMiss(
  ctx: OperationContext,
  p: Record<string, unknown>,
  requested: string | undefined,
  policy: PageReadPolicy,
  direction: 'out' | 'in',
): Promise<void> {
  if (ctx.remote !== false || requested !== undefined || p.json === true) return;
  const readSources = policy.sourceIds ?? (policy.sourceId !== undefined ? [policy.sourceId] : undefined);
  if (readSources === undefined) return;
  const slug = p.slug as string;
  try {
    const rows = await ctx.engine.executeRaw<{ source_id: string }>(
      `SELECT DISTINCT p.source_id FROM pages p JOIN sources s ON s.id = p.source_id
       WHERE p.slug = $1 AND p.deleted_at IS NULL AND s.archived IS NOT TRUE
       ORDER BY p.source_id`,
      [slug],
    );
    const counts: Array<{ sourceId: string; count: number }> = [];
    for (const { source_id: sourceId } of rows) {
      if (readSources.includes(sourceId)) continue;
      const opts = { sourceId, excludePrivate: policy.excludePrivate };
      const links = direction === 'out' ? await ctx.engine.getLinks(slug, opts) : await ctx.engine.getBacklinks(slug, opts);
      if (links.length > 0) counts.push({ sourceId, count: links.length });
    }
    if (counts.length === 0) return;
    const command = direction === 'out' ? 'links' : 'backlinks';
    const label = readSources.length === 1 ? `source ${readSources[0]}` : `sources ${readSources.join(', ')}`;
    ctx.logger.warn(
      `[gbrain] ${command}: no ${direction === 'out' ? 'outgoing' : 'incoming'} links for ${slug} in ${label}; ` +
      `found ${counts.map((c) => `${c.count} in source ${c.sourceId}`).join(', ')}. Rerun with:\n` +
      counts.map((c) => `  gbrain ${command} ${slug} --source ${c.sourceId}`).join('\n'),
    );
  } catch { /* the hint is best-effort; the empty result stands */ }
}

const get_links: Operation = {
  name: 'get_links',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description: `List a page's outgoing links (typed edges to other pages). Use when exploring what a page points at; rows carry status and dates, live relationships by default (status: "all" for history, during: "2022" for a period). Pass source_id or all_sources to widen. Returns up to ${LINK_READ_DEFAULT_LIMIT} rows per call (limit, max ${LINK_READ_MAX_LIMIT}); a cut list's last row carries truncated: true and next_cursor, which you pass as cursor. 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 outgoing links to list.' },
    link_type: { type: 'string', description: 'Only this type.' },
    ...TEMPORAL_EDGE_PARAMS,
    source_id: LINK_SOURCE_ID_PARAM,
    all_sources: LINK_ALL_SOURCES_PARAM,
    limit: LINK_LIMIT_PARAM,
    cursor: LINK_CURSOR_PARAM,
    all: LINK_ALL_PARAM,
  },
  handler: async (ctx, p) => {
    const { links, nextCursor } = await readLinkEdges(ctx, p, 'get_links', 'out');
    return finishLinkPage(links, nextCursor);
  },
  scope: 'read',
  cliHints: { name: 'links', aliases: ['get_links'], positional: ['slug'] },
};

const get_backlinks: Operation = {
  name: 'get_backlinks',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description: `Links to a page, ≤${LINK_READ_DEFAULT_LIMIT}/call; group:"page" by referrer, newest first.`,
  params: {
    slug: { type: 'string', description: 'Page slug.', required: true },
    status: STARTER_STATUS_PARAM,
    as_of: STARTER_AS_OF_PARAM,
    source_id: LINK_SOURCE_ID_PARAM,
    all_sources: LINK_ALL_SOURCES_PARAM,
    type: { type: 'string', description: 'Referrer type.' },
    group: { type: 'string', enum: ['page'], description: 'Per page.' },
    limit: { type: 'number', minimum: 1, description: `≤${LINK_READ_MAX_LIMIT}` },
    cursor: { type: 'string', description: 'Next.' },
    all: LINK_ALL_PARAM,
  },
  handler: async (ctx, p) => {
    if (p.group !== undefined) return readBacklinkPage(ctx, p, (await resolveLinkReadScope(ctx, p, 'get_backlinks')).policy);
    const { links, nextCursor } = await readLinkEdges(ctx, p, 'get_backlinks', 'in');
    const policy = async () => (await resolveLinkReadScope(ctx, p, 'get_backlinks')).policy;
    return finishLinkPage(await withLinkPageStatus(ctx, policy, links), nextCursor);
  },
  scope: 'read',
  cliHints: { name: 'backlinks', positional: ['slug'] },
};

const list_link_sources: Operation = {
  name: 'list_link_sources',
  mutating: false,
  idempotent: true,
  outputRedaction: 'no_stored_text',
  // v114 (#1941): the read-side counterpart to link-add/link-rm. Since
  // link_source is now an open kebab provenance (no allowlist), this is how an
  // agent discovers which provenances a brain actually carries.
  description: 'Link provenances (e.g. markdown, manual) with their edge counts.',
  params: {},
  handler: async (ctx) => {
    // Route through sourceScopeOpts so the read honors both scalar ctx.sourceId
    // and federated ctx.auth.allowedSources (no cross-source provenance leak).
    return ctx.engine.listLinkSources(sourceScopeOpts(ctx));
  },
  scope: 'read',
  cliHints: { name: 'link-sources' },
};

/**
 * Hard cap on traverse_graph depth from MCP callers. The walk is breadth-first
 * and bounded by TRAVERSE_WALK_ROW_CAP pages, but each hop is one more layer of
 * work; without a cap a remote MCP caller could pass depth=1e6. 10 hops is well
 * beyond any realistic
 * relationship query (your OpenClaw's "people who attended meetings with Alice"
 * is 2 hops; the deepest meaningful chain in our test data is 4).
 */
const TRAVERSE_DEPTH_CAP = 10;

/**
 * Default depth for the remote no-direction call. #4666 made that call
 * bidirectional; on an entity hub a depth-5 `both` walk reaches most of the
 * brain and returns the 5,000-row cap of edges on every agent turn. Two hops
 * covers the realistic relationship query ("people who
 * attended meetings with Alice"); a caller that wants more passes `depth`
 * explicitly (still honored up to TRAVERSE_DEPTH_CAP).
 */
const REMOTE_BIDIRECTIONAL_DEFAULT_DEPTH = 2;
const DEFAULT_TRAVERSE_DEPTH = 5;

/**
 * traverse_graph with `hops`: an agent-structured typed chain over the same
 * executor the search planner uses. Returns answers with the evidence edges of
 * each best path and per-hop diagnostics; a chain that finds nothing is a
 * successful result carrying a `relational_chain` notice with the next call.
 */
async function traverseChain(ctx: OperationContext, p: Record<string, unknown>, slug: string) {
  const parsed = validateChainHops(p.hops);
  if (!parsed.ok) {
    throw opError('invalid_params', `traverse_graph: ${parsed.path}: ${parsed.problem}.`,
      `Fix ${parsed.path} and retry; omit hops to walk the graph without a chain.`);
  }
  const { policy } = await resolveLinkReadScope(ctx, p, 'traverse_graph');
  const temporal = await resolveEdgeTemporal(ctx, p, 'traverse_graph');
  reportTemporal(ctx, 'traverse_graph', p, temporal, null);
  const anchors = await resolveChainAnchors(ctx.engine, slug, policy);
  const plan: ChainPlan = { hops: parsed.hops, excludeAnchor: false };
  const { rows, diagnostics } = await runRelationalChain(ctx.engine, anchors, plan, temporal.disabled ? policy : { ...policy, temporal });
  const remote = ctx.remote !== false;
  const edge = (e: ChainEvidenceEdge) => ({ ...e, context: presentEdgeContext(e.context, remote) });
  const answers = rows.filter(r => r.role === 'answer');
  const contexts = (await worldLinkContexts(ctx.engine, ctx.remote,
    answers.flatMap(r => r.best_path.edges.map(e => ({ ...e, source_id: r.source_id }))), chainStoredEdge)).map(e => e.context);
  let next = 0;
  const rawHops = p.hops as Array<Record<string, unknown>>;
  const status = diagnostics.status;
  const fix = chainFix(slug, status, rawHops, readScopeArgs(p), diagnostics.empty_hop);
  if (status !== 'fired' && fix) ctx.emitNotice?.({ code: 'relational_chain', kind: 'degraded', why: fix.why, fix });
  const ignored = (['depth', 'link_type', 'direction'] as const).filter(k => p[k] !== undefined);
  return {
    anchor: slug,
    answers: answers.map(r => ({ slug: r.slug, source_id: r.source_id, path_count: r.path_count, score: r.score })),
    paths: answers.map(r => ({ nodes: r.best_path.nodes, edges: r.best_path.edges.map(e => edge({ ...e, context: contexts[next++] ?? null })) })),
    diagnostics,
    ...(ignored.length ? { set_aside: { ignored, note: `Walked the hops chain; ignored ${ignored.length > 1 ? `${ignored.slice(0, -1).join(', ')} and ${ignored[ignored.length - 1]}` : ignored[0]}: each hop names its link type and direction (toward), and the chain length is the number of hops.` } } : {}),
  };
}

/** A CLI flag token built at runtime (the flag-registry generator scans literal flag strings per command). */
const cliFlag = (name: string) => `--${name}`;

const readScopeArgs = (p: Record<string, unknown>) => ({
  ...(p.source_id !== undefined ? { source_id: p.source_id } : {}), ...(p.all_sources === true ? { all_sources: true } : {}),
});

function chainFix(slug: string, status: string, hops: Array<Record<string, unknown>>, scope: Record<string, unknown>, emptyHop?: number): Action | undefined {
  const hopArgs = (hs: Array<Record<string, unknown>>) => hs.flatMap(h => [cliFlag('hop'), `${String(h.link_type)}:${String(h.toward)}`]);
  if (status === 'anchor_not_found') return readFix(`No page "${slug}" is visible in the searched sources; search for the entity to find its exact slug, then retry the chain with that slug.`,
    { argv: ['gbrain', 'search', slug], mcp: { tool: 'search', arguments: { query: slug } } });
  if (status === 'no_edges') return readFix(`"${slug}" has no typed ${String(hops[0]?.link_type)} edges in the needed direction; the relationship may only be written as plain mentions. A depth-1 walk shows what is linked.`,
    { argv: ['gbrain', 'graph-query', slug, cliFlag('depth'), '1'], mcp: { tool: 'traverse_graph', arguments: { slug, depth: 1, ...scope } } });
  if (status === 'empty_hop' && emptyHop && emptyHop > 1) {
    const prefix = hops.slice(0, emptyHop - 1);
    return readFix(`Hop ${emptyHop} (${String(hops[emptyHop - 1]?.link_type)}) found no typed edges from the pages hop ${emptyHop - 1} reached; the shorter chain lists those pages so you can inspect them.`,
      { argv: ['gbrain', 'graph-query', slug, ...hopArgs(prefix)], mcp: { tool: 'traverse_graph', arguments: { slug, hops: prefix, ...scope } } });
  }
  if (status === 'truncated') return readFix('A chain cap was hit (diagnostics.cap_hit names the cap and hop), so lower-ranked answers were dropped; narrow the chain or start from a more specific page for a complete list.',
    { argv: ['gbrain', 'graph-query', slug, ...hopArgs(hops)], mcp: { tool: 'traverse_graph', arguments: { slug, hops, ...scope } } });
  return undefined;
}

const traverse_graph: Operation = {
  name: 'traverse_graph',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description: `Walk the link graph from a page. Remote default: both directions, depth ${REMOTE_BIDIRECTIONAL_DEFAULT_DEPTH}.`,
  params: {
    slug: { type: 'string', description: 'Start page slug.', required: true },
    depth: { type: 'number', description: `Max depth (cap ${TRAVERSE_DEPTH_CAP}).` },
    link_type: { type: 'string', description: 'Only this link type.' },
    direction: { type: 'string', description: 'Remote default both.', enum: ['in', 'out', 'both'] },
    hops: {
      type: 'array',
      minItems: 1,
      description: '≤3 typed hops, e.g. [{"link_type":"founded","toward":"subject"}]; toward: object|subject.',
      items: { type: 'object', properties: { link_type: { type: 'string' }, toward: { type: 'string' } } },
      fullSurfaceOnly: true,
    },
    source_id: LINK_SOURCE_ID_PARAM,
    all_sources: LINK_ALL_SOURCES_PARAM,
  },
  handler: async (ctx, p) => {
    const slug = p.slug as string;
    if (p.hops !== undefined) return traverseChain(ctx, p, slug);
    const linkType = p.link_type as string | undefined;
    // #4666: remote callers (ctx.remote !== false — fail-closed) default to
    // direction=both, so a node with only INBOUND typed edges stops reading
    // as nodes=1/links=0 (indistinguishable from edge absence). An explicit
    // direction param still wins for callers that want outbound-only.
    const requestedDirection = p.direction as 'in' | 'out' | 'both' | undefined;
    const directionDefaultedToBoth = requestedDirection === undefined && ctx.remote !== false;
    const direction = requestedDirection ?? (directionDefaultedToBoth ? 'both' : undefined);
    // Depth default follows the direction default: a remote call that did not
    // ask for a direction (so walks `both`) AND did not ask for a depth gets
    // the conservative bidirectional default; everything else keeps 5.
    const depthRequested = typeof p.depth === 'number' && p.depth > 0;
    const requestedDepth = depthRequested
      ? (p.depth as number)
      : directionDefaultedToBoth ? REMOTE_BIDIRECTIONAL_DEFAULT_DEPTH : DEFAULT_TRAVERSE_DEPTH;
    if (requestedDepth > TRAVERSE_DEPTH_CAP) {
      ctx.logger.warn(`[gbrain] traverse_graph depth clamped from ${requestedDepth} to ${TRAVERSE_DEPTH_CAP}`);
    }
    const depth = Math.max(1, Math.min(requestedDepth, TRAVERSE_DEPTH_CAP));
    // v0.34.1 (#861 — P0 leak seal): thread caller's source scope so graph
    // walks stay within the auth'd client's accessible sources. Pre-fix,
    // traverseGraph / traversePaths happily followed edges into pages from
    // foreign sources, leaking topology + page metadata via the graph op.
    // #5827: the walk scopes every visited page, so a federated `sourceIds[]`
    // (no-grant remote, or a trusted local unqualified read) walks the
    // federated set in one query; nodes and edges carry their source ids.
    const { policy: readScope } = await resolveLinkReadScope(ctx, p, 'traverse_graph');
    const temporal = await resolveEdgeTemporal(ctx, p, 'traverse_graph');
    const scope = temporal.disabled ? readScope : { ...readScope, temporal };
    reportTemporal(ctx, 'traverse_graph', p, temporal, null);
    // Backward compat: trusted local no-filter callers keep the legacy
    // GraphNode[] shape used by `gbrain graph`. Remote MCP callers need the
    // natural no-filter invocation to surface inbound-only typed edges too,
    // so they default to direction=both and get explicit GraphPath[] edges.
    if (linkType === undefined && requestedDirection === undefined && ctx.remote === false) {
      return ctx.engine.traverseGraph(slug, depth, scope);
    }
    const { paths, truncated } = await ctx.engine.traversePathsDetailed(slug, { depth, linkType, direction, ...scope });
    // Cap hit: the walk stopped at TRAVERSE_WALK_ROW_CAP visited pages or the
    // output at TRAVERSE_PATH_ROW_CAP edge rows, dropping the deepest edges.
    // The stderr note stays; a per-call notice (GBRA-200 stamps it) tells MCP callers, so the GraphPath[] wire shape stays unchanged.
    if (truncated) {
      ctx.logger.warn(
        `[gbrain] traverse_graph output truncated (walk cap ${TRAVERSE_WALK_ROW_CAP} pages, ${TRAVERSE_PATH_ROW_CAP} edge rows; shallowest first). ` +
        `Lower depth or narrow with link_type/direction for a complete walk.`,
      );
      const why = `The walk stopped at its cap (${TRAVERSE_WALK_ROW_CAP} pages, ${TRAVERSE_PATH_ROW_CAP} edge rows; shallowest first), so deeper edges are missing; walk one level shallower or narrow with link_type or direction for a complete walk.`;
      const fix = depth > 1 ? readFix(why, {
        mcp: { tool: 'traverse_graph', arguments: {
          slug, depth: depth - 1, ...(linkType ? { link_type: linkType } : {}), direction, ...readScopeArgs(p),
        } },
      }) : undefined;
      ctx.emitNotice?.({ code: 'graph_walk_truncated', kind: 'degraded', why, ...(fix ? { fix } : {}) });
    }
    return worldLinkContexts(ctx.engine, ctx.remote, paths, storedEdge);
  },
  scope: 'read',
  cliHints: { name: 'graph', positional: ['slug'] },
};

const WANTED_DEFAULT_LIMIT = 50;
const WANTED_MAX_LIMIT = 100;

const wanted_pages: Operation = {
  name: 'wanted_pages',
  mutating: false,
  writeInference: 'none',
  idempotent: true,
  outputRedaction: 'retrieval',
  description: 'Link targets that have no page yet, most-referenced first: each was written as a link but its page does not exist, so no edge exists. Use to find entities worth a page (enrichment) or typo links to fix. The edge appears on its own once the page is created.',
  params: {
    source_id: { type: 'string', description: 'Only targets referenced from this source (must be inside your source grant).' },
    limit: { type: 'number', minimum: 1, description: `Rows per page (default ${WANTED_DEFAULT_LIMIT}, max ${WANTED_MAX_LIMIT}).` },
    offset: { type: 'number', description: 'Skip the first N targets.' },
    count_only: { type: 'boolean', description: 'Return the total with no rows.' },
  },
  scope: 'read',
  handler: async (ctx, p) => {
    const named = p.source_id === undefined ? undefined : String(p.source_id);
    if (named !== undefined) assertSourceInCallerScope(ctx, named);
    const policy = named !== undefined ? await readPolicyOpts(ctx, { sourceId: named }) : await readPolicyOpts(ctx);
    const limit = p.limit === undefined ? WANTED_DEFAULT_LIMIT : Number(p.limit);
    const offset = p.offset === undefined ? 0 : Number(p.offset);
    const limitOk = Number.isInteger(limit) && limit >= 1 && limit <= WANTED_MAX_LIMIT;
    if (!limitOk || !Number.isInteger(offset) || offset < 0) {
      throw invalidParam(ctx, 'wanted_pages', limitOk ? 'offset' : 'limit',
        `wanted_pages: limit must be 1-${WANTED_MAX_LIMIT} and offset a non-negative integer`,
        limitOk ? { def: wanted_pages.params.offset, example: 0 } : { def: wanted_pages.params.limit, example: WANTED_DEFAULT_LIMIT });
    }
    const { total, rows } = await listWantedPages(ctx.engine, { sourceId: policy.sourceId, sourceIds: policy.sourceIds,
      excludePrivate: policy.excludePrivate, privateFilter: privatePagesFilterForCaller,
      limit: p.count_only === true ? 1 : limit, offset });
    const next = offset + limit < total ? offset + limit : null;
    return {
      total, limit, offset, next_offset: p.count_only === true ? null : next,
      targets: p.count_only === true ? [] : rows.map(row => ({ ...row,
        next: row.existing_matches.length
          ? `A page with this name exists (${row.existing_matches[0].slug}); link it by its full slug, e.g. [[${row.existing_matches[0].slug}]].`
          : `Create ${row.target} if it is a real entity (the ${row.referenced_by} linking page(s) gain the edge on the next extraction), or fix the link if it is a typo.` })),
      ...(total === 0 ? { note: 'Every authored link resolves to an existing page.' } : {}),
    };
  },
  cliHints: { name: 'wanted' },
};


// Ops in EXACTLY the canonical `operations` array order.
export const linksOperations: Operation[] = [
  add_link, remove_link, get_links, get_backlinks, list_link_sources, traverse_graph, wanted_pages,
];