Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.3 KB
Raw Blame
/**
 * #2556 — persist a take row from a think synthesis (`gbrain think --take`).
 *
 * The `--take` flag has been documented since v0.28 ("appends a take row to
 * the anchor page") but `RunThinkOpts.take` was never read anywhere in the
 * pipeline: the CLI parsed it, the MCP op gated it (`safeTake`), and both
 * forwarded it into runThink where it died silently. This module is the
 * missing execution half, wired by commands/think.ts and the `think` op.
 *
 * Semantics:
 *   - synthesisOk === false → warn-skip (never persist a stub/empty answer;
 *     same gate persistSynthesis uses).
 *   - claim = the first substantive line of stripGapsSection(answer),
 *     markdown markers stripped, sanitized to a single fence-safe cell
 *     (control chars collapsed, fence-marker text removed, bounded length).
 *   - holder = resolveOwnerHolder (config emotional_weight.user_holder,
 *     else 'self') — the take is the OWNER's synthesized position.
 *   - persistence goes md-first through addTakeToPage (the same canonical
 *     write-through every takes verb uses: fence row on disk, DB mirrored,
 *     mirror failure downgraded to a warning), with the synthesis-derived
 *     trust on the insert.
 *   - #6982 (D-18): the take is refused (TAKE_WRITE_FAILED) when the page's
 *     file is not its canonical copy (write-through off, `storage.db_only`,
 *     gitignored), when the page has no file, or when the file and the
 *     database differ outside the takes section. Appending there would write
 *     a takes-only or stale file that the next sync imports over the page.
 *   - no brain repo (resolveTakesRepoDir null) → TAKE_MIRROR_UNAVAILABLE
 *     warning, nothing written (md is canonical; a DB-only take would be
 *     clobbered by the next reconcile).
 *
 * Remote (MCP) callers never reach this — the `think` op forces
 * safeTake=false for ctx.remote !== false, unchanged.
 */

import type { BrainEngine } from '../engine.ts';
import { stripGapsSection, type ThinkResult } from './index.ts';
import { resolveOwnerHolder } from '../owner-holder.ts';
import { resolveTakesRepoDir, addTakeToPage, TakesWriteError } from '../takes-write.ts';
import { deriveTrust, derivedMaintenanceTransaction } from '../trust/taint.ts';
import { derivedFileTarget } from '../cycle/derived-write-through.ts';
import { fileDatabaseDriftToken, mirroredBody, readStoredBody } from '../facts/file-body-guard.ts';
import { stripTakesFence, TAKES_FENCE_BEGIN } from '../takes-fence.ts';
import { existsSync, readFileSync } from 'node:fs';

/** Max claim length for a fence cell — one readable line, not an essay. */
export const TAKE_CLAIM_MAX_CHARS = 300;

export interface PersistTakeResult {
  /** Appended fence row number, or null when nothing was written. */
  take_row: number | null;
  /** Markdown file the row landed in (set iff take_row is non-null). */
  path?: string;
  /** Machine-stable warning codes (mirrors the think warnings channel). */
  warnings: string[];
}

/**
 * Extract the claim line: first substantive line of the gaps-stripped answer,
 * heading/bullet/quote markers removed, sanitized to a single fence-safe
 * cell. Returns null when the answer has no substantive line. Pure — the
 * unit-test surface.
 */
export function claimFromAnswer(answer: string): string | null {
  const stripped = stripGapsSection(answer ?? '');
  for (const raw of stripped.split('\n')) {
    let line = raw.trim();
    if (!line) continue;
    line = line.replace(/^#{1,6}\s+/, '').replace(/^[-*+>]\s+/, '').trim();
    if (!line) continue;
    // Fence-cell safety (assertSafeCellText would THROW on these; sanitizing
    // here keeps --take best-effort instead of failing the whole think run):
    // collapse control chars to spaces, drop the fence-marker substring.
    line = line
      .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f\n\r\t]+/g, ' ')
      .replaceAll('gbrain:takes', '')
      .replace(/\s{2,}/g, ' ')
      .trim();
    if (!line) continue;
    if (line.length > TAKE_CLAIM_MAX_CHARS) {
      line = `${line.slice(0, TAKE_CLAIM_MAX_CHARS - 1).trimEnd()}…`;
    }
    // A wholly-strikethrough claim round-trips as active:false — unwrap it.
    const struck = /^~~([\s\S]*)~~$/.exec(line);
    if (struck) line = struck[1].trim();
    if (!line) continue;
    return line;
  }
  return null;
}

/**
 * Append the synthesis claim as a take row on the anchor page. Never throws
 * for the expected refusal shapes (no repo, empty answer, failed synthesis) —
 * those return take_row:null with a machine-stable warning so both callers
 * (CLI + op) surface the same story.
 */
