@everworker/oneringai 0.4.3 → 0.4.5

package/dist/{index-CEjKTeSb.d.cts → index-CsQOVhqe.d.cts}

@@ -742,6 +742,319 @@ interface ContextStorageListOptions {
     offset?: number;
 }
 
+/**
+ * ToolCatalogRegistry - Static Global Registry for Tool Categories
+ *
+ * The single source of truth for all tool categories and their tools.
+ * Library users register their own categories and tools at app startup.
+ *
+ * Built-in tools are auto-registered from registry.generated.ts on first access.
+ *
+ * @example
+ * ```typescript
+ * // Register custom category
+ * ToolCatalogRegistry.registerCategory({
+ *   name: 'knowledge',
+ *   displayName: 'Knowledge Graph',
+ *   description: 'Search entities, get facts, manage references',
+ * });
+ *
+ * // Register tools in category
+ * ToolCatalogRegistry.registerTools('knowledge', [
+ *   { name: 'entity_search', displayName: 'Entity Search', description: 'Search people/orgs', tool: entitySearch, safeByDefault: true },
+ * ]);
+ *
+ * // Query
+ * const categories = ToolCatalogRegistry.getCategories();
+ * const tools = ToolCatalogRegistry.getToolsInCategory('knowledge');
+ * const found = ToolCatalogRegistry.findTool('entity_search');
+ * ```
+ */
+
+/**
+ * Definition of a tool category in the catalog.
+ */
+interface ToolCategoryDefinition {
+    /** Unique category name (e.g., 'filesystem', 'knowledge', 'connector:github') */
+    name: string;
+    /** Human-readable display name (e.g., 'File System') */
+    displayName: string;
+    /** Description shown in catalog metatool display */
+    description: string;
+}
+/**
+ * A single tool entry in the catalog.
+ */
+interface CatalogToolEntry {
+    /** The actual tool function (optional when createTool factory is provided) */
+    tool?: ToolFunction;
+    /** Tool name (matches definition.function.name) */
+    name: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Brief description */
+    description: string;
+    /** Whether this tool is safe to execute without user approval */
+    safeByDefault: boolean;
+    /** Whether this tool requires a connector to function */
+    requiresConnector?: boolean;
+    /** Factory for runtime tool creation (e.g., browser tools needing context) */
+    createTool?: (ctx: Record<string, unknown>) => ToolFunction;
+    /** Source identifier (e.g., 'oneringai', 'hosea', 'custom') */
+    source?: string;
+    /** Connector name (for connector-originated tools) */
+    connectorName?: string;
+    /** Service type (e.g., 'github', 'slack') */
+    serviceType?: string;
+    /** Supported connector service types */
+    connectorServiceTypes?: string[];
+}
+/**
+ * Entry format from the generated tool registry (registry.generated.ts).
+ * Used by initializeFromRegistry() and registerFromToolRegistry().
+ */
+interface ToolRegistryEntry {
+    name: string;
+    displayName: string;
+    category: string;
+    description: string;
+    tool: ToolFunction;
+    safeByDefault: boolean;
+    requiresConnector?: boolean;
+}
+/**
+ * Scope for filtering which categories are visible/allowed.
+ *
+ * - `string[]` — shorthand allowlist (only these categories)
+ * - `{ include: string[] }` — explicit allowlist
+ * - `{ exclude: string[] }` — blocklist (all except these)
+ * - `undefined` — all categories allowed
+ */
+type ToolCategoryScope = string[] | {
+    include: string[];
+} | {
+    exclude: string[];
+};
+/**
+ * Connector category metadata returned by discoverConnectorCategories().
+ */
+interface ConnectorCategoryInfo {
+    /** Category name in 'connector:<name>' format */
+    name: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Description */
+    description: string;
+    /** Number of tools */
+    toolCount: number;
+    /** Resolved tools */
+    tools: ToolFunction[];
+}
+/**
+ * Static global registry for tool categories and their tools.
+ *
+ * Like Connector and StorageRegistry, this is a static class that acts
+ * as a single source of truth. App code registers categories at startup,
+ * and plugins/agents query them at runtime.
+ */
+declare class ToolCatalogRegistry {
+    /** Category definitions: name → definition */
+    private static _categories;
+    /** Tools per category: category name → tool entries */
+    private static _tools;
+    /** Whether built-in tools have been registered */
+    private static _initialized;
+    /** Lazy-loaded ConnectorTools module. null = not attempted, false = failed */
+    private static _connectorToolsModule;
+    private static readonly BUILTIN_DESCRIPTIONS;
+    /**
+     * Convert a hyphenated or plain name to a display name.
+     * E.g., 'custom-tools' → 'Custom Tools', 'filesystem' → 'Filesystem'
+     */
+    static toDisplayName(name: string): string;
+    /**
+     * Parse a connector category name, returning the connector name or null.
+     * E.g., 'connector:github' → 'github', 'filesystem' → null
+     */
+    static parseConnectorCategory(category: string): string | null;
+    /**
+     * Get the ConnectorTools module (lazy-loaded, cached).
+     * Returns null if ConnectorTools is not available.
+     * Uses false sentinel to prevent retrying after first failure.
+     *
+     * NOTE: The dynamic require() path fails in bundled environments (Meteor, Webpack).
+     * Call setConnectorToolsModule() at app startup to inject the module explicitly.
+     */
+    static getConnectorToolsModule(): {
+        ConnectorTools: any;
+    } | null;
+    /**
+     * Explicitly set the ConnectorTools module reference.
+     *
+     * Use this in bundled environments (Meteor, Webpack, etc.) where the lazy
+     * require('../../tools/connector/ConnectorTools.js') fails due to path resolution.
+     *
+     * @example
+     * ```typescript
+     * import { ToolCatalogRegistry, ConnectorTools } from '@everworker/oneringai';
+     * ToolCatalogRegistry.setConnectorToolsModule({ ConnectorTools });
+     * ```
+     */
+    static setConnectorToolsModule(mod: {
+        ConnectorTools: any;
+    }): void;
+    /**
+     * Register a tool category.
+     * If the category already exists, updates its metadata.
+     * @throws Error if name is empty or whitespace
+     */
+    static registerCategory(def: ToolCategoryDefinition): void;
+    /**
+     * Register multiple tools in a category.
+     * The category is auto-created if it doesn't exist (with a generic description).
+     * @throws Error if category name is empty or whitespace
+     */
+    static registerTools(category: string, tools: CatalogToolEntry[]): void;
+    /**
+     * Register a single tool in a category.
+     */
+    static registerTool(category: string, tool: CatalogToolEntry): void;
+    /**
+     * Unregister a category and all its tools.
+     */
+    static unregisterCategory(category: string): boolean;
+    /**
+     * Unregister a single tool from a category.
+     */
+    static unregisterTool(category: string, toolName: string): boolean;
+    /**
+     * Get all registered categories.
+     */
+    static getCategories(): ToolCategoryDefinition[];
+    /**
+     * Get a single category by name.
+     */
+    static getCategory(name: string): ToolCategoryDefinition | undefined;
+    /**
+     * Check if a category exists.
+     */
+    static hasCategory(name: string): boolean;
+    /**
+     * Get all tools in a category.
+     */
+    static getToolsInCategory(category: string): CatalogToolEntry[];
+    /**
+     * Get all catalog tools across all categories.
+     */
+    static getAllCatalogTools(): CatalogToolEntry[];
+    /**
+     * Find a tool by name across all categories.
+     */
+    static findTool(name: string): {
+        category: string;
+        entry: CatalogToolEntry;
+    } | undefined;
+    /**
+     * Filter categories by scope.
+     */
+    static filterCategories(scope?: ToolCategoryScope): ToolCategoryDefinition[];
+    /**
+     * Check if a category is allowed by a scope.
+     */
+    static isCategoryAllowed(name: string, scope?: ToolCategoryScope): boolean;
+    /**
+     * Discover all connector categories with their tools.
+     * Calls ConnectorTools.discoverAll() and filters by scope/identities.
+     *
+     * @param options - Optional filtering
+     * @returns Array of connector category info
+     */
+    static discoverConnectorCategories(options?: {
+        scope?: ToolCategoryScope;
+        identities?: Array<{
+            connector: string;
+        }>;
+    }): ConnectorCategoryInfo[];
+    /**
+     * Resolve tools for a specific connector category.
+     *
+     * @param category - Category name in 'connector:<name>' format
+     * @returns Array of resolved tools with names
+     */
+    static resolveConnectorCategoryTools(category: string): Array<{
+        tool: ToolFunction;
+        name: string;
+    }>;
+    /**
+     * Resolve tool names to ToolFunction[].
+     *
+     * Searches registered categories and (optionally) connector tools.
+     * Used by app-level executors (e.g., V25's OneRingAgentExecutor).
+     *
+     * @param toolNames - Array of tool names to resolve
+     * @param options - Resolution options
+     * @returns Resolved tool functions (skips unresolvable names with warning)
+     */
+    static resolveTools(toolNames: string[], options?: {
+        includeConnectors?: boolean;
+        userId?: string;
+        context?: Record<string, unknown>;
+    }): ToolFunction[];
+    /**
+     * Resolve tools grouped by connector name.
+     *
+     * Tools with a `connectorName` go into `byConnector`; all others go into `plain`.
+     * Supports factory-based tool creation via `createTool` when context is provided.
+     *
+     * @param toolNames - Array of tool names to resolve
+     * @param context - Optional context passed to createTool factories
+     * @param options - Resolution options
+     * @returns Grouped tools: plain + byConnector map
+     */
+    static resolveToolsGrouped(toolNames: string[], context?: Record<string, unknown>, options?: {
+        includeConnectors?: boolean;
+    }): {
+        plain: ToolFunction[];
+        byConnector: Map<string, ToolFunction[]>;
+    };
+    /**
+     * Resolve a tool from a CatalogToolEntry, using factory if available.
+     * Returns null if neither tool nor createTool is available.
+     */
+    private static resolveEntryTool;
+    /**
+     * Search connector tools by name (uses lazy accessor).
+     */
+    private static findConnectorTool;
+    /**
+     * Ensure built-in tools from registry.generated.ts are registered.
+     * Called lazily on first query.
+     *
+     * In ESM environments, call `initializeFromRegistry(toolRegistry)` explicitly
+     * from your app startup instead of relying on auto-initialization.
+     */
+    static ensureInitialized(): void;
+    /**
+     * Explicitly initialize from the generated tool registry.
+     * Call this at app startup in ESM environments where lazy require() doesn't work.
+     *
+     * @example
+     * ```typescript
+     * import { toolRegistry } from './tools/registry.generated.js';
+     * ToolCatalogRegistry.initializeFromRegistry(toolRegistry);
+     * ```
+     */
+    static initializeFromRegistry(registry: ToolRegistryEntry[]): void;
+    /**
+     * Internal: register tools from a tool registry array.
+     */
+    private static registerFromToolRegistry;
+    /**
+     * Reset the registry. Primarily for testing.
+     */
+    static reset(): void;
+}
+
 /**
  * AgentContextNextGen - Type Definitions
  *
@@ -1166,6 +1479,8 @@ interface ContextFeatures {
     persistentInstructions?: boolean;
     /** Enable UserInfo plugin (default: false) */
     userInfo?: boolean;
