@isdk/ai-tool 0.5.8 → 0.7.0

package/dist/index-BCco-g_I.d.mts

@@ -0,0 +1,1781 @@
+import { EventEmitter, Event } from 'events-ex';
+import { AdvancePropertyManager } from 'property-manager';
+import { AbilityOptions } from 'custom-ability';
+import { CommonError } from '@isdk/common-error';
+import { Cache, ICacheOptions } from 'secondary-cache';
+import { IncomingMessage, ServerResponse } from 'http';
+
+/**
+ * Represents the data type of a function parameter as a string (e.g., `'string'`, `'number'`).
+ */
+type FuncParamType = string;
+/**
+ * Describes a single function parameter, including its name, type, and description.
+ * @interface
+ */
+interface FuncParam {
+    /**
+     * The name of the parameter.
+     * @type {string}
+     */
+    name?: string;
+    /**
+     * The data type of the parameter, represented as a string identifier (e.g., 'string', 'number').
+     * @type {FuncParamType}
+     */
+    type?: FuncParamType;
+    /**
+     * Indicates whether the parameter is required.
+     * @type {boolean}
+     */
+    required?: boolean;
+    /**
+     * A description of the parameter, explaining its purpose and usage.
+     * @type {string}
+     */
+    description?: string;
+}
+/**
+ * A map of function parameters, where each key is the parameter name.
+ * The value can be either a detailed `FuncParam` object or a simple type string.
+ *
+ * @example
+ * const params: FuncParams = {
+ *   userId: 'string',
+ *   profile: {
+ *     type: 'object',
+ *     description: 'User profile data'
+ *   }
+ * };
+ */
+interface FuncParams {
+    [name: string]: FuncParam | FuncParamType;
+}
+/**
+ * Defines the signature for a tool function's implementation.
+ *
+ * @param {ToolFunc} this - The `this` context is bound to the `ToolFunc` instance.
+ * @param {...any[]} params - Variadic arguments passed to the function.
+ * @returns {any} The result of the function's execution.
+ */
+type TFunc = (this: ToolFunc, ...params: any[]) => any;
+/**
+ * Base configuration for defining a tool function.
+ * @interface
+ */
+interface BaseFuncItem {
+    /**
+     * The unique name of the function.
+     * @type {string}
+     */
+    name?: string;
+    /**
+     * Parameter definitions, which can be an object mapping names to definitions or an array for positional parameters.
+     * @type {FuncParams | FuncParam[]}
+     */
+    params?: FuncParams | FuncParam[];
+    /**
+     * The expected return type of the function, described as a string or a JSON schema object.
+     * @type {string | Record<string, any>}
+     */
+    result?: string | Record<string, any>;
+    /**
+     * The execution scope or context (`this`) for the function.
+     * @type {any}
+     */
+    scope?: any;
+    /**
+     * Tags for grouping or filtering functions.
+     * @type {string | string[]}
+     */
+    tags?: string | string[];
+    /**
+     * A lifecycle hook called once during the `ToolFunc` instance's initialization.
+     * It allows for initial setup, state configuration, or property modification on the instance
+     * before it is used or registered. The `this` context is the `ToolFunc` instance itself.
+     *
+     * @param {FuncItem} [options] - The configuration options for the function.
+     * @example
+     * const myFunc = new ToolFunc({
+     *   name: 'myFunc',
+     *   customState: 'initial',
+     *   setup() {
+     *     // `this` is the myFunc instance
+     *     this.customState = 'configured';
+     *   }
+     * });
+     * console.log(myFunc.customState); // Outputs: 'configured'
+     */
+    setup?: (this: ToolFunc, options?: FuncItem) => void;
+    /**
+     * If true, indicates that this function should be treated as a server-side API.
+     * @type {boolean}
+     */
+    isApi?: boolean;
+    /**
+     * If true, indicates that the function has the *capability* to stream its output.
+     * Whether a specific call is streamed is determined by a `stream` property in the runtime parameters.
+     * @type {boolean}
+     */
+    stream?: boolean;
+    /**
+     * Optional aliases for the function name.
+     * @type {string | string[]}
+     */
+    alias?: string | string[];
+    /**
+     * A bitmask representing asynchronous features supported by the function, built from `AsyncFeatureBits`.
+     * This allows the system to understand if a function supports capabilities like cancellation or multi-tasking.
+     * @see AsyncFeatureBits from `@src/utils/cancelable-ability.ts`
+     * @type {number}
+     * @example
+     * import { AsyncFeatures } from './utils';
+     * const func = new ToolFunc({
+     *   name: 'cancellableTask',
+     *   asyncFeatures: AsyncFeatures.Cancelable | AsyncFeatures.MultiTask,
+     *   // ...
+     * });
+     */
+    asyncFeatures?: number;
+    /**
+     * A map of dependencies this function has on other tool functions.
+     * Declaring dependencies ensures that they are automatically registered when this function is registered.
+     * This is crucial for building modular functions that rely on each other without needing to manage registration order manually.
+     *
+     * @type {{ [name: string]: ToolFunc }}
+     * @example
+     * const helperFunc = new ToolFunc({ name: 'helper', func: () => 'world' });
+     * const mainFunc = new ToolFunc({
+     *   name: 'main',
+     *   depends: {
+     *     helper: helperFunc,
+     *   },
+     *   func() {
+     *     // We can now safely run the dependency
+     *     const result = this.runSync('helper');
+     *     return `Hello, ${result}`;
+     *   }
+     * });
+     * // When mainFunc is registered, helperFunc will be registered automatically.
+     * mainFunc.register();
+     */
+    depends?: {
+        [name: string]: ToolFunc;
+    };
+    /**
+     * A detailed description of what the function does.
+     * @type {string}
+     */
+    description?: string;
+    /**
+     * A concise, human-readable title for the function, often used in UI or by AI.
+     * @type {string}
+     */
+    title?: string;
+}
+/**
+ * Extends `BaseFuncItem` to include the actual function implementation.
+ * @interface
+ */
+interface FuncItem extends BaseFuncItem {
+    /**
+     * The implementation of the tool function.
+     * @type {TFunc}
+     */
+    func?: TFunc;
+}
+/**
+ * Represents a fully-defined tool function where the implementation is mandatory.
+ * @interface
+ */
+interface BaseFunc extends BaseFuncItem {
+    /**
+     * The actual function implementation.
+     * @param {...any} params - The parameters for the function.
+     * @returns {any} The result of the function.
+     */
+    func(...params: any): any;
+}
+/**
+ * A map of registered `ToolFunc` instances, indexed by their names.
+ */
+interface Funcs {
+    [name: string]: ToolFunc;
+}
+/**
+ * Describes a package of tool functions, including methods for registration and unregistration.
+ * @interface
+ */
+interface ToolFuncPackage {
+    /**
+     * The name of the tool function package.
+     * @type {string}
+     */
+    name: string;
+    /**
+     * A method to register all functions within the package.
+     * @param {any} [data] - Optional data to pass to the registration process.
+     */
+    register: (data?: any) => void;
+    /**
+     * An optional method to unregister all functions within the package.
+     */
+    unregister?: () => void;
+}
+/**
+ * Declaration merging to extend the `ToolFunc` class with `BaseFunc` properties and allow arbitrary properties.
+ */
+declare interface ToolFunc extends BaseFunc {
+    [name: string]: any;
+}
+/**
+ * A manager for creating, registering, and executing reusable tool functions.
+ *
+ * `ToolFunc` provides a robust framework for defining functions with rich metadata,
+ * managing their lifecycle, and executing them through a centralized registry.
+ * It is the core component for creating modular and discoverable tools.
+ *
+ * Key Features:
+ * - **Rich Metadata**: Define functions with descriptions, parameters, tags, and titles, making them self-documenting.
+ * - **Static Registry**: A global, static registry (`ToolFunc.items`) allows any part of an application to access and run registered functions by name.
+ * - **Dependency Management**: Use the `depends` property to declare dependencies on other `ToolFunc`s, which are then auto-registered.
+ * - **Aliasing**: Assign multiple names to a function for flexibility.
+ * - **Lifecycle Hooks**: Use the `setup` method for one-time initialization logic when a `ToolFunc` instance is created.
+ * - **Parameter Handling**: Automatically handles both positional and named parameters.
+ *
+ * @extends AdvancePropertyManager
+ *
+ * @example
+ * // 1. Define a helper function
+ * const getUser = new ToolFunc({
+ *   name: 'getUser',
+ *   description: 'Retrieves a user by ID.',
+ *   params: { id: { type: 'string', required: true } },
+ *   func: (params) => ({ id: params.id, name: 'John Doe' }),
+ * });
+ *
+ * // 2. Define a main function that depends on the helper
+ * const welcomeUser = new ToolFunc({
+ *   name: 'welcomeUser',
+ *   title: 'Welcome User',
+ *   description: 'Generates a welcome message for a user.',
+ *   params: { userId: 'string' },
+ *   depends: {
+ *     // By declaring this dependency, `getUser` will be auto-registered
+ *     // when `welcomeUser` is registered.
+ *     userFetcher: getUser,
+ *   },
+ *   func: function(params) {
+ *     // `this` is the ToolFunc instance, so we can use `runSync`
+ *     const user = this.runSync('userFetcher', { id: params.userId });
+ *     return `Hello, ${user.name}!`;
+ *   },
+ * });
+ *
+ * // 3. Register the main function. The dependency is registered automatically.
+ * welcomeUser.register();
+ *
+ * // 4. Run the function from anywhere using the static runner.
+ * async function main() {
+ *   const message = await ToolFunc.run('welcomeUser', { userId: '123' });
+ *   console.log(message); // Outputs: "Hello, John Doe!"
+ * }
+ *
+ * main();
+ */
+declare class ToolFunc extends AdvancePropertyManager {
+    /**
+     * A static registry of all `ToolFunc` instances, indexed by name.
+     * @type {Funcs}
+     */
+    static items: Funcs;
+    /**
+     * A static map of aliases to their corresponding function names.
+     * @type {{ [name: string]: string }}
+     */
+    static aliases: {
+        [name: string]: string;
+    };
+    /**
+     * A conventional property to designate a file path for saving the registered `ToolFunc` data.
+     * Note: The `ToolFunc` class itself does not implement persistence logic. It is up to the
+     * developer to use this path to save and load the `ToolFunc.items` registry if needed.
+     * @type {string}
+     */
+    static dataPath: string;
+    /**
+     * Retrieves a registered function by its name or alias.
+     * @param {string} name - The name or alias of the function to retrieve.
+     * @returns {ToolFunc | undefined} The `ToolFunc` instance if found, otherwise `undefined`.
+     */
+    static get(name: string): ToolFunc;
+    /**
+     * Returns the complete map of all registered functions.
+     * @returns {Funcs} The map of `ToolFunc` instances.
+     */
+    static list(): Funcs;
+    /**
+     * Finds the first registered function that has a specific tag.
+     * @param {string} tagName - The tag to search for.
+     * @returns {ToolFunc | undefined} The first matching `ToolFunc` instance, or `undefined` if none is found.
+     */
+    static getByTag(tagName: string): ToolFunc | undefined;
+    /**
+     * Retrieves all registered functions that have a specific tag.
+     * @param {string} tagName - The tag to search for.
+     * @returns {ToolFunc[]} An array of matching `ToolFunc` instances.
+     */
+    static getAllByTag(tagName: string): ToolFunc[];
+    /**
+     * Checks if any registered function has a specific asynchronous feature.
+     * @param {AsyncFeatureBits} feature - The async feature bit to check for.
+     * @returns {boolean} `true` if the feature is present in any function, otherwise `false`.
+     */
+    static hasAsyncFeature(feature: AsyncFeatureBits): boolean;
+    /**
+     * Asynchronously executes a registered function by name with named parameters.
+     * @param {string} name - The name of the function to run.
+     * @param {any} [params] - The parameters object for the function.
+     * @returns {Promise<any>} A promise that resolves with the function's result.
+     * @throws {NotFoundError} If the function with the given name is not found.
+     */
+    static run(name: string, params?: any): Promise<any>;
+    /**
+     * Synchronously executes a registered function by name with named parameters.
+     * @param {string} name - The name of the function to run.
+     * @param {any} [params] - The parameters object for the function.
+     * @returns {any} The result of the function's execution.
+     * @throws {NotFoundError} If the function with the given name is not found.
+     */
+    static runSync(name: string, params?: any): any;
+    /**
+     * Retrieves a bound, runnable function reference for a registered function.
+     * This reference is suitable for execution with an object of named parameters.
+     * @param {string} name - The name of the function.
+     * @returns {Function | undefined} A bound function reference, or `undefined` if not found.
+     */
+    static getFunc(name: string): any;
+    /**
+     * Asynchronously executes a function using positional arguments.
+     * @param {string} name - The name of the function to run.
+     * @param {...any[]} params - Positional arguments to pass to the function.
+     * @returns {Promise<any>} A promise that resolves with the function's result.
+     * @throws {NotFoundError} If the function with the given name is not found.
+     */
+    static runWithPos(name: string, ...params: any[]): Promise<any>;
+    /**
+     * Synchronously executes a function using positional arguments.
+     * @param {string} name - The name of the function to run.
+     * @param {...any[]} params - Positional arguments to pass to the function.
+     * @returns {any} The result of the function's execution.
+     * @throws {NotFoundError} If the function with the given name is not found.
+     */
+    static runWithPosSync(name: string, ...params: any[]): any;
+    /**
+     * Retrieves a bound, runnable function reference for a registered function.
+     * This reference is suitable for execution with positional arguments.
+     * @param {string} name - The name of the function.
+     * @returns {Function | undefined} A bound function reference, or `undefined` if not found.
+     */
+    static getFuncWithPos(name: string): any;
+    /**
+     * Registers a new tool function.
+     *
+     * @overload
+     * @param {string} name - The name of the function.
+     * @param {FuncItem} options - The function's configuration.
+     * @returns {boolean | ToolFunc} The new `ToolFunc` instance, or `false` if a function with that name already exists.
+     *
+     * @overload
+     * @param {Function} func - The function implementation.
+     * @param {FuncItem} options - The function's configuration.
+     * @returns {boolean | ToolFunc} The new `ToolFunc` instance, or `false` if a function with that name already exists.
+     *
+     * @overload
+     * @param {string | ToolFunc | Function | FuncItem} name - A name, `ToolFunc` instance, function, or configuration object.
+     * @param {FuncItem} [options] - Additional configuration.
+     * @returns {boolean | ToolFunc} The new `ToolFunc` instance, or `false` if a function with that name already exists.
+     */
+    static register(name: string, options: FuncItem): boolean | ToolFunc;
+    static register(func: Function, options: FuncItem): boolean | ToolFunc;
+    static register(name: string | ToolFunc | Function | FuncItem, options?: FuncItem): boolean | ToolFunc;
+    /**
+     * Unregisters a function by its name, also removing any associated aliases.
+     * @param {string} name - The name of the function to unregister.
+     * @returns {ToolFunc | undefined} The unregistered `ToolFunc` instance, or `undefined` if it was not found.
+     */
+    static unregister(name: string): ToolFunc | undefined;
+    /**
+     * Initializes a new `ToolFunc` instance.
+     *
+     * @param {string | Function | FuncItem} name - Can be a function name, a function implementation, or a configuration object.
+     * @param {FuncItem | any} [options={}] - Configuration options if not provided in the first argument.
+     */
+    constructor(name: string | Function | FuncItem, options?: FuncItem | any);
+    /**
+     * Registers the current `ToolFunc` instance into the static registry.
+     * Also registers any declared dependencies.
+     * @returns {boolean | ToolFunc} The instance itself upon successful registration, or `false` if it already exists.
+     */
+    register(): boolean | ToolFunc;
+    /**
+     * Removes the current `ToolFunc` instance from the static registry.
+     * @returns {ToolFunc | undefined} The instance that was unregistered.
+     */
+    unregister(): any;
+    /**
+     * Converts an array of positional arguments into a named parameters object.
+     * This is used internally to support functions defined with named parameters.
+     * @param {any[]} params - An array of positional arguments.
+     * @returns {any[]} An array containing a single parameters object.
+     */
+    arr2ObjParams(params: any[]): any[];
+    /**
+     * Converts a named parameters object into an array of positional arguments.
+     * This is used for functions defined with positional parameters.
+     * @param {any} [params] - A named parameters object.
+     * @returns {any[]} An array of positional arguments.
+     */
+    obj2ArrParams(params?: any): any[];
+    /**
+     * Executes the function synchronously with a named parameters object.
+     * @param {any} [params] - The parameters object for the function.
+     * @returns {any} The result of the function execution.
+     * @throws Will throw an error if an array of parameters is passed to a function that expects an object.
+     */
+    runSync(params?: any): any;
+    /**
+     * Executes the function asynchronously with a named parameters object.
+     * @param {any} [params] - The parameters object for the function.
+     * @returns {Promise<any>} A promise that resolves with the function's result.
+     */
+    run(params?: any): Promise<any>;
+    /**
+     * Asynchronously executes another registered function by name.
+     * This method delegates to `runAsSync()` internally.
+     * @param {string} name - The name of the target function to run.
+     * @param {any} [params] - Optional parameters to pass to the function.
+     * @returns {Promise<any>} A promise that resolves with the result of the function execution.
+     */
+    runAs(name: string, params?: any): Promise<any>;
+    /**
+     * Synchronously executes another registered function by name.
+     * This is a convenience method that forwards the call to the static `runSync()` method.
+     * @param {string} name - The name of the target function to run.
+     * @param {any} [params] - Optional parameters to pass to the function.
+     * @returns {any} The result of the function execution.
+     */
+    runAsSync(name: string, params?: any): any;
+    /**
+     * Gets a bound function reference for execution with named parameters.
+     * If a name is provided, it retrieves a different function from the registry.
+     * Otherwise, it returns a bound version of this instance's `runSync`.
+     * @param {string} [name] - Optional name of the function to retrieve.
+     * @returns {Function | undefined} A function reference or `undefined` if not found.
+     */
+    getFunc(name?: string): any;
+    /**
+     * Executes the function synchronously using positional arguments.
+     * If the function expects named parameters, it converts the arguments automatically.
+     * @param {...any[]} params - Positional arguments passed to the function.
+     * @returns {any} The result of the function execution.
+     */
+    runWithPosSync(...params: any[]): any;
+    /**
+     * Synchronously executes another function by name using positional arguments.
+     * This is a convenience wrapper around the static `runWithPosSync()` method.
+     * @param {string} name - The name of the target function to run.
+     * @param {...any[]} params - Positional arguments to pass to the function.
+     * @returns {any} The result of the function execution.
+     */
+    runWithPosAsSync(name: string, ...params: any[]): any;
+    /**
+     * Executes the function asynchronously using positional arguments.
+     * Delegates to `runWithPosSync()` internally.
+     * @param {...any[]} params - Positional arguments passed to the function.
+     * @returns {Promise<any>} A promise that resolves with the result of the function execution.
+     */
+    runWithPos(...params: any[]): Promise<any>;
+    /**
+     * Asynchronously executes another function by name using positional arguments.
+     * Delegates to `runWithPosAsSync()` internally.
+     * @param {string} name - The name of the target function to run.
+     * @param {...any[]} params - Positional arguments to pass to the function.
+     * @returns {Promise<any>} A promise that resolves with the result of the function execution.
+     */
+    runWithPosAs(name: string, ...params: any[]): Promise<any>;
+    /**
+     * Gets a bound function reference suitable for positional argument execution.
+     * If a name is provided, it retrieves a different function from the registry.
+     * Otherwise, it returns a bound version of this instance's `runWithPosSync`.
+     * @param {string} [name] - Optional name of the function to retrieve.
+     * @returns {Function | undefined} A function reference or `undefined` if not found.
+     */
+    getFuncWithPos(name?: string): any;
+    /**
+     * Checks if the current function instance supports a specific async feature.
+     * @param {AsyncFeatureBits} feature - The async feature bit to check for.
+     * @returns {boolean} `true` if the feature is supported, otherwise `false`.
+     */
+    hasAsyncFeature(feature: AsyncFeatureBits): boolean;
+    /**
+     * Determines if a function call should produce a stream.
+     *
+     * The logic is as follows:
+     * 1. It first checks if the function is generally capable of streaming (`this.stream`).
+     * 2. If it is, it then checks if a `stream` parameter is formally declared in the function's `params` definition.
+     * 3. If both are true, the method returns the value of the `stream` property from the runtime `params` object.
+     * Otherwise, it returns the function's static `stream` capability.
+     *
+     * @param {any} params - The runtime parameters passed to the function call.
+     * @returns {boolean | undefined} `true` if the call should be streamed, `false` or `undefined` otherwise.
+     */
+    isStream(params: any): boolean | undefined;
+}
+/**
+ * Defines the schema for `ToolFunc` properties, used by `AdvancePropertyManager`.
+ * This controls how properties are assigned and exported.
+ * @internal
+ */
+declare const ToolFuncSchema: {
+    name: {
+        type: string;
+    };
+    description: {
+        type: string;
+    };
+    title: {
+        type: string;
+    };
+    func: {
+        type: string;
+        assign(value: Function | string, dest: ToolFunc, src?: ToolFunc, name?: string, options?: any): string | Function;
+    };
+    params: {
+        type: string;
+    };
+    result: {
+        type: string;
+    };
+    setup: {
+        type: string;
+    };
+    depends: {
+        type: string;
+        exported: boolean;
+    };
+    tags: {
+        type: string[];
+    };
+    isApi: {
+        type: string;
+    };
+    stream: {
+        type: string;
+    };
+    asyncFeatures: {
+        type: string;
+    };
+    alias: {
+        type: string[];
+    };
+};
+/**
+ * A unique symbol used to attach metadata to a function object.
+ * @internal
+ */
+declare const FuncMetaSymbol: unique symbol;
+/**
+ * Attaches metadata to a function or `ToolFunc` object.
+ *
+ * This utility merges the provided metadata with any existing metadata on the target.
+ *
+ * @param {Function | ToolFunc} fn - The function or `ToolFunc` instance to which metadata will be added.
+ * @param {any} meta - The metadata object to attach. The operation is skipped if this is not a non-null object.
+ * @param {boolean} [ignoreExists=true] - If `true`, new metadata overwrites existing keys. If `false`, it merges deeply, preserving existing values.
+ * @returns {Function | ToolFunc | undefined} The updated function or `ToolFunc` with metadata, or `undefined` if the operation was skipped.
+ */
+declare function funcWithMeta(fn: Function | ToolFunc, meta: any, ignoreExists?: boolean): Function | ToolFunc | undefined;
+/**
+ * Retrieves metadata associated with a function or `ToolFunc` instance.
+ *
+ * @param {Function | ToolFunc} fn - The function or `ToolFunc` instance from which to retrieve metadata.
+ * @returns {any} The metadata as a plain object, or `undefined` if no metadata is found.
+ */
+declare function funcGetMeta(fn: Function | ToolFunc): any;
+
+/**
+ * A constant representing a passing score, likely used for similarity or relevance thresholds.
+ */
+declare const PASSING_SCORE = 0.618;
+/**
+ * A tuple of supported action names for remote tool interactions.
+ */
+declare const ActionNames: readonly ["get", "post", "put", "delete", "patch", "list", "res"];
+/**
+ * Represents a valid action name for a remote tool, derived from the `ActionNames` tuple.
+ */
+type ActionName = typeof ActionNames[number];
+/**
+ * Defines the signature for a function that processes an AI model's name,
+ * typically for matching or validation purposes.
+ * @param name - The model name string.
+ * @returns A string, a RegExp execution array, or undefined if no match is found.
+ */
+type AIModelNameRuleFn = (name: string) => string | RegExpExecArray | undefined;
+/**
+ * Defines a single rule for matching an AI model name. It can be a simple string,
+ * a regular expression, or a custom function.
+ */
+type AIModelNameRule = string | RegExp | AIModelNameRuleFn;
+/**
+ * Represents a collection of one or more AI model name matching rules.
+ */
+type AIModelNameRules = AIModelNameRule | AIModelNameRule[];
+/**
+ * A schema object defining properties common to all remote tool functions.
+ * This is used by `AdvancePropertyManager` to define how these properties are handled.
+ * @internal
+ */
+declare const RemoteToolFuncSchema: {
+    /**
+     * The action for the remote call. This is primarily interpreted as an RPC method name.
+     * For HTTP transports, it defaults to being sent as a custom RPC method name (e.g., via POST).
+     * Only specific RESTful server implementations might map certain 'action' values (like 'get', 'delete')
+     * to corresponding HTTP methods. Defaults to 'post'.
+     */
+    action: {
+        type: string;
+        assign(value: ActionName, dest: any, src?: any, name?: string, options?: any): "get" | "post" | "put" | "delete" | "patch" | "list" | "res";
+    };
+    /**
+     * Optional fetch options, primarily for use with HTTP-based transports.
+     * @deprecated Use `transport` instead.
+     */
+    fetchOptions: {
+        type: string;
+    };
+    /**
+     * If true, allows the function's body to be exported to the client for local execution.
+     * This is a server-side setting.
+     */
+    allowExportFunc: {
+        type: string;
+    };
+};
+/**
+ * Base interface for a remote function's configuration, extending `BaseFuncItem`
+ * with properties required for remote execution.
+ */
+interface RemoteFuncItem extends BaseFuncItem {
+    /**
+     * The root endpoint for the remote service.
+     * @type {string}
+     * @deprecated Use `transport` instead.
+     */
+    apiRoot?: string;
+    /**
+     * The action to be used for the remote call. This typically represents an RPC method name.
+     * Only for RESTful HTTP transports, it might be mapped to a standard HTTP method (e.g., GET, POST)
+     * @type {ActionName}
+     */
+    action?: ActionName;
+    /**
+     * Options to be passed to the underlying `fetch` call in an HTTP transport.
+     * @type {any}
+     * @deprecated Use `transport` instead.
+     */
+    fetchOptions?: any;
+}
+
+declare class Deque<T = any> extends Array<T> {
+    private _capacity;
+    private _length;
+    private _front;
+    private _disableAutoResize?;
+    constructor(capacity?: number | T[], disableAutoResize?: boolean);
+    push(item: T): number;
+    unshift(item: T): number;
+    /**
+     * Removes and returns the element at the back of the deque.
+     *
+     * @param skipNull When `true`, skips trailing `null`/`undefined` values until a valid element is found or all elements are processed.
+     * @returns The removed element, or `undefined` if the deque is empty or all elements are skipped.
+     *
+     * @example
+     * // Normal pop without skipping
+     * const deque = new Deque([1, 2, 3]);
+     * deque.pop(); // 3
+     *
+     * @example
+     * // Skipping null values
+     * const nullDeque = new Deque([null, 4, null]);
+     * nullDeque.pop(true); // 4
+     * nullDeque.pop(true); // undefined (skipped remaining nulls)
+     *
+     * @example
+     * // Mixed elements with skip
+     * const mixedDeque = new Deque([5, null, 6, null]);
+     * mixedDeque.pop(true); // 6
+     * mixedDeque.pop(false); // null (explicitly not skipping)
+     */
+    pop(skipNull?: boolean): T | undefined;
+    /**
+     * Removes and returns the element at the front of the deque.
+     *
+     * @param skipNull When `true`, skips leading `null`/`undefined` values until a valid element is found or all elements are processed.
+     * @returns The removed element, or `undefined` if the deque is empty or all elements are skipped.
+     *
+     * @example
+     * // Normal shift without skipping
+     * const deque = new Deque([1, 2, 3]);
+     * deque.shift(); // 1
+     *
+     * @example
+     * // Skipping null values
+     * const nullDeque = new Deque([null, 4, null]);
+     * nullDeque.shift(true); // 4
+     * nullDeque.shift(true); // undefined (skipped remaining nulls)
+     *
+     * @example
+     * // Mixed elements with skip
+     * const mixedDeque = new Deque([null, 5, null, 6]);
+     * mixedDeque.shift(true); // 5
+     * mixedDeque.shift(false); // null (explicitly not skipping)
+     */
+    shift(skipNull?: boolean): T | undefined;
+    /**
+     * Gets the number of elements in the deque.
+     *
+     * @returns The current count of elements in the deque.
+     *
+     * @example
+     * const deque = new Deque([1, 2, 3]);
+     * console.log(deque.size); // 3
+     *
+     * @important
+     * Do NOT use the native `Array.length` property. The Deque implementation uses a circular buffer with capacity management, so the native `length` reflects the underlying array capacity, not the actual element count. Always use `size` to get the correct element count.
+     */
+    get size(): number;
+    get(index: number): T | undefined;
+    peekBack(): T | undefined;
+    peekFront(): T | undefined;
+    clear(): void;
+    isEmpty(): boolean;
+    /**
+     * Removes the element at the specified index.
+     * @param index Logical index position (0 represents the front, length-1 represents the back)
+     * @returns The removed element
+     */
+    removeAt(index: number): T | undefined;
+    private checkCapacity;
+    private resizeTo;
+}
+
+declare const DefaultAsyncSemaphoreCapacity = 32;
+type SemaphoreIsReadyFuncType = () => Promise<boolean> | boolean;
+interface BinarySemaphoreOptions {
+    initFn?: () => any;
+    pauseFn?: () => void;
+    resumeFn?: () => void;
+    capacity?: number;
+}
+interface BinarySemaphoreAcquireOptions {
+    signal?: AbortSignal;
+    [n: string]: any;
+}
+interface BinarySemaphoreReleaseOptions {
+    token?: any;
+    [n: string]: any;
+}
+interface BinarySemaphoreReleaserFunc extends BinarySemaphoreReleaseOptions {
+    (): void;
+}
+interface SemaphoreOptions extends BinarySemaphoreOptions {
+    maxConcurrency?: number;
+    isReadyFn?: SemaphoreIsReadyFuncType;
+}
+interface SemaphoreTaskItem extends BinarySemaphoreAcquireOptions {
+    resolve: (value: any) => void;
+    reject: (reason?: any) => void;
+    token?: any;
+}
+/**
+ * A binary semaphore implementation for managing concurrency in asynchronous operations.
+ * Unlike a general semaphore, a binary semaphore allows only one caller to acquire the semaphore at a time.
+ * It provides methods to acquire, release, and manage waiting tasks efficiently.
+ *
+ * Example usage:
+ *
+ * ```typescript
+ * const semaphore = new Semaphore(5); // Allows 5 concurrent operations.
+ *
+ * const semaphore = new Semaphore(
+ *   4, // Allow 4 concurrent async calls
+ *   {
+ *     capacity: 100 // Prealloc space for 100 tokens
+ *   }
+ * );
+ *
+ * async function fetchData(x) {
+ *   await semaphore.acquire()
+ *   try {
+ *     console.log(semaphore.pendingCount + ' calls to fetch are waiting')
+ *     // ... do some async stuff with x
+ *   } finally {
+ *     semaphore.release();
+ *   }
+ * }
+ *
+ * const data = await Promise.all(array.map(fetchData));
+ * ```
+ */
+declare class BinarySemaphore {
+    readonly waiting: Deque<SemaphoreTaskItem | undefined>;
+    protected free: any;
+    protected emitter: EventEmitter;
+    protected useDefaultTokens: boolean;
+    protected pauseFn?: () => void;
+    protected resumeFn?: () => void;
+    protected initTokenFn: (token?: any) => void;
+    protected paused: boolean;
+    protected _activeCount: number;
+    /**
+     * Creates a binary semaphore object for managing concurrency in asynchronous operations.
+     *
+     * @param options.initFn Function that is used to initialize the tokens used to manage the semaphore. The default is () => '1'.
+     * @param options.pauseFn An optional fuction that is called to opportunistically request pausing the the incoming stream of data,
+     *    instead of piling up waiting promises and possibly running out of memory. See examples/pausing.js.
+     * @param options.resumeFn An optional function that is called when there is room again to accept new waiters on the semaphore.
+     *    This function must be declared if a pauseFn is declared.
+     * @param options.capacity Sets the size of the preallocated waiting list inside the semaphore.
+     *    This is typically used by high performance where the developer can make a rough estimate of the number of concurrent users of a semaphore.
+     *
+     * ```ts
+     * const readline = require('readline');
+     *
+     * const rl = readline.createInterface({
+     * 	input: process.stdin,
+     * 	output: process.stdout,
+     * 	terminal: false
+     * });
+     *
+     * function pause() {
+     * 	console.log('Pausing the stream');
+     * 	rl.pause();
+     * }
+     *
+     * function resume() {
+     * 	console.log('Resuming the stream');
+     * 	rl.resume();
+     * }
+     *
+     * const s = new BinarySemaphore({ pauseFn: pause, resumeFn: resume });
+     *
+     * async function parse(line) {
+     * 	await s.acquire();
+     *
+     * 	console.log(line);
+     *
+     * 	s.release();
+     * }
+     *
+     * rl.on('line', line => {
+     * 	parse(line).catch(console.error);
+     * });
+     * ```
+     *
+     */
+    constructor(options?: BinarySemaphoreOptions);
+    initFree(options?: BinarySemaphoreOptions): void;
+    onReleased(options?: BinarySemaphoreReleaseOptions): void;
+    init(options: BinarySemaphoreOptions): void;
+    _newReleaser(options?: BinarySemaphoreReleaseOptions): BinarySemaphoreReleaserFunc;
+    _dispatchTask(task: SemaphoreTaskItem, options?: BinarySemaphoreReleaseOptions): void;
+    lock(options?: BinarySemaphoreAcquireOptions): any;
+    unlock(token?: any): void;
+    /**
+     * Attempt to acquire a token from the semaphore, if one is available immediately. Otherwise, return undefined.
+     *
+     * @return Returns a token if the semaphore is not full; otherwise, returns `undefined`.
+     */
+    tryAcquire(options?: BinarySemaphoreAcquireOptions): any | undefined;
+    /**
+     * Acquire a token from the semaphore, thus decrement the number of available execution slots. If initFn is not used then the return value of the function can be discarded.
+     * @param options.signal An optional AbortSignal to abort the acquisition process. If aborted, the promise will reject with an AbortError.
+     * @return A promise that resolves to a release function when a token is acquired. If the semaphore is full, the caller will be added to a waiting queue.
+     */
+    acquire(options?: BinarySemaphoreAcquireOptions): Promise<BinarySemaphoreReleaserFunc>;
+    /**
+     * Releases the semaphore, incrementing the number of free execution slots. If there are tasks in the waiting queue, the next task will be dispatched.
+     * @param options.token Optional token returned by `acquire()` when using a custom `initFn`. If provided, it will be used to unlock the semaphore.
+     */
+    release(options?: BinarySemaphoreReleaseOptions): void;
+    /**
+     * Drains the semaphore and returns all the initialized tokens in an array. Draining is an ideal way to ensure there are no pending async tasks, for example before a process will terminate.
+     */
+    drain(): Promise<any[]>;
+    abort(reason?: any): void;
+    /**
+     * Get the total count of all active operations.
+     *
+     * This method returns the number of operations that are either:
+     * - Waiting in the queue to acquire the semaphore (`pendingCount`).
+     * - Already acquired the semaphore but have not yet released it.
+     *
+     * @returns {number} The total count of active operations, including both waiting and ongoing tasks.
+     */
+    get activeCount(): number;
+    /**
+     * Get the number of callers waiting on the semaphore, i.e. the number of pending promises.
+     *
+     * @returns The number of waiters in the waiting list.
+     */
+    get pendingCount(): number;
+}
+/**
+ * A Semaphore implementation for managing concurrency in asynchronous operations.
+ * Semaphores allow a fixed number of resources to be accessed concurrently.
+ * This class extends BinarySemaphore and adds support for a maximum concurrency limit and an optional readiness check.
+ *
+ * Example usage:
+ *
+ * ```typescript
+ * const semaphore = new Semaphore(5); // Allows 5 concurrent operations.
+ *
+ * const semaphore = new Semaphore(
+ *   4, // Allow 4 concurrent async calls
+ *   {
+ *     capacity: 100, // Prealloc space for 100 tokens
+ *     isReadyFn: async () => {
+ *       // Check if the system is ready to handle more requests
+ *       return true;
+ *     },
+ *     pauseFn: () => {
+ *       console.log('Pausing the stream');
+ *     },
+ *     resumeFn: () => {
+ *       console.log('Resuming the stream');
+ *     }
+ *   }
+ * );
+ *
+ * async function fetchData(x) {
+ *   await semaphore.acquire()
+ *   try {
+ *     console.log(semaphore.pendingCount() + ' calls to fetch are waiting')
+ *     // ... do some async stuff with x
+ *   } finally {
+ *     semaphore.release();
+ *   }
+ * }
+ *
+ * const data = await Promise.all(array.map(fetchData));
+ * ```
+ */
+declare class Semaphore extends BinarySemaphore {
+    readonly maxConcurrency: number;
+    protected free: Deque<any>;
+    private isReady?;
+    /**
+     * Creates a semaphore object. The first argument is the maximum concurrently number and the second argument is optional.
+     *
+     * @param maxConcurrency The maximum number of callers allowed to acquire the semaphore concurrently.
+     * @param options.initFn Function that is used to initialize the tokens used to manage the semaphore. The default is () => '1'.
+     * @param options.pauseFn An optional function that is called to opportunistically request pausing the incoming stream of data,
+     *    instead of piling up waiting promises and possibly running out of memory. See examples/pausing.js.
+     * @param options.resumeFn An optional function that is called when there is room again to accept new waiters on the semaphore.
+     *    This function must be declared if a pauseFn is declared.
+     * @param options.capacity Sets the size of the preallocated waiting list inside the semaphore.
+     *    This is typically used by high performance where the developer can make a rough estimate of the number of concurrent users of a semaphore.
+     * @param options.isReadyFn An optional function that returns a boolean or a promise that resolves to a boolean indicating whether the semaphore is ready to accept new requests.
+     */
+    constructor(maxConcurrency: number | SemaphoreOptions, options?: SemaphoreOptions);
+    initFree(options: SemaphoreOptions): void;
+    tryAcquire(options?: BinarySemaphoreAcquireOptions): Promise<any | undefined> | any | undefined;
+    unlock(token?: any): void;
+    lock(options?: BinarySemaphoreAcquireOptions): any;
+    drain(): Promise<any[]>;
+}
+/**
+ * Creates a rate limiter function that blocks with a promise whenever the rate limit is hit and resolves the promise once the call rate is within the limit set by rps. The second argument is optional.
+ *
+ * @param rps
+ * @param options.timeUnit The `timeUnit` is an optional argument setting the width of the rate limiting window in milliseconds.
+ *    The default `timeUnit` is 1000 ms, therefore making the rps argument act as requests per second limit.
+ * @param options.uniformDistribution  The `uniformDistribution` argument enforces a discrete uniform distribution over time,
+ *    instead of the default that allows hitting the function rps time and then pausing for timeWindow milliseconds. Setting
+ *    the `uniformDistribution` option is mainly useful in a situation where the flow of rate limit function calls is continuous
+ *    and and occuring faster than timeUnit (e.g. reading a file) and not enabling it would cause the maximum number of calls to
+ *    resolve immediately (thus exhaust the limit immediately) and therefore the next bunch calls would need to wait for timeWindow
+ *    milliseconds. However if the flow is sparse then this option may make the code run slower with no advantages.
+ *
+ * Examples:
+ *
+ * ```ts
+ * async function f() {
+ *   const lim = RateLimit(5); // rps
+ *
+ *   for (let i = 0; i < n; i++) {
+ *     await lim();
+ *     // ... do something async
+ *   }
+ * }
+ * ```
+ *
+ *
+ */
+declare function RateLimit(rps: number, { timeUnit, uniformDistribution, }?: {
+    timeUnit?: number;
+    uniformDistribution?: boolean;
+}): () => Promise<void>;
+
+declare const ToolAsyncMultiTaskBit = 0;
+declare const ToolAsyncCancelableBit = 1;
+declare const ToolAsyncPriorityBit = 2;
+declare enum AsyncFeatureBits {
+    MultiTask = 0,
+    Cancelable = 1,
+    Priority = 2
+}
+declare enum AsyncFeatures {
+    MultiTask = 1,// B0001
+    Cancelable = 2,// B010
+    Priority = 4
+}
+type AsyncTaskId = string | number;
+interface CancelableAbilityOptions extends AbilityOptions {
+    asyncFeatures?: AsyncFeatures;
+    maxTaskConcurrency?: number;
+    isReadyFn?: SemaphoreIsReadyFuncType;
+}
+declare class TaskAbortController extends AbortController {
+    id?: AsyncTaskId;
+    timeoutId?: any;
+    streamController?: ReadableStreamDefaultController;
+    parent: CancelableAbility;
+    constructor(parent: CancelableAbility);
+    abort(reason?: string | Error | CommonError, data?: any): void;
+    throwRejected(alreadyRejected?: boolean): true | undefined;
+}
+interface TaskAbortControllers {
+    [k: AsyncTaskId]: TaskAbortController | undefined;
+}
+interface TaskPromise<T = any> extends Promise<T> {
+    task?: TaskAbortController;
+}
+declare interface CancelableAbility {
+    _asyncFeatures?: number;
+    _maxTaskConcurrency: number | undefined;
+    _isReadyFn?: SemaphoreIsReadyFuncType;
+    [name: string]: any;
+}
+declare class CancelableAbility {
+    generateAsyncTaskId: (taskId?: AsyncTaskId, aborters?: TaskAbortControllers) => AsyncTaskId;
+    cleanMultiTaskAborter: (id: AsyncTaskId, aborters: TaskAbortControllers) => void;
+    __task_aborter: TaskAbortController | TaskAbortControllers | undefined;
+    __task_semaphore: Semaphore | undefined;
+    get maxTaskConcurrency(): number | undefined;
+    get semaphore(): Semaphore | undefined;
+    getSemaphore(isReadyFn?: SemaphoreIsReadyFuncType | undefined): Semaphore | undefined;
+    static hasAsyncFeature(feature: AsyncFeatureBits): boolean;
+    hasAsyncFeature(feature: AsyncFeatureBits): boolean;
+    isAborted(taskId?: AsyncTaskId): boolean;
+    getRunningTask(taskId?: AsyncTaskId): TaskAbortController | undefined;
+    getRunningTaskCount(): number;
+    _generateAsyncTaskId(taskId?: AsyncTaskId, aborters?: TaskAbortControllers): AsyncTaskId;
+    $generateAsyncTaskId(taskId?: AsyncTaskId, aborters?: TaskAbortControllers): AsyncTaskId | undefined;
+    createAborter(params?: any, taskId?: AsyncTaskId, raiseError?: boolean): TaskAbortController;
+    $cleanMultiTaskAborter(id: AsyncTaskId, aborters: TaskAbortControllers): void;
+    cleanTaskAborter(aborter: TaskAbortController): void;
+    _cleanMultiTaskAborter(id: AsyncTaskId, aborters: TaskAbortControllers): void;
+    createTaskPromise<Output = any>(runTask: (params: Record<string, any>, aborter: TaskAbortController) => Promise<Output>, params: Record<string, any>, options?: {
+        taskId?: AsyncTaskId;
+        raiseError?: boolean;
+    }): TaskPromise<Output>;
+    runAsyncCancelableTask<Output = any>(params: Record<string, any> | undefined, runTask: (params: Record<string, any>, aborter: TaskAbortController) => Promise<Output>, options?: {
+        taskId?: AsyncTaskId;
+        raiseError?: boolean;
+        isReadyFn?: SemaphoreIsReadyFuncType;
+    }): TaskPromise<Output>;
+    abort(reason?: string, data?: any): void;
+}
+declare const makeToolFuncCancelable: <T extends Function | (new (...args: any[]) => any)>(targetClass?: T | undefined, options?: AbilityOptions) => T & typeof CancelableAbility & (T extends new (...args: any[]) => any ? InstanceType<T> : T) & CancelableAbility;
+
+declare global {
+	// eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- It has to be an `interface` so that it can be merged.
+	interface SymbolConstructor {
+		readonly observable: symbol;
+	}
+}
+
+/**
+ * @file Defines common types used across transports.
+ */
+
+/**
+ * The generic handler for a remote procedure call (RPC) method.
+ * It receives the parameters and returns the result.
+ * @param params - The parameters for the RPC method.
+ * @param context - Optional context, like the raw request object from the underlying framework.
+ * @returns The result of the RPC method.
+ */
+type RpcMethodHandler = (params: any, context?: any) => Promise<any> | any;
+interface IToolTransport {
+    Tools: typeof ToolFunc;
+    /**
+     * The root endpoint for the remote service.
+     * For HTTP, this is a URL. For IPC, it could be a channel name.
+     */
+    apiRoot: string;
+    /**
+     * Additional options for the transport start or fetch, passed by mount.
+     */
+    options?: any;
+    mount(Tools: typeof ToolFunc, apiRoot?: string, options?: any): any | Promise<any>;
+    [name: string]: any;
+}
+declare abstract class ToolTransport implements IToolTransport {
+    apiRoot: string;
+    Tools: typeof ToolFunc;
+    options?: any;
+    setApiRoot(apiRoot: string): void;
+    mount(Tools: typeof ToolFunc, apiRoot?: string, options?: any): any;
+    abstract _mount(Tools: typeof ToolFunc, apiRoot: string, options?: any): any | Promise<any>;
+}
+
+/**
+ * Defines the public interface for a client-side transport,
+ * responsible for communicating with a ServerTransport.
+ */
+interface IClientToolTransport extends IToolTransport {
+    /**
+     * Connects to the server's discovery endpoint to get the list of available tools.
+     * @returns A promise that resolves to a map of tool function metadata.
+     */
+    loadApis(): Promise<Funcs>;
+    mount(clientTools: typeof ClientTools, apiPrefix?: string, options?: any): any | Promise<any>;
+    /**
+     * Fetches data from the server.
+     * @param name The name of the tool function to fetch.
+     * @param args The object parameters to pass to the server.
+     * @param act The action to perform on the server.
+     * @param subName The name of the sub-resource to fetch.
+     * @param options Additional options for the fetch call.
+     * @returns A promise that resolves with the fetched data.
+     */
+    fetch(name: string, args?: any, act?: ActionName | string, subName?: any, options?: any): any | Promise<any>;
+    [name: string]: any;
+}
+/**
+ * A concrete client transport implementation that uses the browser/node `fetch` API.
+ */
+declare abstract class ClientToolTransport extends ToolTransport implements IClientToolTransport {
+    apiRoot: string;
+    Tools: typeof ClientTools;
+    constructor(apiRoot: string);
+    _mount(clientTools: typeof ClientTools, apiPrefix: string, options?: any): Promise<Funcs>;
+    /**
+     * Connects to the server's discovery endpoint to get the list of available tools.
+     * @returns A promise that resolves to a map of tool function metadata.
+     */
+    loadApis(): Promise<Funcs>;
+    fetch(name: string, args?: any, act?: ActionName | string, subName?: any, fetchOptions?: any): Promise<any>;
+    abstract _fetch(name: string, args?: any, act?: ActionName | string, subName?: any, fetchOptions?: any): any | Promise<any>;
+    abstract toObject(res: any, args?: any): any | Promise<any>;
+}
+
+/**
+ * Alias for `RemoteFuncItem` on the client side.
+ */
+interface ClientFuncItem extends RemoteFuncItem {
+}
+/**
+ * Declaration merging to extend the `ClientTools` class with `ClientFuncItem` properties.
+ */
+declare interface ClientTools extends ClientFuncItem {
+    [name: string]: any;
+}
+/**
+ * Represents a client-side proxy for a remote tool function.
+ *
+ * A `ClientTools` instance is a `ToolFunc` that, when executed, does not run
+ * local code. Instead, it serializes the parameters and uses an injected
+ * transport layer (`IClientToolTransport`) to make a remote procedure call
+ * to its corresponding `ServerTools` counterpart.
+ *
+ * These tools are typically created dynamically by loading definitions from a server.
+ */
+declare class ClientTools extends ToolFunc {
+    static action?: ActionName | string;
+    private static _transport;
+    /**
+     * @deprecated This property is now mainly for informational purposes.
+     * The actual endpoint is managed by the transport.
+     */
+    static get apiRoot(): string;
+    /**
+     * Injects the client-side transport implementation. This is a crucial step
+     * to enable communication with the server.
+     * @param {IClientToolTransport} transport - The transport instance to use for all client-server communication.
+     */
+    static setTransport(transport: IClientToolTransport): void;
+    static get transport(): IClientToolTransport;
+    /**
+     * Loads tool definitions from the remote server via the configured transport.
+     * This method populates the local `ToolFunc` registry with `ClientTools` stubs.
+     */
+    static loadFrom(items?: Funcs): Promise<Funcs>;
+    /**
+     * Synchronously loads tool definitions from a provided object, registering
+     * each one as a `ClientTools` instance.
+     * @param items - A map of tool function metadata, typically from a server.
+     */
+    static loadFromSync(items: Funcs): void;
+    static fetch(name: string, objParam?: any, ...args: any[]): Promise<any>;
+    /**
+     * @deprecated This property is now mainly for informational purposes.
+     * The actual endpoint is managed by the transport.
+     */
+    get apiRoot(): string;
+    fetch(objParam?: any, act?: ActionName, subName?: any): Promise<any>;
+    /**
+     * The core implementation for a client-side tool. When a `ClientTools` instance
+     * is "run", this `func` method is executed. It delegates the call to the
+     * configured transport, which handles the network communication.
+     *
+     * @param objParam - The parameters to send to the remote tool.
+     * @param objParam.stream [boolean] - the optional stream flag. if true, the tool will return a stream(ReadableStream).
+     * @returns The result from the remote tool.
+     */
+    func(objParam: any): Promise<any>;
+}
+/**
+ * The schema definition for `ClientTools` properties.
+ * @internal
+ */
+declare const ClientToolFuncSchema: {
+    action: {
+        type: string;
+        assign(value: ActionName, dest: any, src?: any, name?: string, options?: any): "get" | "post" | "put" | "delete" | "patch" | "list" | "res";
+    };
+    fetchOptions: {
+        type: string;
+    };
+    allowExportFunc: {
+        type: string;
+    };
+};
+
+/**
+ * Defines the structure for parameters passed to a `ServerTools` function.
+ * By convention, it includes optional `_req` and `_res` properties for direct
+ * access to the underlying transport's request and response objects (e.g., from Node.js http).
+ */
+interface ServerFuncParams {
+    /**
+     * The underlying request object from the transport layer (e.g., `IncomingMessage`).
+     * @type {any}
+     */
+    _req?: any;
+    /**
+     * The underlying response or reply object from the transport layer (e.g., `ServerResponse`).
+     * @type {any}
+     */
+    _res?: any;
+    [name: string]: any;
+}
+/**
+ * Configuration interface for a `ServerTools` item.
+ * Extends `RemoteFuncItem` with server-specific options.
+ */
+interface ServerFuncItem extends RemoteFuncItem {
+    /**
+     * If set to true, the body of the function (`func`) will be serialized and sent
+     * to the client when tools are loaded. This allows the client to execute the
+     * function locally instead of making a remote call. Defaults to false.
+     * @type {boolean}
+     */
+    allowExportFunc?: boolean;
+}
+/**
+ * Declaration merging to extend the `ServerTools` class with `ServerFuncItem` properties.
+ */
+declare interface ServerTools extends ServerFuncItem {
+    [name: string]: any;
+}
+/**
+ * Represents a function that runs on a server and can be exposed to clients.
+ *
+ * `ServerTools` extends `ToolFunc` by adding logic for serialization and handling
+ * server-side execution contexts. It is designed to work with a transport layer
+ * (see `transports`) to expose its registered functions over a network.
+ */
+declare class ServerTools extends ToolFunc {
+    private static _apiRoot?;
+    /**
+     * The conventional root path for the API endpoint.
+     */
+    static get apiRoot(): string | undefined;
+    static setApiRoot(v: string): void;
+    /**
+     * Serializes all registered `ServerTools` instances into a JSON object.
+     * This method is typically called by a transport's discovery endpoint.
+     *
+     * It filters for tools that are instances of `ServerTools` or marked as `isApi`.
+     * It omits the `func` body from the output unless `allowExportFunc` is true.
+     *
+     * @returns A map of serializable tool definitions.
+     */
+    static toJSON(): {
+        [name: string]: ServerTools;
+    };
+    /**
+     * Overrides the base `run` method to inject transport-specific context.
+     * If a `context` object containing `req` and `reply` is provided, these are
+     * added to the parameters as `_req` and `_res` before execution.
+     *
+     * @param {ServerFuncParams} params - The parameters for the function.
+     * @param {{ req: any, reply: any }} [context] - The transport-level context.
+     * @returns The result of the function execution.
+     */
+    run(params: ServerFuncParams, context?: {
+        req: any;
+        reply: any;
+    }): Promise<any>;
+    /**
+     * Placeholder for the actual server-side function implementation.
+     * This method is intended to be defined when a `ServerTools` instance is created.
+     * @param params - The parameters for the function.
+     * @returns The result of the function.
+     */
+    func(params: ServerFuncParams): Promise<any> | any;
+}
+/**
+ * The schema definition for `ServerTools` properties.
+ * @internal
+ */
+declare const ServerToolFuncSchema: {
+    action: {
+        type: string;
+        assign(value: ActionName, dest: any, src?: any, name?: string, options?: any): "get" | "post" | "put" | "delete" | "patch" | "list" | "res";
+    };
+    fetchOptions: {
+        type: string;
+    };
+    allowExportFunc: {
+        type: string;
+    };
+};
+
+declare class EventToolFunc extends ToolFunc {
+    _emitter: EventEmitter;
+    description: string;
+    result: string;
+    get emitter(): EventEmitter;
+    func(): EventEmitter;
+}
+declare const event: EventToolFunc;
+
+declare const SecondaryCache: typeof Cache;
+declare function _lrucache(this: ToolFunc, { key, value, options }?: {
+    key?: string;
+    value?: any;
+    options?: ICacheOptions | number;
+}): Cache;
+declare function createLRUCache(name: string, options?: ICacheOptions | number): ToolFunc;
+declare const lrucache: ToolFunc;
+
+interface RpcMethodsClientFuncParams {
+    act?: string;
+    [name: string]: any;
+}
+declare class RpcMethodsClientTool extends ClientTools {
+    fetch(options: RpcMethodsClientFuncParams, action: ActionName, subName?: any): Promise<any>;
+    _func(action: ActionName, options: RpcMethodsClientFuncParams): Promise<any>;
+    func(options: RpcMethodsClientFuncParams): Promise<any>;
+    assignMethods(methods: string[]): void;
+}
+
+interface ResClientFuncParams extends RpcMethodsClientFuncParams {
+    id?: string | number;
+}
+interface ResClientTools {
+    get?({ id }: ResClientFuncParams): any;
+    post?(options: ResClientFuncParams): any;
+    put?({ id }: ResClientFuncParams): any;
+    delete?({ id }: ResClientFuncParams): any;
+    list?(options?: ResClientFuncParams): any;
+}
+declare class ResClientTools extends RpcMethodsClientTool {
+    fetch(options: ResClientFuncParams, action: ActionName): Promise<any>;
+}
+
+type PubSubCtx<T = any> = {
+    event: string;
+    id?: string;
+    ts?: number;
+    from?: string;
+    meta?: any;
+};
+
+/**
+ * Represents the client-side stream for a PubSub connection.
+ *
+ * This interface abstracts the underlying connection object (like an `EventSource`
+ * or `WebSocket` client) into a standardized event-based stream. It provides
+ * methods for listening to events, sending messages (for bidirectional transports),
+ * and managing the connection state.
+ */
+interface PubSubClientStream {
+    /**
+     * The protocol being used for this stream (e.g., 'sse', 'ws', 'ipc').
+     */
+    protocol: 'sse' | 'ws' | 'ipc' | string;
+    /**
+     * Optional. Represents the state of the connection.
+     * This is provided for compatibility with the `EventSource.readyState`
+     * and `WebSocket.readyState` properties.
+     * (e.g., 0 for connecting, 1 for open, 2 for closed).
+     */
+    readyState?: number;
+    /**
+     * Registers a listener for a specific event from the server.
+     * @param event The name of the event to listen for.
+     * @param listener The callback function to execute when the event is received.
+     *   It receives the event data and an optional context object.
+     */
+    on: (event: string, listener: (data: any, ctx?: PubSubCtx) => void) => any;
+    /**
+     * Removes a previously registered event listener.
+     * @param event The name of the event.
+     * @param listener The listener function to remove.
+     */
+    off: (event: string, listener: (data: any, ctx?: PubSubCtx) => void) => void;
+    /**
+     * Closes the connection stream.
+     */
+    close: () => void;
+    /**
+     * Optional. Sends a message from the client to the server.
+     * This method is only available for bidirectional transports like WebSockets or IPC.
+     * It is not supported by unidirectional transports like Server-Sent Events (SSE).
+     * @param event The name of the event to send.
+     * @param data The payload for the event.
+     * @param ctx Optional context for the PubSub operation.
+     */
+    send?: (event: string, data: any, ctx?: PubSubCtx) => void;
+    /**
+     * Optional alias for the `on` method for compatibility with the
+     * standard `EventTarget` interface.
+     */
+    addEventListener?: PubSubClientStream['on'];
+    /**
+     * Optional alias for the `off` method for compatibility with the
+     * standard `EventTarget` interface.
+     */
+    removeEventListener?: PubSubClientStream['off'];
+}
+/**
+ * Defines the interface for a client-side PubSub transport.
+ *
+ * This abstraction is responsible for creating and managing the connection
+ * stream (`PubSubClientStream`) to the server.
+ */
+interface IPubSubClientTransport {
+    /**
+     * Establishes a connection to a server endpoint.
+     * @param url The URL of the server's PubSub endpoint.
+     * @param params Optional parameters for the connection, which might include
+     *   things like authentication tokens, initial subscription topics, or a client ID.
+     * @returns A `PubSubClientStream` instance that represents the active connection.
+     */
+    connect: (url: string, params?: Record<string, any>) => PubSubClientStream;
+    /**
+     * Optional. Disconnects a given stream.
+     * While the `close` method exists on the stream itself, placing `disconnect`
+     * on the transport can be semantically clearer in some architectures.
+     * By default, this should delegate to `stream.close()`.
+     * @param stream The stream to disconnect.
+     */
+    disconnect?: (stream: PubSubClientStream) => void;
+}
+
+/**
+ * Represents the unique identifier for a client connected to the PubSub transport.
+ * This ID is used for targeted message publishing.
+ */
+type PubSubClientId = string;
+/**
+ * Represents a client as seen by the transport layer after a subscription is made.
+ * It contains the client's ID and can hold other transport-specific metadata.
+ */
+interface PubSubClient {
+    /**
+     * The unique identifier for this client.
+     * This can be assigned by the client during connection or generated by the server.
+     */
+    clientId?: PubSubClientId;
+    /**
+     * Allows for storing additional, transport-specific properties about the client.
+     */
+    [k: string]: any;
+}
+/**
+ * Represents an active client connection session on the server.
+ * This object provides a standardized way for the `EventServer` to interact
+ * with a connection, regardless of the underlying transport protocol.
+ */
+interface PubSubServerSession {
+    /**
+     * A unique identifier for the session, typically generated by the transport layer upon connection.
+     */
+    id: string;
+    /**
+     * The unique identifier for the client associated with this session.
+     */
+    clientId?: PubSubClientId;
+    /**
+     * The protocol being used for this session (e.g., 'sse', 'ws', 'ipc').
+     */
+    protocol: 'sse' | 'ws' | 'ipc' | string;
+    /**
+     * Sends an event and data to the client associated with this session.
+     * @param event The name of the event to send.
+     * @param data The payload for the event.
+     * @param ctx Optional context for the PubSub operation.
+     */
+    send: (event: string, data: any, ctx?: PubSubCtx) => void;
+    /**
+     * Closes the connection for this session.
+     */
+    close: () => void;
+    /**
+     * A reference to the raw, underlying connection object or handle
+     * (e.g., a Node.js `ServerResponse` for SSE, or a WebSocket instance).
+     * Use with caution as it is transport-specific.
+     */
+    raw?: any;
+}
+/**
+ * Defines the interface for a server-side PubSub transport layer.
+ *
+ * This abstraction allows the `EventServer` to operate independently of the
+ * underlying real-time communication protocol (e.g., SSE, WebSockets, IPC).
+ * An implementation of this interface is responsible for managing client
+ * connections, subscriptions, and message passing.
+ */
+interface IPubSubServerTransport {
+    /**
+     * A unique, human-readable name for the transport (e.g., 'sse', 'websocket').
+     */
+    readonly name: string;
+    /**
+     * The protocol identifier.
+     */
+    readonly protocol: 'sse' | 'ws' | 'ipc' | string;
+    /**
+     * Optional method to mount or register the transport's endpoint with an HTTP
+     * server or framework. This is typically required for protocols like SSE or
+     * WebSockets that need to handle incoming HTTP requests at a specific path.
+     *
+     * @param path The URL path to handle (e.g., '/api/events').
+     * @param options Additional options for mounting, specific to the framework.
+     */
+    mount?: (path: string, options?: Record<string, any>) => void;
+    /**
+     * Establishes a connection with a client and subscribes it to an event stream.
+     *
+     * This method is designed to be generic. Transport-specific details, such as
+     * HTTP request/response objects or connection handles, should be passed
+     * inside the `options` parameter to avoid polluting the abstraction layer.
+     *
+     * @param events Optional array of event names to initially subscribe the client to.
+     * @param options A container for transport-specific parameters.
+     * @param options.req The underlying request object (e.g., `http.IncomingMessage`).
+     * @param options.res The underlying response object (e.g., `http.ServerResponse`).
+     * @param options.clientId An optional ID provided by the client. If not provided,
+     *   the transport should generate one.
+     * @param options.headers HTTP headers from the client request.
+     * @returns A `PubSubClient` object representing the newly connected client.
+     */
+    subscribe: (events?: string[], options?: {
+        req?: any;
+        res?: any;
+        clientId?: PubSubClientId;
+        headers?: Record<string, string>;
+        [k: string]: any;
+    }) => PubSubClient;
+    /**
+     * Publishes an event from the server to connected clients.
+     *
+     * The transport implementation should handle broadcasting to all relevant
+     * clients or targeting specific clients based on the `target` parameter.
+     *
+     * @param event The name of the event to publish.
+     * @param data The payload for the event.
+     * @param target Optional. Specifies the recipient(s) of the event.
+     *   If omitted, the event is typically broadcast to all subscribed clients.
+     * @param target.clientId A single `PubSubClientId` or an array of IDs to
+     *   send the event to.
+     * @param ctx Optional context for the PubSub operation.
+     */
+    publish: (event: string, data: any, target?: {
+        clientId?: PubSubClientId | PubSubClientId[];
+    }, ctx?: PubSubCtx) => void;
+    /**
+     * Registers a callback to be invoked when a new client connection is established
+     * and a session is created.
+     * @param cb The callback function that receives the new `PubSubServerSession`.
+     */
+    onConnection: (cb: (session: PubSubServerSession) => void) => void;
+    /**
+     * Registers a callback to be invoked when a client disconnects.
+     * @param cb The callback function that receives the `PubSubServerSession` of the
+     *   disconnected client.
+     */
+    onDisconnect: (cb: (session: PubSubServerSession) => void) => void;
+    /**
+     * Optional. Registers a callback to handle incoming messages from clients.
+     * This is only necessary for bidirectional transport protocols like WebSockets or IPC.
+     *
+     * @param cb The callback function that receives the session, event name, data, and context.
+     */
+    onMessage?: (cb: (session: PubSubServerSession, event: string, data: any, ctx?: PubSubCtx) => void) => void;
+}
+
+interface EventClientFuncParams {
+    event?: string | string[];
+    data?: any;
+    act?: 'sub' | 'pub' | 'unsub' | 'init';
+    listener?: (...args: any[]) => void;
+}
+declare class EventClient extends ResClientTools {
+    static _pubSubTransport: IPubSubClientTransport | undefined;
+    static setPubSubTransport(t?: IPubSubClientTransport): void;
+    static get pubSubTransport(): IPubSubClientTransport;
+    _stream: PubSubClientStream | undefined;
+    _streamEvents: string[] | undefined;
+    _sseListeners: Record<string, (data: any, ctx?: PubSubCtx) => void>;
+    _forwardEvents: Set<string>;
+    get evtSource(): PubSubClientStream;
+    get active(): boolean;
+    set active(v: boolean);
+    description: string;
+    initEventStream(events?: string | string[]): PubSubClientStream;
+    esListener(evtType: string, data: any, ctx?: PubSubCtx): void;
+    ebListener: (this: Event, ...data: any[]) => Promise<void>;
+    /**
+     * subscribe server sent event(SSE)
+     * @param events
+     */
+    subscribe(events: string | string[]): Promise<any>;
+    /**
+     * unsubscribe server sent event(SSE)
+     * @param events
+     */
+    unsubscribe(events: string | string[]): Promise<any>;
+    /**
+     * forward local event(s) to server
+     *
+     * subscribe these local events to forward/publish to server
+     *
+     * Note: pls backendEventable(ClientTools or EventClient) first
+     * @param events
+     */
+    forwardEvent(events: string | string[]): void;
+    /**
+     * unforward local event(s) to server
+     *
+     * unsubscribe these local events not to forward/publish to server
+     *
+     * Note: pls backendEventable(ClientTools or EventClient) first
+     * @param events
+     */
+    unforwardEvent(events: string | string[]): void;
+    init(events: string | string[]): Promise<any>;
+    close(): void;
+}
+declare const eventClient: EventClient;
+
+interface RpcMethodsServerFuncParams extends ServerFuncParams {
+    act?: string;
+}
+interface RpcMethodsServerTool {
+    methods: string[];
+}
+declare class RpcMethodsServerTool extends ServerTools {
+    static SpecialRpcMethodNames?: string[];
+    params: FuncParams;
+    get SpecialRpcMethodNames(): any;
+    initRpcMethods(methods?: string[]): void;
+    constructor(name: string | Function | FuncItem, options?: FuncItem | any);
+    cast(key: string, value: any): any;
+    getMethodFromParams(params: RpcMethodsServerFuncParams): string | undefined;
+    castParams(params: RpcMethodsServerFuncParams): RpcMethodsServerFuncParams;
+    func(params: RpcMethodsServerFuncParams): any;
+}
+
+interface ResServerFuncParams extends RpcMethodsServerFuncParams {
+    id?: string | number;
+    val?: any;
+}
+interface ResServerTools {
+    get?({ id }: ResServerFuncParams): any;
+    post?(options: ResServerFuncParams): any;
+    put?({ id }: ResServerFuncParams): any;
+    delete?({ id }: ResServerFuncParams): any;
+    list?(options?: ResServerFuncParams): any;
+}
+declare class ResServerTools extends RpcMethodsServerTool {
+    static SpecialRpcMethodNames: any;
+    action: ActionName;
+    params: FuncParams;
+    constructor(name: string | Function | FuncItem, options?: FuncItem | any);
+    getMethodFromParams(params: ResServerFuncParams): any;
+    castParams(params: RpcMethodsServerFuncParams): RpcMethodsServerFuncParams;
+}
+
+interface EventServerFuncParams extends ServerFuncParams {
+    event?: string | string[];
+    data?: any;
+    act?: 'sub' | 'pub' | 'unsub';
+}
+declare class EventServer extends ResServerTools {
+    private static _boundEbListener?;
+    static _pubSubTransport: IPubSubServerTransport | undefined;
+    static setPubSubTransport(t?: IPubSubServerTransport): void;
+    static get pubSubTransport(): IPubSubServerTransport | undefined;
+    description: string;
+    result: string;
+    depends: {
+        "event-bus": EventToolFunc;
+    };
+    get pubSubTransport(): IPubSubServerTransport | undefined;
+    static publish(data: any, event: string, target?: {
+        clientId?: string | string[];
+    }): void | undefined;
+    static ebListener(eventType: string, ...data: any[]): void;
+    static subscribe(req: IncomingMessage, res: ServerResponse, events?: string[], options?: any): PubSubClient | undefined;
+    static alreadyForward(event: string): true | undefined;
+    publishSSE(data: any, event: string): any;
+    subscribeSSE(req: IncomingMessage, res: ServerResponse, events?: string | string[]): any;
+    forward(events: string | string[]): void;
+    unforward(events: string | string[]): void;
+    list({ _req, _res, event }: EventServerFuncParams): void;
+    $sub({ event }: EventServerFuncParams): {
+        event: string | string[];
+    };
+    $unsub({ event }: EventServerFuncParams): {
+        event: string | string[];
+    };
+    $publish({ event: events, data }: EventServerFuncParams): {
+        event: string[];
+    };
+    isStream(params: ServerFuncParams): boolean;
+}
+declare const eventServer: EventServer;
+
+declare function registerCoreTools(): void;
+
+export { funcGetMeta as $, type AsyncTaskId as A, type BinarySemaphoreOptions as B, ClientToolTransport as C, DefaultAsyncSemaphoreCapacity as D, TaskAbortController as E, type Funcs as F, type TaskAbortControllers as G, type TaskPromise as H, type IPubSubServerTransport as I, CancelableAbility as J, makeToolFuncCancelable as K, type FuncParamType as L, type FuncParam as M, type FuncParams as N, type TFunc as O, type PubSubClientId as P, type BaseFuncItem as Q, RemoteToolFuncSchema as R, ServerTools as S, ToolTransport as T, type FuncItem as U, type BaseFunc as V, type ToolFuncPackage as W, ToolFunc as X, ToolFuncSchema as Y, FuncMetaSymbol as Z, funcWithMeta as _, type AIModelNameRules as a, ClientTools as a0, type ClientFuncItem as a1, ClientToolFuncSchema as a2, type ServerFuncParams as a3, type ServerFuncItem as a4, ServerToolFuncSchema as a5, registerCoreTools as a6, EventToolFunc as a7, event as a8, SecondaryCache as a9, _lrucache as aa, createLRUCache as ab, lrucache as ac, type EventClientFuncParams as ad, EventClient as ae, eventClient as af, type EventServerFuncParams as ag, EventServer as ah, eventServer as ai, type ResClientFuncParams as aj, ResClientTools as ak, type ResServerFuncParams as al, ResServerTools as am, type RpcMethodHandler as an, type IClientToolTransport as ao, type PubSubCtx as ap, type PubSubClient as aq, type PubSubServerSession as b, type IPubSubClientTransport as c, type PubSubClientStream as d, type IToolTransport as e, type ActionName as f, PASSING_SCORE as g, ActionNames as h, type AIModelNameRuleFn as i, type AIModelNameRule as j, type RemoteFuncItem as k, type SemaphoreIsReadyFuncType as l, type BinarySemaphoreAcquireOptions as m, type BinarySemaphoreReleaseOptions as n, type BinarySemaphoreReleaserFunc as o, type SemaphoreOptions as p, type SemaphoreTaskItem as q, BinarySemaphore as r, Semaphore as s, RateLimit as t, ToolAsyncMultiTaskBit as u, ToolAsyncCancelableBit as v, ToolAsyncPriorityBit as w, AsyncFeatureBits as x, AsyncFeatures as y, type CancelableAbilityOptions as z };