Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.2 KB
Raw Blame
import type { BrainEngine } from '../engine.ts';
import { opError } from '../ops/contract.ts';
import { digest, jsonBytes } from './digest.ts';
import { lockCounters, quotaExhausted } from './journal.ts';
import { journalLimitKey, oneYearCapacity, readJournalLimits } from './limits.ts';
import { principalKey } from './model.ts';
import { receiptReservation, retainedReceiptBytes } from './receipt-bytes.ts';

export interface TopologyChange {
  id:string; principal_id:string; request_id:string; digest:string; operation:string; source_id:string;
  source_incarnation:string|null; worktree_ids:string[]; state:'recovering'|'committed'|'failed';
  recovery:Record<string,unknown>|null; recovery_bytes:number; intent_bytes:number; terminal_bytes:number; outcome:Record<string,unknown>|null;
}
export async function priorTopologyChange(engine:BrainEngine,principal:string,requestId:string,intent:unknown):Promise<TopologyChange|null> {
  const page=await engine.executeRaw("SELECT id FROM persistence_requests WHERE principal_kind='local_cli' AND principal_id=$1 AND request_id=$2::uuid",[principal,requestId]);
  if(page.length) throw opError('idempotency_conflict','This request_id belongs to a page mutation.',
    `Request ${requestId} already names a page write, so this lifecycle change was not accepted. Submit it with a new request id, or omit the id so gbrain generates one.`);
  const [prior]=await engine.executeRaw<TopologyChange>('SELECT * FROM persistence_topology_changes WHERE principal_id=$1::uuid AND request_id=$2::uuid',[principal,requestId]);
  if(prior && prior.digest!==digest(intent)) throw opError('idempotency_conflict','This lifecycle request_id was accepted with different arguments.',
    `Request ${requestId} was accepted for a ${prior.operation} of source ${prior.source_id} with other arguments. Reuse it only to resubmit that identical command; give a different change a new request id.`);
  return prior??null;
}
export async function recordTopologyChange(tx:BrainEngine, input:{principal:string;requestId:string;intent:unknown;operation:string;sourceId:string;incarnation:string|null;worktrees:string[]},
  outcome:Record<string,unknown>, recovery:Record<string,unknown>|null=null,recoveryBytes=0):Promise<TopologyChange> {
  const reservation=receiptReservation({});
  const intentBytes=recovery?jsonBytes(input.intent):0;
  if(Buffer.byteLength(JSON.stringify(outcome))+1024>reservation) throw opError('request_too_large','Lifecycle outcome exceeds its retained receipt capacity.',
    `The ${input.operation} of source ${input.sourceId} would record an outcome over ${reservation - 1024} bytes, so nothing was recorded. Report this to the user with the request id ${input.requestId}; it is not a caller mistake.`);
  // #6696 (A1): a change recorded committed keeps only its outcome, so it is trued up at insert; a recovering one keeps the reservation.
  const terminalBytes=recovery?reservation:Math.min(reservation,retainedReceiptBytes({outcome},{stage:'terminal'}));
  const limits=await readJournalLimits(tx);
  const key=principalKey({kind:'local_cli',id:input.principal});
  const counters=await lockCounters(tx,['brain',key,...input.worktrees.map(id=>`worktree:${id}`)]);
  const admitted=await priorTopologyChange(tx,input.principal,input.requestId,input.intent);
  if(admitted&&!recovery&&isRetireAdmission(admitted)){
    const settled=await settleTopologyRetire(tx,admitted,'committed',outcome);
    if(settled)return settled;
  }
  for(const counter of counters){
    const brain=counter.key==='brain';
    if(!counter.key.startsWith('worktree:')){
      await assertQuota(tx,counter,limits,terminalBytes,input);
      if(recovery && (Number(counter.outstanding_count)+1>(brain?limits.brainOutstanding:limits.principalOutstanding)
        ||Number(counter.intent_bytes)+intentBytes>(brain?limits.brainIntentBytes:limits.principalIntentBytes)))
        throw opError('queue_capacity','Pending lifecycle work exceeds available brain/principal request or intent capacity.',
          `Too much lifecycle work is still pending, so the ${input.operation} of source ${input.sourceId} was not accepted. Let the pending work settle, then submit it again; raising ${journalLimitKey(brain?'brainOutstanding':'principalOutstanding')} is the user's call.`, { fix: { argv: ['gbrain', 'sources', 'writer', 'status', '--source', input.sourceId, '--json'], consent: [], actor: 'agent', why: 'Shows the pending lifecycle and recovery work that holds this capacity.', requires_exclusive: false } });
    }
    if(recoveryBytes && counter.key!==key && Number(counter.recovery_bytes)+recoveryBytes>(brain?limits.brainRecoveryBytes:limits.worktreeRecoveryBytes))
      throw opError('queue_capacity','The lifecycle recovery exceeds available brain/worktree capacity.',
        `Recovery records already use the ${journalLimitKey(brain?'brainRecoveryBytes':'worktreeRecoveryBytes')} budget, so the ${input.operation} of source ${input.sourceId} was not accepted. Let recovery settle first; raising the cap is the user's call and recovery records are never removed.`, { fix: { argv: ['gbrain', 'sources', 'writer', 'status', '--source', input.sourceId, '--json'], consent: [], actor: 'agent', why: 'Shows the pending lifecycle and recovery work that holds this capacity.', requires_exclusive: false } });
  }
  const [row]=await tx.executeRaw<TopologyChange>(`INSERT INTO persistence_topology_changes
    (principal_id,request_id,digest,operation,source_id,source_incarnation,worktree_ids,state,recovery,recovery_bytes,terminal_bytes,outcome,intent_bytes)
    VALUES($1::uuid,$2::uuid,$3,$4,$5,$6::uuid,$7::uuid[],$8,$9::text::jsonb,$10,$11,$12::text::jsonb,$13) RETURNING *`,
  [input.principal,input.requestId,digest(input.intent),input.operation,input.sourceId,input.incarnation,input.worktrees,recovery?'recovering':'committed',
    recovery?JSON.stringify(recovery):null,recoveryBytes,terminalBytes,JSON.stringify(outcome),intentBytes]);
  for(const counter of counters){
    if(!counter.key.startsWith('worktree:')) await tx.executeRaw('UPDATE persistence_counters SET lifetime_ids=lifetime_ids+1,terminal_bytes=terminal_bytes+$2 WHERE key=$1',[counter.key,terminalBytes]);
    if(recovery && !counter.key.startsWith('worktree:')) await tx.executeRaw('UPDATE persistence_counters SET outstanding_count=outstanding_count+1,intent_bytes=intent_bytes+$2 WHERE key=$1',[counter.key,intentBytes]);
    if(recoveryBytes && counter.key!==key) await tx.executeRaw('UPDATE persistence_counters SET recovery_bytes=recovery_bytes+$2 WHERE key=$1',[counter.key,recoveryBytes]);
  }
  return row;
}
type JournalLimits=Awaited<ReturnType<typeof readJournalLimits>>;
type Counter=Awaited<ReturnType<typeof lockCounters>>[number];
async function assertQuota(tx:BrainEngine,counter:Counter,limits:JournalLimits,terminalBytes:number,input:{operation:string;sourceId:string}):Promise<void>{
  const brain=counter.key==='brain';
  const ids=Number(counter.lifetime_ids)+1>(brain?limits.brainLifetimeIds:limits.principalLifetimeIds);
  if(!ids&&Number(counter.terminal_bytes)+terminalBytes<=(brain?limits.brainTerminalBytes:limits.principalTerminalBytes)) return;
  const setting=`${brain?'brain':'principal'}${ids?'LifetimeIds':'TerminalBytes'}` as const;
  const used=Number(ids?counter.lifetime_ids:counter.terminal_bytes);
  throw quotaExhausted(`${brain?'brain':'principal'} ${ids?'permanent request IDs':'reserved receipt bytes'} (lifecycle ${input.operation} of source ${input.sourceId})`,
    journalLimitKey(setting),await oneYearCapacity(tx,counter.key,ids?'LifetimeIds':'TerminalBytes',used,limits[setting]),used,limits[setting],ids?'lifetime_ids':'terminal_bytes');
}
/**
 * #8984: a remove or purge that deletes pages in batches (#7702/#8905) first records, in the transaction of its first
 * batch, which incarnation of the source its request_id was admitted against: a recovering row with no recovery
 * record, holding one lifetime ID and a full receipt reservation (so it refuses on a spent quota before deleting
 * anything). recordTopologyChange settles it committed; a retry against another incarnation settles it failed.
 */
