Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.6 KB
Raw Blame
/**
 * GBRA-217: a human reason on a page write. One canonical form for every source of a reason (a caller's
 * `reason` parameter, a Git `gbrain-reason:` trailer), admitted before the write request is journaled.
 *
 * Where it lands: the snapshot a write archives carries it (`page_versions.change_reason`, read back as
 * `replaced_because`), and a write whose file reaches Git carries it in the commit as a path-mapped
 * trailer `gbrain-reason: <path>: <text>`. A private page never puts its reason in a commit message, and
 * a repo-less brain keeps it in the database alone (`reason_recorded.git: 'no_repository'`).
 */
import { relative, sep } from 'node:path';
import { opError } from '../ops/contract.ts';
import { scanTextSpans } from '../secret-scan.ts';
import { privatePagesFilterFragment } from '../search/private-visibility.ts';
import type { GitCommitNote } from './effect-model.ts';
import { sourceCanonicalGit } from './git-door.ts';
import type { SqlEngine, WriteRequest } from './model.ts';
import type { PreparedMutation } from './coordinator.ts';
import type { Notice } from '../agent-output.ts';

export const CHANGE_REASON_MAX = 500;
export const CHANGE_REASON_OPERATIONS: readonly string[] = ['put_page', 'edit_page', 'revert_version'];
export const REASON_TRAILER_KEY = 'gbrain-reason';
const DOCS = 'docs/guides/page-history.md#reasons';

/** Tabs and line breaks become spaces, other control characters go, runs of spaces collapse; empty means absent. */
export function canonicalChangeReason(raw: unknown): string | null {
  if (typeof raw !== 'string') return null;
  const text = raw.replace(/[\t\n\r\u2028\u2029]/g, ' ').replace(/[\u0000-\u001f\u007f]/g, '').replace(/ {2,}/g, ' ').trim();
  return text || null;
}

/**
 * Admission: the canonical reason, or a refusal before anything is journaled. The value is never echoed: an over-long
 * reason is refused by its length, and a secret by the detector that matched.
 */
export function admitChangeReason(raw: unknown): string | null {
  if (raw === undefined || raw === null) return null;
  if (typeof raw !== 'string') throw opError('invalid_params', 'reason must be a string.', 'Pass reason as one line of text, or omit it.');
  const reason = canonicalChangeReason(raw);
  if (reason === null) return null;
  const length = [...reason].length;
  if (length > CHANGE_REASON_MAX) {
    throw opError('change_reason_rejected', `reason is ${length} characters after normalisation; the limit is ${CHANGE_REASON_MAX}. Nothing was written.`,
      `Shorten reason to ${CHANGE_REASON_MAX} characters or fewer and retry the same request.`, { reason: 'reason_too_long', docs: DOCS, legacy_error: 'invalid_params' });
  }
  const hit = scanTextSpans(reason).find(span => span.finding !== null);
  if (hit) {
    const offset = [...reason.slice(0, hit.start)].length;
    throw opError('change_reason_rejected', `reason contains what looks like a secret (${hit.finding!.pattern} at character ${offset}). Nothing was written.`,
      'Remove the secret from reason and retry with a new request_id. A reason is stored in page history and can be pushed in a Git commit message.',
      { reason: 'reason_contains_secret', docs: DOCS, legacy_error: 'invalid_params' });
  }
  return reason;
}

/** The reason note for one path, merged into a note another preparer gave (a repair keeps its subject and trailer). */
export function withReasonNote(path: string, reason: string, base?: GitCommitNote): GitCommitNote {
  const trailer = `${REASON_TRAILER_KEY}: ${path}: ${reason}`;
  return base ? { ...base, trailers: [...(base.trailers ?? []), trailer] }
    : { subject: '', line: `${path}: ${reason}`, trailers: [trailer] };
}

/** A note without what `withReasonNote` added: a reason-only note goes, a merged one keeps its own subject, line and trailers. */
export function withoutReasonNote(note: GitCommitNote): GitCommitNote | undefined {
  const key = `${REASON_TRAILER_KEY}: `;
  const reasons = (note.trailers ?? []).filter(trailer => trailer.startsWith(key)).map(trailer => trailer.slice(key.length));
  if (!reasons.length) return note;
  if (note.subject === '' && reasons.includes(note.line)) return undefined;
  const trailers = (note.trailers ?? []).filter(trailer => !trailer.startsWith(key));
  return { subject: note.subject, line: note.line, ...(trailers.length ? { trailers } : {}) };
}

async function pageWorldVisible(engine: SqlEngine, sourceId: string, slug: string): Promise<boolean> {
  const [page] = await engine.executeRaw<{ world: boolean }>(
    `SELECT ${privatePagesFilterFragment('p')} AS world FROM pages p WHERE p.source_id = $1 AND p.slug = $2 AND p.deleted_at IS NULL`, [sourceId, slug]);
  return page?.world === true;
}

/**
 * The note a file commits with, checked against its page's visibility at commit time: a page that is not world-visible
 * any more (a later member of its group, or a later write, made it private) commits without its reason.
 */
