Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.4 KB
Raw Blame
/**
 * The storage manifest source (GST-1943): one source, `storage`, holding a card per archived item. It is never
 * federated, so ordinary search and bound remote clients without a grant naming it never see cards, and only the
 * storage verbs write it (the page door refuses every other writer, see `assertStorageSourceWriter`).
 *
 * Repo-less brain: a database-only source, created by the first `storage_register`; the database is the record.
 * Repo brain (any active source with a directory): git stays the parent, so the shelf is a hosted git-canonical
 * repository (`hostRepo`), created only by `gbrain storage init` after its preview, which needs managed persistence.
 */
import type { BrainEngine } from '../engine.ts';
import { opError } from '../ops/contract.ts';
import { STORAGE_ROLE, STORAGE_SOURCE_ID } from './door.ts';
import { readFix } from '../ops/op-fix.ts';
import { normalizeSourceConfig, parseSourceConfig } from '../sources-load.ts';
import { addSource } from '../sources-ops.ts';
import { hostRepo, type HostRepoPlan } from '../persistence/hosted-repo.ts';
import { managedPersistenceEnabled } from '../persistence/ownership.ts';
import { syncContentDirectory } from '../sync-applicability.ts';

export { STORAGE_ROLE, STORAGE_SOURCE_ID, storageDoorContext, isStorageDoor, assertStorageSourceWriter } from './door.ts';

export function isStorageRole(config: unknown): boolean {
  return parseSourceConfig(config).role === STORAGE_ROLE;
}

/** `ours`: an empty source a shelf creation started and did not finish marking (hosted by storage init, or database-only). */
export interface StorageSourceState { exists: boolean; archived: boolean; repoBrain: boolean; role: boolean; hosted: boolean; ours: boolean }

/**
 * A repo brain is one with any active source that has a directory (or the legacy sync.repo_path of default); mixed
 * brains count. The gbrain-owned content directory `gbrain init` creates holds no Git checkout, so it does not count.
 */
export async function isRepoBrain(engine: BrainEngine): Promise<boolean> {
  const rows = await engine.executeRaw<{ id: string; local_path: string }>('SELECT id, local_path FROM sources WHERE archived IS NOT TRUE AND local_path IS NOT NULL AND id <> $1', [STORAGE_SOURCE_ID]);
  for (const row of rows) if (!await syncContentDirectory(engine, { sourceId: row.id, repoPath: row.local_path })) return true;
  return !!(await engine.getConfig('sync.repo_path'));
}

export async function storageSourceState(engine: BrainEngine): Promise<StorageSourceState> {
  const [row] = await engine.executeRaw<{ config: unknown; archived: boolean; local_path: string | null; pages: boolean }>(
    'SELECT s.config, s.archived, s.local_path, EXISTS (SELECT 1 FROM pages p WHERE p.source_id = s.id) AS pages FROM sources s WHERE s.id=$1', [STORAGE_SOURCE_ID]);
  const config = row ? parseSourceConfig(row.config) : {};
  const hosted = !!config.hosted_repo;
  return { exists: !!row && !row.archived, archived: !!row?.archived, repoBrain: await isRepoBrain(engine), role: config.role === STORAGE_ROLE, hosted,
    ours: !!row && !row.pages && (hosted || !row.local_path) };
}

/** A `storage` source a shelf creation left without its role (a crash or a concurrent first write), which the next storage write or init finishes. */
const unfinished = (state: StorageSourceState) => state.exists && !state.role && state.ours && (state.hosted || !state.repoBrain);

function notOurs() {
  return opError('storage_manifest_missing', `Source ${STORAGE_SOURCE_ID} exists but is not a storage manifest; nothing was written.`,
    `The storage shelf needs the source ID ${STORAGE_SOURCE_ID}. Ask the user what that source holds before anything else; gbrain sources list shows it. Its pages stay where they are.`);
}

function archivedShelf() {
  return opError('storage_manifest_missing', `Source ${STORAGE_SOURCE_ID} is archived; nothing was written.`,
    `Ask the user whether to bring it back with gbrain sources restore ${STORAGE_SOURCE_ID} (gbrain sources archived shows when it would be purged).`);
}

function initFix() {
  return readFix('Previews creating the storage shelf on this brain; changes nothing.', { argv: ['gbrain', 'storage', 'init', '--dry-run'] });
}

async function markRole(engine: BrainEngine): Promise<void> {
  const [row] = await engine.executeRaw<{ config: unknown }>('SELECT config FROM sources WHERE id=$1', [STORAGE_SOURCE_ID]);
  const config = parseSourceConfig(row?.config);
  config.role = STORAGE_ROLE;
  config.federated = false;
  await engine.executeRaw('UPDATE sources SET config = $1::text::jsonb WHERE id = $2', [JSON.stringify(normalizeSourceConfig(config)), STORAGE_SOURCE_ID]);
}

