@nexus-cortex/core 4.26.0

package/dist/tools/ServerSideTools.js

@@ -0,0 +1,309 @@
+/**
+ * Server-Side Tool Support
+ *
+ * Handles provider-managed agentic tool execution where the provider's
+ * server autonomously loops through tool calls rather than requiring
+ * client-side execution.
+ *
+ * Examples:
+ * - XAI: web_search(), x_search(), code_interpreter()
+ * - Future: Other providers adding similar capabilities
+ *
+ * Architecture:
+ * - Tool definitions flagged as 'server' vs 'client'
+ * - Orchestrator passes tools to provider
+ * - Provider executes autonomously
+ * - Response includes citations, tool usage metadata
+ */
+/**
+ * Server-Side Tool Registry
+ *
+ * Maps provider tool names to their execution modes
+ */
+export const SERVER_SIDE_TOOL_REGISTRY = {
+    // XAI (grok models)
+    xai: {
+        'web_search': 'server',
+        'web_search_with_snippets': 'server',
+        'browse_page': 'server',
+        'x_search': 'server',
+        'x_user_search': 'server',
+        'x_keyword_search': 'server',
+        'x_semantic_search': 'server',
+        'x_thread_fetch': 'server',
+        'code_execution': 'server',
+        'view_image': 'server',
+        'view_x_video': 'server',
+        'file_search': 'server',
+        'mcp': 'server',
+    },
+    // OpenAI (Responses API hosted tools)
+    // R20: OpenAI exposes hosted tools on /v1/responses. They are the direct
+    // equivalent of XAI's server-side tools — declared as `{ type: 'web_search' }`
+    // etc. in the tools array, autonomously looped by OpenAI's infrastructure.
+    openai: {
+        'web_search': 'server',
+        'web_search_preview': 'server',
+        'code_interpreter': 'server',
+        'file_search': 'server',
+        'image_generation': 'server',
+        'computer_use_preview': 'server',
+        'mcp': 'server',
+    },
+    // Anthropic PTC (Programmatic Tool Calling) system tools
+    anthropic: {
+        'code_execution_20260120': 'server',
+        'tool_search_tool_bm25_20251119': 'server',
+    },
+    // Google (future - if they add server-side tools)
+    google: {
+    // Currently all client-side
+    },
+};
+/**
+ * Check if a tool is server-side for a given provider
+ */
+export function isServerSideTool(provider, toolName) {
+    const providerTools = SERVER_SIDE_TOOL_REGISTRY[provider];
+    if (!providerTools)
+        return false;
+    const mode = providerTools[toolName];
+    return mode === 'server' || mode === 'both';
+}
+/**
+ * Check if a tool is client-side for a given provider
+ */
+export function isClientSideTool(provider, toolName) {
+    const providerTools = SERVER_SIDE_TOOL_REGISTRY[provider];
+    if (!providerTools)
+        return true; // Default to client-side
+    const mode = providerTools[toolName];
+    return mode === 'client' || mode === 'both' || mode === undefined;
+}
+/**
+ * Get all server-side tools for a provider
+ */
+export function getServerSideTools(provider) {
+    const providerTools = SERVER_SIDE_TOOL_REGISTRY[provider];
+    if (!providerTools)
+        return [];
+    return Object.entries(providerTools)
+        .filter(([_, mode]) => mode === 'server' || mode === 'both')
+        .map(([name, _]) => name);
+}
+/**
+ * XAI Server-Side Tool Builders
+ *
+ * Helper functions to create XAI-specific server-side tools
+ */
+export const XAIServerSideTools = {
+    /**
+     * Web Search Tool
+     *
+     * Allows autonomous web search and page browsing
+     */
+    webSearch(config) {
+        return {
+            executionMode: 'server',
+            name: 'web_search',
+            description: 'Search the web and browse pages autonomously',
+            serverConfig: config,
+        };
+    },
+    /**
+     * X Search Tool
+     *
+     * Allows autonomous X (Twitter) search
+     */
+    xSearch(config) {
+        return {
+            executionMode: 'server',
+            name: 'x_search',
+            description: 'Search X (Twitter) posts autonomously',
+            serverConfig: config,
+        };
+    },
+    /**
+     * Code Execution Tool
+     *
+     * Allows autonomous Python code execution
+     */
+    codeExecution() {
+        return {
+            executionMode: 'server',
+            name: 'code_execution',
+            description: 'Execute Python code for calculations and analysis',
+        };
+    },
+    // Alias for backward compatibility
+    codeInterpreter() {
+        return this.codeExecution();
+    },
+};
+/**
+ * OpenAI Server-Side Tool Builders
+ *
+ * R20: OpenAI hosted tools on the Responses API. Direct parity with XAI's
+ * server-side tools — same wire-format pattern `{ type: 'tool_name' }` in the
+ * tools array; OpenAI's infrastructure autonomously loops through tool calls
+ * and returns citations/sources in the response metadata.
+ */
+export const OpenAIServerSideTools = {
+    /**
+     * Web Search Tool (Responses API native)
+     *
+     * Autonomous web search with citations.
+     */
+    webSearch() {
+        return {
+            executionMode: 'server',
+            name: 'web_search',
+            description: 'Search the web autonomously with citations',
+        };
+    },
+    /**
+     * Code Interpreter Tool (Responses API native)
+     *
+     * Sandboxed Python execution. Container automatically managed by OpenAI.
+     */
+    codeInterpreter() {
+        return {
+            executionMode: 'server',
+            name: 'code_interpreter',
+            description: 'Execute Python code in a sandboxed container',
+        };
+    },
+    /**
+     * File Search Tool (Responses API native)
+     *
+     * Vector-store-backed retrieval. Requires pre-uploaded vector store ids
+     * (configured at request time via additional API parameters).
+     */
+    fileSearch() {
+        return {
+            executionMode: 'server',
+            name: 'file_search',
+            description: 'Retrieve relevant chunks from pre-uploaded vector stores',
+        };
+    },
+    /**
+     * Image Generation Tool (Responses API native)
+     *
+     * Generates images via gpt-image-1 / DALL-E.
+     */
+    imageGeneration() {
+        return {
+            executionMode: 'server',
+            name: 'image_generation',
+            description: 'Generate images from a text prompt',
+        };
+    },
+};
+/**
+ * Convert ServerSideToolDefinition to CanonicalTool format
+ *
+ * This allows server-side tools to flow through the standard tool pipeline
+ */
+export function toCanonicalTool(toolDef) {
+    return {
+        name: toolDef.name,
+        description: toolDef.description || `${toolDef.name} tool`,
+        schema: {
+            type: 'object',
+            properties: {},
+            required: []
+        },
+        metadata: {
+            executionMode: toolDef.executionMode,
+            serverConfig: toolDef.serverConfig,
+            isServerSideTool: true
+        }
+    };
+}
+/**
+ * Separate client and server tools for a request
+ *
+ * Some providers don't allow mixing client and server tools
+ */
+export function separateTools(provider, tools) {
+    const clientTools = [];
+    const serverTools = [];
+    for (const tool of tools) {
+        const toolName = tool.name || tool.type || tool.function?.name;
+        if (!toolName) {
+            clientTools.push(tool);
+            continue;
+        }
+        if (isServerSideTool(provider, toolName)) {
+            serverTools.push(tool);
+        }
+        else {
+            clientTools.push(tool);
+        }
+    }
+    return { clientTools, serverTools };
+}
+/**
+ * Extract server-side tool metadata from provider response
+ *
+ * Handles different provider response formats
+ */
+export function extractServerSideMetadata(provider, response) {
+    // XAI format
+    if (provider === 'xai') {
+        // Check for Responses API format (has 'output' array)
+        if (response.output && Array.isArray(response.output)) {
+            // XAI Responses API format
+            const serverSideToolCalls = response.output.filter((item) => item.type && item.type.endsWith('_call') // code_interpreter_call, web_search_call, etc.
+            );
+            if (serverSideToolCalls.length > 0 || response.usage?.num_server_side_tools_used > 0) {
+                const toolCalls = serverSideToolCalls.map((tc) => {
+                    const status = tc.status === 'completed' ? 'success' : 'failed';
+                    return {
+                        id: tc.id || '',
+                        name: tc.name || tc.type.replace('_call', ''),
+                        arguments: tc.arguments || '{}',
+                        status,
+                    };
+                });
+                return {
+                    toolUsage: {
+                        server_side_tools: response.usage?.num_server_side_tools_used || toolCalls.length
+                    },
+                    citations: response.usage?.num_sources_used > 0 ? [] : undefined, // Only include if sources were used
+                    toolCalls,
+                    autonomousExecution: true,
+                    providerMetadata: {
+                        reasoning_tokens: response.usage?.output_tokens_details?.reasoning_tokens,
+                        num_sources_used: response.usage?.num_sources_used,
+                    },
+                };
+            }
+        }
+        else {
+            // XAI Messages API format (legacy)
+            const citations = response.citations || [];
+            const toolCalls = (response.tool_calls || []).map((tc) => ({
+                id: tc.id,
+                name: tc.function?.name || tc.name,
+                arguments: tc.function?.arguments || tc.arguments,
+                status: 'success',
+            }));
+            const toolUsage = response.server_side_tool_usage || {};
+            if (Object.keys(toolUsage).length > 0 || citations.length > 0) {
+                return {
+                    toolUsage,
+                    citations,
+                    toolCalls,
+                    autonomousExecution: true,
+                    providerMetadata: {
+                        reasoning_tokens: response.usage?.reasoning_tokens,
+                    },
+                };
+            }
+        }
+    }
+    // Add other providers as they add server-side tool support
+    return null;
+}
+//# sourceMappingURL=ServerSideTools.js.map

