Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.2 KB
Raw Blame
import type { BrainEngine } from '../engine.ts';
import { assertRecoveryVersion } from './recovery-version.ts';
import { isHoldingSlug } from '../facts-fence.ts';

export type Principal = { kind: 'oauth_client' | 'legacy_token' | 'local_cli' | 'local_stdio' | 'application'; id: string };
/** `deferred` (PR B, docs/designs/REFRESH_WRITE_BARRIER.md): admitted during a worktree refresh, unclaimable until it is released. */
export type RequestState = 'queued' | 'deferred' | 'running' | 'recovering' | 'committed' | 'conflict' | 'failed' | 'cancelled';
export interface WriteAuthority {
  /** The caller's self-declared agent label (X-Gbrain-Agent-Label). Unverified text: nothing authorizes on it. */
  agentLabel?: string;
  version: 1;
  principal: Principal;
  remote: boolean;
  /** Original page-visibility ceiling; current policy can only narrow it. */
  excludePrivate?: boolean;
  /**
   * GBRA-231: the audience a shared agent asserted for the write (normalized member:<id>, group:<g>, guest). Preparation
   * and publication re-resolve it against the principal's live may_act_for and members, never the principal's own member.
   */
  /**
   * GST-359 C1: or the attested actor { system, external_id, member } the write was accepted for. Preparation and
   * publication re-resolve it through actorCoverage (access/actor.ts): the principal's live attest right and a live
   * link from the id to the same enabled member, so an unlink, a disabled member or a revoked right refuses it.
   */
  actingFor?: string[] | { system: string; external_id: string; member: string };
  /**
   * GST-363: the member a local_stdio writer's serve was started with (`gbrain serve --stdio-member`). Preparation and
   * publication re-resolve it live (a disabled member reads as nobody); absent, they read config mcp.stdio_member.
   */
  stdioMember?: string;
  /** GST-359 D: the attested operation this write serves when it differs from the stored one (memory_write as remember). */
  attestedOp?: string;
  /** GST-1113: the scope source an attested memory_write named instead of the principal's own; publication re-checks attest_sources. */
  attestedSource?: string;
  /**
   * GST-2492: the entity a remember held on memory/unattributed is for (a strict source, the entity has no page). The
   * write is authorized as a write to that entity (its slug fences, grant prefixes and visibility), never to the
   * holding page, which is gbrain's own companion to it.
   */
  heldFor?: string;
  /**
   * GST-2091: the brain owner (`member:<id>`) whose own credential, with write scope and speaking for itself, made this
   * page write (put_page, edit_page or append_page; put_pages and page uploads store those). Preparation and publication
   * lift the privacy part of the writer's read policy only while storedOwnerWrite still holds; member access always applies.
   */
  ownerWrite?: string;
  databaseOnlyReason?: 'subagent_sandbox' | 'disabled_by_config' | 'no_repo_configured' | 'relative_root' | 'connector_database' | 'unbound_source' | 'overwrite_restore' | 'detached' | 'entity_page_missing';
  autoLinkTrusted?: boolean;
  restrictedNamespace?: boolean;
  sourceId: string;
  sourceIncarnation: string;
  scopes: string[];
  operations: string[] | null;
  slugPrefixes: string[] | null;
  delegatedPrefixes?: string[] | null;
  delegated?: boolean;
  /** Minions job that accepted an OAuth-delegated write; a live `job` grant re-derives only that job's namespace from it. */
  delegatedJobId?: number;
  takesHolders?: string[] | null;
  /** Actual holders touched by a published take mutation; retained after intent compaction. */
  takeHoldersUsed?: string[];
}
/** GST-2492: the slug a write is authorized as: a held remember's entity in place of the holding page, else the page itself. */
export function authorizedSlug(authority: Pick<WriteAuthority, 'heldFor'>, slug: string): string {
  return authority.heldFor && isHoldingSlug(slug) ? authority.heldFor : slug;
}

/**
 * One file's publication recovery. The prior bytes are embedded (`before`, base64), except for a prior file over the
 * single-string ceiling (large-file.ts): `before` is null and the bytes are the staged copy `staging.before` (path,
 * SHA-256 = `beforeHash`, length), which recovery renames back. Its `.tmp.before-<uuid>` name is not a stage name
 * binaries that predate it accept, so they block on it (`unexpected_staging_bytes`) instead of reading `before: null`
 * as an absent file.
 */
export interface FileRecoveryRecord {
  version: 1;
  path: string;
  root: string;
  before: string | null;
  beforeHash: string | null;
  afterHash: string | null;
  mode: number | null;
  afterMode?: number;
  ownerEpoch: string;
  attempt: string;
  after?: string | null;
  /** Absent on recovery records created by older binaries. */
  staging?: import('./staging.ts').RecoveryStaging;
  /** G2 (git-door.ts): a strict source's publication, which commits before its database row; the checkout and the HEAD it started from. */
  door?: { root: string; head: string | null };
}
export interface BundleRecoveryRecord {
  version: 2;
  target: 'skill_bundle';
  root: string;
  ownerEpoch: string;
  attempt: string;
  files: FileRecoveryRecord[];
  staging?: never;
  beforeHash?: never;
}
/**
 * GBRA-190 G4 (D2): the page files one publication writes together (a withdrawal's pages), restored together and
 * committed in one Git commit. Each file is a page file record (version 1 fields, door included on a strict source);
 * `files[0]` is the request's own page when it has a file. Binaries that predate it refuse version 3 unread.
 */