+    /** Enable ToolCatalog plugin for dynamic tool loading/unloading (default: false) */
+    toolCatalog?: boolean;
 }
 /**
  * Default feature configuration
@@ -1198,6 +1513,11 @@ interface PluginConfigs {
      * See UserInfoPluginConfig for full options.
      */
     userInfo?: Record<string, unknown>;
+    /**
+     * Tool catalog plugin config (used when features.toolCatalog=true).
+     * See ToolCatalogPluginConfig for full options.
+     */
+    toolCatalog?: Record<string, unknown>;
 }
 /**
  * AgentContextNextGen configuration
@@ -1238,6 +1558,8 @@ interface AgentContextNextGenConfig {
     tools?: ToolFunction[];
     /** Storage for session persistence */
     storage?: IContextStorage;
+    /** Restrict tool catalog to specific categories */
+    toolCategories?: ToolCategoryScope;
     /** Plugin-specific configurations (used with features flags) */
     plugins?: PluginConfigs;
     /**
@@ -2249,4 +2571,4 @@ declare class HookManager {
     getDisabledHooks(): string[];
 }
 
-export { type TextGenerateOptions as $, type AgentContextNextGenConfig as A, type BeforeCompactionCallback as B, type ContextFeatures as C, type HookName as D, ExecutionContext as E, type FunctionToolDefinition as F, type ITokenEstimator as G, type HookConfig as H, type IContextStorage as I, type CompactionContext as J, type CompactionResult as K, type LLMResponse as L, type MemoryEntry as M, type StaleEntryInfo as N, type OutputItem as O, type PriorityCalculator as P, type PriorityContext as Q, type MemoryIndex as R, type SerializedContextState as S, type Tool as T, type TaskStatusForMemory as U, type WorkingMemoryAccess as V, type WorkingMemoryConfig as W, type ContextStorageListOptions as X, type ContextSessionSummary as Y, type TokenUsage as Z, StreamEventType as _, type MemoryScope as a, isSimpleScope as a$, type ModelCapabilities as a0, MessageRole as a1, type AfterToolContext as a2, type AgentEventName as a3, type AgenticLoopEventName as a4, type AgenticLoopEvents as a5, type ApprovalResult as a6, type ApproveToolContext as a7, type BeforeToolContext as a8, type BuiltInTool as a9, type ReasoningItem as aA, type ResponseCompleteEvent as aB, type ResponseCreatedEvent as aC, type ResponseInProgressEvent as aD, type SimpleScope as aE, type TaskAwareScope as aF, type ThinkingContent as aG, type ToolCallArgumentsDeltaEvent as aH, type ToolCallArgumentsDoneEvent as aI, type ToolCallStartEvent as aJ, ToolCallState as aK, type ToolExecutionContext as aL, type ToolExecutionDoneEvent as aM, type ToolExecutionStartEvent as aN, type ToolModification as aO, type ToolResultContent as aP, type ToolUseContent as aQ, calculateEntrySize as aR, defaultDescribeCall as aS, forPlan as aT, forTasks as aU, getToolCallDescription as aV, isErrorEvent as aW, isOutputTextDelta as aX, isReasoningDelta as aY, isReasoningDone as aZ, isResponseComplete as a_, CONTEXT_SESSION_FORMAT_VERSION as aa, type CompactionItem as ab, ContentType as ac, DEFAULT_CONFIG as ad, DEFAULT_FEATURES as ae, DEFAULT_MEMORY_CONFIG as af, type ErrorEvent as ag, type ExecutionConfig as ah, type Hook as ai, HookManager as aj, type InputImageContent as ak, type InputTextContent as al, type IterationCompleteEvent$1 as am, type JSONSchema as an, MEMORY_PRIORITY_VALUES as ao, type MemoryEntryInput as ap, type MemoryIndexEntry as aq, type Message as ar, type ModifyingHook as as, type OutputTextContent as at, type OutputTextDeltaEvent as au, type OutputTextDoneEvent as av, type OversizedInputResult as aw, type PluginConfigs as ax, type ReasoningDeltaEvent as ay, type ReasoningDoneEvent as az, type ToolFunction as b, isStreamEvent as b0, isTaskAwareScope as b1, isTerminalMemoryStatus as b2, isToolCallArgumentsDelta as b3, isToolCallArgumentsDone as b4, isToolCallStart as b5, scopeEquals as b6, scopeMatches as b7, type ExecutionCompleteEvent as b8, type ExecutionStartEvent as b9, type LLMRequestEvent as ba, type LLMResponseEvent as bb, type ToolCompleteEvent as bc, type ToolStartEvent as bd, type ToolContext as c, type ToolPermissionConfig as d, type ContextBudget as e, type ToolCall as f, type IContextPluginNextGen as g, type MemoryPriority as h, type MemoryTier as i, type ContextEvents as j, type AuthIdentity as k, type ICompactionStrategy as l, type InputItem as m, type Content as n, type PreparedContext as o, type ToolResult as p, type ConsolidationResult as q, type StoredContextSession as r, type ITextProvider as s, type ContextSessionMetadata as t, type StreamEvent as u, type HistoryMode as v, type AgentEvents as w, type AgentResponse as x, type ExecutionMetrics as y, type AuditEntry as z };
+export { StreamEventType as $, type AgentContextNextGenConfig as A, type BeforeCompactionCallback as B, type ContextFeatures as C, type HookName as D, ExecutionContext as E, type FunctionToolDefinition as F, type ITokenEstimator as G, type HookConfig as H, type IContextStorage as I, type ToolCategoryScope as J, type CompactionContext as K, type LLMResponse as L, type MemoryEntry as M, type CompactionResult as N, type OutputItem as O, type PriorityCalculator as P, type StaleEntryInfo as Q, type PriorityContext as R, type SerializedContextState as S, type Tool as T, type MemoryIndex as U, type TaskStatusForMemory as V, type WorkingMemoryConfig as W, type WorkingMemoryAccess as X, type ContextStorageListOptions as Y, type ContextSessionSummary as Z, type TokenUsage as _, type MemoryScope as a, getToolCallDescription as a$, type TextGenerateOptions as a0, type ModelCapabilities as a1, MessageRole as a2, type AfterToolContext as a3, type AgentEventName as a4, type AgenticLoopEventName as a5, type AgenticLoopEvents as a6, type ApprovalResult as a7, type ApproveToolContext as a8, type BeforeToolContext as a9, type OversizedInputResult as aA, type PluginConfigs as aB, type ReasoningDeltaEvent as aC, type ReasoningDoneEvent as aD, type ReasoningItem as aE, type ResponseCompleteEvent as aF, type ResponseCreatedEvent as aG, type ResponseInProgressEvent as aH, type SimpleScope as aI, type TaskAwareScope as aJ, type ThinkingContent as aK, type ToolCallArgumentsDeltaEvent as aL, type ToolCallArgumentsDoneEvent as aM, type ToolCallStartEvent as aN, ToolCallState as aO, ToolCatalogRegistry as aP, type ToolCategoryDefinition as aQ, type ToolExecutionContext as aR, type ToolExecutionDoneEvent as aS, type ToolExecutionStartEvent as aT, type ToolModification as aU, type ToolResultContent as aV, type ToolUseContent as aW, calculateEntrySize as aX, defaultDescribeCall as aY, forPlan as aZ, forTasks as a_, type BuiltInTool as aa, CONTEXT_SESSION_FORMAT_VERSION as ab, type ToolRegistryEntry as ac, type CatalogToolEntry as ad, type CompactionItem as ae, type ConnectorCategoryInfo as af, ContentType as ag, DEFAULT_CONFIG as ah, DEFAULT_FEATURES as ai, DEFAULT_MEMORY_CONFIG as aj, type ErrorEvent as ak, type ExecutionConfig as al, type Hook as am, HookManager as an, type InputImageContent as ao, type InputTextContent as ap, type IterationCompleteEvent$1 as aq, type JSONSchema as ar, MEMORY_PRIORITY_VALUES as as, type MemoryEntryInput as at, type MemoryIndexEntry as au, type Message as av, type ModifyingHook as aw, type OutputTextContent as ax, type OutputTextDeltaEvent as ay, type OutputTextDoneEvent as az, type ToolFunction as b, isErrorEvent as b0, isOutputTextDelta as b1, isReasoningDelta as b2, isReasoningDone as b3, isResponseComplete as b4, isSimpleScope as b5, isStreamEvent as b6, isTaskAwareScope as b7, isTerminalMemoryStatus as b8, isToolCallArgumentsDelta as b9, isToolCallArgumentsDone as ba, isToolCallStart as bb, scopeEquals as bc, scopeMatches as bd, type ExecutionCompleteEvent as be, type ExecutionStartEvent as bf, type LLMRequestEvent as bg, type LLMResponseEvent as bh, type ToolCompleteEvent as bi, type ToolStartEvent as bj, type ToolContext as c, type ToolPermissionConfig as d, type ContextBudget as e, type ToolCall as f, type IContextPluginNextGen as g, type MemoryPriority as h, type MemoryTier as i, type ContextEvents as j, type AuthIdentity as k, type ICompactionStrategy as l, type InputItem as m, type Content as n, type PreparedContext as o, type ToolResult as p, type ConsolidationResult as q, type StoredContextSession as r, type ITextProvider as s, type ContextSessionMetadata as t, type StreamEvent as u, type HistoryMode as v, type AgentEvents as w, type AgentResponse as x, type ExecutionMetrics as y, type AuditEntry as z };