Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.9 KB
Raw Blame
import type { BrainEngine } from '../engine.ts';
import { opError, OperationError } from '../ops/contract.ts';
import type { SqlEngine, WriteRequest } from './model.ts';
import { managedPersistenceEnabled } from './ownership.ts';
import { isConnectorSourceKind } from './connector-identity.ts';
import { detachRestoredPage } from './detached-pages.ts';

/**
 * #5254: a Postgres page write to a filesystem source with no canonical owner
 * (#6449: also a PGLite write to a source activation listed database-only,
 * where the automatic first-write claim is off). Refused by default; `persistence.unbound_write=database_only` lets every
 * page mutation (#5393) write a page with no recorded canonical file to the
 * database only. Those pages
 * carry `pages.database_only_reason='unbound_source'` so writes and sync after
 * binding keep them database-only instead of materializing or overwriting them.
 */
export const UNBOUND_WRITE_KEY = 'persistence.unbound_write';
export const UNBOUND_WRITE_VALUES = ['refuse', 'database_only'] as const;
export type UnboundWritePolicy = typeof UNBOUND_WRITE_VALUES[number];
export const UNBOUND_SOURCE_DOCS = 'docs/guides/write-refusals.md#unbound-sources-on-postgres';
export const UNBOUND_PUBLICATION_MESSAGE = 'The source was bound, or the page gained a canonical file, after this database-only write was accepted.';
export const CONNECTOR_BOUND_HINT = 'Nothing was written. Read the page again and submit the write with a new request_id; the bound source publishes it to its canonical file.';
export const CONNECTOR_BOUND_MESSAGE = 'The connector source gained a canonical owner after this database-only write was accepted.';
export const UNBOUND_COLLISION_MESSAGE = 'A database-only page written while its source was unbound already uses this slug.';

/**
 * #6449: the rooted sources `writer activate` accepted without an owner because
 * `sync.write_through` was off (activation.ts writes the list, deactivation
 * clears it). A PGLite page write to one of them never runs the automatic
 * first-write claim, so turning `sync.write_through` back on refuses with the
 * claim named instead of starting to publish files into an unreviewed checkout.
 */
export const DATABASE_ONLY_SOURCES_KEY = 'persistence.database_only_sources';
export async function readDatabaseOnlyActivatedSources(engine: Pick<BrainEngine, 'getConfig'>): Promise<string[]> {
  try {
    const parsed: unknown = JSON.parse(await engine.getConfig(DATABASE_ONLY_SOURCES_KEY) ?? '[]');
    return Array.isArray(parsed) ? parsed.filter((id): id is string => typeof id === 'string') : [];
  } catch { return []; }
}

export function parseUnboundWriteValue(value: string): UnboundWritePolicy {
  if ((UNBOUND_WRITE_VALUES as readonly string[]).includes(value)) return value as UnboundWritePolicy;
  throw opError('invalid_params', `${UNBOUND_WRITE_KEY} must be one of: ${UNBOUND_WRITE_VALUES.join(', ')} (got '${value}').`,
    `Set it with gbrain config set ${UNBOUND_WRITE_KEY} ${UNBOUND_WRITE_VALUES[0]} (the default) or ${UNBOUND_WRITE_VALUES[1]}.`);
}

/** A missing or unreadable value keeps the refusal. */
export async function readUnboundWritePolicy(engine: Pick<BrainEngine, 'getConfig'>): Promise<UnboundWritePolicy> {
  return await engine.getConfig(UNBOUND_WRITE_KEY) === 'database_only' ? 'database_only' : 'refuse';
}

export function unboundBindCommand(sourceId: string, path: string | null): string {
  return `run gbrain sources writer status ${sourceId} --json and note admin_state, then run gbrain sources writer claim ${sourceId} `
    + `--path ${path ?? '<checkout path on the brain host>'} --admin-intent writer_claim --expected-state <admin_state>`;
}

/**
 * `path` is filled only for trusted local callers; remote callers get a
 * placeholder instead of a host path.
 */