export async function visibleCommitNote(engine: SqlEngine, sourceId: string, slug: unknown, note: GitCommitNote | undefined): Promise<GitCommitNote | undefined> {
  if (!note || typeof slug !== 'string' || withoutReasonNote(note) === note) return note;
  return await pageWorldVisible(engine, sourceId, slug) ? note : withoutReasonNote(note);
}

/**
 * A strict group, once every member has applied and before its one commit: each member's note checked as above, and a
 * member whose reason is dropped reports `git: 'private'` on its receipt.
 */
export async function settleGroupCommitNotes(engine: SqlEngine, members: Array<{ row: Pick<WriteRequest, 'source_id' | 'slug'>; note: GitCommitNote | undefined; outcome: Record<string, unknown> }>): Promise<Array<GitCommitNote | undefined>> {
  const notes: Array<GitCommitNote | undefined> = [];
  for (const { row, note, outcome } of members) {
    const visible = await visibleCommitNote(engine, row.source_id, row.slug, note);
    const recorded = outcome.reason_recorded as ReasonRecorded | undefined;
    if (visible !== note && recorded) outcome.reason_recorded = { ...recorded, git: 'private' };
    notes.push(visible);
  }
  return notes;
}

export type ReasonGit = 'committed' | 'queued' | 'superseded' | 'not_file_backed' | 'private' | 'no_repository' | 'none';
export interface ReasonRecorded { reason: string; version: boolean; version_why?: 'page_created' | 'no_change'; git: ReasonGit }

/**
 * Wraps a page publication so the snapshot its apply archives carries the reason, and its file's commit note carries the
 * trailer when the page that results is world-visible. The snapshot rows are the ones this transaction created for the
 * page (the page lock is held), whichever writer path made them.
 */
export function withChangeReason(row: WriteRequest, prepared: PreparedMutation): PreparedMutation {
  const reason = CHANGE_REASON_OPERATIONS.includes(row.operation) ? canonicalChangeReason(row.intent?.reason) : null;
  if (!reason) return prepared;
  const apply = prepared.apply.bind(prepared);
  prepared.apply = async (tx, preimage) => {
    const pageId = preimage?.page.id ?? null;
    const [before] = pageId === null ? [] : await tx.executeRaw<{ last: number | string | null }>('SELECT max(id) AS last FROM page_versions WHERE page_id = $1', [pageId]);
    const outcome = await apply(tx, preimage);
    const stamped = pageId === null || prepared.noop ? [] : await tx.executeRaw<{ id: number }>(
      'UPDATE page_versions SET change_reason = $2 WHERE page_id = $1 AND id > $3 RETURNING id', [pageId, reason, Number(before?.last ?? 0)]);
    const world = await pageWorldVisible(tx, row.source_id, row.slug);
    let git: ReasonGit;
    if (!prepared.file) git = row.authority.databaseOnlyReason === 'no_repo_configured' ? 'no_repository' : world ? 'not_file_backed' : 'private';
    else if (prepared.noop) git = 'none';
    else if (!world) git = 'private';
    else {
      prepared.file.commit = withReasonNote(relative(prepared.file.root, prepared.file.path).split(sep).join('/'), reason, prepared.file.commit);
      git = await sourceCanonicalGit(tx, row.source_id) ? 'committed' : 'queued';
    }
    const recorded: ReasonRecorded = { reason, version: stamped.length > 0, git,
      ...(stamped.length ? {} : { version_why: prepared.observedRevision === null ? 'page_created' : 'no_change' }) };
    return { ...outcome, reason_recorded: recorded };
  };
  return prepared;
}


/**
 * A receipt's `reason_recorded` once its Git effect settled. A non-strict write's Git effect is superseded when a newer
 * write to the same file commits first: that commit carries only the newer write's note, so this reason is in page
 * history but in no commit. The receipt then says `git: 'superseded'` with a degraded `reason_not_committed` notice.
 * Nothing needs fixing, and retrying the write would be wrong.
 */
export async function settledReasonRecorded(engine: SqlEngine, row: Pick<WriteRequest, 'id' | 'outcome'>): Promise<{ recorded: ReasonRecorded; notice: Notice } | null> {
  const recorded = row.outcome?.reason_recorded as ReasonRecorded | undefined;
  if (recorded?.git !== 'queued') return null;
  const [git] = await engine.executeRaw<{ outcome: Record<string, unknown> | null }>(
    "SELECT outcome FROM persistence_effects WHERE request_id = $1::uuid AND kind = 'git' AND state = 'committed'", [row.id]);
  if (git?.outcome?.git !== 'superseded') return null;
  return { recorded: { ...recorded, git: 'superseded' }, notice: { code: 'reason_not_committed', kind: 'degraded',
    why: 'This write\'s reason is kept in gbrain\'s page history (get_versions replaced_because), but not in a Git commit: a newer write to the same file committed first, carrying only its own reason. Nothing needs fixing; do not retry the write.' } };
}