Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.8 KB
Raw Blame
/**
 * #5969 (D3): a put_page / put_pages body that leaves out the page's Timeline
 * section. The section's presence is read from the content as the caller sent
 * it, before any normalization: `splitBody` returns an empty timeline both for
 * an omission and for a present-but-empty section, and the bare-heading
 * recognizer needs a dated bullet, so the two are indistinguishable later.
 *
 *   - `omitted`: no timeline sentinel and no `## Timeline` / `## History`
 *     heading outside code. A remote caller is refused when stored rows it saw
 *     would be deleted, unless it passes `drop_timeline: true`; a local
 *     preserving writer (no expected_revision) keeps them.
 *   - `emptied`: the section is there with no entries: a deliberate delete for
 *     every writer class, reported.
 *   - `present`: a normal diff, reported.
 *
 * Admission records the section on the intent (`timeline_section`), so
 * failed-writes replay and put_pages batch children carry it unchanged.
 * Maintenance, reconcile and file-import writers record none and keep the
 * shared projection policy.
 */
import type { BrainEngine } from '../engine.ts';
import { findTimelineSplitIndex, frontmatterBodyOffset, parseMarkdown } from '../markdown.ts';
import type { PageSnapshot } from '../page-state/types.ts';
import { opError, type OperationError } from '../ops/contract.ts';
import type { Action } from '../agent-output.ts';
import { bodyHasTimelineEntries, timelineRowsToRemove, type ProjectionWriter, type TimelineRowsRemoved, type TimelineWritePolicy } from './canonical-projections.ts';

export const TIMELINE_SECTIONS = ['present', 'emptied', 'omitted'] as const;
export type TimelineSection = typeof TIMELINE_SECTIONS[number];
export const TIMELINE_OMISSION_CODE = 'timeline_rows_would_be_removed';
const DOCS = 'docs/guides/write-refusals.md#timeline_rows_would_be_removed';
const TIMELINE_HEADING = /^##\s+(timeline|history)\b/i;

function hasTimelineHeading(lines: string[]): boolean {
  let fenced = false;
  for (const line of lines) {
    if (/^\s*(`{3,}|~{3,})/.test(line)) { fenced = !fenced; continue; }
    if (!fenced && TIMELINE_HEADING.test(line.trim())) return true;
  }
  return false;
}

/** What the caller's raw content says about its Timeline section. */
export function timelineSectionOf(content: string, slug: string): TimelineSection {
  const lines = content.slice(frontmatterBodyOffset(content)).split('\n');
  if (findTimelineSplitIndex(lines) === -1 && !hasTimelineHeading(lines)) return 'omitted';
  return bodyHasTimelineEntries(parseMarkdown(content, slug), slug) ? 'present' : 'emptied';
}

export function isTimelineSection(value: unknown): value is TimelineSection {
  return (TIMELINE_SECTIONS as readonly unknown[]).includes(value);
}

/** The policy an ordinary put_page intent carries; none for every other writer. */
export function timelineWritePolicy(intent: Record<string, unknown>, remote: boolean, writer: ProjectionWriter): TimelineWritePolicy | undefined {
  if (!isTimelineSection(intent.timeline_section)) return undefined;
  return { section: intent.timeline_section, drop: intent.drop_timeline === true, preserveOmitted: !remote && writer === 'preserving' };
}

export function timelineOmissionRefusal(slug: string, sourceId: string, removed: TimelineRowsRemoved): OperationError {
  const rows = `${removed.count} timeline row(s) dated ${removed.earliest}${removed.latest !== removed.earliest ? ` to ${removed.latest}` : ''}`;
  const retry: Action = { mcp: { tool: 'put_page', arguments: { slug, source_id: sourceId, drop_timeline: true } }, consent: [], actor: 'agent', requires_exclusive: false,
    why: 'Only if removing every one of those dated entries is intended: the same complete content with drop_timeline: true and a new request_id deletes them and reports them in timeline_rows_removed.',
    inputs: [{ name: 'content', how: 'the same complete page content' }, { name: 'request_id', how: 'a new UUID' }] };
  return opError(TIMELINE_OMISSION_CODE, `This put_page has no Timeline section, so it would delete ${rows} from ${slug}; nothing was written.`,
    `Read the page with get_page include_content:true, keep its Timeline section in your content and resubmit with a new request_id. To remove every dated entry on purpose, resubmit the same content with drop_timeline: true; to remove only some, send the section without those bullets.`,
    { why: 'put_page content replaces the whole page, and a body without a Timeline section would delete dated entries other writers added (add_timeline_entry, imports); a remote write must say so explicitly.',
      docs: DOCS,
      fix: { mcp: { tool: 'get_page', arguments: { slug, source_id: sourceId, include_content: true } }, consent: [], actor: 'agent', requires_exclusive: false,
        why: `Returns ${slug} with its current Timeline section, so the resubmitted content keeps those entries.`,
        verify: { mcp: { tool: 'get_timeline', arguments: { slug } } }, then: retry } });
}

/**
 * Refuse a remote omission that would delete rows. Runs before admission (the
 * caller gets the full fix) and again during preparation against the pinned
 * prior, so a row added in between is not deleted silently.
 */
export async function assertTimelineNotOmitted(engine: BrainEngine, input: { intent: Record<string, unknown>; remote: boolean; writer: ProjectionWriter;
  slug: string; sourceId: string; content: string; prior: PageSnapshot | null }): Promise<void> {
  const policy = timelineWritePolicy(input.intent, input.remote, input.writer);
  if (!input.remote || policy?.section !== 'omitted' || policy.drop || !input.prior || input.prior.page.deleted_at) return;
  const removed = await timelineRowsToRemove(engine, parseMarkdown(input.content, input.slug), input.prior, input.slug, input.writer, policy);
  if (removed) throw timelineOmissionRefusal(input.slug, input.sourceId, removed);
}