@isdk/ai-tool 0.5.8 → 0.7.0

package/dist/index.mjs

@@ -1 +1 @@
-import{AIArgProcessor as s,AIChatRoles as a,AIMessageTypes as u,AIStream as i,AITextGenerationFinishReasons as e,AbortError as r,AbortErrorCode as t,ActionNames as n,AlreadyExistsError as d,AlreadyExistsErrorCode as m,AsyncFeatureBits as o,AsyncFeatures as f,BaseError as p,BinarySemaphore as v,CancelableAbility as F,ChoiceArgProcessor as h,ClientToolFuncSchema as H,ClientTools as V,CommonError as k,ConfigFile as l,DEFAULT_CONFIG_NAME as B,DefaultAsyncSemaphoreCapacity as G,EnvPromptTemplate as I,EnvironmentEx as c,ErrorCode as j,EventBusName as E,EventClient as L,EventEmitter as P,EventName as S,EventServer as T,EventToolFunc as g,FStringPromptTemplate as x,FewShotPromptTemplate as y,FilenameReservedRegex as z,GolangPromptTemplate as N,HashAlgorithm as Q,HfPromptTemplate as Y,IntSet as b,InternalErrorCode as q,Interpreter as w,LLM_TOKENIZER_NAMES as A,LLM_TOKENIZER_NAMES_MAP as C,LRUCache as D,NIL as J,NotFoundError as K,NotFoundErrorCode as M,NotImplementationError as O,NotImplementedErrorCode as R,ObjectArgsToArgsInfo as U,PASSING_SCORE as W,PromptExampleSelector as X,PromptTemplate as Z,PromptTemplateTypes as $,PromptTypes as _,RStreamErrCode as ss,RateLimit as as,ReadableStreamError as us,RemoteToolFuncSchema as is,ResClientTools as es,ResServerTools as rs,ResponseRStreamErrCode as ts,SHUTDOWN_SIGNALS as ns,SSEChannel as ds,SSEChannelAlreadyClosedErrCode as ms,SecondaryCache as os,Semaphore as fs,ServerToolFuncSchema as ps,ServerTools as vs,SignalGate as Fs,TaskAbortController as hs,Template as Hs,TemplateArgProcessor as Vs,ToolAsyncCancelableBit as ks,ToolAsyncMultiTaskBit as ls,ToolAsyncPriorityBit as Bs,ToolFunc as Gs,ToolFuncSchema as Is,WindowsReservedNameRegex as cs,YamlTypeBaseObject as js,_lrucache as Es,assignDirs as Ls,backendEventable as Ps,base32768 as Ss,beforeShutdown as Ts,builtins as gs,canonicalize as xs,completeSentences as ys,concatText as zs,countLLMTokens as Ns,countRegexMatches as Qs,createAbilityInjector as Ys,createCallbacksTransformer as bs,createEmptyReadableStream as qs,createEndWithRepetitionDetector as ws,createError as As,createEventStreamTransformer as Cs,createHfValueFunc as Ds,createLRUCache as Js,createYamlObjectTag as Ks,dateToText as Ms,decodeCharset as Os,defaultTemplateFormat as Rs,detectCharset as Us,encodeLLMTokens as Ws,ensureQuoted as Xs,event as Zs,eventClient as $s,eventServer as _s,eventable as sa,expandConfig as aa,expandEnv as ua,expandObjEnv as ia,expandPath as ea,extNameLevel as ra,fileIsExists as ta,filenameReservedRegex as na,filterValidFnScope as da,findIndexNonEmptyFrom as ma,formatISO as oa,formatTextWithSpace as fa,getAllEnumKeys as pa,getConfigFileNames as va,getConfigs as Fa,getEnvVairables as ha,getFileMetaInfo as Ha,getHashAlgoBySize as Va,getKeysPath as ka,getLLMTokenizer as la,getMultiLevelExtname as Ba,getPackageDir as Ga,getRealFilepath as Ia,getResponseErrorReadableStream as ca,getXDGConfigs as ja,hasDirectoryIn as Ea,hash as La,hashFile as Pa,hashStream as Sa,initShutdown as Ta,interpolateEnv as ga,interpolateFString as xa,interpolateGolangTemplate as ya,isLangUsingSpaces as za,isListItemString as Na,isModelNameMatched as Qa,isPunctuationChar as Ya,isQuoted as ba,isRegExp as qa,isSameString as wa,isSectionString as Aa,isSentenceEnding as Ca,isSepLineString as Da,isStrWrapped as Ja,isSubdirectory as Ka,isTitleString as Ma,isValidFilename as Oa,isValidFilepath as Ra,isWebStream as Ua,jsonFilterToWhere as Wa,jsonToMarkdownStr as Xa,loadAIConfig as Za,loadConfig as $a,loadConfigFile as _a,loadFileFromPaths as su,loadTextFromPaths as au,lrucache as uu,makeToolFuncCancelable as iu,matchUrlProtocol as eu,memoize as ru,messagesToText as tu,mimeType as nu,paramsSizeToScaleStr as du,parse as mu,parse2 as ou,parseCommand as fu,parseDateFormat as pu,parseFString as vu,parseISO as Fu,parseJsJson as hu,parseJsJsonSimpleSync as Hu,parseObjectArgInfo as Vu,parseObjectArgumentInfos as ku,parseObjectArguments as lu,parseObjectArgumentsAsArgInfos as Bu,parseYaml as Gu,quoteStr as Iu,reControlCharsRegex as cu,readFilenamesRecursiveSync as ju,readTextFileChunks as Eu,readTextFileChunksEx as Lu,readableFromAsyncIterable as Pu,registerCoreTools as Su,registerYamlTag as Tu,removeMarkdownBold as gu,removeMarkdownBoldAndItalic as xu,removeMarkdownItalic as yu,replaceWithPlaceholder as zu,restoreFromPlacehoders as Nu,sanitizeFilename as Qu,sanitizeFilepath as Yu,saveConfigFile as bu,scaleStrToParamsSize as qu,shutdown as wu,simplifyObjectArguments as Au,sortedValues as Cu,splitChunks as Du,splitParagraph as Ju,splitSentence as Ku,states as Mu,stringify as Ou,stringifyYaml as Ru,stripConsoleColor as Uu,textToDate as Wu,throwError as Xu,toDate as Zu,toDateTime as $u,toRegExp as _u,tokenize as si,trimStartOfStreamHelper as ai,truncTo as ui,truncateByToken as ii,truncateToTokenLimit as ei,truncateToTokenLimitEx as ri,uuid as ti,v1 as ni,v4 as di,v5 as mi,validate as oi,version as fi,wait as pi,wrapEventEmitter as vi,xxhash as Fi,xxhash32 as hi,xxhash64 as Hi,xxhashAsStr as Vi}from"./chunk-YVFGQB4L.mjs";import{findPort as ki}from"./chunk-VIG2GB47.mjs";export{s as AIArgProcessor,a as AIChatRoles,u as AIMessageTypes,i as AIStream,e as AITextGenerationFinishReasons,r as AbortError,t as AbortErrorCode,n as ActionNames,d as AlreadyExistsError,m as AlreadyExistsErrorCode,o as AsyncFeatureBits,f as AsyncFeatures,p as BaseError,v as BinarySemaphore,F as CancelableAbility,h as ChoiceArgProcessor,H as ClientToolFuncSchema,V as ClientTools,k as CommonError,l as ConfigFile,B as DEFAULT_CONFIG_NAME,G as DefaultAsyncSemaphoreCapacity,I as EnvPromptTemplate,j as ErrorCode,E as EventBusName,L as EventClient,P as EventEmitter,S as EventName,T as EventServer,Mu as EventStates,g as EventToolFunc,x as FStringPromptTemplate,y as FewShotPromptTemplate,z as FilenameReservedRegex,N as GolangPromptTemplate,gs as HFBuiltins,c as HFEnvironment,w as HFInterpreter,Hs as HFTemplate,Q as HashAlgorithm,Y as HfPromptTemplate,b as IntSet,q as InternalErrorCode,A as LLM_TOKENIZER_NAMES,C as LLM_TOKENIZER_NAMES_MAP,D as LRUCache,K as NotFoundError,M as NotFoundErrorCode,O as NotImplementationError,R as NotImplementedErrorCode,U as ObjectArgsToArgsInfo,W as PASSING_SCORE,X as PromptExampleSelector,Z as PromptTemplate,$ as PromptTemplateTypes,_ as PromptTypes,ss as RStreamErrCode,as as RateLimit,us as ReadableStreamError,is as RemoteToolFuncSchema,es as ResClientTools,rs as ResServerTools,ts as ResponseRStreamErrCode,ns as SHUTDOWN_SIGNALS,ds as SSEChannel,ms as SSEChannelAlreadyClosedErrCode,os as SecondaryCache,fs as Semaphore,ps as ServerToolFuncSchema,vs as ServerTools,Fs as SignalGate,hs as TaskAbortController,Vs as TemplateArgProcessor,ks as ToolAsyncCancelableBit,ls as ToolAsyncMultiTaskBit,Bs as ToolAsyncPriorityBit,Gs as ToolFunc,Is as ToolFuncSchema,cs as WindowsReservedNameRegex,js as YamlTypeBaseObject,Es as _lrucache,Ls as assignDirs,Ps as backendEventable,Ss as base32768,Ts as beforeShutdown,xs as canonicalize,ys as completeSentences,zs as concatText,Ns as countLLMTokens,Qs as countRegexMatches,Ys as createAbilityInjector,bs as createCallbacksTransformer,qs as createEmptyReadableStream,ws as createEndWithRepetitionDetector,As as createError,Cs as createEventStreamTransformer,Ds as createHfValueFunc,Js as createLRUCache,Ks as createYamlObjectTag,Ms as dateToText,Os as decodeCharset,Rs as defaultTemplateFormat,Us as detectCharset,Ws as encodeLLMTokens,Xs as ensureQuoted,Zs as event,$s as eventClient,_s as eventServer,sa as eventable,aa as expandConfig,ua as expandEnv,ia as expandObjEnv,ea as expandPath,ra as extNameLevel,ta as fileIsExists,na as filenameReservedRegex,da as filterValidFnScope,ma as findIndexNonEmptyFrom,ki as findPort,oa as formatISO,fa as formatTextWithSpace,pa as getAllEnumKeys,va as getConfigFileNames,Fa as getConfigs,ha as getEnvVairables,Ha as getFileMetaInfo,Va as getHashAlgoBySize,ka as getKeysPath,la as getLLMTokenizer,Ba as getMultiLevelExtname,Ga as getPackageDir,Ia as getRealFilepath,ca as getResponseErrorReadableStream,ja as getXDGConfigs,Ea as hasDirectoryIn,La as hash,Pa as hashFile,Sa as hashStream,mu as hfParse,si as hfTokenize,Ta as initShutdown,ga as interpolateEnv,xa as interpolateFString,ya as interpolateGolangTemplate,za as isLangUsingSpaces,Na as isListItemString,Qa as isModelNameMatched,Ya as isPunctuationChar,ba as isQuoted,qa as isRegExp,wa as isSameString,Aa as isSectionString,Ca as isSentenceEnding,Da as isSepLineString,Ja as isStrWrapped,Ka as isSubdirectory,Ma as isTitleString,Oa as isValidFilename,Ra as isValidFilepath,Ua as isWebStream,Wa as jsonFilterToWhere,Xa as jsonToMarkdownStr,Za as loadAIConfig,$a as loadConfig,_a as loadConfigFile,su as loadFileFromPaths,au as loadTextFromPaths,uu as lrucache,iu as makeToolFuncCancelable,eu as matchUrlProtocol,ru as memoize,tu as messagesToText,nu as mimeType,du as paramsSizeToScaleStr,fu as parseCommand,pu as parseDateFormat,vu as parseFString,Fu as parseISO,hu as parseJsJson,Hu as parseJsJsonSimpleSync,Vu as parseObjectArgInfo,ku as parseObjectArgumentInfos,lu as parseObjectArguments,Bu as parseObjectArgumentsAsArgInfos,Gu as parseYaml,Iu as quoteStr,cu as reControlCharsRegex,ju as readFilenamesRecursiveSync,Eu as readTextFileChunks,Lu as readTextFileChunksEx,Pu as readableFromAsyncIterable,Su as registerCoreTools,Tu as registerYamlTag,gu as removeMarkdownBold,xu as removeMarkdownBoldAndItalic,yu as removeMarkdownItalic,zu as replaceWithPlaceholder,Nu as restoreFromPlacehoders,Qu as sanitizeFilename,Yu as sanitizeFilepath,bu as saveConfigFile,qu as scaleStrToParamsSize,wu as shutdown,Au as simplifyObjectArguments,Cu as sortedValues,Du as splitChunks,Ju as splitParagraph,Ku as splitSentence,Ru as stringifyYaml,Uu as stripConsoleColor,Wu as textToDate,Xu as throwError,Zu as toDate,$u as toDateTime,_u as toRegExp,ai as trimStartOfStreamHelper,ui as truncTo,ii as truncateByToken,ei as truncateToTokenLimit,ri as truncateToTokenLimitEx,ti as uuid,J as uuidNIL,ou as uuidParse,Ou as uuidStringify,oi as uuidValidate,fi as uuidVersion,ni as uuidv1,di as uuidv4,mi as uuidv5,pi as wait,vi as wrapEventEmitter,Fi as xxhash,hi as xxhash32,Hi as xxhash64,Vi as xxhashAsStr};
+import{AIArgProcessor as t,AIChatRoles as e,AIMessageTypes as r,AIStream as s,AITextGenerationFinishReasons as o,AbortError as n,AbortErrorCode as i,ActionNames as a,AlreadyExistsError as c,AlreadyExistsErrorCode as p,ArrayMergeWay as h,ArrayMergeWaySymbol as l,AsyncFeatureBits as u,AsyncFeatures as d,BaseError as f,BinarySemaphore as v,CancelableAbility as y,ChoiceArgProcessor as m,ClientToolFuncSchema as S,ClientTools as w,CommonError as T,ConfigFile as N,DEFAULT_CONFIG_NAME as E,DefaultAsyncSemaphoreCapacity as $,DefaultDateFormat as O,EnvStringTemplate as C,ErrorCode as J,EventBusName as g,EventClient as j,EventEmitter as R,EventName as P,EventServer as x,EventToolFunc as q,FStringTemplate as H,FewShotPromptTemplate as b,FilenameReservedRegex as G,FuncMetaSymbol as I,GolangStringTemplate as L,HashAlgorithm as D,IntSet as F,InternalErrorCode as M,LLM_TOKENIZER_NAMES as _,LLM_TOKENIZER_NAMES_MAP as k,LRUCache as A,NIL as B,NotFoundError as V,NotFoundErrorCode as Q,NotImplementationError as U,NotImplementedErrorCode as z,ObjectArgsToArgsInfo as K,PASSING_SCORE as W,PromptExampleSelector as X,RStreamErrCode as Y,RateLimit as Z,ReadableStreamError as tt,RemoteToolFuncSchema as et,ResClientTools as rt,ResServerTools as st,ResponseRStreamErrCode as ot,SHUTDOWN_SIGNALS as nt,SSEChannel as it,SSEChannelAlreadyClosedErrCode as at,SecondaryCache as ct,Semaphore as pt,ServerToolFuncSchema as ht,ServerTools as lt,SignalGate as ut,StrangeHumanName as dt,StringTemplate as ft,TaskAbortController as vt,TemplateArgProcessor as yt,ToolAsyncCancelableBit as mt,ToolAsyncMultiTaskBit as St,ToolAsyncPriorityBit as wt,ToolFunc as Tt,ToolFuncSchema as Nt,WindowsReservedNameRegex as Et,YamlTypeBaseObject as $t,_lrucache as Ot,add as Ct,assignDirs as Jt,backendEventable as gt,base32768 as jt,beforeShutdown as Rt,calcPerplexity as Pt,calcPerplexitySimple as xt,canonicalize as qt,completeSentences as Ht,concatText as bt,countLLMTokens as Gt,countRegexMatches as It,createAbilityInjector as Lt,createCallbacksTransformer as Dt,createEmptyReadableStream as Ft,createEndWithRepetitionDetector as Mt,createError as _t,createEventStreamTransformer as kt,createHfValueFunc as At,createLRUCache as Bt,createYamlObjectTag as Vt,dateToText as Qt,decodeCharset as Ut,defaultTemplateFormat as zt,defaultsWithConcat as Kt,detectCharset as Wt,encodeLLMTokens as Xt,ensureQuoted as Yt,event as Zt,eventClient as te,eventServer as ee,eventable as re,expandConfig as se,expandEnv as oe,expandObjEnv as ne,expandPath as ie,expandPathInObject as ae,expandPaths as ce,extNameLevel as pe,fileIsExists as he,filterValidFnScope as le,findIndexNonEmptyFrom as ue,formatISO as de,formatTextWithSpace as fe,funcGetMeta as ve,funcWithMeta as ye,genUrlParamsStr as me,getAllEnumKeys as Se,getConfigFileNames as we,getConfigs as Te,getEnvVairables as Ne,getFileMetaInfo as Ee,getHashAlgoBySize as $e,getKeysPath as Oe,getLLMTokenizer as Ce,getMultiLevelExtname as Je,getPackageDir as ge,getRealFilepath as je,getResponseErrorReadableStream as Re,getXDGConfigs as Pe,hasDirectoryIn as xe,hash as qe,hashFile as He,hashObject as be,hashStream as Ge,initShutdown as Ie,isLangUsingSpaces as Le,isListItemString as De,isModelNameMatched as Fe,isPunctuationChar as Me,isQuoted as _e,isRegExp as ke,isSameString as Ae,isSectionString as Be,isSentenceEnding as Ve,isSepLineString as Qe,isStrWrapped as Ue,isSubdirectory as ze,isTitleString as Ke,isValidFilename as We,isValidFilepath as Xe,isWebStream as Ye,joinSplitWords as Ze,jsonFilterToWhere as tr,jsonToMarkdownStr as er,loadAIConfig as rr,loadConfig as sr,loadConfigFile as or,loadFileFromPaths as nr,loadTextFromPaths as ir,lrucache as ar,makeToolFuncCancelable as cr,matchUrlProtocol as pr,memoize as hr,mergeArray as lr,messagesToText as ur,mimeType as dr,normalizePath as fr,paramsSizeToScaleStr as vr,parse as yr,parseCommand as mr,parseDateFormat as Sr,parseISO as wr,parseJsJson as Tr,parseJsJsonSimpleSync as Nr,parseObjectArgInfo as Er,parseObjectArgumentInfos as $r,parseObjectArguments as Or,parseObjectArgumentsAsArgInfos as Cr,parseYaml as Jr,pruneSubdirectories as gr,pruneSubdirectoriesInPlace as jr,quoteStr as Rr,readFilenamesRecursiveSync as Pr,readTextFileChunks as xr,readTextFileChunksEx as qr,readableFromAsyncIterable as Hr,registerCoreTools as br,registerYamlTag as Gr,removeMarkdownBold as Ir,removeMarkdownBoldAndItalic as Lr,removeMarkdownItalic as Dr,replaceWithPlaceholder as Fr,restoreFromPlacehoders as Mr,sanitizeFilename as _r,sanitizeFilepath as kr,saveConfigFile as Ar,scaleStrToParamsSize as Br,shutdown as Vr,simplifyObjectArguments as Qr,sleep as Ur,sortedValues as zr,splitChunks as Kr,splitParagraph as Wr,splitSentence as Xr,splitWords as Yr,states as Zr,stringify as ts,stringifyYaml as es,stripConsoleColor as rs,textToDate as ss,throwError as os,toDate as ns,toDateTime as is,toRegExp as as,trimStartOfStreamHelper as cs,truncTo as ps,truncateByToken as hs,truncateToTokenLimit as ls,truncateToTokenLimitEx as us,uuid as ds,v1 as fs,v4 as vs,v5 as ys,validate as ms,version as Ss,wait as ws,wrapEventEmitter as Ts,xxhash as Ns,xxhash32 as Es,xxhash64 as $s,xxhashAsStr as Os,yieldExec as Cs}from"./chunk-LNTIQQNN.mjs";import{findPort as Js}from"./chunk-VIG2GB47.mjs";var gs=class{setApiRoot(t){this.apiRoot=t}mount(t,e,r){if(e)this.setApiRoot(e);else if(!(e=this.apiRoot))throw new Error("apiRoot is required");return this.Tools=t,this.options=r,this._mount(t,e,r)}},js=class extends gs{constructor(t){if(!t)throw new Error("apiRoot is required for HttpClientTransport");super(),this.setApiRoot(t)}async _mount(t,e,r){return t.setTransport(this),t.loadFrom()}async loadApis(){return this.fetch("",void 0,"get",void 0,{headers:{"Content-Type":"application/json"}})}async fetch(t,e,r,s,o){o={...this.options,...o};const n=await this._fetch(t,e,r,s,o);if(e?.stream)return n;return await this.toObject(n,e)}};import{defaultsDeep as Rs}from"lodash-es";var Ps=class extends gs{_mount(t,e,r){this.addDiscoveryHandler(e,()=>t),this.addRpcHandler(t,e,r)}start(t){return this.options&&(t=Rs(t,this.options)),this._start(t)}};import xs from"http";import{URL as qs}from"url";import{defaultsDeep as Hs}from"lodash-es";var bs=class extends Ps{constructor(t){super(),this.discoveryHandlerInfo=null,this.rpcHandlerInfo=null,this.server=t?xs.createServer(t,this.requestListener.bind(this)):xs.createServer(this.requestListener.bind(this))}async requestListener(t,e){const{url:r,method:s}=t;if(!r)return e.statusCode=400,e.setHeader("Content-Type","application/json"),void e.end(JSON.stringify({error:"Bad Request"}));if(this.discoveryHandlerInfo&&"GET"===s&&r===this.discoveryHandlerInfo.prefix)try{const t=this.discoveryHandlerInfo.handler();e.setHeader("Content-Type","application/json"),e.statusCode=200,e.end(JSON.stringify(t)),console.log(`[HttpServerTransport] Handled GET ${r} for discovery`)}catch(t){e.statusCode=500,e.setHeader("Content-Type","application/json"),e.end(JSON.stringify({error:t.message||"Internal Server Error"}))}else this.rpcHandlerInfo&&r.startsWith(this.rpcHandlerInfo.prefix)?await this.handleRpcRequest(t,e):(e.statusCode=404,e.setHeader("Content-Type","application/json"),e.end(JSON.stringify({error:"Not Found"})))}addDiscoveryHandler(t,e){this.discoveryHandlerInfo={prefix:t,handler:e},console.log(`[HttpServerTransport] Mapped GET ${t} for discovery`)}addRpcHandler(t,e,r){e.endsWith("/")||(e+="/"),this.rpcHandlerInfo={prefix:e,serverTools:t,options:r},console.log(`[HttpServerTransport] Mapped RPC calls for prefix ${e}`)}async handleRpcRequest(t,e){if(!this.rpcHandlerInfo||!t.url)return e.statusCode=500,e.setHeader("Content-Type","application/json"),void e.end(JSON.stringify({error:"RPC handler not configured"}));const{serverTools:r,prefix:s}=this.rpcHandlerInfo,o=t.url.split("?")[0].substring(s.length),[n,i]=o.split("/"),a=r.get(n);if(!a)return e.statusCode=404,e.setHeader("Content-Type","application/json"),void e.end(JSON.stringify({error:`${n} Not Found`,data:{what:n}}));let c;const p=t.method;try{if("GET"===p||"DELETE"===p){const e=new qs(t.url,`http://${t.headers.host}`).searchParams.get("p");c=e?JSON.parse(e):{}}else{const e=await this.getRequestBody(t);c=e?JSON.parse(e):{}}c._req=t,c._res=e,void 0!==i&&(c.id=i);let r=await a.run(c);a.isStream(c)?r&&"function"==typeof r.pipe?r.pipe(e):e.writableEnded||e.end():(e.setHeader("Content-Type","application/json"),e.statusCode=200,e.end(JSON.stringify(r)))}catch(t){if(console.error("Error during RPC execution:",t),e.headersSent)return;e.setHeader("Content-Type","application/json"),t.code&&"number"==typeof t.code?(e.statusCode=t.code,t.stack&&(t.stack=void 0),e.end(JSON.stringify(t))):(e.statusCode=500,e.end(JSON.stringify({error:t.message||"Internal Server Error"})))}}getRequestBody(t){return new Promise((e,r)=>{let s="";t.on("data",t=>{s+=t.toString()}),t.on("end",()=>{e(s)}),t.on("error",t=>{r(t)})})}async _start(t){const{port:e,host:r="0.0.0.0"}=Hs(t,{port:3e3});return new Promise((t,s)=>{this.server.on("error",t=>{console.error("[HttpServerTransport] Server error:",t),s(t)}),this.server.listen(e,r,()=>{const e=this.server.address(),r="string"==typeof e?e:`${e?.address}:${e?.port}`;console.log(`[HttpServerTransport] Server listening on ${r}`),t()})})}async stop(){return new Promise((t,e)=>{if(!this.server.listening)return t();this.server.close(r=>{if(r)return e(r);t()})})}getRaw(){return this.server}},Gs=class extends js{async loadApis(){const t=await fetch(this.apiRoot,{headers:{"Content-Type":"application/json"}});if(!t.ok)throw new Error(`Failed to load tools from ${this.apiRoot}: ${t.statusText}`);return await t.json()}async _fetch(t,e,r,s,o){const n=["post","put","patch"];let i;r||(r=this.Tools.action||"post"),"res"===r&&(r="get"),o.headers&&o.headers["Content-Type"]||!n.includes(r)||(o.headers={"Content-Type":"application/json",...o.headers}),e?.stream&&!o.headers.Connection&&(o.headers.Connection="keep-alive"),s?("string"!=typeof s&&(s=JSON.stringify(s)),t&&(s=t+"/"+s)):s=t,o.method=r.toUpperCase(),"get"===r||"delete"===r?i=s+me(e):(o.body=JSON.stringify(e),i=s),o.headers&&!n.includes(r)&&delete o.headers["Content-Type"];const a=await fetch(`${this.apiRoot}/${i}`,o);if(!a.ok){throw await this.errorFrom(t,a)}return a}async errorFrom(t,e){let r,s=e.status,o=e.statusText;if(e.body){const s=await e.text();try{const e=JSON.parse(s);e&&(e.error&&(o=e.error),e.name&&(t=e.name),e.data&&(r=e.data,r.name=t,r.what&&(r.msg=o,o=r.what)),e.message&&(o=o+":"+e.message))}catch(t){console.warn("🚀 ~ parse error body to json:",t)}}return _t(o,t,s)}async toObject(t,e){return await t.json()}},Is=class{constructor(){this.name="sse",this.protocol="sse",this.channel=new it}mount(){}subscribe(t,e){const{req:r,res:s,clientId:o}=e??{};if(!r||!s)throw new Error("SSE subscribe requires options.req and options.res");const n=this.channel.subscribe(r,s,t,o),i={id:`${Date.now()}-${Math.random().toString(36).slice(2)}`,clientId:n.clientId,protocol:"sse",send:(t,e)=>{s.write(`event: ${t}\n`),s.write(`data: ${JSON.stringify(e)}\n\n`)},close:()=>s.end?.(),raw:s};return this.onConn?.(i),r.on("close",()=>this.onDis?.(i)),n}publish(t,e,r){this.channel.publish(e,t,r)}onConnection(t){this.onConn=t}onDisconnect(t){this.onDis=t}},Ls=class{connect(t,e){const r=e?`?${new URLSearchParams(e).toString()}`:"",s=new EventSource(`${t}${r}`),o=new Map,n=(t,e)=>{const r=r=>{const s=r.data,o=s?"string"==typeof s?JSON.parse(s):s:void 0;e(o,{...r,event:t})};let n=o.get(t);n||(n=new Map,o.set(t,n)),n.set(e,r),s.addEventListener(t,r)},i=(t,e)=>{const r=o.get(t),n=r?.get(e);n&&(s.removeEventListener(t,n),r.delete(e))};return{protocol:"sse",get readyState(){return s.readyState},on:n,off:i,addEventListener:n,removeEventListener:i,close:()=>s.close()}}disconnect(t){return t.close()}};export{t as AIArgProcessor,e as AIChatRoles,r as AIMessageTypes,s as AIStream,o as AITextGenerationFinishReasons,n as AbortError,i as AbortErrorCode,a as ActionNames,c as AlreadyExistsError,p as AlreadyExistsErrorCode,h as ArrayMergeWay,l as ArrayMergeWaySymbol,u as AsyncFeatureBits,d as AsyncFeatures,f as BaseError,v as BinarySemaphore,y as CancelableAbility,m as ChoiceArgProcessor,S as ClientToolFuncSchema,js as ClientToolTransport,w as ClientTools,T as CommonError,N as ConfigFile,E as DEFAULT_CONFIG_NAME,$ as DefaultAsyncSemaphoreCapacity,O as DefaultDateFormat,C as EnvPromptTemplate,J as ErrorCode,g as EventBusName,j as EventClient,R as EventEmitter,P as EventName,x as EventServer,Zr as EventStates,q as EventToolFunc,H as FStringPromptTemplate,b as FewShotPromptTemplate,G as FilenameReservedRegex,I as FuncMetaSymbol,L as GolangPromptTemplate,D as HashAlgorithm,Gs as HttpClientToolTransport,bs as HttpServerToolTransport,F as IntSet,M as InternalErrorCode,_ as LLM_TOKENIZER_NAMES,k as LLM_TOKENIZER_NAMES_MAP,A as LRUCache,V as NotFoundError,Q as NotFoundErrorCode,U as NotImplementationError,z as NotImplementedErrorCode,K as ObjectArgsToArgsInfo,W as PASSING_SCORE,X as PromptExampleSelector,ft as PromptTemplate,Y as RStreamErrCode,Z as RateLimit,tt as ReadableStreamError,et as RemoteToolFuncSchema,rt as ResClientTools,st as ResServerTools,ot as ResponseRStreamErrCode,nt as SHUTDOWN_SIGNALS,it as SSEChannel,at as SSEChannelAlreadyClosedErrCode,ct as SecondaryCache,pt as Semaphore,ht as ServerToolFuncSchema,Ps as ServerToolTransport,lt as ServerTools,ut as SignalGate,Ls as SseClientPubSubTransport,Is as SseServerPubSubTransport,dt as StrangeHumanName,vt as TaskAbortController,yt as TemplateArgProcessor,mt as ToolAsyncCancelableBit,St as ToolAsyncMultiTaskBit,wt as ToolAsyncPriorityBit,Tt as ToolFunc,Nt as ToolFuncSchema,gs as ToolTransport,Et as WindowsReservedNameRegex,$t as YamlTypeBaseObject,Ot as _lrucache,Ct as addDate,Jt as assignDirs,gt as backendEventable,jt as base32768,Rt as beforeShutdown,Pt as calcPerplexity,xt as calcPerplexitySimple,qt as canonicalize,Ht as completeSentences,bt as concatText,Gt as countLLMTokens,It as countRegexMatches,Lt as createAbilityInjector,Dt as createCallbacksTransformer,Ft as createEmptyReadableStream,Mt as createEndWithRepetitionDetector,_t as createError,kt as createEventStreamTransformer,At as createHfValueFunc,Bt as createLRUCache,Vt as createYamlObjectTag,Qt as dateToText,Ut as decodeCharset,zt as defaultTemplateFormat,Kt as defaultsWithConcat,Wt as detectCharset,Xt as encodeLLMTokens,Yt as ensureQuoted,Zt as event,te as eventClient,ee as eventServer,re as eventable,se as expandConfig,oe as expandEnv,ne as expandObjEnv,ie as expandPath,ae as expandPathInObject,ce as expandPaths,pe as extNameLevel,he as fileIsExists,le as filterValidFnScope,ue as findIndexNonEmptyFrom,Js as findPort,de as formatISO,fe as formatTextWithSpace,ve as funcGetMeta,ye as funcWithMeta,me as genUrlParamsStr,Se as getAllEnumKeys,we as getConfigFileNames,Te as getConfigs,Ne as getEnvVairables,Ee as getFileMetaInfo,$e as getHashAlgoBySize,Oe as getKeysPath,Ce as getLLMTokenizer,Je as getMultiLevelExtname,ge as getPackageDir,je as getRealFilepath,Re as getResponseErrorReadableStream,Pe as getXDGConfigs,xe as hasDirectoryIn,qe as hash,He as hashFile,be as hashObject,Ge as hashStream,Ie as initShutdown,Le as isLangUsingSpaces,De as isListItemString,Fe as isModelNameMatched,Me as isPunctuationChar,_e as isQuoted,ke as isRegExp,Ae as isSameString,Be as isSectionString,Ve as isSentenceEnding,Qe as isSepLineString,Ue as isStrWrapped,ze as isSubdirectory,Ke as isTitleString,We as isValidFilename,Xe as isValidFilepath,Ye as isWebStream,Ze as joinSplitWords,tr as jsonFilterToWhere,er as jsonToMarkdownStr,rr as loadAIConfig,sr as loadConfig,or as loadConfigFile,nr as loadFileFromPaths,ir as loadTextFromPaths,ar as lrucache,cr as makeToolFuncCancelable,pr as matchUrlProtocol,hr as memoize,lr as mergeArray,ur as messagesToText,dr as mimeType,fr as normalizePath,vr as paramsSizeToScaleStr,mr as parseCommand,Sr as parseDateFormat,wr as parseISO,Tr as parseJsJson,Nr as parseJsJsonSimpleSync,Er as parseObjectArgInfo,$r as parseObjectArgumentInfos,Or as parseObjectArguments,Cr as parseObjectArgumentsAsArgInfos,Jr as parseYaml,gr as pruneSubdirectories,jr as pruneSubdirectoriesInPlace,Rr as quoteStr,Pr as readFilenamesRecursiveSync,xr as readTextFileChunks,qr as readTextFileChunksEx,Hr as readableFromAsyncIterable,br as registerCoreTools,Gr as registerYamlTag,Ir as removeMarkdownBold,Lr as removeMarkdownBoldAndItalic,Dr as removeMarkdownItalic,Fr as replaceWithPlaceholder,Mr as restoreFromPlacehoders,_r as sanitizeFilename,kr as sanitizeFilepath,Ar as saveConfigFile,Br as scaleStrToParamsSize,Vr as shutdown,Qr as simplifyObjectArguments,Ur as sleep,zr as sortedValues,Kr as splitChunks,Wr as splitParagraph,Xr as splitSentence,Yr as splitWords,es as stringifyYaml,rs as stripConsoleColor,ss as textToDate,os as throwError,ns as toDate,is as toDateTime,as as toRegExp,cs as trimStartOfStreamHelper,ps as truncTo,hs as truncateByToken,ls as truncateToTokenLimit,us as truncateToTokenLimitEx,ds as uuid,B as uuidNIL,yr as uuidParse,ts as uuidStringify,ms as uuidValidate,Ss as uuidVersion,fs as uuidv1,vs as uuidv4,ys as uuidv5,ws as wait,Ts as wrapEventEmitter,Ns as xxhash,Es as xxhash32,$s as xxhash64,Os as xxhashAsStr,Cs as yieldExec};

