Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.6 KB
Raw Blame
/**
 * Guest notes, slice 4 (GBRA-504, decision J1): the brain owner keeps a guest note as an owner page.
 *
 * promote_guest_note (CLI: gbrain guests promote) runs only for the owner: the trusted local CLI outside
 * enforced-member mode and outside an --as preview, or a remote or stdio caller that reads as the owner (bound to
 * config access.owner_member, speaking for no one else). Everyone else is refused guest_promotion_owner_only before
 * anything is read. The owner page is a normal put_page through the caller's own write path (git first where the target
 * source has a repository, database-only where it has none), carrying the guest note's type, title, body and readers
 * plus 'promoted_from: <guest source>:<slug>' for people reading it. The link itself lives in guest_promotions (one row
 * per guest page and target; a link whose target page was purged no longer counts as kept, and promoting again rewrites
 * the page and that one link), which
 * guest rows read as guest.promoted (guests/marker.ts), and which refuses the broker's delete of the note
 * (guests/admission.ts refuseRemoteGuestDelete). The guest page and its mark are never changed.
 */
import { OperationError, type OperationContext } from '../ops/contract.ts';
import { federatedSearchScope } from '../ops/context.ts';
import { serializeMarkdown } from '../markdown.ts';
import { assertInlineBody } from '../page-body/page-shape.ts';
import { currentCallerAccess } from '../search/private-visibility.ts';
import type { PageType } from '../types.ts';
import type { BrainEngine } from '../engine.ts';

const DOCS = 'docs/guides/write-refusals.md#guest_promotion_owner_only';

export function guestPromotionOwnerOnly(slug: unknown): OperationError {
  const command = typeof slug === 'string' && slug.trim() ? 'gbrain guests promote ' + slug.trim().toLowerCase() : 'gbrain guests promote with the note\'s slug';
  return new OperationError('guest_promotion_owner_only', 'Only the brain owner can keep a guest note as an owner page, so nothing was read or written.',
    'Do not retry. Ask the brain owner; if they want to keep the note, they run ' + command + ' on the brain host.', DOCS);
}

/**
 * The owner, and only the owner, may promote (see the module comment). Enforced-member mode never reaches here as a
 * trusted local caller: its gate (cli/enforced-member-classes.ts) refuses gbrain guests and promote_guest_note.
 */
export function isGuestPromotionOwner(ctx: Pick<OperationContext, 'remote' | 'viaSubagent' | 'accessIdentity' | 'applyRemoteReadPolicy'>): boolean {
  if (ctx.viaSubagent) return false;
  if (ctx.remote === false) return !ctx.applyRemoteReadPolicy && !ctx.accessIdentity?.length;
  const access = currentCallerAccess();
  return access.owner === true && !access.actor;
}

const text = (value: unknown, name: string, required = false): string | undefined => {
  if (value === undefined && !required) return undefined;
  if (typeof value !== 'string' || value.trim() === '') throw new OperationError('invalid_params', name + ' must be a non-empty string.', 'Pass ' + name + ' as a page slug or source id.');
  return value.trim();
};

async function guestNote(ctx: OperationContext, slug: string, guestSource: string | undefined): Promise<{ id: number; source_id: string }> {
  const rows = await ctx.engine.executeRaw<{ id: number; source_id: string }>(
    'SELECT p.id, p.source_id FROM pages p JOIN guest_sources g ON g.source_id = p.source_id WHERE p.slug = $1 AND p.deleted_at IS NULL'
      + (guestSource ? ' AND p.source_id = $2' : '') + ' ORDER BY p.source_id', guestSource ? [slug, guestSource] : [slug]);
  const scope = ctx.remote === false ? null : federatedSearchScope(ctx, guestSource);
  const readable = scope ? scope.sourceIds ?? (scope.sourceId !== undefined ? [scope.sourceId] : null) : null;
  const found = rows.filter(r => !readable || readable.includes(r.source_id));
  if (!found.length) {
    throw new OperationError('page_not_found', 'No live guest note ' + slug + (guestSource ? ' in source ' + guestSource : '') + ' is visible here, so nothing was promoted.',
      'Pass the slug of a page in a guest source (find_pages or gbrain guests promote --help); a deleted note is restored by the brain owner first.');
  }
  if (found.length > 1) {
    throw new OperationError('invalid_params', 'Guest note ' + slug + ' exists in several guest sources (' + found.map(r => r.source_id).join(', ') + ').',
      'Pass guest_source naming the one to promote.');
  }
  return { id: Number(found[0]!.id), source_id: found[0]!.source_id };
}