export function unboundSourceError(sourceId: string, path: string | null, scope: 'database_only_eligible' | 'file_backed', classic = false): OperationError {
  const bind = `bind the source on the brain host: ${unboundBindCommand(sourceId, path)} `
    + '(if an operator has locked writer administration, ask the operator to unlock it first)';
  // #6122: on a brain whose managed persistence is not activated, a claim alone fences classic sync of the source,
  // so the working path is the file plus classic sync; claiming is named with that consequence.
  // Classic sync imports commits, not the working tree, so the hint names the commit; a remote caller cannot reach the checkout.
  const edit = path
    ? `write the page as ${path}/<slug>.md (check generated frontmatter with gbrain frontmatter validate --stdin --path <slug>.md), commit it in that checkout, then run gbrain sync --source ${sourceId}`
    : `ask the user to write the page as <slug>.md in the source's checkout on the brain host, commit it, and run gbrain sync --source ${sourceId}`;
  const trap = `For a gbrain-owned checkout instead (a brain-wide change: ask the user first), ${bind}, then activate managed persistence (preview first: gbrain sources writer activate --confirm-quiesced --dry-run --json). `
    + `Managed persistence is not activated on this brain, so a claim without activation blocks classic sync of ${sourceId} until it is activated or the claim is released with gbrain sources writer deactivate.`;
  const suggestion = classic ? scope === 'database_only_eligible'
    ? `Source '${sourceId}' has a checkout path but no canonical owner. Choose one: ${edit}; or allow database-only writes to unbound sources `
      + `with gbrain config set ${UNBOUND_WRITE_KEY} database_only. Pages written that way stay database-only and are not materialized into canonical files after binding. ${trap}`
    : `Source '${sourceId}' has a checkout path but no canonical owner. To change this page, ${edit}. `
      + `${UNBOUND_WRITE_KEY}=database_only does not apply: this page came from a canonical file, and a database-only edit would be lost on the next sync. ${trap}`
    : scope === 'database_only_eligible'
    ? `Source '${sourceId}' has a checkout path but no canonical owner. Choose one: ${bind}; or allow database-only writes to unbound sources `
      + `with gbrain config set ${UNBOUND_WRITE_KEY} database_only. Pages written that way stay database-only and are not materialized into canonical files after binding.`
    : `Source '${sourceId}' has a checkout path but no canonical owner. To write this page, ${bind}. `
      + `${UNBOUND_WRITE_KEY}=database_only does not apply: this page came from a canonical file, and a database-only edit would be lost on the owner's next sync.`;
  const error = new OperationError('owner_unavailable', 'This source has no designated canonical owner.', suggestion, UNBOUND_SOURCE_DOCS);
  error.detail = 'unbound_source';
  // A configuration state, not a transient one: a retry gets the same refusal, and every way out is the user's choice.
  error.retryable = false;
  error.fix = {
    ask_user: true,
    consent: [],
    actor: path ? 'agent' : 'user',
    why: classic
      ? `The brain is in classic mode: the checkout of '${sourceId}' is the source of truth and gbrain only reads it, so a page is saved as a committed file followed by gbrain sync. Don't retry, claim the source or activate managed mode to get one write through.`
      : `Source '${sourceId}' has no canonical owner; binding it or allowing database-only pages is a brain-wide decision for the user.`,
    user_message: classic
      ? path
        ? `Your brain is in classic mode, so pages are saved as files in the checkout. I can write it as <slug>.md in ${path}, commit it and run gbrain sync --source ${sourceId}. Or I can explain the two other options: database-only pages, or managed mode.`
        : `Your brain is in classic mode, so I can't save pages directly. Save it as <slug>.md in the ${sourceId} folder, commit it, and run gbrain sync --source ${sourceId}. Or I can explain the two other options: database-only pages, or managed mode.`
      : `Source '${sourceId}' has no canonical owner, so I can't save this page. You can bind the source on the brain host, or allow database-only pages${scope === 'file_backed' ? ' (not for this page, which came from a file)' : ''}; I can explain what each changes.`,
    docs: UNBOUND_SOURCE_DOCS,
    requires_exclusive: false,
  };
  return error;
}

export type UnboundWriteDecision = { kind: 'claim' } | { kind: 'database_only'; reason: 'connector_database' | 'unbound_source' };

/**
 * The one rule for a write-through write to a source with a checkout root but
 * no worktree binding, shared by page writers and fact writers (#6608):
 * a connector source is database-only by design and never claimed; PGLite
 * claims the source automatically unless activation listed it database-only
 * (#6449); otherwise a target with a recorded canonical file, or any
 * `persistence.unbound_write` other than `database_only`, refuses with
 * `unboundSourceError`, and the rest is written database-only (`unbound_source`).
 * `path` names the checkout in the refusal; pass it only for trusted local callers.
 */