package/dist/tools/ServerSideTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServerSideTools.js","sourceRoot":"","sources":["../../src/tools/ServerSideTools.ts"],"names":[],"mappings":"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"}

package/dist/tools/ToolFactory.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Tool Factory
+ *
+ * Unified interface for accessing all tools (base + addon).
+ * Provides single point of access for orchestrator and adapters.
+ *
+ * Phase 1: Tool Architecture Refactor
+ */
+import type { AddonToolDefinition, CanonicalToolDefinition, ToolFactoryInterface } from './types/CanonicalTool.js';
+/**
+ * Unified tool factory
+ *
+ * Provides access to all tools (base + addon) through a single interface.
+ * Base tools are immutable, addon tools can be registered/removed dynamically.
+ */
+export declare class ToolFactory implements ToolFactoryInterface {
+    /**
+     * Get all available tools (base + addon)
+     *
+     * Base tools are always included. Addon tools are added if registered.
+     * Deduplicates by tool name, with base tools taking precedence.
+     */
+    getAllTools(): CanonicalToolDefinition[];
+    /**
+     * Get a specific tool by name
+     *
+     * Searches base tools first, then addon tools.
+     */
+    getTool(name: string): CanonicalToolDefinition | undefined;
+    /**
+     * Get base tools only
+     */
+    getBaseTools(): CanonicalToolDefinition[];
+    /**
+     * Get addon tools only
+     */
+    getAddonTools(): AddonToolDefinition[];
+    /**
+     * Get historical tools only
+     */
+    getHistoricalTools(): CanonicalToolDefinition[];
+    /**
+     * Register an addon tool
+     *
+     * @throws Error if tool name conflicts with base tool
+     * @throws Error if addon tool already exists
+     */
+    registerAddonTool(tool: AddonToolDefinition): void;
+    /**
+     * Remove an addon tool
+     *
+     * @returns true if tool was removed, false if not found
+     */
+    removeAddonTool(name: string): boolean;
+    /**
+     * Check if a tool exists (base or addon)
+     */
+    hasTool(name: string): boolean;
+    /**
+     * Get tool count (base + addon)
+     */
+    getToolCount(): number;
+    /**
+     * Clear addon tools (temporary or all)
+     */
+    clearAddonTools(persistent?: boolean): void;
+    /**
+     * Export persistent addon tools for storage
+     */
+    exportAddonTools(): AddonToolDefinition[];
+    /**
+     * Import persistent addon tools from storage
+     */
+    importAddonTools(tools: AddonToolDefinition[]): void;
+    /**
+     * Get essential tools only (discoveryTier === 'essential').
+     * Used for PTC deferred tool loading — essential tools are always loaded,
+     * standard tools get defer_loading: true and are discovered via Tool Search.
+     */
+    getEssentialTools(): CanonicalToolDefinition[];
+    /**
+     * Get standard tools only (discoveryTier === 'standard' or unset, excluding essential).
+     * These are candidates for defer_loading when PTC is enabled.
+     */
+    getStandardTools(): CanonicalToolDefinition[];
+}
+export declare const toolFactory: ToolFactory;
+//# sourceMappingURL=ToolFactory.d.ts.map