package/dist/test/util.js

@@ -1 +1 @@
-"use strict";var e,r=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,u=Object.getOwnPropertyNames,o=Object.getPrototypeOf,c=Object.prototype.hasOwnProperty,i=(e,r,o,i)=>{if(r&&"object"==typeof r||"function"==typeof r)for(let f of u(r))c.call(e,f)||f===o||t(e,f,{get:()=>r[f],enumerable:!(i=n(r,f))||i.enumerable});return e},f={};function a(e,r){expect(e.length).toBeGreaterThanOrEqual(r.length);for(let t=0;t<r.length;t++)if(e[t]!==r[t])return!1;return!0}((e,r)=>{for(var n in r)t(e,n,{get:r[n],enumerable:!0})})(f,{compareStr:()=>a,findPort:()=>s,rmFile:()=>m}),module.exports=(e=f,i(t({},"__esModule",{value:!0}),e));var l=((e,n,u)=>(u=null!=e?r(o(e)):{},i(!n&&e&&e.__esModule?u:t(u,"default",{value:e,enumerable:!0}),e)))(require("net"));async function s(e,r=10){return new Promise(((t,n)=>{void 0===e?e=0:("string"==typeof e&&(e=parseInt(e)),e>=0||(e=0));const u=l.default.createServer();u.on("error",(t=>{"EADDRINUSE"===t.code&&(e++,--r>0)?u.listen(e):n(t)})),u.on("listening",(async()=>{const e=u.address().port;u.close(),t(e)})),u.listen(e)}))}var b=require("fs");function m(e){(0,b.existsSync)(e)&&(0,b.rmSync)(e,{recursive:!0}),(0,b.existsSync)(e+".temp")&&(0,b.rmSync)(e+".temp",{recursive:!0})}
+"use strict";var e,r=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,u=Object.getOwnPropertyNames,o=Object.getPrototypeOf,c=Object.prototype.hasOwnProperty,i=(e,r,o,i)=>{if(r&&"object"==typeof r||"function"==typeof r)for(let f of u(r))c.call(e,f)||f===o||t(e,f,{get:()=>r[f],enumerable:!(i=n(r,f))||i.enumerable});return e},f={};function a(e,r){expect(e.length).toBeGreaterThanOrEqual(r.length);for(let t=0;t<r.length;t++)if(e[t]!==r[t])return!1;return!0}((e,r)=>{for(var n in r)t(e,n,{get:r[n],enumerable:!0})})(f,{compareStr:()=>a,findPort:()=>s,rmFile:()=>m}),module.exports=(e=f,i(t({},"__esModule",{value:!0}),e));var l=((e,n,u)=>(u=null!=e?r(o(e)):{},i(!n&&e&&e.__esModule?u:t(u,"default",{value:e,enumerable:!0}),e)))(require("net"));async function s(e,r=10){return new Promise((t,n)=>{void 0===e?e=0:("string"==typeof e&&(e=parseInt(e)),e>=0||(e=0));const u=l.default.createServer();u.on("error",t=>{"EADDRINUSE"===t.code&&(e++,--r>0)?u.listen(e):n(t)}),u.on("listening",async()=>{const e=u.address().port;u.close(),t(e)}),u.listen(e)})}var b=require("fs");function m(e){(0,b.existsSync)(e)&&(0,b.rmSync)(e,{recursive:!0}),(0,b.existsSync)(e+".temp")&&(0,b.rmSync)(e+".temp",{recursive:!0})}

