digital-tools 2.0.2 → 2.1.1

package/test/define.test.js

@@ -0,0 +1,306 @@
+/**
+ * Tests for Tool Definition functionality
+ *
+ * Covers defineTool, defineAndRegister, createToolExecutor, and toolBuilder.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { defineTool, defineAndRegister, createToolExecutor, toolBuilder, registry, } from '../src/index.js';
+describe('defineTool', () => {
+    it('creates a tool with basic config', () => {
+        const tool = defineTool({
+            id: 'basic.tool',
+            name: 'Basic Tool',
+            description: 'A basic tool',
+            category: 'data',
+            input: {
+                type: 'object',
+                properties: {
+                    value: { type: 'string', description: 'Input value' },
+                },
+                required: ['value'],
+            },
+            handler: async (input) => ({ result: input }),
+        });
+        expect(tool.id).toBe('basic.tool');
+        expect(tool.name).toBe('Basic Tool');
+        expect(tool.description).toBe('A basic tool');
+        expect(tool.category).toBe('data');
+    });
+    it('converts input schema to parameters', () => {
+        const tool = defineTool({
+            id: 'param.tool',
+            name: 'Param Tool',
+            description: 'Tool with parameters',
+            category: 'data',
+            input: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Name input' },
+                    age: { type: 'number', description: 'Age input' },
+                },
+                required: ['name'],
+            },
+            handler: async (input) => input,
+        });
+        expect(tool.parameters).toHaveLength(2);
+        expect(tool.parameters[0].name).toBe('name');
+        expect(tool.parameters[0].required).toBe(true);
+        expect(tool.parameters[1].name).toBe('age');
+        expect(tool.parameters[1].required).toBe(false);
+    });
+    it('sets subcategory', () => {
+        const tool = defineTool({
+            id: 'subcat.tool',
+            name: 'Subcategory Tool',
+            description: 'Tool with subcategory',
+            category: 'data',
+            subcategory: 'transform',
+            input: { type: 'object', properties: {} },
+            handler: async () => ({}),
+        });
+        expect(tool.subcategory).toBe('transform');
+    });
+    it('sets output schema', () => {
+        const tool = defineTool({
+            id: 'output.tool',
+            name: 'Output Tool',
+            description: 'Tool with output',
+            category: 'data',
+            input: { type: 'object', properties: {} },
+            output: {
+                type: 'object',
+                properties: {
+                    result: { type: 'string' },
+                },
+            },
+            handler: async () => ({ result: 'done' }),
+        });
+        expect(tool.output).toBeDefined();
+        expect(tool.output?.schema).toHaveProperty('properties');
+    });
+    it('applies options', () => {
+        const tool = defineTool({
+            id: 'options.tool',
+            name: 'Options Tool',
+            description: 'Tool with options',
+            category: 'data',
+            input: { type: 'object', properties: {} },
+            handler: async () => ({}),
+            options: {
+                audience: 'agent',
+                tags: ['test', 'example'],
+                idempotent: true,
+            },
+        });
+        expect(tool.audience).toBe('agent');
+        expect(tool.tags).toContain('test');
+        expect(tool.idempotent).toBe(true);
+    });
+    it('handler is callable', async () => {
+        const tool = defineTool({
+            id: 'callable.tool',
+            name: 'Callable Tool',
+            description: 'Tool with callable handler',
+            category: 'data',
+            input: {
+                type: 'object',
+                properties: { x: { type: 'number' } },
+                required: ['x'],
+            },
+            handler: async (input) => ({ doubled: input.x * 2 }),
+        });
+        const result = await tool.handler({ x: 5 });
+        expect(result).toEqual({ doubled: 10 });
+    });
+});
+describe('defineAndRegister', () => {
+    beforeEach(() => {
+        registry.clear();
+    });
+    it('creates and registers a tool', () => {
+        const tool = defineAndRegister({
+            id: 'register.tool',
+            name: 'Register Tool',
+            description: 'Auto-registered tool',
+            category: 'data',
+            input: { type: 'object', properties: {} },
+            handler: async () => ({}),
+        });
+        expect(tool.id).toBe('register.tool');
+        expect(registry.has('register.tool')).toBe(true);
+    });
+});
+describe('createToolExecutor', () => {
+    beforeEach(() => {
+        registry.clear();
+        registry.register(defineTool({
+            id: 'exec.test',
+            name: 'Exec Test',
+            description: 'Test execution',
+            category: 'data',
+            input: {
+                type: 'object',
+                properties: { value: { type: 'string' } },
+                required: ['value'],
+            },
+            handler: async (input) => ({
+                upper: input.value.toUpperCase(),
+            }),
+        }));
+        registry.register(defineTool({
+            id: 'exec.agent-only',
+            name: 'Agent Only',
+            description: 'Agent only tool',
+            category: 'data',
+            input: { type: 'object', properties: {} },
+            handler: async () => ({ result: 'agent' }),
+            options: { audience: 'agent' },
+        }));
+        registry.register(defineTool({
+            id: 'exec.error',
+            name: 'Error Tool',
+            description: 'Tool that throws',
+            category: 'data',
+            input: { type: 'object', properties: {} },
+            handler: async () => {
+                throw new Error('Tool error');
+            },
+        }));
+    });
+    it('executes a tool with context', async () => {
+        const executor = createToolExecutor({
+            executor: { type: 'agent', id: 'agent_1', name: 'Test Agent' },
+            environment: 'test',
+        });
+        const result = await executor.execute('exec.test', { value: 'hello' });
+        expect(result.success).toBe(true);
+        expect(result.data?.upper).toBe('HELLO');
+    });
+    it('returns error for non-existent tool', async () => {
+        const executor = createToolExecutor({
+            executor: { type: 'agent', id: 'agent_1', name: 'Test Agent' },
+        });
+        const result = await executor.execute('non.existent', {});
+        expect(result.success).toBe(false);
+        expect(result.error?.code).toBe('TOOL_NOT_FOUND');
+    });
+    it('checks audience restrictions', async () => {
+        const executor = createToolExecutor({
+            executor: { type: 'human', id: 'user_1', name: 'Test User' },
+        });
+        const result = await executor.execute('exec.agent-only', {});
+        expect(result.success).toBe(false);
+        expect(result.error?.code).toBe('ACCESS_DENIED');
+    });
+    it('handles execution errors', async () => {
+        const executor = createToolExecutor({
+            executor: { type: 'agent', id: 'agent_1', name: 'Test Agent' },
+        });
+        const result = await executor.execute('exec.error', {});
+        expect(result.success).toBe(false);
+        expect(result.error?.code).toBe('EXECUTION_ERROR');
+        expect(result.error?.message).toBe('Tool error');
+    });
+    it('tracks execution metadata', async () => {
+        const executor = createToolExecutor({
+            executor: { type: 'agent', id: 'agent_1', name: 'Test Agent' },
+            requestId: 'req_123',
+        });
+        const result = await executor.execute('exec.test', { value: 'test' });
+        expect(result.metadata?.duration).toBeGreaterThanOrEqual(0);
+        expect(result.metadata?.requestId).toBe('req_123');
+    });
+    it('lists available tools', () => {
+        const executor = createToolExecutor({
+            executor: { type: 'human', id: 'user_1', name: 'Test User' },
+        });
+        const available = executor.listAvailable();
+        // Should not include agent-only tool
+        expect(available.some(t => t.id === 'exec.test')).toBe(true);
+        expect(available.some(t => t.id === 'exec.agent-only')).toBe(false);
+    });
+});
+describe('toolBuilder', () => {
+    beforeEach(() => {
+        registry.clear();
+    });
+    it('builds a tool with fluent API', () => {
+        const tool = toolBuilder('builder.test')
+            .name('Builder Test')
+            .description('Built with builder')
+            .category('data')
+            .subcategory('transform')
+            .input({
+            type: 'object',
+            properties: {
+                value: { type: 'string' },
+            },
+            required: ['value'],
+        })
+            .handler(async (input) => ({ result: input.value }))
+            .build();
+        expect(tool.id).toBe('builder.test');
+        expect(tool.name).toBe('Builder Test');
+        expect(tool.category).toBe('data');
+        expect(tool.subcategory).toBe('transform');
+    });
+    it('sets output schema', () => {
+        const tool = toolBuilder('output.test')
+            .name('Output Test')
+            .description('With output')
+            .category('data')
+            .input({ type: 'object', properties: {} })
+            .output({ type: 'object', properties: { result: { type: 'string' } } })
+            .handler(async () => ({ result: 'done' }))
+            .build();
+        expect(tool.output).toBeDefined();
+    });
+    it('sets options', () => {
+        const tool = toolBuilder('options.test')
+            .name('Options Test')
+            .description('With options')
+            .category('data')
+            .input({ type: 'object', properties: {} })
+            .options({
+            audience: 'both',
+            tags: ['builder'],
+        })
+            .handler(async () => ({}))
+            .build();
+        expect(tool.audience).toBe('both');
+        expect(tool.tags).toContain('builder');
+    });
+    it('registers tool with register()', () => {
+        const tool = toolBuilder('register.test')
+            .name('Register Test')
+            .description('Auto register')
+            .category('data')
+            .input({ type: 'object', properties: {} })
+            .handler(async () => ({}))
+            .register();
+        expect(registry.has('register.test')).toBe(true);
+    });
+    it('throws if required fields are missing', () => {
+        expect(() => {
+            toolBuilder('incomplete.test')
+                .name('Incomplete')
+                // Missing description, category, input, handler
+                .build();
+        }).toThrow();
+    });
+    it('handler is callable after build', async () => {
+        const tool = toolBuilder('callable.test')
+            .name('Callable')
+            .description('Callable handler')
+            .category('data')
+            .input({
+            type: 'object',
+            properties: { n: { type: 'number' } },
+            required: ['n'],
+        })
+            .handler(async (input) => ({ squared: input.n * input.n }))
+            .build();
+        const result = await tool.handler({ n: 4 });
+        expect(result).toEqual({ squared: 16 });
+    });
+});

package/test/registry.test.js

@@ -0,0 +1,357 @@
+/**
+ * Tests for Tool Registry functionality
+ *
+ * Covers tool registration, querying, and MCP conversion.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { registry, createRegistry, registerTool, getTool, executeTool, toMCP, listMCPTools, defineTool, } from '../src/index.js';
+describe('Registry', () => {
+    beforeEach(() => {
+        registry.clear();
+    });
+    describe('register', () => {
+        it('registers a tool', () => {
+            const tool = defineTool({
+                id: 'test.tool',
+                name: 'Test Tool',
+                description: 'A test tool',
+                category: 'data',
+                input: {
+                    type: 'object',
+                    properties: { value: { type: 'string' } },
+                    required: ['value'],
+                },
+                handler: async (input) => ({ result: input }),
+            });
+            registry.register(tool);
+            expect(registry.has('test.tool')).toBe(true);
+        });
+        it('overwrites existing tool with same id', () => {
+            const tool1 = defineTool({
+                id: 'test.tool',
+                name: 'Tool V1',
+                description: 'Version 1',
+                category: 'data',
+                input: { type: 'object', properties: {} },
+                handler: async () => ({ v: 1 }),
+            });
+            const tool2 = defineTool({
+                id: 'test.tool',
+                name: 'Tool V2',
+                description: 'Version 2',
+                category: 'data',
+                input: { type: 'object', properties: {} },
+                handler: async () => ({ v: 2 }),
+            });
+            registry.register(tool1);
+            registry.register(tool2);
+            expect(registry.get('test.tool')?.name).toBe('Tool V2');
+        });
+    });
+    describe('get', () => {
+        it('returns tool by id', () => {
+            const tool = defineTool({
+                id: 'get.test',
+                name: 'Get Test',
+                description: 'Test get',
+                category: 'data',
+                input: { type: 'object', properties: {} },
+                handler: async () => ({}),
+            });
+            registry.register(tool);
+            expect(registry.get('get.test')?.name).toBe('Get Test');
+        });
+        it('returns undefined for non-existent tool', () => {
+            expect(registry.get('non.existent')).toBeUndefined();
+        });
+    });
+    describe('has', () => {
+        it('returns true for registered tool', () => {
+            const tool = defineTool({
+                id: 'has.test',
+                name: 'Has Test',
+                description: 'Test has',
+                category: 'data',
+                input: { type: 'object', properties: {} },
+                handler: async () => ({}),
+            });
+            registry.register(tool);
+            expect(registry.has('has.test')).toBe(true);
+        });
+        it('returns false for non-existent tool', () => {
+            expect(registry.has('non.existent')).toBe(false);
+        });
+    });
+    describe('unregister', () => {
+        it('removes a tool from registry', () => {
+            const tool = defineTool({
+                id: 'unregister.test',
+                name: 'Unregister Test',
+                description: 'Test unregister',
+                category: 'data',
+                input: { type: 'object', properties: {} },
+                handler: async () => ({}),
+            });
+            registry.register(tool);
+            const result = registry.unregister('unregister.test');
+            expect(result).toBe(true);
+            expect(registry.has('unregister.test')).toBe(false);
+        });
+        it('returns false for non-existent tool', () => {
+            expect(registry.unregister('non.existent')).toBe(false);
+        });
+    });
+    describe('list', () => {
+        it('returns all tool ids', () => {
+            registry.register(defineTool({
+                id: 'list.a',
+                name: 'A',
+                description: 'A',
+                category: 'data',
+                input: { type: 'object', properties: {} },
+                handler: async () => ({}),
+            }));
+            registry.register(defineTool({
+                id: 'list.b',
+                name: 'B',
+                description: 'B',
+                category: 'web',
+                input: { type: 'object', properties: {} },
+                handler: async () => ({}),
+            }));
+            const ids = registry.list();
+            expect(ids).toContain('list.a');
+            expect(ids).toContain('list.b');
+        });
+        it('returns empty array when no tools', () => {
+            expect(registry.list()).toHaveLength(0);
+        });
+    });
+    describe('query', () => {
+        beforeEach(() => {
+            registry.register(defineTool({
+                id: 'query.data.1',
+                name: 'Data Tool 1',
+                description: 'Data tool',
+                category: 'data',
+                subcategory: 'transform',
+                input: { type: 'object', properties: {} },
+                handler: async () => ({}),
+                options: { audience: 'agent', tags: ['json', 'parse'] },
+            }));
+            registry.register(defineTool({
+                id: 'query.web.1',
+                name: 'Web Tool 1',
+                description: 'Web tool',
+                category: 'web',
+                subcategory: 'fetch',
+                input: { type: 'object', properties: {} },
+                handler: async () => ({}),
+                options: { audience: 'human', tags: ['http'] },
+            }));
+            registry.register(defineTool({
+                id: 'query.data.2',
+                name: 'Data Tool 2',
+                description: 'Another data tool',
+                category: 'data',
+                subcategory: 'validate',
+                input: { type: 'object', properties: {} },
+                handler: async () => ({}),
+                options: { audience: 'both', tags: ['validate'] },
+            }));
+        });
+        it('filters by category', () => {
+            const results = registry.query({ category: 'data' });
+            expect(results).toHaveLength(2);
+            expect(results.every(t => t.category === 'data')).toBe(true);
+        });
+        it('filters by subcategory', () => {
+            const results = registry.query({ subcategory: 'transform' });
+            expect(results).toHaveLength(1);
+            expect(results[0].id).toBe('query.data.1');
+        });
+        it('filters by tags', () => {
+            const results = registry.query({ tags: ['json'] });
+            expect(results).toHaveLength(1);
+            expect(results[0].id).toBe('query.data.1');
+        });
+        it('filters by audience', () => {
+            const agentResults = registry.query({ audience: 'agent' });
+            // agent can use tools with audience: agent, both, or undefined
+            expect(agentResults.length).toBeGreaterThanOrEqual(1);
+        });
+        it('searches by text', () => {
+            const results = registry.query({ search: 'another' });
+            expect(results).toHaveLength(1);
+            expect(results[0].id).toBe('query.data.2');
+        });
+        it('applies pagination', () => {
+            const results = registry.query({ limit: 2 });
+            expect(results).toHaveLength(2);
+        });
+        it('applies offset', () => {
+            const all = registry.query({});
+            const offset = registry.query({ offset: 1 });
+            expect(offset).toHaveLength(all.length - 1);
+        });
+    });
+    describe('byCategory', () => {
+        it('returns tools by category', () => {
+            registry.register(defineTool({
+                id: 'cat.web.1',
+                name: 'Web',
+                description: 'Web',
+                category: 'web',
+                input: { type: 'object', properties: {} },
+                handler: async () => ({}),
+            }));
+            registry.register(defineTool({
+                id: 'cat.data.1',
+                name: 'Data',
+                description: 'Data',
+                category: 'data',
+                input: { type: 'object', properties: {} },
+                handler: async () => ({}),
+            }));
+            const webTools = registry.byCategory('web');
+            expect(webTools).toHaveLength(1);
+            expect(webTools[0].id).toBe('cat.web.1');
+        });
+    });
+    describe('clear', () => {
+        it('removes all tools', () => {
+            registry.register(defineTool({
+                id: 'clear.1',
+                name: 'Clear',
+                description: 'Clear',
+                category: 'data',
+                input: { type: 'object', properties: {} },
+                handler: async () => ({}),
+            }));
+            registry.clear();
+            expect(registry.list()).toHaveLength(0);
+        });
+    });
+});
+describe('createRegistry', () => {
+    it('creates a new isolated registry', () => {
+        const reg1 = createRegistry();
+        const reg2 = createRegistry();
+        reg1.register(defineTool({
+            id: 'isolated.1',
+            name: 'Isolated',
+            description: 'Isolated',
+            category: 'data',
+            input: { type: 'object', properties: {} },
+            handler: async () => ({}),
+        }));
+        expect(reg1.has('isolated.1')).toBe(true);
+        expect(reg2.has('isolated.1')).toBe(false);
+    });
+});
+describe('registerTool', () => {
+    beforeEach(() => {
+        registry.clear();
+    });
+    it('registers tool in global registry', () => {
+        const tool = defineTool({
+            id: 'global.test',
+            name: 'Global',
+            description: 'Global',
+            category: 'data',
+            input: { type: 'object', properties: {} },
+            handler: async () => ({}),
+        });
+        registerTool(tool);
+        expect(registry.has('global.test')).toBe(true);
+    });
+});
+describe('getTool', () => {
+    beforeEach(() => {
+        registry.clear();
+    });
+    it('gets tool from global registry', () => {
+        const tool = defineTool({
+            id: 'get.global',
+            name: 'Get Global',
+            description: 'Get global',
+            category: 'data',
+            input: { type: 'object', properties: {} },
+            handler: async () => ({}),
+        });
+        registry.register(tool);
+        expect(getTool('get.global')?.name).toBe('Get Global');
+    });
+});
+describe('executeTool', () => {
+    beforeEach(() => {
+        registry.clear();
+    });
+    it('executes a registered tool', async () => {
+        const tool = defineTool({
+            id: 'execute.test',
+            name: 'Execute',
+            description: 'Execute',
+            category: 'data',
+            input: { type: 'object', properties: { value: { type: 'string' } } },
+            handler: async (input) => ({ doubled: input.value + input.value }),
+        });
+        registry.register(tool);
+        const result = await executeTool('execute.test', { value: 'test' });
+        expect(result.doubled).toBe('testtest');
+    });
+    it('throws for non-existent tool', async () => {
+        await expect(executeTool('non.existent', {})).rejects.toThrow('not found');
+    });
+});
+describe('toMCP', () => {
+    it('converts tool to MCP format', () => {
+        const tool = defineTool({
+            id: 'mcp.test',
+            name: 'MCP Test',
+            description: 'Test MCP conversion',
+            category: 'data',
+            input: {
+                type: 'object',
+                properties: {
+                    url: { type: 'string', description: 'URL to fetch' },
+                    timeout: { type: 'number', description: 'Timeout in ms' },
+                },
+                required: ['url'],
+            },
+            handler: async () => ({}),
+        });
+        const mcp = toMCP(tool);
+        expect(mcp.name).toBe('mcp.test');
+        expect(mcp.description).toBe('Test MCP conversion');
+        expect(mcp.inputSchema.type).toBe('object');
+        expect(mcp.inputSchema.properties).toHaveProperty('url');
+        expect(mcp.inputSchema.required).toContain('url');
+    });
+});
+describe('listMCPTools', () => {
+    beforeEach(() => {
+        registry.clear();
+    });
+    it('lists all tools in MCP format', () => {
+        registry.register(defineTool({
+            id: 'mcp.list.1',
+            name: 'Tool 1',
+            description: 'Tool 1',
+            category: 'data',
+            input: { type: 'object', properties: {} },
+            handler: async () => ({}),
+        }));
+        registry.register(defineTool({
+            id: 'mcp.list.2',
+            name: 'Tool 2',
+            description: 'Tool 2',
+            category: 'web',
+            input: { type: 'object', properties: {} },
+            handler: async () => ({}),
+        }));
+        const mcpTools = listMCPTools();
+        expect(mcpTools).toHaveLength(2);
+        expect(mcpTools.every(t => 'inputSchema' in t)).toBe(true);
+    });
+});