export async function persistTakeFromSynthesis(
  engine: BrainEngine,
  result: Pick<ThinkResult, 'answer' | 'synthesisOk' | 'taint_refs'>,
  opts: { anchor: string; sourceId?: string; lockTimeoutMs?: number },
): Promise<PersistTakeResult> {
  const warnings: string[] = [];

  // Same persistence gate as persistSynthesis: an explicit false means the
  // stub/malformed/empty path — a take asserting nothing must not be minted.
  if (result.synthesisOk === false) {
    warnings.push('TAKE_SKIPPED_SYNTHESIS_FAILED');
    return { take_row: null, warnings };
  }

  const claim = claimFromAnswer(result.answer);
  if (!claim) {
    warnings.push('TAKE_SKIPPED_EMPTY_ANSWER');
    return { take_row: null, warnings };
  }

  const brainDir = await resolveTakesRepoDir(engine);
  if (!brainDir) {
    // md is canonical for takes — with no repo there is nothing durable to
    // write (a DB-only row would be deleted by the next fence reconcile).
    warnings.push('TAKE_MIRROR_UNAVAILABLE');
    return { take_row: null, warnings };
  }

  const holder = resolveOwnerHolder({
    configValue: await engine.getConfig('emotional_weight.user_holder'),
  });

  // #5575 I2: the take restates the synthesis, so it carries the tier of everything in the synthesis prompt.
  const derivation = await deriveTrust(engine, result.taint_refs ?? [], { channel: 'derive:think' });
  try {
    await assertTakeFileCanonical(engine, opts.anchor, opts.sourceId ?? 'default');
    const { rowNum, mirror } = await addTakeToPage(
      {
        engine,
        slug: opts.anchor,
        brainDir,
        sourceId: opts.sourceId,
        trust: derivation.trust,
        ...(opts.lockTimeoutMs !== undefined ? { lockTimeoutMs: opts.lockTimeoutMs } : {}),
      },
      { claim, kind: 'take', holder, source: 'think' },
    );
    if (mirror.mirror_warning) {
      warnings.push(`TAKE_DB_MIRROR_WARNING: ${mirror.mirror_warning}`);
    } else {
      try {
        await derivedMaintenanceTransaction(engine, derivation, async tx => ({ result: undefined, rows: (await tx.executeRaw<{ id: number }>(
          'SELECT k.id FROM takes k JOIN pages p ON p.id=k.page_id WHERE p.source_id=$1 AND p.slug=$2 AND k.row_num=$3',
          [opts.sourceId ?? 'default', opts.anchor, rowNum])).map(take => ({ table: 'takes' as const, id: Number(take.id), sourceId: opts.sourceId ?? 'default' })) }));
      } catch (e) {
        warnings.push(`TAKE_LINEAGE_WARNING: the take was written at its derived trust tier but its input edges were not recorded: ${e instanceof Error ? e.message : String(e)}`);
      }
    }
    return { take_row: rowNum, path: mirror.path, warnings };
  } catch (e) {
    // Typed write refusals (page not found, lock timeout, fence malformed)
    // become a loud warning + null row — think's answer already printed and
    // must not be lost to a persistence failure.
    const detail = e instanceof TakesWriteError ? `${e.code}: ${e.message}` : (e instanceof Error ? e.message : String(e));
    warnings.push(`TAKE_WRITE_FAILED: ${detail}`);
    return { take_row: null, warnings };
  }
}

/** A page body with its takes section (fence and the heading addTakeToPage adds) removed and whitespace collapsed. */
function bodyOutsideTakes(compiledTruth: string | null, timeline: string | null): string {
  const text = `${compiledTruth ?? ''}\n${timeline ?? ''}`.replace(new RegExp(`(^|\\n)## Takes\\s*\\n(?=${TAKES_FENCE_BEGIN})`), '$1');
  return stripTakesFence(text).replace(/\s+/g, ' ').trim();
}

async function assertTakeFileCanonical(engine: BrainEngine, slug: string, sourceId: string): Promise<void> {
  const stored = await readStoredBody(engine, sourceId, slug);
  if (!stored) return;
  const resolved = await derivedFileTarget(engine, slug, sourceId);
  if (!resolved.ok) {
    throw new TakesWriteError('mirror_unavailable',
      `${slug} has no canonical markdown file (${resolved.skipped}), so the take was not written: a takes file there would be imported over the database page.`,
      `Add it with gbrain takes add ${slug} --source ${sourceId}, which puts a database-only page's take in its database body.`);
  }
  const path = resolved.target.filePath;
  if (!existsSync(path)) {
    throw new TakesWriteError('mirror_unavailable',
      `${slug} has no checkout file, so the take was not written: a takes-only file would be imported over the database page.`,
      `Restore the page's file first (gbrain get ${slug} --source ${sourceId}, then gbrain put ${slug} --source-id ${sourceId} with write-through on), then rerun the take.`);
  }
  const file = mirroredBody(readFileSync(path, 'utf-8'), slug);
  if (bodyOutsideTakes(file.compiled_truth, file.timeline) !== bodyOutsideTakes(stored.compiled_truth, stored.timeline)) {
    throw new TakesWriteError('mirror_unavailable', fileDatabaseDriftToken(slug, sourceId, 'before', 'the take was not written'));
  }
}