Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.0 KB
Raw Blame
import { spawn } from 'node:child_process';
import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, rmSync } from 'node:fs';
import { lstat, readdir } from 'node:fs/promises';
import { join } from 'node:path';
import { flushDirectory, flushFile } from '../fs-durable.ts';
import type { Action } from '../agent-output.ts';
import { opError, OperationError } from '../ops/contract.ts';
import { readFix } from '../ops/op-fix.ts';
import { durableSsrfFlags, GIT_ENV, GIT_SSRF_SUBCOMMAND_FLAGS, LFS_OFF_CLONE_CONFIG, parseRemoteUrl } from '../git-remote.ts';
import { persistenceHome } from './identity.ts';
import { gitChildEnv } from '../git-env.ts';

export { flushDirectory as flushTopologyDirectory } from '../fs-durable.ts';
const recoveryFix=(why:string):Action=>readFix(why,{argv:['gbrain','sources','writer','status','--json']});
export function topologyDirectoryIdentity(path:string):{device:string;inode:string;birthNs:string}{
  const info=lstatSync(path,{bigint:true});
  if(!info.isDirectory()||info.isSymbolicLink())throw opError('recovery_required','The staging directory was substituted.',
    `The topology staging path ${path} is no longer the directory gbrain created, so the lifecycle step stopped for recovery. Inspect the pending recovery in writer status; do not delete or recreate the staging directory by hand.`,
    {fix:recoveryFix('Shows pending lifecycle requests and their recovery records, read-only.')});
  return {device:info.dev.toString(),inode:info.ino.toString(),birthNs:info.birthtimeNs.toString()};
}
/**
 * Complete tree accounting includes .git, sparse files, and metadata headroom. A path below the
 * root that vanishes or stops being a directory mid-walk (git's auto-gc pruning .git/objects) is
 * counted as already seen; errors on the root and every other error still throw.
 */
export async function topologyDirectoryBytes(root:string,limit=Number.MAX_SAFE_INTEGER):Promise<number>{
  let bytes=0;
  const pending=[root];
  while(pending.length){
    const path=pending.pop()!;
    let info;
    try{info=await lstat(path);}catch(error){if((error as NodeJS.ErrnoException).code==='ENOENT')continue;throw error;}
    bytes+=4096+info.size;
    if(!Number.isSafeInteger(bytes)||bytes>limit)throw opError('request_too_large','The staged checkout exceeds its reserved recovery capacity.',
      `The checkout staged at ${root} is larger than the ${limit} bytes reserved for its recovery. Inspect the pending lifecycle request in writer status; it needs a smaller repository or a larger recovery budget, which is the user's call.`,
      {fix:recoveryFix('Shows the pending lifecycle request and the recovery capacity it holds, read-only.')});
    if(!info.isDirectory())continue;
    let entries:string[];
    try{entries=await readdir(path);}catch(error){
      const code=(error as NodeJS.ErrnoException).code;
      if(path!==root&&(code==='ENOENT'||code==='ENOTDIR'))continue;
      throw error;
    }
    for(const entry of entries)pending.push(join(path,entry));
  }
  return bytes;
}
export function flushTopologyTree(root:string):void{
  const visit=(path:string)=>{
    const info=lstatSync(path);
    if(info.isSymbolicLink())throw opError('writer_manifest_unsafe','Canonical checkout recovery refuses symbolic links.',
      `The staged checkout contains a symbolic link at ${path}, and canonical recovery never follows links. Replace it with a regular file or directory in the repository, then inspect the pending recovery in writer status.`,
      {fix:recoveryFix('Shows the pending lifecycle request this staged checkout belongs to, read-only.')});
    if(info.isDirectory()){
      for(const entry of readdirSync(path))visit(join(path,entry));
      flushDirectory(path);
    }else if(info.isFile()){
      flushFile(path);
    }
  };
  visit(root);
}

/** Reserved staging, no DB checkout; kill only this owned Git child on overflow. skipLfs: the clone keeps git-lfs downloads and hooks off, as cloneRepo does. */
export async function cloneTopologyCheckout(url:string,destination:string,maxBytes:number,{skipLfs=false,timeoutMs=600_000}:{skipLfs?:boolean;timeoutMs?:number}={}):Promise<void>{
  parseRemoteUrl(url);
  if(!existsSync(destination)||!lstatSync(destination).isDirectory()||lstatSync(destination).isSymbolicLink()||readdirSync(destination).length)
    throw opError('recovery_required','The reserved clone staging directory must remain empty before cloning.',
      `The reserved clone directory ${destination} is missing or not empty, so cloning stopped for recovery. Inspect the pending recovery in writer status; recovery owns that directory, so do not clear it by hand.`,
      {fix:recoveryFix('Shows pending lifecycle requests and their recovery records, read-only.')});
  const base=join(persistenceHome(),'empty-hooks');mkdirSync(base,{recursive:true,mode:0o700});
  const hooks=mkdtempSync(join(base,'clone-'));
  const child=spawn('git',[...durableSsrfFlags(),'-c',`core.hooksPath=${hooks}`, 'clone',...GIT_SSRF_SUBCOMMAND_FLAGS,...(skipLfs?LFS_OFF_CLONE_CONFIG:[]),'--depth=1','--',url,destination],
    {stdio:['ignore','ignore','ignore'],detached:process.platform!=='win32',env:gitChildEnv({ ...GIT_ENV })});
  let failure:unknown,check:Promise<void>|undefined,stopping:Promise<void>|undefined,abandon=()=>{};
  const stop=(error:unknown)=>{
    failure??=error;
    if(stopping)return;
    // Git can launch index-pack/remote helpers that still own staging files.
    // Terminate this invocation's complete process tree before cleanup.
    stopping=new Promise<void>((resolve)=>{
      if(!child.pid){resolve();return;}
      if(process.platform==='win32'){
        const killer=spawn('taskkill',['/PID',String(child.pid),'/T','/F'],{stdio:'ignore'});
        killer.once('exit',()=>resolve());killer.once('error',()=>{child.kill('SIGKILL');resolve();});
      }else{try{process.kill(-child.pid,'SIGKILL');}catch{}resolve();}
    });
    abandon();
  };
  const monitor=setInterval(()=>{
    if(!check)check=topologyDirectoryBytes(destination,maxBytes).then(()=>{}).catch(stop).finally(()=>{check=undefined;});
  },50);
  const timer=setTimeout(()=>stop(opError('storage_error','The staged clone exceeded its execution deadline.',
    `Cloning into ${destination} ran past ${Math.round(timeoutMs/1000)} seconds and was stopped. Check that the remote is reachable and not unexpectedly large, and inspect the pending lifecycle request in writer status before submitting it again.`,
    {fix:recoveryFix('Shows the pending lifecycle request and whether it is held for recovery, read-only.')})),timeoutMs);
  try{
    const code=await new Promise<number|null>((resolve,reject)=>{child.once('error',reject);child.once('exit',resolve);abandon=()=>resolve(null);});
    await check;await stopping;
    if(failure)throw failure;
    if(code!==0)throw new OperationError('storage_error','The reserved source clone failed.','Inspect the configured remote and owner Git credentials.');
    await topologyDirectoryBytes(destination,maxBytes);
  }finally{clearInterval(monitor);clearTimeout(timer);await check;await stopping;rmSync(hooks,{recursive:true,force:true});}
}