Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.1 KB
Raw Blame
/**
 * Segmented page storage (Wave B): how a page object says where its body
 * lives. A segmented page (`body_storage = 'segmented'`) keeps its body in
 * `page_body_manifest` + `page_segment_texts`; its `compiled_truth` and
 * `timeline` columns are NULL. Every reader that turns a page row into a
 * `Page` (`rowToPage`, the snapshot readers) gives such a page enumerable
 * getters for the body fields that throw `page_body_segmented`, so a path
 * that needs the whole body as one string fails before it reads or writes
 * anything, and so do `{...page}`, `JSON.stringify(page)` and `structuredClone`.
 *
 * `Page` itself stays one shape (making it a union broke over a thousand
 * sites): the runtime getters and `scripts/check-page-body-readers.ts` are the
 * enforcement, not the type checker.
 */
import { OperationError, opError } from '../ops/contract.ts';
import { PAGE_MAX_BYTES } from '../page-size-policy.ts';
import type { Page } from '../types.ts';
import type { BodyStorage } from './types.ts';

/** A segmented page as metadata: no body strings, only its size. */
export type SegmentedPage = Omit<Page, 'compiled_truth' | 'timeline'> & { body_storage: 'segmented'; body_bytes: number };

type BodyShape = { body_storage?: BodyStorage | null; body_bytes?: number | null };

/** The body fields a page-like object exposes; `content` where the object carries a rendered page. */
export type SegmentedBodyField = 'compiled_truth' | 'timeline' | 'content';

/** True when the page's body lives in segments (its body fields throw). */
export function isSegmentedPage(page: BodyShape): boolean {
  return page.body_storage === 'segmented';
}

/**
 * True when the page's body fields are still the throwing getters: a segmented
 * page that was not read back as strings (`materializedPage` leaves a body over
 * the single-string ceiling unread). Such a body was written by the streamed
 * import, which holds files with facts or takes fences.
 */
export function bodyUnread(page: object): boolean {
  return Object.getOwnPropertyDescriptor(page, 'compiled_truth')?.get !== undefined;
}

/** The page's fields without its body, for a copy whose body comes from elsewhere (a page with an unread body cannot be spread). */
export function withoutBody<T extends object>(page: T): Omit<T, SegmentedBodyField> {
  const copy: Record<string, unknown> = {};
  for (const key of Object.keys(page)) if (key !== 'compiled_truth' && key !== 'timeline' && key !== 'content') copy[key] = (page as Record<string, unknown>)[key];
  return copy as Omit<T, SegmentedBodyField>;
}

/** The stored body a fence merge reads: an unread body holds no facts or takes fences, so it reads as empty. */
export function fenceBody(page: { compiled_truth: string; timeline?: string | null }): { compiled_truth: string; timeline: string } {
  return bodyUnread(page) ? { compiled_truth: '', timeline: '' } : { compiled_truth: page.compiled_truth, timeline: page.timeline ?? '' };
}

/** The refusal every whole-body path gives a segmented page; `site` names the path in the message. */
export function pageBodySegmentedError(page: { slug?: string; source_id?: string }, site: string) {
  const slug = page.slug ?? '<unknown>';
  const sourceId = page.source_id ?? 'default';
  return opError('page_body_segmented',
    `${site}: page ${slug} (source ${sourceId}) stores its body in segments, and this path reads or writes the whole body as one string. Nothing was read or changed.`,
    "This path cannot process a page stored in segments yet; retrying refuses the same way. Read the page in pieces: get_page body: 'auto' returns its outline and first window, and body: 'window' reads any lines or bytes.",
    { fix: { argv: ['gbrain', 'get', '--source', sourceId, '--body', 'auto', '--', slug],
      mcp: { tool: 'get_page', arguments: { slug, source_id: sourceId, body: 'auto' } },
      consent: [], actor: 'agent', requires_exclusive: false, why: "Returns the page's outline and its first window, with next_cursor to read on." } });
}

/**
 * The refusal of a write that reads the body whole (a fence or timeline edit through the put path) on a segmented page
 * over PAGE_MAX_BYTES (24 MiB): up to it the page is read back as strings and written as a normal put.
 */