package/dist/tools/ToolFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolFactory.d.ts","sourceRoot":"","sources":["../../src/tools/ToolFactory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACrB,MAAM,0BAA0B,CAAC;AAIlC;;;;;GAKG;AACH,qBAAa,WAAY,YAAW,oBAAoB;IACtD;;;;;OAKG;IACH,WAAW,IAAI,uBAAuB,EAAE;IAuBxC;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS;IAW1D;;OAEG;IACH,YAAY,IAAI,uBAAuB,EAAE;IAIzC;;OAEG;IACH,aAAa,IAAI,mBAAmB,EAAE;IAItC;;OAEG;IACH,kBAAkB,IAAI,uBAAuB,EAAE;IAI/C;;;;;OAKG;IACH,iBAAiB,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI;IAalD;;;;OAIG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAWtC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,eAAe,CAAC,UAAU,GAAE,OAAe,GAAG,IAAI;IAIlD;;OAEG;IACH,gBAAgB,IAAI,mBAAmB,EAAE;IAIzC;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,EAAE,GAAG,IAAI;IAIpD;;;;OAIG;IACH,iBAAiB,IAAI,uBAAuB,EAAE;IAS9C;;;OAGG;IACH,gBAAgB,IAAI,uBAAuB,EAAE;CAI9C;AAGD,eAAO,MAAM,WAAW,aAAoB,CAAC"}