package/docs/api/README.md

@@ -0,0 +1,165 @@
+**@isdk/ai-tool**
+
+***
+
+# @isdk/ai-tool
+
+A powerful TypeScript framework for creating, managing, and communicating with modular functions. It's perfect for building AI agent tools, backend services, and extensible plugin systems with a clean, decoupled architecture.
+
+## Core Features
+
+- **Modular & Inheritable Tools:** Define functions in a structured way with a clear class hierarchy (`ToolFunc` -> `ServerTools` -> `ResServerTools`).
+- **Pluggable RPC Transport:** Decouple your business logic from the network layer. Communicate between client and server using HTTP, IPC, or any custom protocol.
+- **Pluggable PubSub Transport:** Create real-time, bidirectional event buses for features like notifications and live updates. Implementations for SSE (Server-Sent Events) and Electron IPC are included.
+- **Global Registry:** Easily access any registered function from anywhere in your application.
+
+## Installation
+
+```bash
+npm install @isdk/ai-tool
+```
+
+## Core Architecture: Tool Inheritance
+
+`@isdk/ai-tool` is built on a foundation of extensible classes. Understanding their hierarchy and design is key to using the library effectively.
+
+### Design Philosophy: Static vs. Instance
+
+A key design principle in `ToolFunc` is the separation of roles between the static class and its instances:
+
+- **The Static Class as Manager:** The static side of `ToolFunc` (e.g., `ToolFunc.register`, `ToolFunc.run`, `ToolFunc.get`) acts as a global **registry** and **executor**. It manages all tool definitions, allowing any part of your application to discover and run tools by name without needing a direct reference to the tool's instance.
+
+- **The Instance as the Tool:** An instance (`new ToolFunc(...)`) represents a single, concrete **tool**. It holds the actual function logic, all its metadata (name, description, parameters), and any internal state.
+
+This separation provides the best of both worlds: the power of object-oriented encapsulation for defining individual tools and the convenience of a globally accessible service for managing and executing them.
+
+### Tool Inheritance Hierarchy
+
+The library follows a clear inheritance path, adding specialized features at each level. For a detailed breakdown of each type and how they separate business logic from communication, see the [**Guide to Server & Client Tools**](_media/server_client_tools.md).
+
+**Server-Side Inheritance:**
+`ToolFunc` -> `ServerTools` -> `RpcMethodsServerTool` -> `ResServerTools`
+
+- **`ToolFunc`**: The base for any function, containing core logic and metadata. For more details, see the [ToolFunc Guide](_media/toolFunc.md).
+- **`ServerTools`**: Extends `ToolFunc` to be discoverable and callable by remote clients.
+- **`RpcMethodsServerTool`**: Extends `ServerTools` to allow a single tool to expose multiple methods (e.g., a `Math` tool with `add` and `subtract` methods).
+- **`ResServerTools`**: Extends `RpcMethodsServerTool` to automatically provide a resource-oriented (CRUD) interface.
+
+**Client-Side Inheritance:**
+A parallel hierarchy exists for the client, designed to seamlessly call the server-side tools.
+`ToolFunc` -> `ClientTools` -> `RpcMethodsClientTool` -> `ResClientTools`
+
+## Client-Server RPC with Transports
+
+The framework shines in a client-server setup, allowing you to call backend functions as if they were local.
+
+### Server-Side Example
+
+Use `ServerTools` to define a backend function and `FastifyServerToolTransport` to expose it over HTTP.
+
+```typescript
+// server.ts
+import { ServerTools, FastifyServerToolTransport } from '@isdk/ai-tool';
+
+// Define a tool that can be called remotely
+ServerTools.register({
+  name: 'getUserProfile',
+  params: { id: { type: 'string' } },
+  func: async ({ id }: { id: string }) => {
+    return { id, name: 'Jane Doe', email: 'jane.doe@example.com' };
+  },
+});
+
+// Create a transport and mount the tools under the '/api' prefix
+const serverTransport = new FastifyServerToolTransport();
+serverTransport.mount(ServerTools, '/api');
+
+// Start the server
+serverTransport.start({ port: 3000 });
+```
+
+### Client-Side Example
+
+The `mount` method handles both setting the transport and loading tool definitions from the server in one step.
+
+```typescript
+// client.ts
+import { ClientTools, HttpClientToolTransport } from '@isdk/ai-tool';
+
+async function main() {
+  const apiRoot = 'http://localhost:3000/api';
+
+  // 1. Setup the client transport and mount the tools
+  const clientTransport = new HttpClientToolTransport(apiRoot);
+  await clientTransport.mount(ClientTools);
+
+  // 2. Get the remote tool and run it
+  const getUserProfile = ClientTools.get('getUserProfile');
+  const profile = await getUserProfile.run({ id: '123' });
+
+  console.log(profile);
+}
+main();
+```
+
+> For a deeper dive into how transports work, see the [Transport Layer Guide](_media/transport.md).
+
+## Real-Time Events with PubSub
+
+`@isdk/ai-tool` includes a powerful event system for real-time communication, built on a pluggable PubSub transport layer.
+
+### Quick Example: SSE (Server-Sent Events)
+
+**Server-Side:**
+```typescript
+// server.ts (additions)
+import { EventServer, SseServerPubSubTransport, eventServer } from '@isdk/ai-tool';
+
+// Set the PubSub transport for the EventServer
+EventServer.setPubSubTransport(new SseServerPubSubTransport());
+eventServer.register(); // Register the default event tool
+
+// Now you can publish events from anywhere in your backend
+setInterval(() => {
+  EventServer.publish('server-time', { time: new Date().toISOString() });
+}, 2000);
+```
+
+**Client-Side:**
+```typescript
+// client.ts (additions)
+import { EventClient, SseClientPubSubTransport, eventClient, backendEventable } from '@isdk/ai-tool';
+
+// Set the PubSub transport for the EventClient
+EventClient.setPubSubTransport(new SseClientPubSubTransport());
+
+// Make the client event-aware and register it
+backendEventable(EventClient);
+eventClient.setApiRoot('http://localhost:3000/api'); // Your API root
+eventClient.register();
+
+// Subscribe to and listen for server events
+await eventClient.subscribe('server-time');
+eventClient.on('server-time', (data) => {
+  console.log('Live time from server:', data.time);
+});
+```
+
+> For more detailed examples, including the Electron IPC transport, see the [**Real-time Events (PubSub) Guide**](_media/pubsub.md).
+
+## Contribution
+
+If you would like to contribute to the project, please read the [CONTRIBUTING.md](_media/CONTRIBUTING.md) file for guidelines on how to get started.
+
+## License
+
+The project is licensed under the MIT License. See the [LICENSE-MIT](_media/LICENSE-MIT) file for more details.
+
+## Credit
+
+This project is inspired by and uses code from several excellent open-source projects:
+
+* [@huggingface/jinja](https://github.com/huggingface/huggingface.js)
+* [eventsource-parser](https://github.com/rexxars/eventsource-parser)
+* [async-sema](https://github.com/vercel/async-sema)
+* [modelfusion](https://github.com/vercel/modelfusion)

package/docs/{_media → api/_media}/CONTRIBUTING.md

@@ -5,7 +5,7 @@ Please feel free to file GitHub Issues or propose Pull Requests. We're always ha
 ## Testing
 
 ```shell
-npm test
+pnpm test
 ```
 
 ## Releasing
@@ -13,6 +13,6 @@ npm test
 Releases are supposed to be done from master, version bumping is automated through [`standard-version`](https://github.com/absolute-version/commit-and-tag-version):
 
 ```shell
-npm run release -- --dry-run  # verify output manually
-npm run release               # follow the instructions from the output of this command
+pnpm run release -- --dry-run  # verify output manually
+pnpm run release               # follow the instructions from the output of this command
 ```

package/docs/api/_media/pubsub.md

@@ -0,0 +1,326 @@
+# Developer's Guide: Real-time Events with EventServer & EventClient
+
+This guide provides a comprehensive overview of the `EventServer` and `EventClient` tools, a powerful system for real-time, bidirectional communication. It is built on a **pluggable PubSub transport layer**, making it independent of the underlying communication protocol. You can use Server-Sent Events (SSE), WebSockets, IPC, or any other protocol by providing a corresponding transport implementation.
+
+**Prerequisite:** This document assumes you understand the base transport layer. If not, please review the [`transport_readme.md`](./transport_readme.md) first.
+
+## Core Concept: The Unified Event Bus
+
+The primary goal of this system is to create a seamless event bus that spans both the server and the client. It uses an abstract, pluggable PubSub transport for server-to-client messages and standard RPC calls for client-to-server messages.
+
+The key feature is the ability to **"forward"** events. You can configure the server to automatically listen for events on its internal, global `eventBus` and relay them to clients. Likewise, you can configure the client to forward its local events to the server. This creates a powerful, decoupled architecture where different parts of your application can communicate without direct dependencies.
+
+### Aspect-Oriented Programming (AoP) and Event Emitters
+
+A crucial concept is that `EventClient` (and `ClientTools` in general) can be enhanced with event emitter capabilities. By using a library like `events-ex`, you can give your client-side tool instances standard `on`, `off`, and `emit` methods. This allows `EventClient` to act as a local event bus that is transparently synchronized with the server.
+
+## Example 1: HTTP and Server-Sent Events (SSE)
+
+### Architecture (SSE)
+
+The following diagram illustrates how the components interact when using the provided SSE-based transport. Other transports (like WebSockets or IPC) would follow a similar pattern.
+
+```mermaid
+graph TD
+    subgraph Client-Side
+        C_App[Client Application]
+        C_EventBus(Local Event Emitter)
+        EC[EventClient] -- "uses" --> C_PubSub[SseClientPubSubTransport]
+        C_Transport[HttpClientToolTransport]
+
+        C_App -- "emit/on" --> C_EventBus
+        EC -- "decorated with" --> C_EventBus
+        C_PubSub -- "HTTP GET (SSE)" --> S_PubSub
+        EC -- "RPC calls" --> C_Transport
+    end
+
+    subgraph Server-Side
+        S_Transport[FastifyServerToolTransport] -- "receives RPC" --> ES[EventServer]
+        ES -- "uses" --> S_PubSub[SseServerPubSubTransport]
+        S_PubSub -- "handles SSE connections" --> ES
+        ES -- "interacts with" --> S_EventBus[Global Server EventBus]
+        OtherServices[Other Server Logic] -- "emit/on" --> S_EventBus
+    end
+
+    subgraph "Network (HTTP)"
+        C_Transport -- "RPC: POST /api/event" --> S_Transport
+    end
+```
+
+### Server-Side Setup (SSE)
+
+In your server setup, you must first tell `EventServer` which transport to use, then register the `eventServer` instance.
+
+```typescript
+// In your server entry file (e.g., server.ts)
+import {
+  eventServer,
+  FastifyServerToolTransport,
+  ResServerTools,
+  EventServer, // Import EventServer class
+  SseServerPubSubTransport // Import the SSE transport
+} from '@isdk/ai-tool';
+
+async function main() {
+  // **Crucial Step: Set the PubSub transport for the server**
+  EventServer.setPubSubTransport(new SseServerPubSubTransport());
+
+  // Register the eventServer tool instance
+  eventServer.register();
+
+  const serverTransport = new FastifyServerToolTransport();
+  // Mount the base class; the transport finds all registered tools
+  serverTransport.mount(ResServerTools, '/api');
+
+  // ... start server
+  await serverTransport.start({port: 3000})
+}
+```
+
+### Client-Side Setup (SSE)
+
+On the client, you must set the appropriate PubSub transport (matching the server's), enhance the `EventClient` with `EventEmitter` capabilities, and register the instance.
+
+```typescript
+// In your client-side code
+import {
+  backendEventable,
+  EventClient,
+  eventClient,
+  HttpClientToolTransport,
+  ResClientTools,
+  SseClientPubSubTransport // Import the SSE transport
+} from '@isdk/ai-tool';
+
+async function main() {
+  const apiRoot = 'http://localhost:3003/api';
+  const clientTransport = new HttpClientToolTransport(apiRoot);
+  await clientTransport.mount(ResClientTools);
+
+  // **Crucial Step 1: Set the PubSub transport for the client**
+  EventClient.setPubSubTransport(new SseClientPubSubTransport());
+
+  // **Crucial Step 2: Make the client eventable**
+  backendEventable(EventClient);
+  eventClient.register();
+
+  // Now you can use eventClient.on, .off, .emit
+}
+```
+
+---
+
+## Example 2: Electron IPC Transport
+
+This transport uses Electron's Inter-Process Communication (IPC) to create an event bus between the main process (server) and renderer processes (clients).
+
+### Server-Side Setup (Electron Main Process)
+
+In your Electron main process, you instantiate an `ElectronServerPubSubTransport` with a unique namespace. This namespace acts like an `apiRoot` and ensures that different event buses don't conflict.
+
+```typescript
+// In your Electron main process (e.g., main.ts)
+import {
+  EventServer,
+  eventServer,
+  ElectronServerPubSubTransport,
+} from '@isdk/ai-tool';
+
+// 1. Define a unique namespace for this event bus
+const electronApiRoot = '/electron/events';
+
+// 2. Create a transport instance for this specific namespace
+const electronTransport = new ElectronServerPubSubTransport(electronApiRoot);
+
+// 3. Set the transport on the EventServer
+// Note: This is a static property. For multiple, different event servers
+// (e.g., one for SSE, one for Electron), you would create subclasses of EventServer
+// to hold each static transport instance separately.
+EventServer.setPubSubTransport(electronTransport);
+
+// 4. Register the eventServer tool instance. It will now use the Electron transport.
+eventServer.register();
+
+// Now you can use the global eventBus to emit events, and the EventServer
+// will forward them to any connected renderer process.
+```
+
+### Client-Side Setup (Electron Renderer Process)
+
+In the renderer process, you must use the same namespace (`apiRoot`) to connect to the correct event bus in the main process.
+
+**Important:** The `EventClient` still relies on an RPC mechanism for actions like `subscribe` and `unsubscribe`. You must have a corresponding RPC transport set up between the renderer and main process for the full functionality to work. The example below focuses only on setting up the PubSub portion.
+
+```typescript
+// In your Electron renderer process (e.g., preload.ts or renderer.ts)
+import {
+  EventClient,
+  eventClient,
+  ElectronClientPubSubTransport,
+  backendEventable,
+} from '@isdk/ai-tool';
+
+// 1. The apiRoot MUST match the namespace used in the main process
+const electronApiRoot = '/electron/events';
+
+// 2. Set the PubSub transport on the EventClient class
+EventClient.setPubSubTransport(new ElectronClientPubSubTransport());
+
+// 3. Make the EventClient class event-aware
+backendEventable(EventClient);
+
+// 4. Configure the eventClient INSTANCE
+// This tells the client which event bus to connect to.
+eventClient.setApiRoot(electronApiRoot);
+eventClient.register();
+
+// 5. Now you can use the event client
+async function setupEvents() {
+  await eventClient.subscribe('some-event-from-main');
+
+  eventClient.on('some-event-from-main', (data) => {
+    console.log('Received event from main process:', data);
+  });
+
+  // Forward a local event to the main process
+  eventClient.forwardEvent('event-from-renderer');
+  eventClient.emit('event-from-renderer', { my: 'data' });
+}
+
+setupEvents();
+```
+
+---
+
+## General Usage (Transport-Agnostic)
+
+Once the setup is complete, the API for using the event bus is the same regardless of the underlying transport.
+
+### Forwarding and Publishing Events (Server-Side)
+
+The server can push events to clients either by forwarding them from a central event bus or by publishing them directly. With the latest updates, the `publish` method now supports targeted delivery to specific clients, in addition to broadcasting.
+
+**Note:** The availability of targeted publishing depends on the underlying transport implementation. While the `EventServer` API supports it, some transports (like the current SSE transport) may only be capable of broadcasting.
+
+```typescript
+import { eventServer, EventServer } from '@isdk/ai-tool';
+import { event } from '@isdk/ai-tool/funcs/event'; // The global eventBus
+
+const eventBus = event.runSync();
+
+// **Forwarding (Recommended)**
+// Automatically relay events from the global eventBus to subscribed clients.
+eventServer.forward(['user-updated', 'item-added']);
+
+// Now, any other part of your server can simply emit events on the bus:
+function updateUser(user: any) {
+  eventBus.emit('user-updated', { userId: user.id, status: 'active' });
+}
+
+// **Direct Publishing**
+// The `EventServer.publish` method allows sending an event directly to clients.
+// Its signature is: `publish(event: string, data: any, target?: { clientId: string | string[] })`.
+
+// 1. Broadcast to all clients subscribed to 'broadcast-message'.
+// This is the default behavior when `target` is omitted.
+function sendBroadcast() {
+    EventServer.publish('broadcast-message', { message: 'Server is restarting soon!' });
+}
+
+// 2. Send a targeted event to a specific client.
+// This requires knowing the `clientId` of the recipient.
+function sendDirectMessage(clientId: string, message: string) {
+    const target = { clientId };
+    EventServer.publish('private-message', { text: message }, target);
+}
+
+// 3. Send an event to a group of specific clients.
+function sendToGroup(clientIds: string[], message: string) {
+    const target = { clientId: clientIds };
+    EventServer.publish('group-message', { text: message }, target);
+}
+
+// **Receiving Client Events**
+// Listen for events that were published or forwarded from a client.
+eventBus.on('client-action', (data: any, event: any) => {
+  console.log(`Received event "$\{event.type\}" from a client:`, data);
+});
+```
+
+### Subscribing, Listening, and Publishing (Client-Side)
+
+```typescript
+// **Subscribe and Listen**
+await eventClient.subscribe(['user-updated', 'broadcast-message']);
+
+eventClient.on('user-updated', (data: any) => {
+  console.log('User updated on server!', data);
+});
+
+// **Publish an Event to the Server**
+eventClient.publish({
+    event: 'client-action',
+    data: { action: 'button-click', value: 123 }
+});
+
+// **Forwarding Client Events (Recommended)**
+eventClient.forwardEvent(['user-settings-changed']);
+
+function onSettingsSave(newSettings: any) {
+    eventClient.emit('user-settings-changed', newSettings);
+}
+```
+
+This transport-agnostic architecture provides a clean, powerful, and decoupled way to build real-time, interactive applications. By separating the event logic from the communication protocol, you can choose the best transport for your needs while maintaining a consistent, unified event model.
+
+---
+
+## Implementing a Custom PubSub Transport
+
+For developers who need to integrate a different messaging protocol (e.g., WebSockets, MQTT), you can create your own transport by implementing the `IPubSubServerTransport` interface from `@isdk/ai-tool/transports/pubsub/server`.
+
+The core interface is defined as follows:
+
+```typescript
+export interface IPubSubServerTransport {
+  readonly name: string;
+  readonly protocol: string;
+
+  // Optional: For transports that need to hook into an HTTP server
+  mount?: (path: string, options?: Record<string, any>) => void;
+
+  // Establish a connection with a client and subscribe them to events.
+  // The `options` object is a generic container for transport-specific
+  // parameters, like HTTP request/response objects for SSE.
+  subscribe: (
+    events?: string[],
+    options?: {
+      req?: any;
+      res?: any;
+      clientId?: string;
+      [k: string]: any;
+    }
+  ) => PubSubClient; // Return a client object, minimally with a `clientId`.
+
+  // Publish an event from the server to clients.
+  // The `target` parameter allows for broadcasting (default) or
+  // targeted delivery to specific client IDs.
+  publish: (
+    event: string,
+    data: any,
+    target?: { clientId?: string | string[] }
+  ) => void;
+
+  // Lifecycle hooks to let the EventServer know about connections.
+  onConnection: (cb: (session: PubSubServerSession) => void) => void;
+  onDisconnect: (cb: (session: PubSubServerSession) => void) => void;
+
+  // Optional: For bidirectional transports (e.g., WebSockets)
+  // to handle messages received from the client.
+  onMessage?: (
+    cb: (session: PubSubServerSession, event: string, data: any) => void
+  ) => void;
+}
+```
+
+By implementing this interface, your custom transport can be plugged directly into the `EventServer` using `EventServer.setPubSubTransport(new YourCustomTransport())`, enabling the entire real-time event system over your chosen protocol.