export function pageBodyOverCeilingError(page: { slug?: string; source_id?: string; body_bytes?: number | null }, site: string) {
  const slug = page.slug ?? '<unknown>';
  const sourceId = page.source_id ?? 'default';
  return opError('page_body_segmented',
    `${site}: page ${slug} (source ${sourceId}) stores its ${Number(page.body_bytes ?? 0)}-byte body in segments, over the 24 MiB (${PAGE_MAX_BYTES}-byte) limit up to which this write reads the body whole. Nothing was read or changed.`,
    "This write edits a page stored in segments by reading its body whole, which works up to 24 MiB; this page is larger, so retrying refuses the same way. Read the page in pieces: get_page body: 'auto' returns its outline and first window, and body: 'window' reads any lines or bytes.",
    { fix: { argv: ['gbrain', 'get', '--source', sourceId, '--body', 'auto', '--', slug],
      mcp: { tool: 'get_page', arguments: { slug, source_id: sourceId, body: 'auto' } },
      consent: [], actor: 'agent', requires_exclusive: false, why: "Returns the page's outline and its first window, with next_cursor to read on." } });
}

/** True when `fix` is the read step pageBodySegmentedError and pageBodyOverCeilingError give: get_page reading the page in pieces. */
export function readsPageInPieces(fix: { mcp?: { tool?: string } } | undefined): boolean {
  return fix?.mcp?.tool === 'get_page';
}

/**
 * A write refused `page_body_segmented` whose next step reads the page in pieces (its own or, with no fix, the code's
 * registry default), which changes nothing for a writer: the same refusal with no step to run (next: report), and a
 * writer's suggestion unless it carries one of its own. A refusal with a write fix of its own (remember's unattributed
 * save) is left as it is.
 */
export function asSegmentedWriteRefusal(error: unknown): void {
  if (!(error instanceof OperationError) || error.canonicalCode !== 'page_body_segmented') return;
  if (error.fix && !readsPageInPieces(error.fix)) return;
  if (error.fix || !error.suggestion) error.suggestion = 'This write needs the page\'s whole body as one string, which it cannot get from a page stored in segments, so retrying refuses the same way and nothing was changed. '
    + 'On such a page edit_page and append_page change its text, and add_tag and remove_tag its tags.';
  error.fix = { consent: [], actor: 'agent', requires_exclusive: false,
    why: 'No retry of this write can change this page; tell the user which change could not be made, or make it with edit_page, append_page, add_tag or remove_tag.' };
}

/** Throws `page_body_segmented` for a segmented page; `site` names the caller. Inline pages pass. */
export function assertInlineBody(page: BodyShape & { slug?: string; source_id?: string }, site: string): void {
  if (isSegmentedPage(page)) throw pageBodySegmentedError(page, site);
}

/**
 * UTF-8 bytes of the page body: `body_bytes` for a segmented page (its body is
 * never loaded), else the bytes of `compiled_truth` + `timeline`.
 */
export function pageBodyBytes(page: BodyShape & { compiled_truth?: string | null; timeline?: string | null }): number {
  if (isSegmentedPage(page)) return Number(page.body_bytes ?? 0);
  return Buffer.byteLength(page.compiled_truth ?? '', 'utf8') + Buffer.byteLength(page.timeline ?? '', 'utf8');
}

/**
 * Replace the body fields of a segmented page object with enumerable getters
 * and setters that throw `page_body_segmented`. Enumerable on purpose: spread,
 * `JSON.stringify` and `Object.assign` read them and throw instead of copying
 * an empty body.
 */
export function guardSegmentedBody<T extends object>(page: T, site: string,
  fields: readonly SegmentedBodyField[] = ['compiled_truth', 'timeline']): T {
  const ref = page as { slug?: string; source_id?: string };
  for (const field of fields) {
    const refuse = (): never => { throw pageBodySegmentedError(ref, `${site}.${field}`); };
    Object.defineProperty(page, field, { enumerable: true, configurable: false, get: refuse, set: refuse });
  }
  return page;
}