export interface PagesRecoveryRecord {
  version: 3;
  target: 'pages';
  root: string;
  ownerEpoch: string;
  attempt: string;
  files: FileRecoveryRecord[];
  staging?: never;
  beforeHash?: never;
}
export type RecoveryRecord = FileRecoveryRecord | BundleRecoveryRecord | PagesRecoveryRecord;
/** The most page files one publication writes together (a withdrawal's bound, withdrawal-discovery.ts). */
export const PAGES_RECOVERY_MAX_FILES = 256;
export function recoveryFiles(record: RecoveryRecord): FileRecoveryRecord[] {
  assertRecoveryVersion('persistence_requests', record, null);
  if (record.version === 1) return [record];
  if (record.version === 2 && record.target === 'skill_bundle' && Array.isArray(record.files)
    && record.files.length > 0 && record.files.length <= 128 && record.files.every(file => file.version === 1)) return record.files;
  if (record.version === 3 && record.target === 'pages' && Array.isArray(record.files)
    && record.files.length > 0 && record.files.length <= PAGES_RECOVERY_MAX_FILES && record.files.every(file => file.version === 1)) return record.files;
  throw new Error('unsupported_mutation_protocol');
}
/** A shared-skill bundle's record, whose files are bundle files (bundle-files.ts), not page files. */
export function isBundleRecovery(record: RecoveryRecord): record is BundleRecoveryRecord {
  return record.version === 2;
}
export interface WriteRequest {
  id: string;
  principal_kind: Principal['kind'];
  principal_id: string;
  request_id: string;
  operation: string;
  target_kind?: 'page' | 'skill_bundle';
  protocol_version?: 1 | 2;
  source_id: string;
  source_incarnation: string;
  page_id: number | null;
  slug: string;
  worktree_id: string | null;
  topology_generation: string | number | null;
  digest: string;
  intent: Record<string, unknown> | null;
  authority: WriteAuthority;
  sequence: string | number;
  state: RequestState;
  /** The refresh a deferred write was admitted behind; kept after it drains, so its claim runs the refresh-change check. */
  deferred_refresh_id?: string | null;
  /** GST-1582: the source's last imported commit ('' for none) when a claimed write was held for an import; kept after it lands. */
  deferred_import_from?: string | null;
  execution_token: string | null;
  claim_expires_at: Date | string | null;
  recovery: RecoveryRecord | null;
  recovery_bytes: string | number;
  intent_bytes: string | number;
  terminal_reservation: string | number;
  outcome: Record<string, unknown> | null;
  error_code: string | null;
  error_message: string | null;
  /** #5974 structured failure (publication-failure.ts); receipts expose only its public view. */
  error_detail?: Record<string, unknown> | null;
  blocked_reason: string | null;
  /** F6: the non-UUID request_id the client sent (request_id is its UUIDv5); outside the intent digest, kept through compaction. */
  client_request_id?: string | null;
  compacted: boolean;
  publication_started: boolean;
  /** #6278 (v220): preparations cut off by a deadline or an expired `preparing` claim; reset by a commit. Absent on rows read before the migration. */
  /** #6176 (v217): the owner's claim-phase stamp (claim-phase.ts), read back by `claimStateOf`; absent on rows read before the migration. */
  claim_phase?: unknown;
  preparation_attempts?: number;
  /** Large-pages hardening (v261): transient interruptions counted against `persistence.max_transient_retries` (transient-retry.ts). */
  transient_interruptions?: number;
  /** v261: the earliest time a claim takes this queued row again (a transient interruption's backoff); null means now. */
  next_attempt_at?: Date | string | null;
  /** #6278: on a row the claim statements return: the stamp the previous claim left (its last recorded step). Never stored. */
  previous_claim_phase?: unknown;
  created_at: Date | string;
  updated_at: Date | string;
  completed_at: Date | string | null;
}
export const TERMINAL_STATES: ReadonlySet<RequestState> = new Set(['committed', 'conflict', 'failed', 'cancelled']);
export interface JournalLimits {
  principalOutstanding: number; brainOutstanding: number;
  principalIntentBytes: number; brainIntentBytes: number;
  principalLifetimeIds: number; brainLifetimeIds: number;
  principalTerminalBytes: number; brainTerminalBytes: number;
  brainRecoveryBytes: number; worktreeRecoveryBytes: number;
}
/**
 * Cumulative defaults are sized so one principal admitting 600 writes a day
 * (the reported autopilot workload) runs at least one year: lifetime IDs last
 * about 417 days; receipt bytes hold a 30-day window of 16 KiB reservations
 * plus about 4 KiB retained per compacted receipt for about 590 days.
 * Outstanding intent per principal holds two page-ceiling writes
 * (page-size-policy.ts, 24 MiB each, JSON-escaped) plus headroom, so one
 * large write never refuses another from the same principal.
 */
export const DEFAULT_JOURNAL_LIMITS: Readonly<JournalLimits> = Object.freeze({
  principalOutstanding: 100, brainOutstanding: 1000,
  principalIntentBytes: 64 * 1024 ** 2, brainIntentBytes: 256 * 1024 ** 2,
  // GBRA-108: the cumulative caps are opt-in (Infinity until persistence.limits.* sets one); housekeeping and doctor bound receipt storage.
  principalLifetimeIds: Infinity, brainLifetimeIds: Infinity,
  principalTerminalBytes: Infinity, brainTerminalBytes: Infinity,
  brainRecoveryBytes: 1024 ** 3, worktreeRecoveryBytes: 256 * 1024 ** 2,
});
export type SqlEngine = Pick<BrainEngine, 'executeRaw'>;
export function principalKey(p: Principal): string { return `principal:${p.kind}:${p.id}`; }
export function requestPrincipal(r: WriteRequest): Principal { return { kind: r.principal_kind, id: r.principal_id }; }
export function isTerminal(r: Pick<WriteRequest, 'state'>): boolean { return TERMINAL_STATES.has(r.state); }