export function isRetireAdmission(row:TopologyChange):boolean{
  return row.state==='recovering'&&row.recovery===null&&['remove','purge'].includes(row.operation);
}
export const RETIRE_SUPERSEDED='source_retire_superseded';
export function isSupersededRetire(row:TopologyChange):boolean{
  return row.state==='failed'&&row.outcome?.error===RETIRE_SUPERSEDED;
}
export async function admitTopologyRetire(tx:BrainEngine,input:{principal:string;requestId:string;intent:unknown;operation:string;sourceId:string;incarnation:string;worktrees:string[];expiredOnly?:boolean}):Promise<void>{
  const limits=await readJournalLimits(tx);
  const reservation=receiptReservation({});
  const counters=await lockCounters(tx,['brain',principalKey({kind:'local_cli',id:input.principal})]);
  for(const counter of counters) await assertQuota(tx,counter,limits,reservation,input);
  await tx.executeRaw(`INSERT INTO persistence_topology_changes
    (principal_id,request_id,digest,operation,source_id,source_incarnation,worktree_ids,state,terminal_bytes,outcome)
    VALUES($1::uuid,$2::uuid,$3,$4,$5,$6::uuid,$7::uuid[],'recovering',$8,$9::text::jsonb)`,
  [input.principal,input.requestId,digest(input.intent),input.operation,input.sourceId,input.incarnation,input.worktrees,reservation,
    JSON.stringify({operation:input.operation,source_id:input.sourceId,source_incarnation:input.incarnation,...(input.expiredOnly?{expired_only:true}:{})})]);
  for(const counter of counters) await tx.executeRaw('UPDATE persistence_counters SET lifetime_ids=lifetime_ids+1,terminal_bytes=terminal_bytes+$2 WHERE key=$1',[counter.key,reservation]);
}
/** Settles a retire admission and trues its reserved receipt bytes up to the outcome it keeps; null when already settled. */
export async function settleTopologyRetire(tx:BrainEngine,row:TopologyChange,state:'committed'|'failed',outcome:Record<string,unknown>):Promise<TopologyChange|null>{
  const counters=await lockCounters(tx,['brain',principalKey({kind:'local_cli',id:row.principal_id})]);
  const terminalBytes=Math.min(receiptReservation({}),retainedReceiptBytes({outcome},{stage:'terminal'}));
  const [settled]=await tx.executeRaw<TopologyChange>(`UPDATE persistence_topology_changes SET state=$2,outcome=$3::text::jsonb,terminal_bytes=$4,updated_at=now()
    WHERE id=$1::uuid AND state='recovering' AND recovery IS NULL RETURNING *`,[row.id,state,JSON.stringify(outcome),terminalBytes]);
  if(!settled)return null;
  for(const counter of counters) await tx.executeRaw('UPDATE persistence_counters SET terminal_bytes=terminal_bytes+$2 WHERE key=$1',[counter.key,terminalBytes-Number(row.terminal_bytes)]);
  return settled;
}
/** A lifecycle change that deleted or changed incarnation X fails every other request still admitted against X: none can resume. Requests are keyed by (principal, request_id), so the same request_id under another CLI registration is another request. */
export async function supersedeTopologyRetires(tx:BrainEngine,sourceId:string,incarnation:string,principal:string,requestId:string):Promise<void>{
  const rows=await tx.executeRaw<TopologyChange>(`SELECT * FROM persistence_topology_changes WHERE source_id=$1 AND source_incarnation=$2::uuid
    AND state='recovering' AND recovery IS NULL AND operation IN ('remove','purge') AND NOT (principal_id=$3::uuid AND request_id=$4::uuid) ORDER BY id`,[sourceId,incarnation,principal,requestId]);
  for(const row of rows) await settleTopologyRetire(tx,row,'failed',{...row.outcome,error:RETIRE_SUPERSEDED});
}
/** Caller retains owner/source guards and completes final state in this same transaction. */
export async function releaseTopologyReservation(tx:BrainEngine,row:TopologyChange):Promise<boolean>{
  // Revocation or removal prevents publication, never cleanup of its prior
  // durable reservation. Lock an extant principal without checking its grant.
  await tx.executeRaw('SELECT id FROM persistence_local_writers WHERE id=$1::uuid FOR SHARE',[row.principal_id]);
  const principal=principalKey({kind:'local_cli',id:row.principal_id});
  const counters=await lockCounters(tx,['brain',principal,...row.worktree_ids.map(id=>`worktree:${id}`)]);
  const [current]=await tx.executeRaw<TopologyChange>('SELECT * FROM persistence_topology_changes WHERE id=$1::uuid FOR UPDATE',[row.id]);
  if(!current?.recovery)return false;
  const intentBytes=Number(current.intent_bytes);
  for(const counter of counters){
    // Pre-accounting recovery rows have zero intent_bytes and did not reserve
    // an outstanding slot. New normalized JSON always occupies at least one byte.
    if(intentBytes>0 && !counter.key.startsWith('worktree:')) await tx.executeRaw('UPDATE persistence_counters SET outstanding_count=outstanding_count-1,intent_bytes=intent_bytes-$2 WHERE key=$1',[counter.key,intentBytes]);
    if(counter.key!==principal) await tx.executeRaw('UPDATE persistence_counters SET recovery_bytes=recovery_bytes-$2 WHERE key=$1',[counter.key,Number(current.recovery_bytes)]);
  }
  await tx.executeRaw('UPDATE persistence_topology_changes SET recovery=NULL,recovery_bytes=0,intent_bytes=0,updated_at=now() WHERE id=$1::uuid',[row.id]);
  return true;
}
export function topologyReceipt(row:TopologyChange):Record<string,unknown>{
  return {...row.outcome,request_id:row.request_id,state:row.state,retry_after_ms:row.state==='recovering'?1000:null};
}