/** * Named toolset groups for organising tools into reusable collections. * * Port of `praisonaiagents/toolsets.py`. Toolsets are named groups of tool * names that can be enabled as a unit and composed via `includes` * (recursive, with cycle detection). * * ```ts * import { registerToolset, resolveToolset } from 'praisonai/toolsets'; * registerToolset('web', ['internet_search', 'crawl4ai']); * registerToolset('files', ['read_file', 'write_file']); * registerToolset('research', undefined, ['web', 'files']); * resolveToolset('research'); // ['internet_search', 'crawl4ai', 'read_file', 'write_file'] * ``` * * Prebuilt toolsets carry the same Python tool names as * `toolsets.py::_load_prebuilt_toolsets`, so `resolveToolset('web')` returns * the same list on both sides. Only some of those names have a TypeScript * builtin under `src/tools/builtins`; {@link TOOLSET_TOOL_ID_MAP} records the * mapping and {@link resolveToolsetBuiltinIds} yields only the registry ids * that exist here — resolution never invents a tool. * * Python's `threading.RLock` / double-checked singleton are omitted: the * registry is single-threaded in JavaScript. */ /** Constructor options for {@link ToolsetSpec} (Python dataclass fields). */ export interface ToolsetSpecConfig { /** Unique name for the toolset. */ name: string; /** Tool names included directly in this toolset. Default `[]`. */ tools?: string[]; /** Other toolset names to include (recursive composition). Default `[]`. */ includes?: string[]; /** Optional description of the toolset's purpose. Default `""`. */ description?: string; } /** * Specification for a named toolset group. * * Python parity: `toolsets.py::ToolsetSpec`. */ export declare class ToolsetSpec { name: string; tools: string[]; includes: string[]; description: string; constructor(config: ToolsetSpecConfig); } /** * Python prebuilt tool name → TypeScript builtin registry id * (`src/tools/builtins`, as registered by `registerBuiltinTools()`). * * Only names with a real TypeScript builtin appear here. Python names such as * `internet_search`, `duckduckgo`, `read_file` or `execute_command` have no * TypeScript builtin and are deliberately absent. */ export declare const TOOLSET_TOOL_ID_MAP: Readonly>; /** TypeScript builtin registry id for a Python tool name, or `null` when none exists. */ export declare function toolsetToolId(toolName: string): string | null; /** * Registry for managing named toolset groups. * * Python parity: `toolsets.py::ToolsetRegistry`. Provides registration and * resolution of toolset groups, with support for recursive composition via * includes. */ export declare class ToolsetRegistry { private readonly _toolsets; private _prebuiltLoaded; /** * Register a named toolset (Python `register_toolset`). * * As in Python, registering a name that already exists is a silent no-op * unless `overwrite` is true. Nothing is thrown. */ registerToolset(name: string, tools?: string[] | null, includes?: string[] | null, description?: string, overwrite?: boolean): void; /** Remove a toolset; true if removed, false if not found (Python `unregister_toolset`). */ unregisterToolset(name: string): boolean; /** * Get a defensive copy of a toolset, or `null` if not found * (Python `get_toolset` returns `None`). */ getToolset(name: string): ToolsetSpec | null; /** All registered toolset names, in registration order (Python `list_toolsets`). */ listToolsets(): string[]; /** * Resolve a toolset name to a flat, de-duplicated list of tool names * (Python `resolve_toolset`). * * @throws Error `Toolset not found: ` or * `Circular dependency detected in toolset: ` (Python `ValueError`). */ resolveToolset(name: string): string[]; /** * Resolve a toolset, honouring the model-family preferred edit format * (Python `resolve_toolset_for_model`). * * Behaves exactly like {@link resolveToolset} but, when the resolved * harness profile expresses a preferred edit primitive and both primitives * are present, the preferred one is advertised first. Falsy or unknown * models reproduce {@link resolveToolset} byte-for-byte. */ resolveToolsetForModel(name: string, model?: string | null): string[]; /** * Resolve multiple toolsets to a flat, de-duplicated list of tool names * (Python `resolve_toolsets`). */ resolveToolsets(names: string[]): string[]; /** * Resolve multiple toolsets, honouring the model's preferred edit format * (Python `resolve_toolsets_for_model`). */ resolveToolsetsForModel(names: string[], model?: string | null): string[]; /** * TypeScript-only: resolve toolsets to the builtin registry ids that exist * under `src/tools/builtins` (see {@link TOOLSET_TOOL_ID_MAP}). Tool names * with no TypeScript builtin are dropped, so the result may be shorter than * {@link resolveToolsets} — or empty for toolsets such as `files`. */ resolveToolsetBuiltinIds(names: string[]): string[]; /** * Reorder edit primitives so the model's preferred one is advertised first * (Python `_apply_preferred_edit_order`). Never throws; any resolution * error leaves `tools` unchanged. */ private static _applyPreferredEditOrder; /** Recursive helper with cycle detection (Python `_resolve_toolset_recursive`). */ private _resolveToolsetRecursive; /** Ensure prebuilt toolsets are loaded exactly once (Python `_ensure_prebuilt_loaded`). */ private _ensurePrebuiltLoaded; /** * Load the standard prebuilt toolsets (Python `_load_prebuilt_toolsets`). * Tool names are the Python names; see {@link TOOLSET_TOOL_ID_MAP} for which * of them have a TypeScript builtin. */ private _loadPrebuiltToolsets; /** Clear all registered toolsets; prebuilt toolsets reload on next access (Python `clear`). */ clear(): void; /** True if a toolset is registered (Python `__contains__`). */ has(name: string): boolean; /** Number of registered toolsets (Python `__len__`). */ get size(): number; /** Python `__repr__`. */ toString(): string; } /** The global toolset registry singleton (Python `get_toolset_registry`). */ export declare function getToolsetRegistry(): ToolsetRegistry; /** Register a named toolset with the global registry (Python `register_toolset`). */ export declare function registerToolset(name: string, tools?: string[] | null, includes?: string[] | null, description?: string, overwrite?: boolean): void; /** Resolve a toolset name to a flat list of tool names (Python `resolve_toolset`). */ export declare function resolveToolset(name: string): string[]; /** Resolve multiple toolset names to a flat list of tool names (Python `resolve_toolsets`). */ export declare function resolveToolsets(names: string[]): string[]; /** * Resolve multiple toolsets, honouring the model's preferred edit format * (Python `resolve_toolsets_for_model`). */ export declare function resolveToolsetsForModel(names: string[], model?: string | null): string[]; /** All registered toolset names (Python `list_toolsets`). */ export declare function listToolsets(): string[]; /** Get a toolset by name, or `null` (Python `get_toolset`). */ export declare function getToolset(name: string): ToolsetSpec | null; /** Remove a toolset from the global registry (Python `unregister_toolset`). */ export declare function unregisterToolset(name: string): boolean; /** Check if a toolset is registered (Python `has_toolset`). */ export declare function hasToolset(name: string): boolean; /** * TypeScript-only: builtin registry ids for the tools in `names` that exist * under `src/tools/builtins`. See {@link ToolsetRegistry.resolveToolsetBuiltinIds}. */ export declare function resolveToolsetBuiltinIds(names: string[]): string[];