/**
 * Whether a storage write can land: throws the refusal it would get, and says whether the first write creates the
 * database-only shelf (a repo-less brain) or finishes one a crash or a concurrent first write left without its role.
 * A repo brain must run `gbrain storage init` first; any other `storage` source without the role is someone else's,
 * refused. Writes nothing.
 */
export async function shelfWritable(engine: BrainEngine): Promise<{ creates: boolean; exists: boolean }> {
  const state = await storageSourceState(engine);
  if (state.archived) throw archivedShelf();
  if (state.exists && state.role) return { creates: false, exists: true };
  if (unfinished(state)) return { creates: true, exists: true };
  if (state.exists) throw notOurs();
  if (state.repoBrain) throw opError('storage_manifest_missing', 'This brain keeps its pages in Git, so the storage shelf is a hosted Git repository that gbrain storage init creates; nothing was written.',
    'Preview it with gbrain storage init --dir <absolute path> --dry-run, and apply the command it prints after the user agrees. It needs managed persistence (gbrain sources writer activate).',
    { fix: initFix() });
  return { creates: true, exists: false };
}

/** The shelf a storage write lands in: a repo-less brain gets its database-only source on first use (see shelfWritable). */
export async function ensureStorageSource(engine: BrainEngine): Promise<void> {
  const { creates, exists } = await shelfWritable(engine);
  if (!creates) return;
  if (!exists) {
    try { await addSource(engine, { id: STORAGE_SOURCE_ID, name: 'Storage manifest', federated: false }); } catch (error) {
      const now = await storageSourceState(engine);
      if (!now.exists || (!now.role && !unfinished(now))) throw error;
    }
  }
  await markRole(engine);
}

export interface StorageInitResult { action: 'none' | 'create_database_source' | 'host_repo'; dry_run: boolean; repo_brain: boolean; summary: string[]; apply?: string[]; plan?: HostRepoPlan }

/** `gbrain storage init`: preview, then apply. Repo-less: a database-only source. Repo brain: hostRepo, then the role. */
export async function initStorageSource(engine: BrainEngine, opts: { dir?: string; pushRemote?: string; dryRun: boolean; expect?: string }): Promise<StorageInitResult> {
  const state = await storageSourceState(engine);
  if (state.archived) throw archivedShelf();
  if (state.exists && state.role && (!state.repoBrain || state.hosted)) {
    return { action: 'none', dry_run: opts.dryRun, repo_brain: state.repoBrain, summary: [`The storage shelf (source ${STORAGE_SOURCE_ID}) already exists${state.hosted ? ' as a hosted Git repository' : ''}.`] };
  }
  if (unfinished(state)) {
    const summary = [`Marks source ${STORAGE_SOURCE_ID}, which an earlier storage init or first register created, as the storage shelf (not federated).`];
    if (!opts.dryRun) await markRole(engine);
    return { action: 'none', dry_run: opts.dryRun, repo_brain: state.repoBrain, summary, ...(opts.dryRun ? { apply: ['gbrain', 'storage', 'init'] } : {}) };
  }
  if (state.exists && !state.role) throw notOurs();
  if (!state.repoBrain) {
    const summary = [`Creates source ${STORAGE_SOURCE_ID}, database-only and not federated, as the storage shelf. This brain has no Git checkout, so the database is the record.`];
    if (opts.dryRun) return { action: 'create_database_source', dry_run: true, repo_brain: false, summary, apply: ['gbrain', 'storage', 'init'] };
    await ensureStorageSource(engine);
    return { action: 'create_database_source', dry_run: false, repo_brain: false, summary };
  }
  if (!opts.dir) throw opError('invalid_params', 'This brain keeps its pages in Git, so the storage shelf needs a directory for its hosted repository.',
    'Pass --dir <absolute path outside every checkout>; nothing was changed.', { fix: initFix() });
  if (!await managedPersistenceEnabled(engine)) throw opError('strict_requires_managed',
    'The storage shelf on a brain with a Git checkout is a git-canonical hosted repository, which needs managed persistence; nothing was created.',
    'Ask the user whether to turn on managed persistence for this brain (gbrain sources writer activate), then preview gbrain storage init again.');
  const plan = await hostRepo(engine, { sourceId: STORAGE_SOURCE_ID, dir: opts.dir, dryRun: opts.dryRun, ...(opts.pushRemote ? { pushRemote: opts.pushRemote } : {}), ...(opts.expect ? { expect: opts.expect } : {}) });
  const apply = plan.apply ? ['gbrain', 'storage', 'init', '--dir', opts.dir, ...(opts.pushRemote ? ['--push-remote', opts.pushRemote] : []), '--expect', plan.plan_hash] : undefined;
  if (!plan.dry_run) await markRole(engine);
  return { action: 'host_repo', dry_run: plan.dry_run, repo_brain: true, summary: [...plan.summary, 'The source is not federated and only the storage verbs write it.'], ...(apply ? { apply } : {}), plan };
}