Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.8 KB
Raw Blame
import { AsyncLocalStorage } from 'node:async_hooks';
import { describeFixes } from '../fence-repair/report.ts';
import { basename, relative } from 'node:path';
import type { BrainEngine } from '../engine.ts';
import type { Action } from '../agent-output.ts';
import { opError, OperationError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { importFromContent } from '../import-file.ts';
import { readCommittedBlob } from './revision.ts';
import { parseMarkdown } from '../markdown.ts';
import { prepareCanonicalProjections } from '../persistence/canonical-projections.ts';
import { digest } from '../persistence/digest.ts';
import type { ResolvedPack } from '../schema-pack/registry.ts';
import type { CompanyBrainPlan, InspectionEntry } from './types.ts';
import type { SourceIngestionCheckpoint } from './receipts.ts';
import { companyBrainProfile, companyBrainPolicyFingerprint, type CompanyBrainProfile } from './policy.ts';
import { maintenanceTransaction } from '../persistence/attribution.ts';
import { syncDispatchRow } from '../sync-dispatch-read.ts';
export { companyBrainProfile, type CompanyBrainProfile } from './policy.ts';

function statusFix(sourceId: string): Action {
  return readFix(`Shows source ${sourceId}'s registration, ingestion receipt, and outstanding phase.`, { argv: ['gbrain', 'sources', 'status', '--json'] });
}

function resumeCommand(sourceId: string): string {
  return `gbrain sync --source ${sourceId} --no-embed --no-pull`;
}

export async function getCompanyBrainProfile(engine: BrainEngine, sourceId: string): Promise<CompanyBrainProfile | null> {
  // The receipt a source without a policy is checked for (of the source's current incarnation) is read beside it.
  // GBRA-133: inside a CLI sync's routing scope the source's routing row answers both (sync-dispatch-read.ts).
  const routing = await syncDispatchRow(engine, sourceId);
  const [[source], [receipt]] = routing ? [routing.id === null ? [] : [routing], routing.company_receipt ? [true] : []] : await Promise.all([engine.executeRaw<{ config: unknown; incarnation: string }>('SELECT config,incarnation FROM sources WHERE id=$1', [sourceId]),
    engine.executeRaw(`SELECT r.id FROM source_ingestion_receipts r JOIN sources s ON s.id=r.source_id AND s.incarnation=r.source_incarnation
      WHERE r.source_id=$1 AND r.profile='company-brain' LIMIT 1`, [sourceId])]);
  if (!source) return null;
  const profile = companyBrainProfile(source.config);
  if (!profile) {
    if (receipt) {
      throw opError('profile_incompatible', 'The durable company approval has no source policy. Reconnect explicitly; sync cannot fall back to an unrestricted profile.',
        `Source ${sourceId} has a company-brain receipt but no stored source policy. Check its status; reconnecting means previewing removal with gbrain sources remove ${sourceId} --dry-run and connecting again, a destructive step the user approves. Do not edit stored policy fields.`,
        { fix: statusFix(sourceId) });
    }
  }
  return profile;
}

export interface CompanyBrainSyncContext {
  sourceId: string;
  sourceIncarnation: string;
  receiptId: string;
  plan: CompanyBrainPlan;
  entries: ReadonlyMap<string, InspectionEntry>;
  pack: ResolvedPack;
  policyFingerprint: string;
  failureCode?: string;
  protect(checkpoints: SourceIngestionCheckpoint[]): Promise<void>;
}
const active = new AsyncLocalStorage<CompanyBrainSyncContext>();
export const withCompanyBrainSync = <T>(context: CompanyBrainSyncContext, run: () => T): T => active.run(context, run);
export function currentCompanyBrainSync(sourceId?: string): CompanyBrainSyncContext | undefined {
  const context = active.getStore();
  return context?.sourceId === sourceId ? context : undefined;
}

export async function withCompanyBrainSource<T>(engine: BrainEngine, sourceId: string | undefined, run: (tx: BrainEngine) => Promise<T>): Promise<T> {
  const context = currentCompanyBrainSync(sourceId);
  if (!context) return run(engine);
  return engine.transaction(async tx => {
    const [source] = await tx.executeRaw<{ incarnation: string; local_path: string; config: unknown }>('SELECT incarnation,local_path,config FROM sources WHERE id=$1 AND NOT archived FOR SHARE', [sourceId!]);
    const profile = source ? companyBrainProfile(source.config) : null;
    if (!source || source.incarnation !== context.sourceIncarnation || !profile || source.local_path !== profile.repository.root || profile.receiptId !== context.receiptId ||
      companyBrainPolicyFingerprint(profile, sourceId!) !== context.policyFingerprint) {
      throw opError('source_changed', 'The source incarnation or approved ingestion changed before publication.',
        `Another connect or sync changed source ${sourceId}'s registration or approval while this import ran, so this page was not published. Check the receipt, then resume with ${resumeCommand(sourceId!)}.`,
        { fix: statusFix(sourceId!) });
    }
    return run(tx);
  });
}

export function softDeleteSyncPages(engine: BrainEngine, slugs: string[], opts: { sourceId: string }): Promise<string[]> {
  return withCompanyBrainSource(engine, opts.sourceId, tx => maintenanceTransaction(tx, inner => inner.softDeletePages(slugs, opts)));
}

export async function readCompanyBrainPlan(engine: BrainEngine, receiptId: string): Promise<CompanyBrainPlan> {
  const [row] = await engine.executeRaw<{ completed_keys: CompanyBrainPlan[] }>(
    "SELECT completed_keys FROM op_checkpoints WHERE op='company-brain-plan' AND fingerprint=$1", [receiptId]);
  if (!row?.completed_keys?.[0]) {
    throw opError('checkpoint_missing', 'The approved source plan is missing; do not restart from a different revision.',
      `Receipt ${receiptId}'s approved plan checkpoint is gone, so gbrain will not resume from another revision. Check the source status; starting over needs a removal preview and a new reviewed connection, which the user approves.`,
      { fix: readFix(`Shows which source holds receipt ${receiptId} and its outstanding phase.`, { argv: ['gbrain', 'sources', 'status', '--json'] }) });
  }
  return row.completed_keys[0];
}

export async function importCompanyBrainFile(engine: BrainEngine, filePath: string, sourceId: string) {
  const context = currentCompanyBrainSync(sourceId);
  if (!context?.plan.revision) {
    throw opError('plan_stale', 'An approved committed source plan is required.',
      `This import of source ${sourceId} ran outside an approved company-brain sync. Run ${resumeCommand(sourceId)} so the approved plan governs it.`,
      { fix: statusFix(sourceId) });
  }
  const path = relative(context.plan.revision.root, filePath).split('\\').join('/');
  const entry = context.entries.get(path);
  if (!entry?.page || entry.disposition !== 'included') {
    throw opError('plan_stale', 'The import path is outside the approved selection.',
      `${path} is not in source ${sourceId}'s approved selection. Changing the selection needs a new inspection and a separately approved connection.`,
      { fix: statusFix(sourceId) });
  }
  const content = (await readCommittedBlob(context.plan.revision, entry, context.plan.limits)).toString('utf8');
  const pack = context.pack;
  const parsed = parseMarkdown(content, entry.page.slug, { activePack: pack.manifest });
  const snapshot = await engine.readPageSnapshot(entry.page.slug, { sourceId });
  const canonical = (page: Pick<typeof parsed, 'type' | 'title' | 'compiled_truth' | 'timeline' | 'frontmatter'>, tags: string[]) => ({ type: page.type, title: page.title, body: page.compiled_truth,
    timeline: page.timeline ?? '', frontmatter: page.frontmatter, tags: [...new Set(tags)].sort() });
  return importFromContent(engine, entry.page.slug, content, { sourceId, noEmbed: true, remote: false, holdNoncanonicalPrivate: true,
    activePack: pack.manifest, filename: basename(path).replace(/\.mdx?$/i, ''), sourcePath: path,
    prepare: async ready => {
      const tags = [...(snapshot?.tags ?? []), ...ready.parsedPage.tags];
      if (digest(canonical(parsed, parsed.tags)) !== digest(canonical(ready.parsedPage, tags))) {
        // #6188 (UC3): a fence Tier 1 would normalize is named by location; the repository commit is the only fix.
        const fences = ready.result.fences_normalized ?? [];
        throw opError('source_writeback_required', fences.length ? `Canonical preparation would normalize a facts or takes fence (${describeFixes(fences)}); this profile never writes repository files.`
          : 'Canonical preparation requires a source-content correction; this profile never writes repository files.',
          fences.length ? `${path} has a facts or takes fence gbrain would normalize (${describeFixes(fences)}), and this profile never edits repository files. Fix the fence in the repository and commit, then resume with ${resumeCommand(sourceId)}.`
            : `${path} would change when published canonically (for example normalized frontmatter or tags), and this profile never edits repository files. Review the needed correction with the user, commit it, then resume with ${resumeCommand(sourceId)}.`);
      }
      if (ready.slug !== entry.page!.slug || ready.observedRevision !== (snapshot?.revision ?? null)) {
        throw opError('revision_conflict', 'The approved file no longer names the same page revision.',
          `Page ${entry.page!.slug} in source ${sourceId} changed after this sync read it, so nothing was published for it. Resume with ${resumeCommand(sourceId)} to import against the current revision.`,
          { fix: statusFix(sourceId) });
      }
      const project = await prepareCanonicalProjections(engine, ready.parsedPage, ready.slug, sourceId, snapshot, 'immutable');
      await withCompanyBrainSource(engine, sourceId, async tx => { await ready.apply(tx); await project(tx); });
      return ready.result;
    } }).catch(error => {
      if (error instanceof OperationError) context.failureCode = error.code;
      throw error;
    });
}