/**
 * Records the promotion link: relinks the one row for this guest page and target, else inserts it. A concurrent
 * promotion that inserted the same link first keeps its row (ON CONFLICT on guest_promotions_link_key, v314), so the
 * second call succeeds instead of failing on the unique key after its page was written.
 */
export async function linkGuestPromotion(engine: Pick<BrainEngine, 'executeRaw'>, link: { guestPageId: number; targetSource: string; targetSlug: string;
  by: { kind: string; id: string }; requestId: string | null }): Promise<void> {
  await engine.executeRaw(`WITH relinked AS (UPDATE guest_promotions SET promoted_by_kind = $4, promoted_by_id = $5, promoted_at = now(), request_id = $6
      WHERE guest_page_id = $1 AND target_source_id = $2 AND target_slug = $3 RETURNING id)
    INSERT INTO guest_promotions (guest_page_id, target_source_id, target_slug, promoted_by_kind, promoted_by_id, request_id)
    SELECT $1, $2, $3, $4, $5, $6 WHERE NOT EXISTS (SELECT 1 FROM relinked) ON CONFLICT DO NOTHING`,
    [link.guestPageId, link.targetSource, link.targetSlug, link.by.kind, link.by.id, link.requestId]);
}

export async function promoteGuestNote(ctx: OperationContext, p: Record<string, unknown>): Promise<Record<string, unknown>> {
  if (!isGuestPromotionOwner(ctx)) throw guestPromotionOwnerOnly(p.slug);
  const slug = text(p.slug, 'slug', true)!.toLowerCase();
  const note = await guestNote(ctx, slug, text(p.guest_source, 'guest_source'));
  const { pageMutationSource, submitPageMutation, requestPrincipalForContext } = await import('../persistence/page-mutations.ts');
  const targetSource = pageMutationSource(ctx, { source_id: p.source_id }, 'put_page');
  if ((await ctx.engine.executeRaw('SELECT 1 FROM guest_sources WHERE source_id = $1', [targetSource])).length) {
    throw new OperationError('invalid_params', 'Source ' + targetSource + ' is a guest source; a promoted note becomes an owner page in an owner source.',
      'Pass source_id naming one of your own sources, or omit it to use your write source.');
  }
  const target = (text(p.to, 'to') ?? slug).toLowerCase();
  const result = { guest: { source_id: note.source_id, slug }, page: { source_id: targetSource, slug: target } };
  const [kept] = await ctx.engine.executeRaw(`SELECT 1 FROM guest_promotions g WHERE g.guest_page_id = $1 AND g.target_source_id = $2 AND g.target_slug = $3
    AND EXISTS (SELECT 1 FROM pages t WHERE t.source_id = g.target_source_id AND t.slug = g.target_slug)`, [note.id, targetSource, target]);
  if (kept) return { status: 'already_promoted', ...result };
  const page = await ctx.engine.getPage(slug, { sourceId: note.source_id });
  if (!page) throw new OperationError('page_not_found', 'Guest note ' + slug + ' was deleted while it was promoted; nothing was written.', 'Ask the brain owner to restore it, then promote it again.');
  assertInlineBody(page, 'promote_guest_note');
  const readers = page.frontmatter?.readable_by;
  const content = serializeMarkdown({ ...(readers !== undefined ? { readable_by: readers } : {}), promoted_from: note.source_id + ':' + slug },
    page.compiled_truth ?? '', page.timeline ?? '', { type: page.type as PageType, title: page.title, tags: [] });
  if (ctx.dryRun) return { dry_run: true, status: 'would_promote', ...result };
  const link = async (requestId: unknown) => linkGuestPromotion(ctx.engine, { guestPageId: note.id, targetSource, targetSlug: target,
    by: await requestPrincipalForContext(ctx), requestId: typeof requestId === 'string' ? requestId : null });
  const written = await ctx.engine.getPage(target, { sourceId: targetSource });
  if (written?.frontmatter?.promoted_from === note.source_id + ':' + slug) {
    await link(null);
    return { status: 'promoted', ...result, recovered: true };
  }
  const params = { slug: target, content, source_id: targetSource, ...(typeof p.request_id === 'string' ? { request_id: p.request_id } : {}) };
  (await import('../persistence/page-visibility.ts')).assertSubmittedReaders(ctx.remote, target, content);
  const write = await submitPageMutation(ctx, { operation: 'put_page', params });
  await link(write.request_id);
  return { status: 'promoted', ...result, write };
}