export async function decideUnboundWrite(engine: BrainEngine,
  input: { sourceId: string; sourceKind: string | null; fileBacked: boolean; path: string | null }): Promise<UnboundWriteDecision> {
  if (isConnectorSourceKind(input.sourceKind)) return { kind: 'database_only', reason: 'connector_database' };
  if (engine.kind === 'pglite' && !(await readDatabaseOnlyActivatedSources(engine)).includes(input.sourceId)) return { kind: 'claim' };
  if (input.fileBacked || await readUnboundWritePolicy(engine) !== 'database_only') {
    throw unboundSourceError(input.sourceId, input.path, input.fileBacked ? 'file_backed' : 'database_only_eligible', !await managedPersistenceEnabled(engine));
  }
  return { kind: 'database_only', reason: 'unbound_source' };
}

export function unboundPublicationHint(sourceId: string): string {
  return `Source '${sourceId}' gained a canonical owner, or the page gained a canonical file, after this database-only write was accepted, so nothing was written. `
    + 'Read the page again and submit the write with a new request_id; a bound source publishes it to its canonical file.';
}

/**
 * Runs inside the publication transaction after the source row is share-locked
 * (authorizeStoredRequest), so a concurrent claim either committed before this
 * read or waits for the publication to finish.
 */
export async function assertUnboundPublication(tx: SqlEngine, row: Pick<WriteRequest, 'authority' | 'source_id' | 'operation'>, sourcePath: string | null | undefined): Promise<void> {
  // A page or memory write admitted database-only to an unbound connector source (connector_database)
  // must not publish around canonical files once the source has an owner. Connector intents
  // (submit_job) carry their own sync-authority check.
  if (row.authority.databaseOnlyReason === 'connector_database' && row.operation !== 'submit_job') {
    const bound = await tx.executeRaw('SELECT 1 FROM persistence_source_bindings WHERE source_id=$1 LIMIT 1', [row.source_id]);
    if (bound.length) throw new OperationError('owner_unavailable', CONNECTOR_BOUND_MESSAGE, CONNECTOR_BOUND_HINT);
    return;
  }
  if (row.authority.databaseOnlyReason !== 'unbound_source') return;
  const bound = await tx.executeRaw('SELECT 1 FROM persistence_source_bindings WHERE source_id=$1 LIMIT 1', [row.source_id]);
  if (!bound.length && !sourcePath) return;
  const error = new OperationError('owner_unavailable', UNBOUND_PUBLICATION_MESSAGE, unboundPublicationHint(row.source_id), UNBOUND_SOURCE_DOCS);
  error.detail = 'unbound_source';
  throw error;
}

/**
 * The publication's database-only stamp of the page it wrote: `unbound_source`
 * for a write admitted that way, and `detached` (forgetting the recorded file)
 * for a `restore_page` with `detach` (#6609, `detached-pages.ts`).
 */
export async function classifyUnboundPage(tx: SqlEngine, row: Pick<WriteRequest, 'authority' | 'source_id' | 'slug' | 'operation' | 'intent'>): Promise<void> {
  await detachRestoredPage(tx, row);
  if (row.authority.databaseOnlyReason !== 'unbound_source') return;
  await tx.executeRaw("UPDATE pages SET database_only_reason='unbound_source' WHERE source_id=$1 AND slug=$2 AND database_only_reason IS NULL",
    [row.source_id, row.slug]);
}

export async function isUnboundSourcePage(engine: SqlEngine, sourceId: string, slug: string): Promise<boolean> {
  const [row] = await engine.executeRaw<{ database_only_reason: string | null }>(
    'SELECT database_only_reason FROM pages WHERE source_id=$1 AND slug=$2', [sourceId, slug]);
  return row?.database_only_reason === 'unbound_source';
}

export function unboundWriteWarning(operation: string, sourceId: string, admittedUnbound: boolean): string {
  return `${operation} wrote only to the database for source '${sourceId}': ` + (admittedUnbound
    ? `the source has no canonical owner and ${UNBOUND_WRITE_KEY}=database_only, so no markdown file was created. `
    : 'this page was written while the source had no canonical owner. ')
    + 'The page stays database-only and is not materialized into a canonical file after binding.';
}