package/dist/tools/ToolFactory.js

@@ -0,0 +1,153 @@
+/**
+ * Tool Factory
+ *
+ * Unified interface for accessing all tools (base + addon).
+ * Provides single point of access for orchestrator and adapters.
+ *
+ * Phase 1: Tool Architecture Refactor
+ */
+import { baseToolRegistry } from './registries/BaseToolRegistry.js';
+import { addonToolRegistry } from './registries/AddonToolRegistry.js';
+/**
+ * Unified tool factory
+ *
+ * Provides access to all tools (base + addon) through a single interface.
+ * Base tools are immutable, addon tools can be registered/removed dynamically.
+ */
+export class ToolFactory {
+    /**
+     * Get all available tools (base + addon)
+     *
+     * Base tools are always included. Addon tools are added if registered.
+     * Deduplicates by tool name, with base tools taking precedence.
+     */
+    getAllTools() {
+        const baseTools = baseToolRegistry.getAllTools();
+        const addonTools = addonToolRegistry.getAllTools();
+        // Use Map to deduplicate by tool name
+        // Base tools added first, so they take precedence over addon tools
+        const toolMap = new Map();
+        // Add base tools first (these are immutable and take precedence)
+        baseTools.forEach(tool => {
+            toolMap.set(tool.name, tool);
+        });
+        // Add addon tools only if name doesn't already exist
+        addonTools.forEach(tool => {
+            if (!toolMap.has(tool.name)) {
+                toolMap.set(tool.name, tool);
+            }
+        });
+        return Array.from(toolMap.values());
+    }
+    /**
+     * Get a specific tool by name
+     *
+     * Searches base tools first, then addon tools.
+     */
+    getTool(name) {
+        // Check base tools first (immutable)
+        const baseTool = baseToolRegistry.getTool(name);
+        if (baseTool) {
+            return baseTool;
+        }
+        // Check addon tools
+        return addonToolRegistry.getTool(name);
+    }
+    /**
+     * Get base tools only
+     */
+    getBaseTools() {
+        return baseToolRegistry.getAllTools();
+    }
+    /**
+     * Get addon tools only
+     */
+    getAddonTools() {
+        return addonToolRegistry.getAllTools();
+    }
+    /**
+     * Get historical tools only
+     */
+    getHistoricalTools() {
+        return baseToolRegistry.getToolsByCategory('historical');
+    }
+    /**
+     * Register an addon tool
+     *
+     * @throws Error if tool name conflicts with base tool
+     * @throws Error if addon tool already exists
+     */
+    registerAddonTool(tool) {
+        // Prevent overriding base tools
+        if (baseToolRegistry.hasTool(tool.name)) {
+            throw new Error(`Cannot register addon tool '${tool.name}': name conflicts with base tool. ` +
+                `Base tools are immutable.`);
+        }
+        // Register the addon tool
+        addonToolRegistry.registerTool(tool);
+    }
+    /**
+     * Remove an addon tool
+     *
+     * @returns true if tool was removed, false if not found
+     */
+    removeAddonTool(name) {
+        // Cannot remove base tools
+        if (baseToolRegistry.hasTool(name)) {
+            throw new Error(`Cannot remove '${name}': it is a base tool. Base tools are immutable.`);
+        }
+        return addonToolRegistry.removeTool(name);
+    }
+    /**
+     * Check if a tool exists (base or addon)
+     */
+    hasTool(name) {
+        return baseToolRegistry.hasTool(name) || addonToolRegistry.hasTool(name);
+    }
+    /**
+     * Get tool count (base + addon)
+     */
+    getToolCount() {
+        return this.getAllTools().length;
+    }
+    /**
+     * Clear addon tools (temporary or all)
+     */
+    clearAddonTools(persistent = false) {
+        addonToolRegistry.clearTools(persistent);
+    }
+    /**
+     * Export persistent addon tools for storage
+     */
+    exportAddonTools() {
+        return addonToolRegistry.exportTools();
+    }
+    /**
+     * Import persistent addon tools from storage
+     */
+    importAddonTools(tools) {
+        addonToolRegistry.importTools(tools);
+    }
+    /**
+     * Get essential tools only (discoveryTier === 'essential').
+     * Used for PTC deferred tool loading — essential tools are always loaded,
+     * standard tools get defer_loading: true and are discovered via Tool Search.
+     */
+    getEssentialTools() {
+        const ESSENTIAL_TOOL_NAMES = new Set([
+            'ReadFile', 'WriteFile', 'EditFile', 'Shell', 'Glob', 'Grep',
+        ]);
+        return this.getAllTools().filter((t) => t.discoveryTier === 'essential' || ESSENTIAL_TOOL_NAMES.has(t.name));
+    }
+    /**
+     * Get standard tools only (discoveryTier === 'standard' or unset, excluding essential).
+     * These are candidates for defer_loading when PTC is enabled.
+     */
+    getStandardTools() {
+        const essential = new Set(this.getEssentialTools().map((t) => t.name));
+        return this.getAllTools().filter((t) => !essential.has(t.name));
+    }
+}
+// Export singleton instance
+export const toolFactory = new ToolFactory();
+//# sourceMappingURL=ToolFactory.js.map

package/dist/tools/ToolFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolFactory.js","sourceRoot":"","sources":["../../src/tools/ToolFactory.ts"],"names":[],"mappings":"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"}